April 1, 2019
\nWelcome to Django 2.2!
\nThese release notes cover the new features, as well as\nsome backwards incompatible changes you’ll\nwant to be aware of when upgrading from Django 2.1 or earlier. We’ve\nbegun the deprecation process for some features.
\nSee the How to upgrade Django to a newer version guide if you’re updating an existing\nproject.
\nDjango 2.2 is designated as a long-term support release. It will receive security updates for at least\nthree years after its release. Support for the previous LTS, Django 1.11, will\nend in April 2020.
\nDjango 2.2 supports Python 3.5, 3.6, 3.7, 3.8 (as of 2.2.8), and 3.9 (as of\n2.2.17). We highly recommend and only officially support the latest release\nof each series.
\nThe new CheckConstraint and\nUniqueConstraint classes enable adding custom\ndatabase constraints. Constraints are added to models using the\nMeta.constraints option.
django.contrib.adminLink to this heading#Added a CSS class to the column headers of\nTabularInline.
django.contrib.authLink to this heading#The HttpRequest is now passed as the first positional argument to\nRemoteUserBackend.configure_user(), if it accepts it.
django.contrib.gisLink to this heading#django.contrib.postgresLink to this heading#The new ordering argument for\nArrayAgg and\nStringAgg determines the\nordering of the aggregated elements.
The new BTreeIndex,\nHashIndex and\nSpGistIndex classes allow\ncreating B-Tree, hash, and SP-GiST indexes in the database.
BrinIndex now has the\nautosummarize parameter.
The new search_type parameter of\nSearchQuery allows searching for\na phrase or raw expression.
django.contrib.staticfilesLink to this heading#Added path matching to the collectstatic --ignore option so that\npatterns like /vendor/*.js can be used.
Added result streaming for QuerySet.iterator() on SQLite.
The new View.setup hook\ninitializes view attributes before calling\ndispatch(). It allows mixins to set up\ninstance attributes for reuse in child classes.
Added support and translations for the Armenian language.
The new --force-color option forces colorization of the command\noutput.
inspectdb now creates models for foreign tables on PostgreSQL.
inspectdb --include-views now creates models for materialized views\non Oracle and PostgreSQL.
The new inspectdb --include-partitions option allows creating\nmodels for partition tables on PostgreSQL. In older versions, models are\ncreated child tables instead the parent.
inspectdb now introspects DurationField\nfor Oracle and PostgreSQL, and AutoField for\nSQLite.
On Oracle, dbshell is wrapped with rlwrap, if available.\nrlwrap provides a command history and editing of keyboard input.
The new makemigrations --no-header option avoids writing header\ncomments in generated migration file(s). This option is also available for\nsquashmigrations.
runserver can now use Watchman to improve the performance of\nwatching a large number of files for changes.
The new migrate --plan option prints the list of migration\noperations that will be performed.
NoneType can now be serialized in migrations.
You can now register custom serializers\nfor migrations.
Added support for PostgreSQL operator classes (Index.opclasses).
Added support for partial indexes (Index.condition).
Added the NullIf and\nReverse database functions, as well as\nmany math database functions.
Setting the new ignore_conflicts parameter of\nQuerySet.bulk_create() to True tells the database to ignore\nfailure to insert rows that fail uniqueness constraints or other checks.
The new ExtractIsoYear function extracts\nISO-8601 week-numbering years from DateField and\nDateTimeField, and the new iso_year\nlookup allows querying by an ISO-8601 week-numbering year.
The new QuerySet.bulk_update() method allows efficiently updating\nspecific fields on multiple model instances.
Django no longer always starts a transaction when a single query is being\nperformed, such as Model.save(), QuerySet.update(), and\nModel.delete(). This improves the performance of autocommit by reducing\nthe number of database round trips.
Added SQLite support for the StdDev and\nVariance functions.
The handling of DISTINCT aggregation is added to the\nAggregate class. Adding allow_distinct =\nTrue as a class attribute on\nAggregate subclasses allows a distinct keyword argument to be\nspecified on initialization to ensure that the aggregate function is only\ncalled for each distinct value of expressions.
The RelatedManager.add(), create(),\nremove(), set(),\nget_or_create(), and update_or_create() methods are now allowed on\nmany-to-many relationships with intermediate models. The new\nthrough_defaults argument is used to specify values for new intermediate\nmodel instance(s).
Added HttpRequest.headers to allow simple access to a request’s\nheaders.
You can now deserialize data using natural keys containing forward\nreferences by passing\nhandle_forward_references=True to serializers.deserialize().\nAdditionally, loaddata handles forward references automatically.
The new SimpleTestCase.assertURLEqual() assertion checks for a given\nURL, ignoring the ordering of the query string.\nassertRedirects() uses the new assertion.
The test Client now supports automatic JSON\nserialization of list and tuple data when\ncontent_type='application/json'.
The new ORACLE_MANAGED_FILES test\ndatabase setting allows using Oracle Managed Files (OMF) tablespaces.
Deferrable database constraints are now checked at the end of each\nTestCase test on SQLite 3.20+, just like on other\nbackends that support deferrable constraints. These checks aren’t implemented\nfor older versions of SQLite because they would require expensive table\nintrospection there.
DiscoverRunner now skips the setup of databases\nnot referenced by tests.
The new ResolverMatch.route attribute stores the route of the\nmatching URL pattern.
MaxValueValidator, MinValueValidator,\nMinLengthValidator, and MaxLengthValidator now accept\na callable limit_value.
This section describes changes that may be needed in third-party database\nbackends.
\nThird-party database backends must implement support for table check\nconstraints or set DatabaseFeatures.supports_table_check_constraints to\nFalse.
Third party database backends must implement support for ignoring\nconstraints or uniqueness errors while inserting or set\nDatabaseFeatures.supports_ignore_conflicts to False.
Third party database backends must implement introspection for\nDurationField or set DatabaseFeatures.can_introspect_duration_field\nto False.
DatabaseFeatures.uses_savepoints now defaults to True.
Third party database backends must implement support for partial indexes or\nset DatabaseFeatures.supports_partial_indexes to False.
DatabaseIntrospection.table_name_converter() and\ncolumn_name_converter() are removed. Third party database backends may\nneed to instead implement DatabaseIntrospection.identifier_converter().\nIn that case, the constraint names that\nDatabaseIntrospection.get_constraints() returns must be normalized by\nidentifier_converter().
SQL generation for indexes is moved from Index to\nSchemaEditor and these SchemaEditor methods are added:
_create_primary_key_sql() and _delete_primary_key_sql()
_delete_index_sql() (to pair with _create_index_sql())
_delete_unique_sql (to pair with _create_unique_sql())
_delete_fk_sql() (to pair with _create_fk_sql())
_create_check_sql() and _delete_check_sql()
The third argument of DatabaseWrapper.__init__(),\nallow_thread_sharing, is removed.
ModelAdmin classesLink to this heading#For example, in older versions of Django:
\nfrom django.contrib import admin\n\n\nclass BaseAdmin(admin.ModelAdmin):\n actions = ["a"]\n\n\nclass SubAdmin(BaseAdmin):\n actions = ["b"]\nSubAdmin would have actions 'a' and 'b'.
Now actions follows standard Python inheritance. To get the same result as\nbefore:
class SubAdmin(BaseAdmin):\n actions = BaseAdmin.actions + ["b"]\ndjango.contrib.gisLink to this heading#Support for GDAL 1.9 and 1.10 is dropped.
TransactionTestCase serialized data loadingLink to this heading#Initial data migrations are now loaded in\nTransactionTestCase at the end of the test, after the\ndatabase flush. In older versions, this data was loaded at the beginning of the\ntest, but this prevents the test --keepdb option from working\nproperly (the database was empty at the end of the whole test suite). This\nchange shouldn’t have an impact on your tests unless you’ve customized\nTransactionTestCase’s internals.
sqlparse is required dependencyLink to this heading#To simplify a few parts of Django’s database handling, sqlparse 0.2.2+ is now a required dependency. It’s automatically installed along\nwith Django.
\ncached_property aliasesLink to this heading#In usage like:
\nfrom django.utils.functional import cached_property\n\n\nclass A:\n @cached_property\n def base(self):\n return ...\n\n alias = base\nalias is not cached. Where the problem can be detected (Python 3.6 and\nlater), such usage now raises TypeError: Cannot assign the same\ncached_property to two different names ('base' and 'alias').
Use this instead:
\nimport operator\n\n\nclass A:\n ...\n\n alias = property(operator.attrgetter("base"))\nPermissions for proxy models are now\ncreated using the content type of the proxy model rather than the content type\nof the concrete model. A migration will update existing permissions when you\nrun migrate.
In the admin, the change is transparent for proxy models having the same\napp_label as their concrete model. However, in older versions, users with\npermissions for a proxy model with a different app_label than its\nconcrete model couldn’t access the model in the admin. That’s now fixed, but\nyou might want to audit the permissions assignments for such proxy models\n([add|view|change|delete]_myproxy) prior to upgrading to ensure the new\naccess is appropriate.
Finally, proxy model permission strings must be updated to use their own\napp_label. For example, for app.MyProxyModel inheriting from\nother_app.ConcreteModel, update\nuser.has_perm('other_app.add_myproxymodel') to\nuser.has_perm('app.add_myproxymodel').
Media assetsLink to this heading#Form Media assets are now merged using a topological sort algorithm, as the\nold pairwise merging algorithm is insufficient for some cases. CSS and\nJavaScript files which don’t include their dependencies may now be sorted\nincorrectly (where the old algorithm produced results correctly by\ncoincidence).
Audit all Media classes for any missing dependencies. For example,\nwidgets depending on django.jQuery must specify\njs=['admin/js/jquery.init.js', ...] when declaring form media assets.
To improve readability, the UUIDField form field now displays values with\ndashes, e.g. 550e8400-e29b-41d4-a716-446655440000 instead of\n550e8400e29b41d4a716446655440000.
On SQLite, PositiveIntegerField and PositiveSmallIntegerField now\ninclude a check constraint to prevent negative values in the database. If you\nhave existing invalid data and run a migration that recreates a table, you’ll\nsee CHECK constraint failed.
For consistency with WSGI servers, the test client now sets the\nContent-Length header to a string rather than an integer.
The return value of django.utils.text.slugify() is no longer marked as\nHTML safe.
The default truncation character used by the urlizetrunc,\ntruncatechars, truncatechars_html,\ntruncatewords, and truncatewords_html template filters\nis now the real ellipsis character (…) instead of 3 dots. You may have to\nadapt some test output comparisons.
Support for bytestring paths in the template filesystem loader is removed.
django.utils.http.urlsafe_base64_encode() now returns a string instead\nof a bytestring, and django.utils.http.urlsafe_base64_decode() may no\nlonger 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\n1.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\nrenders <option> values of unknown, true, and false instead\nof 1, 2, and 3. For backwards compatibility, the old values are\nstill accepted as data.
Group.name max_length\nis increased from 80 to 150 characters.
Tests that violate deferrable database constraints now error when run on\nSQLite 3.20+, just like on other backends that support such constraints.
To catch usage mistakes, the test Client and\ndjango.utils.http.urlencode() now raise TypeError if None is\npassed as a value to encode because None can’t be encoded in GET and POST\ndata. Either pass an empty string or omit the value.
The ping_google management command now defaults to https\ninstead of http for the sitemap’s URL. If your site uses http, use the\nnew ping_google --sitemap-uses-http option. If you use the\ndjango.contrib.sitemaps.ping_google function, set the new\nsitemap_uses_https argument to False.
runserver no longer supports pyinotify (replaced by Watchman).
The Avg, StdDev, and\nVariance aggregate functions now return a\nDecimal instead of a float when the input is Decimal.
Tests will fail on SQLite if apps without migrations have relations to apps\nwith migrations. This has been a documented restriction since migrations were\nadded in Django 1.7, but it fails more reliably now. You’ll see tests failing\nwith errors like no such table: <app_label>_<model>. This was observed\nwith several third-party apps that had models in tests without migrations.\nYou must add migrations for such models.
Providing an integer in the key argument of the cache.delete() or\ncache.get() now raises ValueError.
Plural equations for some languages are changed, because the latest versions\nfrom Transifex are incorporated.
\n\nMeta.ordering will no longer affect GROUP BY queriesLink to this heading#A model’s Meta.ordering affecting GROUP BY queries (such as\n.annotate().values()) is a common source of confusion. Such queries now\nissue a deprecation warning with the advice to add an order_by() to retain\nthe current query. Meta.ordering will be ignored in such queries starting\nin Django 3.1.
django.utils.timezone.FixedOffset is deprecated in favor of\ndatetime.timezone.
The undocumented QuerySetPaginator alias of\ndjango.core.paginator.Paginator is deprecated.
The FloatRangeField model and form fields in django.contrib.postgres\nare deprecated in favor of a new name, DecimalRangeField, to match the\nunderlying numrange data type used in the database.
The FILE_CHARSET setting is deprecated. Starting with Django 3.1, files\nread from disk must be UTF-8 encoded.
django.contrib.staticfiles.storage.CachedStaticFilesStorage is\ndeprecated due to the intractable problems that it has. Use\nManifestStaticFilesStorage or a third-party cloud storage instead.
RemoteUserBackend.configure_user() is now passed request as the\nfirst positional argument, if it accepts it. Support for overrides that don’t\naccept it will be removed in Django 3.1.
The SimpleTestCase.allow_database_queries,\nTransactionTestCase.multi_db, and TestCase.multi_db\nattributes are deprecated in favor of SimpleTestCase.databases,\nTransactionTestCase.databases, and TestCase.databases.\nThese new attributes allow databases dependencies to be declared in order to\nprevent unexpected queries against non-default databases to leak state\nbetween tests. The previous behavior of allow_database_queries=True and\nmulti_db=True can be achieved by setting databases='__all__'.