Upgrading to Django 1.5
#######################

:date: 2013-08-29 19:30
:tags: Django
:slug: upgrading-to-django-1.5
:author: Brian Neal
:summary: Here are my notes about upgrading to Django 1.5.

Upgrading to Django 1.5
=======================

`Django`_ 1.5 came out a while ago, and I finally got around to upgrading two
of my largest sites. I thought I would make a list of what I changed at a high
level for my own reference. Perhaps someone else may find it useful as well.

In any event, I highly recommend you read the excellent `release notes`_ and
`deprecation timeline`_. I also recommend you run with warnings turned on::

   $ python -Wall manage.py runserver

This will help you flag down issues in your code. If you aren't sure where
a warning is coming from, you can turn warnings into exceptions and get
a traceback (see the Python docs on the warnings_ library). Another trick is to
put a pdb_ breakpoint in the Django code before or after the warning, then you
can examine the call stack with the ``w`` command.

Upgrading Issues
================

Here are the issues that I ran into. Of course you may have a very different
experience depending on what features of Django you used and the details of
your site.

#. **Replace occurrences of Django's simplejson with json**. The Django team
   deprecated their version of the json library since they had dropped support
   for older versions of Python.

#. **select_related's depth argument is deprecated**. Instead of using
   ``depth`` I had to explictly name which relationships to follow.

#. **The cleanup management command is now called clearsessions**. I have
   a Celery_ task I had to update because of this name change.

#. **Remove my {% load url from future %} tags**. Long ago I had converted to
   the newer ``url`` tag behavior by using this tag. Since this is now the
   current behavior I could remove all of these tags.
 
#. **The LOGIN_* settings now accept URL names**. These settings can now accept
   URL names which allows me to be more DRY (Don't Repeat Yourself). I no
   longer have to maintain URL patterns in two places.

#. **Management commands should use self.stdout, etc. for output**. I'm not
   sure if this is required, but it makes it easier to test your management
   commands.

#. **slugify is now available at django.utils.text**. I was doing something
   kind of hacky by invoking the slugify template filter in Python code. Now
   this slugify code is more naturally available as a free Python function
   without the template filter baggage.

#. **Remove all references to django.contrib.markup**. Django decided not to be
   so tightly coupled to various third party markup languages. I can see their
   reasoning, as it does add to their maintenance burden, but it is kind of
   inconvenient if you already relied on it. Fortunately I had a while ago
   stopped relying on the Markdown filter and had used a custom solution.
   Seeing this issue in the release notes caused me to go looking through my
   code and I found some unused templates and ``INSTALLED_APPS`` setting that
   I could remove.  On my second site, I had one tiny usage of the Textile
   filter that I decided to just get rid of since it was hardly worth carrying
   the dependency for. I wrote a quick and dirty management command to convert
   the database from storing Textile markup to HTML and I was done.

#. **localflavor is deprecated in preferece to a third party app**. I was using
   some US state fields in a few models. All I had to do was pip_ install
   `django-localflavor`_, fix up some imports, update my requirements files,
   and I was good.

#. **Function-based generic views are now gone**. A third party application
   I am using made use of the old function-based generic views. These have been
   replaced with the newer class-based generic views. Luckily I wasn't actually
   using the views in this application, I am only relying on it's models and
   utilities. In this case I simply removed the inclusion of the application's
   ``urls.py`` and all was well. The application is no longer maintained so
   I would have had to port to the class-based views if I had needed them.

#. **The adminmedia template tags library is now gone**. I wasn't actually
   using this anymore, but I had a template that was still loading it. This
   cruft was removed.

What I didn't do
================

Django 1.5's largest new feature is probably its support for a `configurable
User model`_. This impacts my largest site, and I wasn't quite sure how to
proceed on this front. This is the only issue I feel like Django threw me under
the bus on. Fortunately, the ``get_profile()`` and ``AUTH_PROFILE_MODULE``
stuff will not be removed until Django 1.7. In addition, the author of the
South_ library is developing model migration support which will also land in
Django 1.7. Thus there is some time to sort this out, and I'm hoping Django
will have some tutorials or docs on how to migrate away from the old
``AUTH_PROFILE_MODULE`` scheme.

Conclusion
==========

The upgrade process went smoother and quicker than I thought thanks to the
excellent release notes and the Django team's use of Python warnings to flag
deprecated features.


.. _Django: https://www.djangoproject.com/
.. _release notes: https://docs.djangoproject.com/en/1.5/releases/1.5/
.. _deprecation timeline: https://docs.djangoproject.com/en/1.5/internals/deprecation/
.. _warnings: http://docs.python.org/library/warnings.html
.. _pdb: http://docs.python.org/library/pdb.html
.. _Celery: http://www.celeryproject.org/
.. _pip: http://www.pip-installer.org/en/latest/
.. _django-localflavor: https://pypi.python.org/pypi/django-localflavor
.. _configurable user model: https://docs.djangoproject.com/en/1.5/topics/auth/customizing/#auth-custom-user
.. _South: http://south.aeracode.org/