mirror of
https://github.com/django/django.git
synced 2024-12-25 02:26:12 +00:00
8efd20f96d
It uses a static manifest file that is created when running collectstatic in the JSON format.
1159 lines
50 KiB
Plaintext
1159 lines
50 KiB
Plaintext
============================================
|
||
Django 1.7 release notes - UNDER DEVELOPMENT
|
||
============================================
|
||
|
||
Welcome to Django 1.7!
|
||
|
||
These release notes cover the `new features`_, as well as some `backwards
|
||
incompatible changes`_ you'll want to be aware of when upgrading from Django
|
||
1.6 or older versions. We've also dropped some features, which are detailed in
|
||
:doc:`our deprecation plan </internals/deprecation>`, and we've `begun the
|
||
deprecation process for some features`_.
|
||
|
||
.. _`new features`: `What's new in Django 1.7`_
|
||
.. _`backwards incompatible changes`: `Backwards incompatible changes in 1.7`_
|
||
.. _`begun the deprecation process for some features`: `Features deprecated in 1.7`_
|
||
|
||
Python compatibility
|
||
====================
|
||
|
||
Django 1.7 requires Python 2.7 or above, though we **highly recommend**
|
||
the latest minor release. Support for Python 2.6 has been dropped.
|
||
|
||
This change should affect only a small number of Django users, as most
|
||
operating-system vendors today are shipping Python 2.7 or newer as their default
|
||
version. If you're still using Python 2.6, however, you'll need to stick to
|
||
Django 1.6 until you can upgrade your Python version. Per :doc:`our support
|
||
policy </internals/release-process>`, Django 1.6 will continue to receive
|
||
security support until the release of Django 1.8.
|
||
|
||
What's new in Django 1.7
|
||
========================
|
||
|
||
Schema migrations
|
||
~~~~~~~~~~~~~~~~~
|
||
|
||
Django now has built-in support for schema migrations. It allows models
|
||
to be updated, changed, and deleted by creating migration files that represent
|
||
the model changes and which can be run on any development, staging or production
|
||
database.
|
||
|
||
Migrations are covered in :doc:`their own documentation</topics/migrations>`,
|
||
but a few of the key features are:
|
||
|
||
* ``syncdb`` has been deprecated and replaced by ``migrate``. Don't worry -
|
||
calls to ``syncdb`` will still work as before.
|
||
|
||
* A new ``makemigrations`` command provides an easy way to autodetect changes
|
||
to your models and make migrations for them.
|
||
|
||
:data:`~django.db.models.signals.pre_syncdb` and
|
||
:data:`~django.db.models.signals.post_syncdb` have been replaced by
|
||
:data:`~django.db.models.signals.pre_migrate` and
|
||
:data:`~django.db.models.signals.post_migrate` respectively. These new
|
||
signals have slightly different arguments. Check the documentation for
|
||
details.
|
||
|
||
* The ``allow_syncdb`` method on database routers is now called ``allow_migrate``,
|
||
but still performs the same function. Routers with ``allow_syncdb`` methods
|
||
will still work, but that method name is deprecated and you should change
|
||
it as soon as possible (nothing more than renaming is required).
|
||
|
||
App-loading refactor
|
||
~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Historically, Django applications were tightly linked to models. A singleton
|
||
known as the "app cache" dealt with both installed applications and models.
|
||
The models module was used as an identifier for applications in many APIs.
|
||
|
||
As the concept of :doc:`Django applications </ref/applications>` matured, this
|
||
code showed some shortcomings. It has been refactored into an "app registry"
|
||
where models modules no longer have a central role and where it's possible to
|
||
attach configuration data to applications.
|
||
|
||
Improvements thus far include:
|
||
|
||
* Applications can run code at startup, before Django does anything else, with
|
||
the :meth:`~django.apps.AppConfig.ready` method of their configuration.
|
||
|
||
* Application labels are assigned correctly to models even when they're
|
||
defined outside of ``models.py``. You don't have to set
|
||
:attr:`~django.db.models.Options.app_label` explicitly any more.
|
||
|
||
* It is possible to omit ``models.py`` entirely if an application doesn't
|
||
have any models.
|
||
|
||
* Applications can be relabeled with the :attr:`~django.apps.AppConfig.label`
|
||
attribute of application configurations, to work around label conflicts.
|
||
|
||
* The name of applications can be customized in the admin with the
|
||
:attr:`~django.apps.AppConfig.verbose_name` of application configurations.
|
||
|
||
* Django imports all application configurations and models as soon as it
|
||
starts, through a deterministic and straightforward process. This should
|
||
make it easier to diagnose import issues such as import loops.
|
||
|
||
* The admin has an :class:`~django.contrib.admin.apps.AdminConfig` application
|
||
configuration class. When Django starts, this class takes care of calling
|
||
:func:`~django.contrib.admin.autodiscover()`. To use it, simply replace
|
||
``'django.contrib.admin'`` in :setting:`INSTALLED_APPS` with
|
||
``'django.contrib.admin.apps.AdminConfig'`` and remove
|
||
``admin.autodiscover()`` from your URLconf.
|
||
|
||
New method on Field subclasses
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
To help power both schema migrations and composite keys, the :class:`~django.db.models.Field` API now
|
||
has a new required method: ``deconstruct()``.
|
||
|
||
This method takes no arguments, and returns a tuple of four items:
|
||
|
||
* ``name``: The field's attribute name on its parent model, or None if it is not part of a model
|
||
* ``path``: A dotted, Python path to the class of this field, including the class name.
|
||
* ``args``: Positional arguments, as a list
|
||
* ``kwargs``: Keyword arguments, as a dict
|
||
|
||
These four values allow any field to be serialized into a file, as well as
|
||
allowing the field to be copied safely, both essential parts of these new features.
|
||
|
||
This change should not affect you unless you write custom Field subclasses;
|
||
if you do, you may need to reimplement the ``deconstruct()`` method if your
|
||
subclass changes the method signature of ``__init__`` in any way. If your
|
||
field just inherits from a built-in Django field and doesn't override ``__init__``,
|
||
no changes are necessary.
|
||
|
||
If you do need to override ``deconstruct()``, a good place to start is the
|
||
built-in Django fields (``django/db/models/fields/__init__.py``) as several
|
||
fields, including ``DecimalField`` and ``DateField``, override it and show how
|
||
to call the method on the superclass and simply add or remove extra arguments.
|
||
|
||
Calling custom ``QuerySet`` methods from the ``Manager``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
The :meth:`QuerySet.as_manager() <django.db.models.query.QuerySet.as_manager>`
|
||
class method has been added to :ref:`create Manager with QuerySet methods
|
||
<create-manager-with-queryset-methods>`.
|
||
|
||
Using a custom manager when traversing reverse relations
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
It is now possible to :ref:`specify a custom manager
|
||
<using-custom-reverse-manager>` when traversing a reverse relationship.
|
||
|
||
New system check framework
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
We've added a new :doc:`System check framework </ref/checks>` for
|
||
detecting common problems (like invalid models) and providing hints for
|
||
resolving those problems. The framework is extensible so you can add your
|
||
own checks for your own apps and libraries.
|
||
|
||
To perform system checks, you use the :djadmin:`check` management command.
|
||
This command replaces the older :djadmin:`validate` management command.
|
||
|
||
New ``Prefetch`` object for advanced ``prefetch_related`` operations.
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
The new :class:`~django.db.models.Prefetch` object allows customizing
|
||
prefetch operations.
|
||
|
||
You can specify the ``QuerySet`` used to traverse a given relation
|
||
or customize the storage location of prefetch results.
|
||
|
||
This enables things like filtering prefetched relations, calling
|
||
:meth:`~django.db.models.query.QuerySet.select_related()` from a prefetched
|
||
relation, or prefetching the same relation multiple times with different
|
||
querysets. See :meth:`~django.db.models.query.QuerySet.prefetch_related()`
|
||
for more details.
|
||
|
||
Admin shortcuts support time zones
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
The "today" and "now" shortcuts next to date and time input widgets in the
|
||
admin are now operating in the :ref:`current time zone
|
||
<default-current-time-zone>`. Previously, they used the browser time zone,
|
||
which could result in saving the wrong value when it didn't match the current
|
||
time zone on the server.
|
||
|
||
In addition, the widgets now display a help message when the browser and
|
||
server time zone are different, to clarify how the value inserted in the field
|
||
will be interpreted.
|
||
|
||
Using database cursors as context managers
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Prior to Python 2.7, database cursors could be used as a context manager. The
|
||
specific backend's cursor defined the behavior of the context manager. The
|
||
behavior of magic method lookups was changed with Python 2.7 and cursors were
|
||
no longer usable as context managers.
|
||
|
||
Django 1.7 allows a cursor to be used as a context manager that is a shortcut
|
||
for the following, instead of backend specific behavior.
|
||
|
||
.. code-block:: python
|
||
|
||
c = connection.cursor()
|
||
try:
|
||
c.execute(...)
|
||
finally:
|
||
c.close()
|
||
|
||
Custom lookups
|
||
~~~~~~~~~~~~~~
|
||
|
||
It is now possible to write custom lookups and transforms for the ORM.
|
||
Custom lookups work just like Django's inbuilt lookups (e.g. ``lte``,
|
||
``icontains``) while transforms are a new concept.
|
||
|
||
The :class:`django.db.models.Lookup` class provides a way to add lookup
|
||
operators for model fields. As an example it is possible to add ``day_lte``
|
||
operator for ``DateFields``.
|
||
|
||
The :class:`django.db.models.Transform` class allows transformations of
|
||
database values prior to the final lookup. For example it is possible to
|
||
write a ``year`` transform that extracts year from the field's value.
|
||
Transforms allow for chaining. After the ``year`` transform has been added
|
||
to ``DateField`` it is possible to filter on the transformed value, for
|
||
example ``qs.filter(author__birthdate__year__lte=1981)``.
|
||
|
||
For more information about both custom lookups and transforms refer to
|
||
:doc:`custom lookups </ref/models/custom-lookups>` documentation.
|
||
|
||
Minor features
|
||
~~~~~~~~~~~~~~
|
||
|
||
:mod:`django.contrib.admin`
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
* You can now implement :attr:`~django.contrib.admin.AdminSite.site_header`,
|
||
:attr:`~django.contrib.admin.AdminSite.site_title`, and
|
||
:attr:`~django.contrib.admin.AdminSite.index_title` attributes on a custom
|
||
:class:`~django.contrib.admin.AdminSite` in order to easily change the admin
|
||
site's page title and header text. No more needing to override templates!
|
||
|
||
* Buttons in :mod:`django.contrib.admin` now use the ``border-radius`` CSS
|
||
property for rounded corners rather than GIF background images.
|
||
|
||
* Some admin templates now have ``app-<app_name>`` and ``model-<model_name>``
|
||
classes in their ``<body>`` tag to allow customizing the CSS per app or per
|
||
model.
|
||
|
||
* The admin changelist cells now have a ``field-<field_name>`` class in the
|
||
HTML to enable style customizations.
|
||
|
||
* The admin's search fields can now be customized per-request thanks to the new
|
||
:meth:`django.contrib.admin.ModelAdmin.get_search_fields` method.
|
||
|
||
* The :meth:`ModelAdmin.get_fields()
|
||
<django.contrib.admin.ModelAdmin.get_fields>` method may be overridden to
|
||
customize the value of :attr:`ModelAdmin.fields
|
||
<django.contrib.admin.ModelAdmin.fields>`.
|
||
|
||
* In addition to the existing ``admin.site.register`` syntax, you can use the
|
||
new :func:`~django.contrib.admin.register` decorator to register a
|
||
:class:`~django.contrib.admin.ModelAdmin`.
|
||
|
||
* You may specify :meth:`ModelAdmin.list_display_links
|
||
<django.contrib.admin.ModelAdmin.list_display_links>` ``= None`` to disable
|
||
links on the change list page grid.
|
||
|
||
* You may now specify :attr:`ModelAdmin.view_on_site
|
||
<django.contrib.admin.ModelAdmin.view_on_site>` to control whether or not to
|
||
display the "View on site" link.
|
||
|
||
:mod:`django.contrib.auth`
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
* Any ``**kwargs`` passed to
|
||
:meth:`~django.contrib.auth.models.User.email_user()` are passed to the
|
||
underlying :meth:`~django.core.mail.send_mail()` call.
|
||
|
||
* The :func:`~django.contrib.auth.decorators.permission_required` decorator can
|
||
take a list of permissions as well as a single permission.
|
||
|
||
* You can override the new :meth:`AuthenticationForm.confirm_login_allowed()
|
||
<django.contrib.auth.forms.AuthenticationForm.confirm_login_allowed>` method
|
||
to more easily customize the login policy.
|
||
|
||
* :func:`django.contrib.auth.views.password_reset` takes an optional
|
||
``html_email_template_name`` parameter used to send a multipart HTML email
|
||
for password resets.
|
||
|
||
:mod:`django.contrib.gis`
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
* The default OpenLayers library version included in widgets has been updated
|
||
from 2.11 to 2.13.
|
||
|
||
* Prepared geometries now also support the ``crosses``, ``disjoint``,
|
||
``overlaps``, ``touches`` and ``within`` predicates, if GEOS 3.3 or later is
|
||
installed.
|
||
|
||
:mod:`django.contrib.messages`
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
* The backends for :mod:`django.contrib.messages` that use cookies, will now
|
||
follow the :setting:`SESSION_COOKIE_SECURE` and
|
||
:setting:`SESSION_COOKIE_HTTPONLY` settings.
|
||
|
||
* The :ref:`messages context processor <message-displaying>` now adds a
|
||
dictionary of default levels under the name ``DEFAULT_MESSAGE_LEVELS``.
|
||
|
||
* :class:`~django.contrib.messages.storage.base.Message` objects now have a
|
||
``level_tag`` attribute that contains the string representation of the
|
||
message level.
|
||
|
||
:mod:`django.contrib.redirects`
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
* :class:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware`
|
||
has two new attributes
|
||
(:attr:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware.response_gone_class`
|
||
and
|
||
:attr:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware.response_redirect_class`)
|
||
that specify the types of :class:`~django.http.HttpResponse` instances the
|
||
middleware returns.
|
||
|
||
:mod:`django.contrib.sessions`
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
* The ``"django.contrib.sessions.backends.cached_db"`` session backend now
|
||
respects :setting:`SESSION_CACHE_ALIAS`. In previous versions, it always used
|
||
the `default` cache.
|
||
|
||
:mod:`django.contrib.sitemaps`
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
* The :mod:`sitemap framework<django.contrib.sitemaps>` now makes use of
|
||
:attr:`~django.contrib.sitemaps.Sitemap.lastmod` to set a ``Last-Modified``
|
||
header in the response. This makes it possible for the
|
||
:class:`~django.middleware.http.ConditionalGetMiddleware` to handle
|
||
conditional ``GET`` requests for sitemaps which set ``lastmod``.
|
||
|
||
:mod:`django.contrib.staticfiles`
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
* The :ref:`static files storage classes <staticfiles-storages>` may be
|
||
subclassed to override the permissions that collected static files and
|
||
directories receive by setting the
|
||
:attr:`~django.core.files.storage.FileSystemStorage.file_permissions_mode`
|
||
and :attr:`~django.core.files.storage.FileSystemStorage.directory_permissions_mode`
|
||
parameters. See :djadmin:`collectstatic` for example usage.
|
||
|
||
* The :class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage`
|
||
backend gets a sibling class called
|
||
:class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage`
|
||
that doesn't use the cache system at all but instead a JSON file called
|
||
``staticfiles.json`` for storing the mapping between the original file name
|
||
(e.g. ``css/styles.css``) and the hashed file name (e.g.
|
||
``css/styles.55e7cbb9ba48.css``. The ``staticfiles.json`` file is created
|
||
when running the :djadmin:`collectstatic` management command and should
|
||
be a less expensive alternative for remote storages such as Amazon S3.
|
||
|
||
See the :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage`
|
||
docs for more information.
|
||
|
||
:mod:`django.contrib.syndication`
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
* The :class:`~django.utils.feedgenerator.Atom1Feed` syndication feed's
|
||
``updated`` element now utilizes ``updateddate`` instead of ``pubdate``,
|
||
allowing the ``published`` element to be included in the feed (which
|
||
relies on ``pubdate``).
|
||
|
||
Cache
|
||
^^^^^
|
||
|
||
* Access to caches configured in :setting:`CACHES` is now available via
|
||
:data:`django.core.cache.caches`. This dict-like object provides a different
|
||
instance per thread. It supersedes :func:`django.core.cache.get_cache` which
|
||
is now deprecated.
|
||
|
||
* If you instanciate cache backends directly, be aware that they aren't
|
||
thread-safe any more, as :data:`django.core.cache.caches` now yields
|
||
different instances per thread.
|
||
|
||
Email
|
||
^^^^^
|
||
|
||
* :func:`~django.core.mail.send_mail` now accepts an ``html_message``
|
||
parameter for sending a multipart ``text/plain`` and ``text/html`` email.
|
||
* The SMTP :class:`~django.core.mail.backends.smtp.EmailBackend` now accepts a
|
||
:attr:`~django.core.mail.backends.smtp.EmailBackend.timeout` parameter.
|
||
|
||
File Uploads
|
||
^^^^^^^^^^^^
|
||
|
||
* The new :attr:`UploadedFile.content_type_extra
|
||
<django.core.files.uploadedfile.UploadedFile.content_type_extra>` attribute
|
||
contains extra parameters passed to the ``content-type`` header on a file
|
||
upload.
|
||
|
||
* The new :setting:`FILE_UPLOAD_DIRECTORY_PERMISSIONS` setting controls
|
||
the file system permissions of directories created during file upload, like
|
||
:setting:`FILE_UPLOAD_PERMISSIONS` does for the files themselves.
|
||
|
||
* The :attr:`FileField.upload_to <django.db.models.FileField.upload_to>`
|
||
attribute is now optional. If it is omitted or given ``None`` or an empty
|
||
string, a subdirectory won't be used for storing the uploaded files.
|
||
|
||
Forms
|
||
^^^^^
|
||
|
||
* The ``<label>`` and ``<input>`` tags rendered by
|
||
:class:`~django.forms.RadioSelect` and
|
||
:class:`~django.forms.CheckboxSelectMultiple` when looping over the radio
|
||
buttons or checkboxes now include ``for`` and ``id`` attributes, respectively.
|
||
Each radio button or checkbox includes an ``id_for_label`` attribute to
|
||
output the element's ID.
|
||
|
||
* :attr:`Field.choices<django.db.models.Field.choices>` now allows you to
|
||
customize the "empty choice" label by including a tuple with an empty string
|
||
or ``None`` for the key and the custom label as the value. The default blank
|
||
option ``"----------"`` will be omitted in this case.
|
||
|
||
* :class:`~django.forms.MultiValueField` allows optional subfields by setting
|
||
the ``require_all_fields`` argument to ``False``. The ``required`` attribute
|
||
for each individual field will be respected, and a new ``incomplete``
|
||
validation error will be raised when any required fields are empty.
|
||
|
||
* The :meth:`~django.forms.Form.clean` method on a form no longer needs to
|
||
return ``self.cleaned_data``. If it does return a changed dictionary then
|
||
that will still be used.
|
||
|
||
* After a temporary regression in Django 1.6, it's now possible again to make
|
||
:class:`~django.forms.TypedChoiceField` ``coerce`` method return an arbitrary
|
||
value.
|
||
|
||
* :attr:`SelectDateWidget.months
|
||
<django.forms.extras.widgets.SelectDateWidget.months>` can be used to
|
||
customize the wording of the months displayed in the select widget.
|
||
|
||
* The ``min_num`` and ``validate_min`` parameters were added to
|
||
:func:`~django.forms.formsets.formset_factory` to allow validating
|
||
a minimum number of submitted forms.
|
||
|
||
* The metaclasses used by ``Form`` and ``ModelForm`` have been reworked to
|
||
support more inheritance scenarios. The previous limitation that prevented
|
||
inheriting from both ``Form`` and ``ModelForm`` simultaneously have been
|
||
removed as long as ``ModelForm`` appears first in the MRO.
|
||
|
||
* It's now possible to opt-out from a ``Form`` field declared in a parent class
|
||
by shadowing it with a non-``Field`` value.
|
||
|
||
* The new :meth:`~django.forms.Form.add_error()` method allows adding errors
|
||
to specific form fields.
|
||
|
||
* The dict-like attribute :attr:`~django.forms.Form.errors` now has two new
|
||
methods :meth:`~django.forms.Form.errors.as_data()` and
|
||
:meth:`~django.forms.Form.errors.as_json()`. The former returns a ``dict``
|
||
that maps fields to their original errors, complete with all metadata
|
||
(error code and params), the latter returns the errors serialized as json.
|
||
|
||
Internationalization
|
||
^^^^^^^^^^^^^^^^^^^^
|
||
|
||
* The :attr:`django.middleware.locale.LocaleMiddleware.response_redirect_class`
|
||
attribute allows you to customize the redirects issued by the middleware.
|
||
|
||
* The :class:`~django.middleware.locale.LocaleMiddleware` now stores the user's
|
||
selected language with the session key ``_language``. Previously it was
|
||
stored with the key ``django_language``, but keys reserved for Django should
|
||
start with an underscore. For backwards compatibility ``django_language`` is
|
||
still read from in 1.7. Sessions will be migrated to the new ``_language``
|
||
key as they are written.
|
||
|
||
* The :ttag:`blocktrans` now supports a ``trimmed`` option. This
|
||
option will remove newline characters from the beginning and the end of the
|
||
content of the ``{% blocktrans %}`` tag, replace any whitespace at the
|
||
beginning and end of a line and merge all lines into one using a space
|
||
character to separate them. This is quite useful for indenting the content of
|
||
a ``{% blocktrans %}`` tag without having the indentation characters end up
|
||
in the corresponding entry in the PO file, which makes the translation
|
||
process easier.
|
||
|
||
* When you run :djadmin:`makemessages` from the root directory of your project,
|
||
any extracted strings will now be automatically distributed to the proper
|
||
app or project message file. See :ref:`how-to-create-language-files` for
|
||
details.
|
||
|
||
Management Commands
|
||
^^^^^^^^^^^^^^^^^^^
|
||
|
||
* The :djadminopt:`--no-color` option for ``django-admin.py`` allows you to
|
||
disable the colorization of management command output.
|
||
|
||
* The new :djadminopt:`--natural-foreign` and :djadminopt:`--natural-primary`
|
||
options for :djadmin:`dumpdata`, and the new ``use_natural_foreign_keys`` and
|
||
``use_natural_primary_keys`` arguments for ``serializers.serialize()``, allow
|
||
the use of natural primary keys when serializing.
|
||
|
||
* It is no longer necessary to provide the cache table name or the
|
||
:djadminopt:`--database` option for the :djadmin:`createcachetable` command.
|
||
Django takes this information from your settings file. If you have configured
|
||
multiple caches or multiple databases, all cache tables are created.
|
||
|
||
* The :djadmin:`runserver` command received several improvements:
|
||
|
||
* On Linux systems, if pyinotify_ is installed, the development server will
|
||
reload immediately when a file is changed. Previously, it polled the
|
||
filesystem for changes every second. That caused a small delay before
|
||
reloads and reduced battery life on laptops.
|
||
|
||
.. _pyinotify: https://pypi.python.org/pypi/pyinotify
|
||
|
||
* In addition, the development server automatically reloads when a
|
||
translation file is updated, i.e. after running
|
||
:djadmin:`compilemessages`.
|
||
|
||
* All HTTP requests are logged to the console, including requests for static
|
||
files or ``favicon.ico`` that used to be filtered out.
|
||
|
||
* Management commands can now produce syntax colored output under Windows if
|
||
the ANSICON third-party tool is installed and active.
|
||
|
||
Models
|
||
^^^^^^
|
||
|
||
* The :meth:`QuerySet.update_or_create()
|
||
<django.db.models.query.QuerySet.update_or_create>` method was added.
|
||
|
||
* The new :attr:`~django.db.models.Options.default_permissions` model
|
||
``Meta`` option allows you to customize (or disable) creation of the default
|
||
add, change, and delete permissions.
|
||
|
||
* Explicit :class:`~django.db.models.OneToOneField` for
|
||
:ref:`multi-table-inheritance` are now discovered in abstract classes.
|
||
|
||
* Is it now possible to avoid creating a backward relation for
|
||
:class:`~django.db.models.OneToOneField` by setting its
|
||
:attr:`~django.db.models.ForeignKey.related_name` to
|
||
``'+'`` or ending it with ``'+'``.
|
||
|
||
* :class:`F expressions <django.db.models.F>` support the power operator
|
||
(``**``).
|
||
|
||
* The ``remove()`` and ``clear()`` methods of the related managers created by
|
||
``ForeignKey`` and ``GenericForeignKey`` now accept the ``bulk`` keyword
|
||
argument to control whether or not to perform operations in bulk
|
||
(i.e. using ``QuerySet.update()``). Defaults to ``True``.
|
||
|
||
* It is now possible to use ``None`` as a query value for the :lookup:`iexact`
|
||
lookup.
|
||
|
||
Signals
|
||
^^^^^^^
|
||
|
||
* The ``enter`` argument was added to the
|
||
:data:`~django.test.signals.setting_changed` signal.
|
||
|
||
* The model signals can be now be connected to using a ``str`` of the
|
||
``'app_label.ModelName'`` form – just like related fields – to lazily
|
||
reference their senders.
|
||
|
||
Templates
|
||
^^^^^^^^^
|
||
|
||
* The :meth:`Context.push() <django.template.Context.push>` method now returns
|
||
a context manager which automatically calls :meth:`pop()
|
||
<django.template.Context.pop>` upon exiting the ``with`` statement.
|
||
Additionally, :meth:`push() <django.template.Context.push>` now accepts
|
||
parameters that are passed to the ``dict`` constructor used to build the new
|
||
context level.
|
||
|
||
* The :ttag:`widthratio` template tag now accepts an "as" parameter to capture
|
||
the result in a variable.
|
||
|
||
* The :ttag:`include` template tag will now also accept anything with a
|
||
``render()`` method (such as a ``Template``) as an argument. String
|
||
arguments will be looked up using
|
||
:func:`~django.template.loader.get_template` as always.
|
||
|
||
* It is now possible to :ttag:`include` templates recursively.
|
||
|
||
* Template objects now have an origin attribute set when
|
||
:setting:`TEMPLATE_DEBUG` is ``True``. This allows template origins to be
|
||
inspected and logged outside of the ``django.template`` infrastructure.
|
||
|
||
* ``TypeError`` exceptions are no longer silenced when raised during the
|
||
rendering of a template.
|
||
|
||
* The following functions now accept a ``dirs`` parameter which is a list or
|
||
tuple to override :setting:`TEMPLATE_DIRS`:
|
||
|
||
* :func:`django.template.loader.get_template()`
|
||
* :func:`django.template.loader.select_template()`
|
||
* :func:`django.shortcuts.render()`
|
||
* :func:`django.shortcuts.render_to_response()`
|
||
|
||
* The :tfilter:`time` filter now accepts timzone-related :ref:`format
|
||
specifiers <date-and-time-formatting-specifiers>` ``'e'``, ``'O'`` , ``'T'``
|
||
and ``'Z'`` and is able to digest :ref:`time-zone-aware
|
||
<naive_vs_aware_datetimes>` ``datetime`` instances performing the expected
|
||
rendering.
|
||
|
||
* The :ttag:`cache` tag will now try to use the cache called
|
||
"template_fragments" if it exists and fall back to using the default cache
|
||
otherwise. It also now accepts an optional ``using`` keyword argument to
|
||
control which cache it uses.
|
||
|
||
Requests
|
||
^^^^^^^^
|
||
|
||
* The new :attr:`HttpRequest.scheme <django.http.HttpRequest.scheme>` attribute
|
||
specifies the scheme of the request (``http`` or ``https`` normally).
|
||
|
||
Tests
|
||
^^^^^
|
||
|
||
* :class:`~django.test.runner.DiscoverRunner` has two new attributes,
|
||
:attr:`~django.test.runner.DiscoverRunner.test_suite` and
|
||
:attr:`~django.test.runner.DiscoverRunner.test_runner`, which facilitate
|
||
overriding the way tests are collected and run.
|
||
|
||
* The ``fetch_redirect_response`` argument was added to
|
||
:meth:`~django.test.SimpleTestCase.assertRedirects`. Since the test
|
||
client can't fetch externals URLs, this allows you to use ``assertRedirects``
|
||
with redirects that aren't part of your Django app.
|
||
|
||
* Correct handling of scheme when making comparisons in
|
||
:meth:`~django.test.SimpleTestCase.assertRedirects`.
|
||
|
||
* The ``secure`` argument was added to all the request methods of
|
||
:class:`~django.test.Client`. If ``True``, the request will be made
|
||
through HTTPS.
|
||
|
||
* Requests made with :meth:`Client.login() <django.test.Client.login>` and
|
||
:meth:`Client.logout() <django.test.Client.logout>` respect defaults defined
|
||
in :class:`~django.test.Client` instantiation and are processed through
|
||
middleware.
|
||
|
||
* :meth:`~django.test.TransactionTestCase.assertNumQueries` now prints
|
||
out the list of executed queries if the assertion fails.
|
||
|
||
* The ``WSGIRequest`` instance generated by the test handler is now attached to
|
||
the :attr:`django.test.Response.wsgi_request` attribute.
|
||
|
||
Validators
|
||
^^^^^^^^^^
|
||
|
||
* :class:`~django.core.validators.URLValidator` now accepts an optional
|
||
``schemes`` argument which allows customization of the accepted URI schemes
|
||
(instead of the defaults ``http(s)`` and ``ftp(s)``).
|
||
|
||
Backwards incompatible changes in 1.7
|
||
=====================================
|
||
|
||
.. warning::
|
||
|
||
In addition to the changes outlined in this section, be sure to review the
|
||
:doc:`deprecation plan </internals/deprecation>` for any features that
|
||
have been removed. If you haven't updated your code within the
|
||
deprecation timeline for a given feature, its removal may appear as a
|
||
backwards incompatible change.
|
||
|
||
allow_syncdb/allow_migrate
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
While Django will still look at ``allow_syncdb`` methods even though they
|
||
should be renamed to ``allow_migrate``, there is a subtle difference in which
|
||
models get passed to these methods.
|
||
|
||
For apps with migrations, ``allow_migrate`` will now get passed
|
||
:ref:`historical models <historical-models>`, which are special versioned models
|
||
without custom attributes, methods or managers. Make sure your ``allow_migrate``
|
||
methods are only referring to fields or other items in ``model._meta``.
|
||
|
||
App-loading changes
|
||
~~~~~~~~~~~~~~~~~~~
|
||
|
||
Start-up sequence
|
||
^^^^^^^^^^^^^^^^^
|
||
|
||
Django 1.7 loads application configurations and models as soon as it starts.
|
||
While this behavior is more straightforward and is believed to be more robust,
|
||
regressions cannot be ruled out. You may encounter the following exceptions:
|
||
|
||
* ``RuntimeError: App registry isn't ready yet.`` This happens when importing
|
||
an application configuration or a models module triggers code that depends
|
||
on the app registry.
|
||
|
||
For example, :func:`~django.utils.translation.ugettext()` uses the app
|
||
registry to look up translation catalogs in applications. To translate at
|
||
import time, you need :func:`~django.utils.translation.ugettext_lazy()`
|
||
instead. (Using :func:`~django.utils.translation.ugettext()` would be a bug,
|
||
because the translation would happen at import time, rather than at each
|
||
request depending on the active language.)
|
||
|
||
Executing database queries with the ORM at import time in models modules
|
||
will also trigger this exception. The ORM cannot function properly until all
|
||
models are available.
|
||
|
||
* ``ImportError: cannot import name ...`` This happens if the import sequence
|
||
ends up in a loop.
|
||
|
||
To eliminate such problems, you should minimize dependencies between your
|
||
models modules and do as little work as possible at import time. To avoid
|
||
executing code at import time, you can move it into a function and cache its
|
||
results. The code will be executed when you first need its results. This
|
||
concept is known as "lazy evaluation".
|
||
|
||
Standalone scripts
|
||
^^^^^^^^^^^^^^^^^^
|
||
|
||
If you're using Django in a plain Python script — rather than a management
|
||
command — and you rely on the :envvar:`DJANGO_SETTINGS_MODULE` environment
|
||
variable, you must now explicitly initialize Django at the beginning of your
|
||
script with::
|
||
|
||
>>> import django
|
||
>>> django.setup()
|
||
|
||
Otherwise, you will hit ``RuntimeError: App registry isn't ready yet.``
|
||
|
||
App registry consistency
|
||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
It is no longer possible to have multiple installed applications with the same
|
||
label. In previous versions of Django, this didn't always work correctly, but
|
||
didn't crash outright either.
|
||
|
||
If you have two apps with the same label, you should create an
|
||
:class:`~django.apps.AppConfig` for one of them and override its
|
||
:class:`~django.apps.AppConfig.label` there. You should then adjust your code
|
||
wherever it references this application or its models with the old label.
|
||
|
||
It isn't possible to import the same model twice through different paths any
|
||
more. As of Django 1.6, this may happen only if you're manually putting a
|
||
directory and a subdirectory on :envvar:`PYTHONPATH`. Refer to the section on
|
||
the new project layout in the :doc:`1.4 release notes </releases/1.4>` for
|
||
migration instructions.
|
||
|
||
You should make sure that:
|
||
|
||
* All models are defined in applications that are listed in
|
||
:setting:`INSTALLED_APPS` or have an explicit
|
||
:attr:`~django.db.models.Options.app_label`.
|
||
|
||
* Models aren't imported as a side-effect of loading their application.
|
||
Specifically, you shouldn't import models in the root module of an
|
||
application nor in the module that define its configuration class.
|
||
|
||
Django will enforce these requirements as of version 1.9, after a deprecation
|
||
period.
|
||
|
||
Subclassing AppCommand
|
||
^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Subclasses of :class:`~django.core.management.AppCommand` must now implement a
|
||
:meth:`~django.core.management.AppCommand.handle_app_config` method instead of
|
||
``handle_app()``. This method receives an :class:`~django.apps.AppConfig`
|
||
instance instead of a models module.
|
||
|
||
Introspecting applications
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Since :setting:`INSTALLED_APPS` now supports application configuration classes
|
||
in addition to application modules, you should review code that accesses this
|
||
setting directly and use the app registry (:attr:`django.apps.apps`) instead.
|
||
|
||
The app registry has preserved some features of the old app cache. Even though
|
||
the app cache was a private API, obsolete methods and arguments will be
|
||
removed through a standard deprecation path, with the exception of the
|
||
following changes that take effect immediately:
|
||
|
||
* ``get_model`` raises :exc:`~exceptions.LookupError` instead of returning
|
||
``None`` when no model is found.
|
||
|
||
* The ``only_installed`` argument of ``get_model`` and ``get_models`` no
|
||
longer exists, nor does the ``seed_cache`` argument of ``get_model``.
|
||
|
||
Management commands and order of :setting:`INSTALLED_APPS`
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
When several applications provide management commands with the same name,
|
||
Django loads the command from the application that comes first in
|
||
:setting:`INSTALLED_APPS`. Previous versions loaded the command from the
|
||
application that came last.
|
||
|
||
This brings discovery of management commands in line with other parts of
|
||
Django that rely on the order of :setting:`INSTALLED_APPS`, such as static
|
||
files, templates, and translations.
|
||
|
||
Behavior of ``LocMemCache`` regarding pickle errors
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
An inconsistency existed in previous versions of Django regarding how pickle
|
||
errors are handled by different cache backends.
|
||
``django.core.cache.backends.locmem.LocMemCache`` used to fail silently when
|
||
such an error occurs, which is inconsistent with other backends and leads to
|
||
cache-specific errors. This has been fixed in Django 1.7, see
|
||
`Ticket #21200`_ for more details.
|
||
|
||
.. _Ticket #21200: https://code.djangoproject.com/ticket/21200
|
||
|
||
Cache keys are now generated from the request's absolute URL
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Previous versions of Django generated cache keys using a request's path and
|
||
query string but not the scheme or host. If a Django application was serving
|
||
multiple subdomains or domains, cache keys could collide. In Django 1.7, cache
|
||
keys vary by the absolute URL of the request including scheme, host, path, and
|
||
query string. For example, the URL portion of a cache key is now generated from
|
||
``http://www.example.com/path/to/?key=val`` rather than ``/path/to/?key=val``.
|
||
The cache keys generated by Django 1.7 will be different from the keys
|
||
generated by older versions of Django. After upgrading to Django 1.7, the first
|
||
request to any previously cached URL will be a cache miss .
|
||
|
||
Passing ``None`` to ``Manager.db_manager()``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
In previous versions of Django, it was possible to use
|
||
``db_manager(using=None)`` on a model manager instance to obtain a manager
|
||
instance using default routing behavior, overriding any manually specified
|
||
database routing. In Django 1.7, a value of ``None`` passed to db_manager will
|
||
produce a router that *retains* any manually assigned database routing -- the
|
||
manager will *not* be reset. This was necessary to resolve an inconsistency in
|
||
the way routing information cascaded over joins. See `Ticket #13724`_ for more
|
||
details.
|
||
|
||
.. _Ticket #13724: https://code.djangoproject.com/ticket/13724
|
||
|
||
pytz may be required
|
||
~~~~~~~~~~~~~~~~~~~~
|
||
|
||
If your project handles datetimes before 1970 or after 2037 and Django raises
|
||
a :exc:`~exceptions.ValueError` when encountering them, you will have to
|
||
install pytz_. You may be affected by this problem if you use Django's time
|
||
zone-related date formats or :mod:`django.contrib.syndication`.
|
||
|
||
``remove()`` and ``clear()`` methods of related managers
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
The ``remove()`` and ``clear()`` methods of the related managers created by
|
||
``ForeignKey``, ``GenericForeignKey``, and ``ManyToManyField`` suffered from a
|
||
number of issues. Some operations ran multiple data modifying queries without
|
||
wrapping them in a transaction, and some operations didn't respect default
|
||
filtering when it was present (i.e. when the default manager on the related
|
||
model implemented a custom ``get_queryset()``).
|
||
|
||
Fixing the issues introduced some backward incompatible changes:
|
||
|
||
- The default implementation of ``remove()`` for ``ForeignKey`` related managers
|
||
changed from a series of ``Model.save()`` calls to a single
|
||
``QuerySet.update()`` call. The change means that ``pre_save`` and
|
||
``post_save`` signals aren't sent anymore. You can use the ``bulk=False``
|
||
keyword argument to revert to the previous behavior.
|
||
|
||
- The ``remove()`` and ``clear()`` methods for ``GenericForeignKey`` related
|
||
managers now perform bulk delete. The ``Model.delete()`` method isn't called
|
||
on each instance anymore. You can use the ``bulk=False`` keyword argument to
|
||
revert to the previous behavior.
|
||
|
||
- The ``remove()`` and ``clear()`` methods for ``ManyToManyField`` related
|
||
managers perform nested queries when filtering is involved, which may or
|
||
may not be an issue depending on your database and your data itself.
|
||
See :ref:`this note <nested-queries-performance>` for more details.
|
||
|
||
.. _pytz: https://pypi.python.org/pypi/pytz/
|
||
|
||
Miscellaneous
|
||
~~~~~~~~~~~~~
|
||
|
||
* The :meth:`django.core.files.uploadhandler.FileUploadHandler.new_file()`
|
||
method is now passed an additional ``content_type_extra`` parameter. If you
|
||
have a custom :class:`~django.core.files.uploadhandler.FileUploadHandler`
|
||
that implements ``new_file()``, be sure it accepts this new parameter.
|
||
|
||
* :class:`ModelFormSet<django.forms.models.BaseModelFormSet>`’s no longer
|
||
delete instances when ``save(commit=False)`` is called. See
|
||
:attr:`~django.forms.formsets.BaseFormSet.can_delete` for instructions on how
|
||
to manually delete objects from deleted forms.
|
||
|
||
* Loading empty fixtures emits a ``RuntimeWarning`` rather than raising
|
||
:class:`~django.core.management.CommandError`.
|
||
|
||
* :func:`django.contrib.staticfiles.views.serve` will now raise an
|
||
:exc:`~django.http.Http404` exception instead of
|
||
:exc:`~django.core.exceptions.ImproperlyConfigured` when :setting:`DEBUG`
|
||
is ``False``. This change removes the need to conditionally add the view to
|
||
your root URLconf, which in turn makes it safe to reverse by name. It also
|
||
removes the ability for visitors to generate spurious HTTP 500 errors by
|
||
requesting static files that don't exist or haven't been collected yet.
|
||
|
||
* The :meth:`django.db.models.Model.__eq__` method is now defined in a
|
||
way where instances of a proxy model and its base model are considered
|
||
equal when primary keys match. Previously only instances of exact same
|
||
class were considered equal on primary key match.
|
||
|
||
* The :meth:`django.db.models.Model.__eq__` method has changed such that
|
||
two ``Model`` instances without primary key values won't be considered
|
||
equal (unless they are the same instance).
|
||
|
||
* The :meth:`django.db.models.Model.__hash__` will now raise ``TypeError``
|
||
when called on an instance without a primary key value. This is done to
|
||
avoid mutable ``__hash__`` values in containers.
|
||
|
||
* :class:`~django.db.models.AutoField` columns in SQLite databases will now be
|
||
created using the ``AUTOINCREMENT`` option, which guarantees monotonic
|
||
increments. This will cause primary key numbering behavior to change on
|
||
SQLite, becoming consistent with most other SQL databases. This will only
|
||
apply to newly created tables. If you have a database created with an older
|
||
version of Django, you will need to migrate it to take advantage of this
|
||
feature. For example, you could do the following:
|
||
|
||
#) Use :djadmin:`dumpdata` to save your data.
|
||
#) Rename the existing database file (keep it as a backup).
|
||
#) Run :djadmin:`migrate` to create the updated schema.
|
||
#) Use :djadmin:`loaddata` to import the fixtures you exported in (1).
|
||
|
||
* ``django.contrib.auth.models.AbstractUser`` no longer defines a
|
||
:meth:`~django.db.models.Model.get_absolute_url()` method. The old definition
|
||
returned ``"/users/%s/" % urlquote(self.username)`` which was arbitrary
|
||
since applications may or may not define such a url in ``urlpatterns``.
|
||
Define a ``get_absolute_url()`` method on your own custom user object or use
|
||
:setting:`ABSOLUTE_URL_OVERRIDES` if you want a URL for your user.
|
||
|
||
* The static asset-serving functionality of the
|
||
:class:`django.test.LiveServerTestCase` class has been simplified: Now it's
|
||
only able to serve content already present in :setting:`STATIC_ROOT` when
|
||
tests are run. The ability to transparently serve all the static assets
|
||
(similarly to what one gets with :setting:`DEBUG = True <DEBUG>` at
|
||
development-time) has been moved to a new class that lives in the
|
||
``staticfiles`` application (the one actually in charge of such feature):
|
||
:class:`django.contrib.staticfiles.testing.StaticLiveServerCase`. In other
|
||
words, ``LiveServerTestCase`` itself is less powerful but at the same time
|
||
has less magic.
|
||
|
||
Rationale behind this is removal of dependency of non-contrib code on
|
||
contrib applications.
|
||
|
||
* The old cache URI syntax (e.g. ``"locmem://"``) is no longer supported. It
|
||
still worked, even though it was not documented or officially supported. If
|
||
you're still using it, please update to the current :setting:`CACHES` syntax.
|
||
|
||
* The default ordering of ``Form`` fields in case of inheritance has changed to
|
||
follow normal Python MRO. Fields are now discovered by iterating through the
|
||
MRO in reverse with the topmost class coming last. This only affects you if
|
||
you relied on the default field ordering while having fields defined on both
|
||
the current class *and* on a parent ``Form``.
|
||
|
||
* The ``required`` argument of
|
||
:class:`~django.forms.extras.widgets.SelectDateWidget` has been removed.
|
||
This widget now respects the form field's ``is_required`` attribute like
|
||
other widgets.
|
||
|
||
* :meth:`~django.db.models.query.QuerySet.select_related` now chains in the
|
||
same way as other similar calls like ``prefetch_related``. That is,
|
||
``select_related('foo', 'bar')`` is equivalent to
|
||
``select_related('foo').select_related('bar')``. Previously the latter would
|
||
have been equivalent to ``select_related('bar')``.
|
||
|
||
* GeoDjango dropped support for GEOS < 3.1.
|
||
|
||
* The ``init_connection_state`` method of database backends now executes in
|
||
autocommit mode (unless you set :setting:`AUTOCOMMIT <DATABASE-AUTOCOMMIT>`
|
||
to ``False``). If you maintain a custom database backend, you should check
|
||
that method.
|
||
|
||
Features deprecated in 1.7
|
||
==========================
|
||
|
||
``django.core.cache.get_cache``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
:func:`django.core.cache.get_cache` has been supplanted by
|
||
:data:`django.core.cache.caches`.
|
||
|
||
``django.utils.dictconfig``/``django.utils.importlib``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
``django.utils.dictconfig`` and ``django.utils.importlib`` were copies of
|
||
respectively :mod:`logging.config` and :mod:`importlib` provided for Python
|
||
versions prior to 2.7. They have been deprecated.
|
||
|
||
``django.utils.tzinfo``
|
||
~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
``django.utils.tzinfo`` provided two :class:`~datetime.tzinfo` subclasses,
|
||
``LocalTimezone`` and ``FixedOffset``. They've been deprecated in favor of
|
||
more correct alternatives provided by :mod:`django.utils.timezone`,
|
||
:func:`django.utils.timezone.get_default_timezone` and
|
||
:func:`django.utils.timezone.get_fixed_timezone`.
|
||
|
||
``django.utils.unittest``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
``django.utils.unittest`` provided uniform access to the ``unittest2`` library
|
||
on all Python versions. Since ``unittest2`` became the standard library's
|
||
:mod:`unittest` module in Python 2.7, and Django 1.7 drops support for older
|
||
Python versions, this module isn't useful anymore. It has been deprecated. Use
|
||
:mod:`unittest` instead.
|
||
|
||
``django.utils.datastructures.SortedDict``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
As :class:`~collections.OrderedDict` was added to the standard library in
|
||
Python 2.7, :class:`~django.utils.datastructures.SortedDict` is no longer
|
||
needed and has been deprecated.
|
||
|
||
Custom SQL location for models package
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Previously, if models were organized in a package (``myapp/models/``) rather
|
||
than simply ``myapp/models.py``, Django would look for :ref:`initial SQL data
|
||
<initial-sql>` in ``myapp/models/sql/``. This bug has been fixed so that Django
|
||
will search ``myapp/sql/`` as documented. The old location will continue to
|
||
work until Django 1.9.
|
||
|
||
``declared_fieldsets`` attribute on ``ModelAdmin``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
``ModelAdmin.declared_fieldsets`` has been deprecated. Despite being a private
|
||
API, it will go through a regular deprecation path. This attribute was mostly
|
||
used by methods that bypassed ``ModelAdmin.get_fieldsets()`` but this was
|
||
considered a bug and has been addressed.
|
||
|
||
``syncdb``
|
||
~~~~~~~~~~
|
||
|
||
The :djadmin:`syncdb` command has been deprecated in favor of the new :djadmin:`migrate`
|
||
command. ``migrate`` takes the same arguments as ``syncdb`` used to plus a few
|
||
more, so it's safe to just change the name you're calling and nothing else.
|
||
|
||
``util`` modules renamed to ``utils``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
The following instances of ``util.py`` in the Django codebase have been renamed
|
||
to ``utils.py`` in an effort to unify all util and utils references:
|
||
|
||
* ``django.contrib.admin.util``
|
||
* ``django.contrib.gis.db.backends.util``
|
||
* ``django.db.backends.util``
|
||
* ``django.forms.util``
|
||
|
||
``get_formsets`` method on ``ModelAdmin``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
``ModelAdmin.get_formsets`` has been deprecated in favor of the new
|
||
:meth:`~django.contrib.admin.ModelAdmin.get_formsets_with_inlines`, in order to
|
||
better handle the case of selecting showing inlines on a ``ModelAdmin``.
|
||
|
||
``IPAddressField``
|
||
~~~~~~~~~~~~~~~~~~
|
||
|
||
The :class:`django.db.models.IPAddressField` and
|
||
:class:`django.forms.IPAddressField` fields have been deprecated in favor of
|
||
:class:`django.db.models.GenericIPAddressField` and
|
||
:class:`django.forms.GenericIPAddressField`.
|
||
|
||
``BaseMemcachedCache._get_memcache_timeout`` method
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
The ``BaseMemcachedCache._get_memcache_timeout()`` method has been renamed to
|
||
``get_backend_timeout()``. Despite being a private API, it will go through the
|
||
normal deprecation.
|
||
|
||
Natural key serialization options
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
The ``--natural`` and ``-n`` options for :djadmin:`dumpdata` have been
|
||
deprecated. Use :djadminopt:`--natural-foreign` instead.
|
||
|
||
Similarly, the ``use_natural_keys`` argument for ``serializers.serialize()``
|
||
has been deprecated. Use ``use_natural_foreign_keys`` instead.
|
||
|
||
Merging of ``POST`` and ``GET`` arguments into ``WSGIRequest.REQUEST``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
It was already strongly suggested that you use ``GET`` and ``POST`` instead of
|
||
``REQUEST``, because the former are more explicit. The property ``REQUEST`` is
|
||
deprecated and will be removed in Django 1.9.
|
||
|
||
``django.utils.datastructures.MergeDict`` class
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
``MergeDict`` exists primarily to support merging ``POST`` and ``GET``
|
||
arguments into a ``REQUEST`` property on ``WSGIRequest``. To merge
|
||
dictionaries, use ``dict.update()`` instead. The class ``MergeDict`` is
|
||
deprecated and will be removed in Django 1.9.
|
||
|
||
Language codes ``zh-cn``, ``zh-tw`` and ``fy-nl``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
The currently used language codes for Simplified Chinese ``zh-cn``,
|
||
Traditional Chinese ``zh-tw`` and (Western) Frysian ``fy-nl`` are deprecated
|
||
and should be replaced by the language codes ``zh-hans``, ``zh-hant`` and
|
||
``fy`` respectively. If you use these language codes, you should rename the
|
||
locale directories and update your settings to reflect these changes. The
|
||
deprecated language codes will be removed in Django 1.9.
|
||
|
||
``django.utils.functional.memoize`` function
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
The function ``memoize`` is deprecated and should be replaced by the
|
||
``functools.lru_cache`` decorator (available from Python 3.2 onwards).
|
||
|
||
Django ships a backport of this decorator for older Python versions and it's
|
||
available at ``django.utils.lru_cache.lru_cache``. The deprecated function will
|
||
be removed in Django 1.9.
|
||
|
||
Geo Sitemaps
|
||
~~~~~~~~~~~~
|
||
|
||
Google has retired support for the Geo Sitemaps format. Hence Django support
|
||
for Geo Sitemaps is deprecated and will be removed in Django 1.8.
|
||
|
||
Passing callable arguments to queryset methods
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Callable arguments for querysets were an undocumented feature that was
|
||
unreliable. It's been deprecated and will be removed in Django 1.9.
|
||
|
||
Callable arguments were evaluated when a queryset was constructed rather than
|
||
when it was evaluated, thus this feature didn't offer any benefit compared to
|
||
evaluating arguments before passing them to queryset and created confusion that
|
||
the arguments may have been evaluated at query time.
|
||
|
||
``ADMIN_FOR`` setting
|
||
~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
The ``ADMIN_FOR`` feature, part of the admindocs, has been removed. You can
|
||
remove the setting from your configuration at your convenience.
|
||
|
||
``SplitDateTimeWidget`` with ``DateTimeField``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
``SplitDateTimeWidget`` support in :class:`~django.forms.DateTimeField` is
|
||
deprecated, use ``SplitDateTimeWidget`` with
|
||
:class:`~django.forms.SplitDateTimeField` instead.
|
||
|
||
``validate``
|
||
~~~~~~~~~~~~
|
||
|
||
:djadmin:`validate` command is deprecated in favor of :djadmin:`check` command.
|
||
|
||
``django.core.management.BaseCommand``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
``requires_model_validation`` is deprecated in favor of a new
|
||
``requires_system_checks`` flag. If the latter flag is missing, then the
|
||
value of the former flag is used. Defining both ``requires_system_checks`` and
|
||
``requires_model_validation`` results in an error.
|
||
|
||
The ``check()`` method has replaced the old ``validate()`` method.
|
||
|
||
``ModelAdmin.validator``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
``ModelAdmin.validator`` is deprecated in favor of new ``checks`` attribute.
|
||
|
||
``django.db.backends.DatabaseValidation.validate_field``
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
This method is deprecated in favor of a new ``check_field`` method.
|
||
The functionality required by ``check_field()`` is the same as that provided
|
||
by ``validate_field()``, but the output format is different. Third-party database
|
||
backends needing this functionality should modify their backends to provide an
|
||
implementation of ``check_field()``.
|