diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt index 4f5ef0e48b..9e88ec489b 100644 --- a/docs/internals/deprecation.txt +++ b/docs/internals/deprecation.txt @@ -2,37 +2,42 @@ Django Deprecation Timeline =========================== -This document outlines when various pieces of Django will be removed, following -their deprecation, as per the :ref:`deprecation policy -`. +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 `. More details +about each item can often be found in the release notes of two versions prior. 1.3 --- - * ``AdminSite.root()``. This release will remove the old method for - hooking up admin URLs. This has been deprecated since the 1.1 - release. +See the :doc:`Django 1.1 release notes` for more details on +these changes. + + * ``AdminSite.root()``. This method of hooking up the admin URLs will be + removed in favor of including ``admin.site.urls``. * Authentication backends need to define the boolean attributes - ``supports_object_permissions`` and ``supports_anonymous_user``. - The old backend style is deprecated since the 1.2 release. - - * The :mod:`django.contrib.gis.db.backend` module, including the - ``SpatialBackend`` interface, is deprecated since the 1.2 release. + ``supports_object_permissions`` and ``supports_anonymous_user`` until + version 1.4, at which point it will be assumed that all backends will + support these options. 1.4 --- - * ``CsrfResponseMiddleware``. This has been deprecated since the 1.2 - release, in favor of the template tag method for inserting the CSRF - token. ``CsrfMiddleware``, which combines ``CsrfResponseMiddleware`` - and ``CsrfViewMiddleware``, is also deprecated. +See the :doc:`Django 1.2 release notes` 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. - * ``SMTPConnection``. The 1.2 release deprecated the ``SMTPConnection`` - class in favor of a generic E-mail backend API. + * The :mod:`django.contrib.gis.db.backend` module will be removed in favor + of the specific backends. + + * ``SMTPConnection`` will be removed in favor of a generic E-mail backend API. * The many to many SQL generation functions on the database backends will be removed. @@ -45,46 +50,40 @@ their deprecation, as per the :ref:`deprecation policy removed. * The ``get_db_prep_save``, ``get_db_prep_value`` and - ``get_db_prep_lookup`` methods on Field were modified in 1.2 - to support multiple databases. In 1.4, the support functions - that allow methods with the old prototype to continue - working will be removed. + ``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()``), which have - been deprecated since the 1.2 release, will be removed. The + ``user.get_and_delete_messages()``), will be removed. The :doc:`messages framework ` 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 depends on the messages + means that the admin application will depend on the messages context processor. - * Authentication backends need to support the ``obj`` parameter for - permission checking. The ``supports_object_permissions`` variable - is not checked any longer and can be removed. + * 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 need to support the ``AnonymousUser`` - being passed to all methods dealing with permissions. - The ``supports_anonymous_user`` variable is not checked any - longer and can be removed. + * 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. These have been deprecated since the 1.2 - release. + backwards compatibility. * ``django.utils.translation.get_date_formats()`` and - ``django.utils.translation.get_partial_date_formats()``. These - functions are replaced by the new locale aware formatting; use - ``django.utils.formats.get_format()`` to get the appropriate - formats. + ``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``: ``DEFAULT_DATE_INPUT_FORMATS``, + * In ``django.forms.fields``, the constants: ``DEFAULT_DATE_INPUT_FORMATS``, ``DEFAULT_TIME_INPUT_FORMATS`` and - ``DEFAULT_DATETIME_INPUT_FORMATS``. Use + ``DEFAULT_DATETIME_INPUT_FORMATS`` will be removed. Use ``django.utils.formats.get_format()`` to get the appropriate formats. @@ -92,22 +91,22 @@ their deprecation, as per the :ref:`deprecation policy along with the ``django.test.simple.run_tests()`` test runner. * The ``views.feed()`` view and ``feeds.Feed`` class in - ``django.contrib.syndication`` have been deprecated since the 1.2 - release. The class-based view ``views.Feed`` should be used instead. + ``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``. This has been - deprecated since the 1.2 release. + ``django.contrib.auth.context_processors.auth``. - * The ``postgresql`` database backend has been deprecated in favor of - the ``postgresql_psycopg2`` backend. + * The ``postgresql`` database backend will be removed, use the + ``postgresql_psycopg2`` backend instead. - * The ``no`` language code has been deprecated in favor of the ``nb`` - language code. + * The ``no`` language code will be removed and has been replaced by the + ``nb`` language code. - * Authentication backends need to define the boolean attribute - ``supports_inactive_user``. + * 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 @@ -119,50 +118,47 @@ their deprecation, as per the :ref:`deprecation policy 1.5 --- - * The ``mod_python`` request handler has been deprecated since the 1.3 - release. The ``mod_wsgi`` handler should be used instead. +See the :doc:`Django 1.3 release notes` for more details on +these changes. + + * 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 ` has been - deprecated since the 1.3 release. The - :attr:`~django.test.client.Response.templates` attribute should be + objects returned by the :ref:`test client ` will be removed. + The :attr:`~django.test.client.Response.templates` attribute should be used instead. - * The features of the :class:`django.test.simple.DjangoTestRunner` - (including fail-fast and Ctrl-C test termination) can now be provided - by the unittest-native :class:`TextTestRunner`. The - :class:`~django.test.simple.DjangoTestRunner` will be removed in - favor of using the unittest-native class. + * The :class:`~django.test.simple.DjangoTestRunner` will be removed. + Instead use a unittest-native class. The features of the + :class:`django.test.simple.DjangoTestRunner` (including fail-fast and + Ctrl-C test termination) can currently be provided by the unittest-native + :class:`TextTestRunner`. * The undocumented function - :func:`django.contrib.formtools.utils.security_hash` - is deprecated, in favor of :func:`django.contrib.formtools.utils.form_hmac` + :func:`django.contrib.formtools.utils.security_hash` will be removed, + instead use :func:`django.contrib.formtools.utils.form_hmac` - * The function-based generic views have been deprecated in - favor of their class-based cousins. The following modules - will be removed: + * The function-based generic view modules will be removed in favor of their + class-based equivalents, outlined :doc:`here + `: - * :mod:`django.views.generic.create_update` - * :mod:`django.views.generic.date_based` - * :mod:`django.views.generic.list_detail` - * :mod:`django.views.generic.simple` - - * The :class:`~django.core.servers.basehttp.AdminMediaHandler` has - been deprecated in favor of the + * The :class:`~django.core.servers.basehttp.AdminMediaHandler` will be + removed. In its place use :class:`~django.contrib.staticfiles.handlers.StaticFilesHandler`. * 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. The new-style + template variable, not an implied string. Until then, the new-style behavior is provided in the ``future`` template tag library. * The :djadmin:`reset` and :djadmin:`sqlreset` management commands - are deprecated. + will be removed. - * Authentication backends need to support a inactive user + * Authentication backends will need to support an inactive user being passed to all methods dealing with permissions. - The ``supports_inactive_user`` variable is not checked any - longer and can be removed. + 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 @@ -172,27 +168,31 @@ their deprecation, as per the :ref:`deprecation policy :class:`~django.http.SimpleCookie`. * :class:`django.core.context_processors.PermWrapper` and - :class:`django.core.context_processors.PermLookupDict` - will be moved to :class:`django.contrib.auth.context_processors.PermWrapper` - and :class:`django.contrib.auth.context_processors.PermLookupDict`, + :class:`django.core.context_processors.PermLookupDict` will be removed in + favor of the corresponding + :class:`django.contrib.auth.context_processors.PermWrapper` and + :class:`django.contrib.auth.context_processors.PermLookupDict`, respectively. - * The :setting:`MEDIA_URL` or :setting:`STATIC_URL` settings are + * 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`` was deprecated in 1.4 - due to intractable security and performance issues. The argument will be - removed in 1.5. + * ``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. 1.6 --- +See the :doc:`Django 1.4 release notes` for more details on +these changes. + * The compatibility modules ``django.utils.copycompat`` and ``django.utils.hashcompat`` as well as the functions - ``django.utils.itercompat.all`` and ``django.utils.itercompat.any`` - have been deprecated since the 1.4 release. The native versions - should be used instead. + ``django.utils.itercompat.all`` and ``django.utils.itercompat.any`` will + be removed. The Python builtin versions should be used instead. * The :func:`~django.views.decorators.csrf.csrf_response_exempt` and :func:`~django.views.decorators.csrf.csrf_view_exempt` decorators will @@ -204,13 +204,11 @@ their deprecation, as per the :ref:`deprecation policy * The :class:`~django.core.cache.backends.memcached.CacheClass` backend was split into two in Django 1.3 in order to introduce support for PyLibMC. The historical :class:`~django.core.cache.backends.memcached.CacheClass` - is now an alias for :class:`~django.core.cache.backends.memcached.MemcachedCache`. - In Django 1.6, the historical alias will be removed. + will be removed in favor of :class:`~django.core.cache.backends.memcached.MemcachedCache`. * The UK-prefixed objects of ``django.contrib.localflavor.uk`` will only - be accessible through their new GB-prefixed names (GB is the correct - ISO 3166 code for United Kingdom). They have been deprecated since the - 1.4 release. + be accessible through their GB-prefixed names (GB is the correct + ISO 3166 code for United Kingdom). * The :setting:`IGNORABLE_404_STARTS` and :setting:`IGNORABLE_404_ENDS` settings have been superseded by :setting:`IGNORABLE_404_URLS` in @@ -218,7 +216,7 @@ their deprecation, as per the :ref:`deprecation policy * The :doc:`form wizard ` has been refactored to use class based views with pluggable backends in 1.4. - The previous implementation will be deprecated. + The previous implementation will be removed. * Legacy ways of calling :func:`~django.views.decorators.cache.cache_page` will be removed. @@ -230,26 +228,23 @@ their deprecation, as per the :ref:`deprecation policy * The template tag :func:`django.contrib.admin.templatetags.adminmedia.admin_media_prefix` - was deprecated since Django 1.4 and will be removed in favor of the - generic static files handling. + will be removed in favor of the generic static files handling. - * The builin truncation functions - :func:`django.utils.text.truncate_words` and - :func:`django.utils.text.truncate_html_words` - were deprecated since Django 1.4 and will be removed in favor - of the ``django.utils.text.Truncator`` class. + * The builtin truncation functions :func:`django.utils.text.truncate_words` + and :func:`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. - * In 1.4, 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` were moved to :mod:`django.conf.urls` - from their previous location ``django.conf.urls.defaults``. This module - was deprecated at the same time and will be removed in this Django release. + * ``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 Databrowse contrib module was deprecated in 1.4 and will be removed. + * The Databrowse contrib module will be removed. 2.0 ---