django/docs/internals/deprecation.txt

===========================
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.4
---

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

* ``CsrfResponseMiddleware`` and ``CsrfMiddleware`` will be removed.  Use
  the ``{% csrf_token %}`` template tag inside forms to enable CSRF
  protection. ``CsrfViewMiddleware`` remains and is enabled by default.

* The old imports for CSRF functionality (``django.contrib.csrf.*``),
  which moved to core in 1.2, will be removed.

* The ``django.contrib.gis.db.backend`` module will be removed in favor
  of the specific backends.

* ``SMTPConnection`` will be removed in favor of a generic Email backend API.

* The many to many SQL generation functions on the database backends
  will be removed.

* The ability to use the ``DATABASE_*`` family of top-level settings to
  define database connections will be removed.

* The ability to use shorthand notation to specify a database backend
  (i.e., ``sqlite3`` instead of ``django.db.backends.sqlite3``) will be
  removed.

* The ``get_db_prep_save``, ``get_db_prep_value`` and
  ``get_db_prep_lookup`` methods will have to support multiple databases.

* The ``Message`` model (in ``django.contrib.auth``), its related
  manager in the ``User`` model (``user.message_set``), and the
  associated methods (``user.message_set.create()`` and
  ``user.get_and_delete_messages()``), will be removed.  The
  :doc:`messages framework </ref/contrib/messages>` should be used
  instead. The related ``messages`` variable returned by the
  auth context processor will also be removed. Note that this
  means that the admin application will depend on the messages
  context processor.

* Authentication backends will need to support the ``obj`` parameter for
  permission checking. The ``supports_object_permissions`` attribute
  will no longer be checked and can be removed from custom backends.

* Authentication backends will need to support the ``AnonymousUser`` class
  being passed to all methods dealing with permissions.  The
  ``supports_anonymous_user`` variable will no longer be checked and can be
  removed from custom backends.

* The ability to specify a callable template loader rather than a
  ``Loader`` class will be removed, as will the ``load_template_source``
  functions that are included with the built in template loaders for
  backwards compatibility.

* ``django.utils.translation.get_date_formats()`` and
  ``django.utils.translation.get_partial_date_formats()``. These functions
  will be removed; use the locale-aware
  ``django.utils.formats.get_format()`` to get the appropriate formats.

* In ``django.forms.fields``, the constants: ``DEFAULT_DATE_INPUT_FORMATS``,
  ``DEFAULT_TIME_INPUT_FORMATS`` and
  ``DEFAULT_DATETIME_INPUT_FORMATS`` will be removed. Use
  ``django.utils.formats.get_format()`` to get the appropriate
  formats.

* The ability to use a function-based test runners will be removed,
  along with the ``django.test.simple.run_tests()`` test runner.

* The ``views.feed()`` view and ``feeds.Feed`` class in
  ``django.contrib.syndication`` will be removed. The class-based view
  ``views.Feed`` should be used instead.

* ``django.core.context_processors.auth``.  This release will
  remove the old method in favor of the new method in
  ``django.contrib.auth.context_processors.auth``.

* The ``postgresql`` database backend will be removed, use the
  ``postgresql_psycopg2`` backend instead.

* The ``no`` language code will be removed and has been replaced by the
  ``nb`` language code.

* Authentication backends will need to define the boolean attribute
  ``supports_inactive_user`` until version 1.5 when it will be assumed that
  all backends will handle inactive users.

* ``django.db.models.fields.XMLField`` will be removed. This was
  deprecated as part of the 1.3 release. An accelerated deprecation
  schedule has been used because the field hasn't performed any role
  beyond that of a simple ``TextField`` since the removal of oldforms.
  All uses of ``XMLField`` can be replaced with ``TextField``.

* The undocumented ``mixin`` parameter to the ``open()`` method of
  ``django.core.files.storage.Storage`` (and subclasses) will be removed.


1.5
---

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

* Starting Django without a :setting:`SECRET_KEY` will result in an exception
  rather than a `DeprecationWarning`. (This is accelerated from the usual
  deprecation path; see the :doc:`Django 1.4 release notes</releases/1.4>`.)

* The ``mod_python`` request handler will be removed. The ``mod_wsgi``
  handler should be used instead.

* The ``template`` attribute on :class:`~django.test.client.Response`
  objects returned by the :ref:`test client <test-client>` will be removed.
  The :attr:`~django.test.client.Response.templates` attribute should be
  used instead.

* The ``django.test.simple.DjangoTestRunner`` will be removed.
  Instead use a unittest-native class.  The features of the
  ``django.test.simple.DjangoTestRunner`` (including fail-fast and
  Ctrl-C test termination) can currently be provided by the unittest-native
  :class:`~unittest.TextTestRunner`.

* The undocumented function
  ``django.contrib.formtools.utils.security_hash`` will be removed,
  instead use ``django.contrib.formtools.utils.form_hmac``

* The function-based generic view modules will be removed in favor of their
  class-based equivalents, outlined :doc:`here
  </topics/class-based-views/index>`.

* The ``django.core.servers.basehttp.AdminMediaHandler`` will be
  removed.  In its place use
  ``django.contrib.staticfiles.handlers.StaticFilesHandler``.

* The template tags library ``adminmedia`` and the template tag ``{%
  admin_media_prefix %}`` will be removed in favor of the generic static files
  handling. (This is faster than the usual deprecation path; see the
  :doc:`Django 1.4 release notes</releases/1.4>`.)

* The :ttag:`url` and :ttag:`ssi` template tags will be
  modified so that the first argument to each tag is a template variable, not
  an implied string. In 1.4, this behavior is provided by a version of the tag
  in the ``future`` template tag library.

* The ``reset`` and ``sqlreset`` management commands will be removed.

* Authentication backends will need to support an inactive user
  being passed to all methods dealing with permissions.
  The ``supports_inactive_user`` attribute will no longer be checked
  and can be removed from custom backends.

* :meth:`~django.contrib.gis.geos.GEOSGeometry.transform` will raise
  a :class:`~django.contrib.gis.geos.GEOSException` when called
  on a geometry with no SRID value.

* ``django.http.CompatCookie`` will be removed in favor of
  ``django.http.SimpleCookie``.

* ``django.core.context_processors.PermWrapper`` and
  ``django.core.context_processors.PermLookupDict`` will be removed in
  favor of the corresponding
  ``django.contrib.auth.context_processors.PermWrapper`` and
  ``django.contrib.auth.context_processors.PermLookupDict``, respectively.

* The :setting:`MEDIA_URL` or :setting:`STATIC_URL` settings will be
  required to end with a trailing slash to ensure there is a consistent
  way to combine paths in templates.

* ``django.db.models.fields.URLField.verify_exists`` will be removed. The
  feature was deprecated in 1.3.1 due to intractable security and
  performance issues and will follow a slightly accelerated deprecation
  timeframe.

* Translations located under the so-called *project path* will be ignored during
  the translation building process performed at runtime. The
  :setting:`LOCALE_PATHS` setting can be used for the same task by including the
  filesystem path to a ``locale`` directory containing non-app-specific
  translations in its value.

* The Markup contrib app will no longer support versions of Python-Markdown
  library earlier than 2.1. An accelerated timeline was used as this was
  a security related deprecation.

* The ``CACHE_BACKEND`` setting will be removed. The cache backend(s) should be
  specified in the :setting:`CACHES` setting.

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.

1.8
---

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

2.0
---

* ``django.views.defaults.shortcut()``. This function has been moved
  to ``django.contrib.contenttypes.views.shortcut()`` as part of the
  goal of removing all ``django.contrib`` references from the core
  Django codebase. The old shortcut will be removed in the 2.0
  release.

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