2.2.txt

============================================
Django 2.2 release notes - UNDER DEVELOPMENT
============================================

*Expected April 2019*

Welcome to Django 2.2!

These release notes cover the :ref:`new features <whats-new-2.2>`, as well as
some :ref:`backwards incompatible changes <backwards-incompatible-2.2>` you'll
want to be aware of when upgrading from Django 2.1 or earlier. We've
:ref:`begun the deprecation process for some features
<deprecated-features-2.2>`.

See the :doc:`/howto/upgrade-version` guide if you're updating an existing
project.

Django 2.2 is designated as a :term:`long-term support release`. It will
receive security updates for at least three years after its release. Support
for the previous LTS, Django 1.11, will end in April 2020.

Python compatibility
====================

Django 2.2 supports Python 3.5, 3.6, and 3.7. We **highly recommend** and only
officially support the latest release of each series.

.. _whats-new-2.2:

What's new in Django 2.2
========================

Constraints
-----------

The new :class:`~django.db.models.CheckConstraint` and
:class:`~django.db.models.UniqueConstraint` classes enable adding custom
database constraints. Constraints are added to models using the
:attr:`Meta.constraints <django.db.models.Options.constraints>` option.

Minor features
--------------

:mod:`django.contrib.admin`
~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Added a CSS class to the column headers of
  :class:`~django.contrib.admin.TabularInline`.

:mod:`django.contrib.admindocs`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ...

:mod:`django.contrib.auth`
~~~~~~~~~~~~~~~~~~~~~~~~~~

* ...

:mod:`django.contrib.contenttypes`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ...

:mod:`django.contrib.gis`
~~~~~~~~~~~~~~~~~~~~~~~~~

* Added Oracle support for the
  :class:`~django.contrib.gis.db.models.functions.Envelope` function.

* Added SpatiaLite support for the :lookup:`coveredby` and :lookup:`covers`
  lookups.

:mod:`django.contrib.messages`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ...

:mod:`django.contrib.postgres`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* The new ``ordering`` argument for
  :class:`~django.contrib.postgres.aggregates.ArrayAgg` and
  :class:`~django.contrib.postgres.aggregates.StringAgg` determines the
  ordering of the aggregated elements.

* The new :class:`~django.contrib.postgres.indexes.BTreeIndex`,
  :class:`~django.contrib.postgres.indexes.HashIndex` and
  :class:`~django.contrib.postgres.indexes.SpGistIndex` classes allow
  creating ``B-Tree``, ``hash``, and ``SP-GiST`` indexes in the database.

* :class:`~django.contrib.postgres.indexes.BrinIndex` now has the
  ``autosummarize`` parameter.

* The new ``search_type`` parameter of
  :class:`~django.contrib.postgres.search.SearchQuery` allows searching for
  a phrase or raw expression.

:mod:`django.contrib.redirects`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ...

:mod:`django.contrib.sessions`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ...

:mod:`django.contrib.sitemaps`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ...

:mod:`django.contrib.sites`
~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ...

:mod:`django.contrib.staticfiles`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Added path matching to the :option:`collectstatic --ignore` option so that
  patterns like ``/vendor/*.js`` can be used.

:mod:`django.contrib.syndication`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ...

Cache
~~~~~

* ...

CSRF
~~~~

* ...

Database backends
~~~~~~~~~~~~~~~~~

* Added result streaming for :meth:`.QuerySet.iterator` on SQLite.

Email
~~~~~

* ...

File Storage
~~~~~~~~~~~~

* ...

File Uploads
~~~~~~~~~~~~

* ...


Forms
~~~~~

* ...

Generic Views
~~~~~~~~~~~~~

* The new :meth:`View.setup <django.views.generic.base.View.setup>` hook
  initializes view attributes before calling
  :meth:`~django.views.generic.base.View.dispatch`. It allows mixins to setup
  instance attributes for reuse in child classes.

Internationalization
~~~~~~~~~~~~~~~~~~~~

* ...

Management Commands
~~~~~~~~~~~~~~~~~~~

* The new :option:`--force-color` option forces colorization of the command
  output.

* :djadmin:`inspectdb` now creates models for foreign tables on PostgreSQL.

* :option:`inspectdb --include-views` now creates models for materialized views
  on Oracle and PostgreSQL.

* The new :option:`inspectdb --include-partitions` option allows creating
  models for partition tables on PostgreSQL. In older versions, models are
  created child tables instead the parent.

* :djadmin:`inspectdb` now introspects :class:`~django.db.models.DurationField`
  for Oracle and PostgreSQL.

* On Oracle, :djadmin:`dbshell` is wrapped with ``rlwrap``, if available.
  ``rlwrap`` provides a command history and editing of keyboard input.

* The new :option:`makemigrations --no-header` option avoids writing header
  comments in generated migration file(s). This option is also available for
  :djadmin:`squashmigrations`.

Migrations
~~~~~~~~~~

* The new :option:`migrate --plan` option prints the list of migration
  operations that will be performed.

* ``NoneType`` can now be serialized in migrations.

Models
~~~~~~

* Added support for PostgreSQL operator classes (:attr:`.Index.opclasses`).

* Added support for partial indexes (:attr:`.Index.condition`).

* Added many :ref:`math database functions <math-functions>`.

* Setting the new ``ignore_conflicts`` parameter of
  :meth:`.QuerySet.bulk_create` to ``True`` tells the database to ignore
  failure to insert rows that fail uniqueness constraints or other checks.

* The new :class:`~django.db.models.functions.ExtractIsoYear` function extracts
  ISO-8601 week-numbering years from :class:`~django.db.models.DateField` and
  :class:`~django.db.models.DateTimeField`, and the new :lookup:`iso_year`
  lookup allows querying by an ISO-8601 week-numbering year.

* The new :meth:`.QuerySet.bulk_update` method allows efficiently updating
  specific fields on multiple model instances.

* Django no longer always starts a transaction when a single query is being
  performed, such as ``Model.save()``, ``QuerySet.update()``, and
  ``Model.delete()``. This improves the performance of autocommit by reducing
  the number of database round trips.

* Added SQLite support for :class:`~django.db.models.StdDev` and
  :class:`~django.db.models.Variance`.

Requests and Responses
~~~~~~~~~~~~~~~~~~~~~~

* ...

Serialization
~~~~~~~~~~~~~

* You can now deserialize data using natural keys containing :ref:`forward
  references <natural-keys-and-forward-references>` by passing
  ``handle_forward_references=True`` to ``serializers.deserialize()``.
  Additionally, :djadmin:`loaddata` handles forward references automatically.

Signals
~~~~~~~

* ...

Templates
~~~~~~~~~

* ...

Tests
~~~~~

* The new :meth:`.SimpleTestCase.assertURLEqual` assertion checks for a given
  URL, ignoring the ordering of the query string.
  :meth:`~.SimpleTestCase.assertRedirects` uses the new assertion.

* The test :class:`~.django.test.Client` now supports automatic JSON
  serialization of list and tuple ``data`` when
  ``content_type='application/json'``.

* The new :setting:`ORACLE_MANAGED_FILES <TEST_ORACLE_MANAGED_FILES>` test
  database setting allows using Oracle Managed Files (OMF) tablespaces.

* Deferrable database constraints are now checked at the end of each
  :class:`~django.test.TestCase` test on SQLite 3.20+, just like on other
  backends that support deferrable constraints. These checks aren't implemented
  for older versions of SQLite because they would require expensive table
  introspection there.

URLs
~~~~

* The new :attr:`.ResolverMatch.route` attribute stores the route of the
  matching URL pattern.

Validators
~~~~~~~~~~

* :class:`.MaxValueValidator`, :class:`.MinValueValidator`,
  :class:`.MinLengthValidator`, and :class:`.MaxLengthValidator` now accept
  a callable ``limit_value``.

.. _backwards-incompatible-2.2:

Backwards incompatible changes in 2.2
=====================================

Database backend API
--------------------

This section describes changes that may be needed in third-party database
backends.

* Third-party database backends must implement support for table check
  constraints or set ``DatabaseFeatures.supports_table_check_constraints`` to
  ``False``.

* Third party database backends must implement support for ignoring
  constraints or uniqueness errors while inserting or set
  ``DatabaseFeatures.supports_ignore_conflicts`` to ``False``.

* Third party database backends must implement introspection for
  ``DurationField`` or set ``DatabaseFeatures.can_introspect_duration_field``
  to ``False``.

* ``DatabaseFeatures.uses_savepoints`` now defaults to ``True``.

* Third party database backends must implement support for partial indexes or
  set ``DatabaseFeatures.supports_partial_indexes`` to ``False``.

* Several ``SchemaEditor`` attributes are changed:

  * ``sql_create_check`` is replaced with ``sql_create_constraint``.
  * ``sql_delete_check`` is replaced with ``sql_delete_constraint``.
  * ``sql_create_fk`` is replaced with ``sql_foreign_key_constraint``,
    ``sql_constraint``, and ``sql_create_constraint``.

* ``DatabaseIntrospection.table_name_converter()`` and
  ``column_name_converter()`` are removed. Third party database backends may
  need to instead implement ``DatabaseIntrospection.identifier_converter()``.
  In that case, the constraint names that
  ``DatabaseIntrospection.get_constraints()`` returns must be normalized by
  ``identifier_converter()``.

Admin actions are no longer collected from base ``ModelAdmin`` classes
----------------------------------------------------------------------

For example, in older versions of Django::

    from django.contrib import admin

    class BaseAdmin(admin.ModelAdmin):
        actions = ['a']

    class SubAdmin(BaseAdmin):
        actions = ['b']

``SubAdmin`` will have actions ``'a'`` and ``'b'``.

Now ``actions`` follows standard Python inheritance. To get the same result as
before::

    class SubAdmin(BaseAdmin):
        actions = BaseAdmin.actions + ['b']

:mod:`django.contrib.gis`
-------------------------

* Support for GDAL 1.9 and 1.10 is dropped.

``TransactionTestCase`` serialized data loading
-----------------------------------------------

Initial data migrations are now loaded in
:class:`~django.test.TransactionTestCase` at the end of the test, after the
database flush. In older versions, this data was loaded at the beginning of the
test, but this prevents the :option:`test --keepdb` option from working
properly (the database was empty at the end of the whole test suite). This
change shouldn't have an impact on your tests unless you've customized
:class:`~django.test.TransactionTestCase`'s internals.

``sqlparse`` is required dependency
-----------------------------------

To simplify a few parts of Django's database handling, `sqlparse
<https://pypi.org/project/sqlparse/>`_ is now a required dependency. It's
automatically installed along with Django.

``cached_property`` aliases
---------------------------

In usage like::

    from django.utils.functional import cached_property

    class A:

        @cached_property
        def base(self):
            return ...

        alias = base

``alias`` is not cached. Such usage now raises ``TypeError: Cannot assign the
same cached_property to two different names ('base' and 'alias').`` on Python
3.6 and later.

Use this instead::

    import operator

    class A:

        ...

        alias = property(operator.attrgetter('base'))

Miscellaneous
-------------

* To improve readability, the ``UUIDField`` form field now displays values with
  dashes, e.g. ``550e8400-e29b-41d4-a716-446655440000`` instead of
  ``550e8400e29b41d4a716446655440000``.

* On SQLite, ``PositiveIntegerField`` and ``PositiveSmallIntegerField`` now
  include a check constraint to prevent negative values in the database. If you
  have existing invalid data and run a migration that recreates a table, you'll
  see ``CHECK constraint failed``.

* For consistency with WSGI servers, the test client now sets the
  ``Content-Length`` header to a string rather than an integer.

* The return value of :func:`django.utils.text.slugify` is no longer marked as
  HTML safe.

* The default truncation character used by the :tfilter:`urlizetrunc`,
  :tfilter:`truncatechars`, :tfilter:`truncatechars_html`,
  :tfilter:`truncatewords`, and :tfilter:`truncatewords_html` template filters
  is now the real ellipsis character (``…``) instead of 3 dots. You may have to
  adapt some test output comparisons.

* Support for bytestring paths in the template filesystem loader is removed.

* :func:`django.utils.http.urlsafe_base64_encode` now returns a string instead
  of a bytestring, and :func:`django.utils.http.urlsafe_base64_decode` may no
  longer be passed a bytestring.

* Support for ``cx_Oracle`` < 6.0 is removed.

* The minimum supported version of ``mysqlclient`` is increased from 1.3.7 to
  1.3.13.

* The minimum supported version of SQLite is increased from 3.7.15 to 3.8.3.

* In an attempt to provide more semantic query data, ``NullBooleanSelect`` now
  renders ``<option>`` values of ``unknown``, ``true``, and ``false`` instead
  of ``1``, ``2``, and ``3``. For backwards compatibility, the old values are
  still accepted as data.

* :attr:`Group.name <django.contrib.auth.models.Group.name>` ``max_length``
  is increased from 80 to 150 characters.

* Tests that violate deferrable database constraints now error when run on
  SQLite 3.20+, just like on other backends that support such constraints.

.. _deprecated-features-2.2:

Features deprecated in 2.2
==========================

Model ``Meta.ordering`` will no longer affect ``GROUP BY`` queries
------------------------------------------------------------------

A model's ``Meta.ordering`` affecting ``GROUP BY`` queries (such as
``.annotate().values()``) is a common source of confusion. Such queries now
issue a deprecation warning with the advice to add an ``order_by()`` to retain
the current query. ``Meta.ordering`` will be ignored in such queries starting
in Django 3.1.

Miscellaneous
-------------

* ``django.utils.timezone.FixedOffset`` is deprecated in favor of
  :class:`datetime.timezone`.

* The undocumented ``QuerySetPaginator`` alias of
  ``django.core.paginator.Paginator`` is deprecated.

* The ``FloatRangeField`` model and form fields in ``django.contrib.postgres``
  are deprecated in favor of a new name, ``DecimalRangeField``, to match the
  underlying ``numrange`` data type used in the database.

* The ``FILE_CHARSET`` setting is deprecated. Starting with Django 3.1, files
  read from disk must be UTF-8 encoded.

* ``django.contrib.staticfiles.storage.CachedStaticFilesStorage`` is
  deprecated due to the intractable problems that is has. Use
  :class:`.ManifestStaticFilesStorage` or a third-party cloud storage instead.