===========================
Django Deprecation Timeline
===========================

This document outlines when various pieces of Django will be removed or altered
in a backward incompatible way, following their deprecation, as per the
:ref:`deprecation policy <internal-release-deprecation-policy>`. More details
about each item can often be found in the release notes of two versions prior.

1.6
---

See the :doc:`Django 1.4 release notes</releases/1.4>` for more details on
these changes.

* ``django.contrib.databrowse`` will be removed.

* ``django.contrib.localflavor`` will be removed following an accelerated
  deprecation.

* ``django.contrib.markup`` will be removed following an accelerated
  deprecation.

* The compatibility modules ``django.utils.copycompat`` and
  ``django.utils.hashcompat`` as well as the functions
  ``django.utils.itercompat.all`` and ``django.utils.itercompat.any`` will
  be removed. The Python builtin versions should be used instead.

* The ``csrf_response_exempt`` and ``csrf_view_exempt`` decorators will
  be removed. Since 1.4 ``csrf_response_exempt`` has been a no-op (it
  returns the same function), and ``csrf_view_exempt`` has been a
  synonym for ``django.views.decorators.csrf.csrf_exempt``, which should
  be used to replace it.

* The ``django.core.cache.backends.memcached.CacheClass`` backend
  was split into two in Django 1.3 in order to introduce support for
  PyLibMC. The historical ``CacheClass`` will be removed in favor of
  ``django.core.cache.backends.memcached.MemcachedCache``.

* The UK-prefixed objects of ``django.contrib.localflavor.uk`` will only
  be accessible through their GB-prefixed names (GB is the correct
  ISO 3166 code for United Kingdom).

* The ``IGNORABLE_404_STARTS`` and ``IGNORABLE_404_ENDS`` settings have been
  superseded by :setting:`IGNORABLE_404_URLS` in the 1.4 release. They will be
  removed.

* The :doc:`form wizard </ref/contrib/formtools/form-wizard>` has been
  refactored to use class-based views with pluggable backends in 1.4.
  The previous implementation will be removed.

* Legacy ways of calling
  :func:`~django.views.decorators.cache.cache_page` will be removed.

* The backward-compatibility shim to automatically add a debug-false
  filter to the ``'mail_admins'`` logging handler will be removed. The
  :setting:`LOGGING` setting should include this filter explicitly if
  it is desired.

* The builtin truncation functions ``django.utils.text.truncate_words()``
  and ``django.utils.text.truncate_html_words()`` will be removed in
  favor of the ``django.utils.text.Truncator`` class.

* The :class:`~django.contrib.gis.geoip.GeoIP` class was moved to
  :mod:`django.contrib.gis.geoip` in 1.4 -- the shortcut in
  :mod:`django.contrib.gis.utils` will be removed.

* ``django.conf.urls.defaults`` will be removed. The functions
  :func:`~django.conf.urls.include`, :func:`~django.conf.urls.patterns` and
  :func:`~django.conf.urls.url` plus :data:`~django.conf.urls.handler404`,
  :data:`~django.conf.urls.handler500`, are now available through
  :mod:`django.conf.urls` .

* The functions ``setup_environ()`` and ``execute_manager()`` will be removed
  from :mod:`django.core.management`. This also means that the old (pre-1.4)
  style of :file:`manage.py` file will no longer work.

* Setting the ``is_safe`` and ``needs_autoescape`` flags as attributes of
  template filter functions will no longer be supported.

* The attribute ``HttpRequest.raw_post_data`` was renamed to ``HttpRequest.body``
  in 1.4. The backward compatibility will be removed --
  ``HttpRequest.raw_post_data`` will no longer work.

* The value for the ``post_url_continue`` parameter in
  ``ModelAdmin.response_add()`` will have to be either ``None`` (to redirect
  to the newly created object's edit page) or a pre-formatted url. String
  formats, such as the previous default ``'../%s/'``, will not be accepted any
  more.

1.7
---

See the :doc:`Django 1.5 release notes</releases/1.5>` for more details on
these changes.

* The module ``django.utils.simplejson`` will be removed. The standard library
  provides :mod:`json` which should be used instead.

* The function ``django.utils.itercompat.product`` will be removed. The Python
  builtin version should be used instead.

* Auto-correction of INSTALLED_APPS and TEMPLATE_DIRS settings when they are
  specified as a plain string instead of a tuple will be removed and raise an
  exception.

* The ``mimetype`` argument to the ``__init__`` methods of
  :class:`~django.http.HttpResponse`,
  :class:`~django.template.response.SimpleTemplateResponse`, and
  :class:`~django.template.response.TemplateResponse`, will be removed.
  ``content_type`` should be used instead. This also applies to the
  :func:`~django.shortcuts.render_to_response` shortcut and
  the sitemamp views, :func:`~django.contrib.sitemaps.views.index` and
  :func:`~django.contrib.sitemaps.views.sitemap`.

* When :class:`~django.http.HttpResponse` is instantiated with an iterator,
  or when :attr:`~django.http.HttpResponse.content` is set to an iterator,
  that iterator will be immediately consumed.

* The ``AUTH_PROFILE_MODULE`` setting, and the ``get_profile()`` method on
  the User model, will be removed.

* The ``cleanup`` management command will be removed. It's replaced by
  ``clearsessions``.

* The ``daily_cleanup.py`` script will be removed.

* The ``depth`` keyword argument will be removed from
  :meth:`~django.db.models.query.QuerySet.select_related`.

* The undocumented ``get_warnings_state()``/``restore_warnings_state()``
  functions from :mod:`django.test.utils` and the ``save_warnings_state()``/
  ``restore_warnings_state()``
  :ref:`django.test.*TestCase <django-testcase-subclasses>` methods are
  deprecated. Use the :class:`warnings.catch_warnings` context manager
  available starting with Python 2.6 instead.

* The undocumented ``check_for_test_cookie`` method in
  :class:`~django.contrib.auth.forms.AuthenticationForm` will be removed
  following an accelerated deprecation. Users subclassing this form should
  remove calls to this method, and instead ensure that their auth related views
  are CSRF protected, which ensures that cookies are enabled.

* The version of :func:`django.contrib.auth.views.password_reset_confirm` that
  supports base36 encoded user IDs
  (``django.contrib.auth.views.password_reset_confirm_uidb36``) will be
  removed. If your site has been running Django 1.6 for more than
  :setting:`PASSWORD_RESET_TIMEOUT_DAYS`, this change will have no effect. If
  not, then any password reset links generated before you upgrade to Django 1.7
  won't work after the upgrade.

1.8
---

* ``django.contrib.comments`` will be removed.

* The following transaction management APIs will be removed:

  - ``TransactionMiddleware``,
  - the decorators and context managers ``autocommit``, ``commit_on_success``,
    and ``commit_manually``, defined in ``django.db.transaction``,
  - the functions ``commit_unless_managed`` and ``rollback_unless_managed``,
    also defined in ``django.db.transaction``,
  - the ``TRANSACTIONS_MANAGED`` setting.

  Upgrade paths are described in the :ref:`transaction management docs
  <transactions-upgrading-from-1.5>`.

* The :ttag:`cycle` and :ttag:`firstof` template tags will auto-escape their
  arguments. In 1.6 and 1.7, this behavior is provided by the version of these
  tags in the ``future`` template tag library.

* The ``SEND_BROKEN_LINK_EMAILS`` setting will be removed. Add the
  :class:`django.middleware.common.BrokenLinkEmailsMiddleware` middleware to
  your :setting:`MIDDLEWARE_CLASSES` setting instead.

* ``django.middleware.doc.XViewMiddleware`` will be removed. Use
  ``django.contrib.admindocs.middleware.XViewMiddleware`` instead.

* ``Model._meta.module_name`` was renamed to ``model_name``.

* Remove the backward compatible shims introduced to rename ``get_query_set``
  and similar queryset methods. This affects the following classes:
  ``BaseModelAdmin``, ``ChangeList``, ``BaseCommentNode``,
  ``GenericForeignKey``, ``Manager``, ``SingleRelatedObjectDescriptor`` and
  ``ReverseSingleRelatedObjectDescriptor``.

* Remove the backward compatible shims introduced to rename the attributes
  ``ChangeList.root_query_set`` and ``ChangeList.query_set``.

* ``django.views.defaults.shortcut`` will be removed, as part of the
  goal of removing all ``django.contrib`` references from the core
  Django codebase. Instead use
  ``django.contrib.contenttypes.views.shortcut``. ``django.conf.urls.shortcut``
  will also be removed.

* Support for the Python Imaging Library (PIL) module will be removed, as it
  no longer appears to be actively maintained & does not work on Python 3.
  You are advised to install `Pillow`_, which should be used instead.

.. _`Pillow`: https://pypi.python.org/pypi/Pillow

* The following private APIs will be removed:

  - ``django.db.backend``
  - ``django.db.close_connection()``
  - ``django.db.backends.creation.BaseDatabaseCreation.set_autocommit()``
  - ``django.db.transaction.is_managed()``
  - ``django.db.transaction.managed()``

* ``django.forms.widgets.RadioInput`` will be removed in favor of
  ``django.forms.widgets.RadioChoiceInput``.

* The module ``django.test.simple`` and the class
  ``django.test.simple.DjangoTestSuiteRunner`` will be removed. Instead use
  ``django.test.runner.DiscoverRunner``.

* The module ``django.test._doctest`` will be removed. Instead use the doctest
  module from the Python standard library.

* The ``CACHE_MIDDLEWARE_ANONYMOUS_ONLY`` setting will be removed.

* Usage of the hard-coded *Hold down "Control", or "Command" on a Mac, to select
  more than one.* string to override or append to user-provided ``help_text`` in
  forms for ManyToMany model fields will not be performed by Django anymore
  either at the model or forms layer.

* The ``Model._meta.get_(add|change|delete)_permission`` methods will
  be removed.

2.0
---

* ``ssi`` and ``url`` template tags will be removed from the ``future`` template
  tag library (used during the 1.3/1.4 deprecation period).
