December 2, 2017
\nWelcome to Django 2.0!
\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 1.11 or earlier. We’ve\ndropped some features that have reached the end of\ntheir deprecation cycle, and we’ve begun the deprecation process for some\nfeatures.
\nThis release starts Django’s use of a loose form of semantic versioning, but there aren’t any major backwards incompatible\nchanges that might be expected of a 2.0 release. Upgrading should be a similar\namount of effort as past feature releases.
\nSee the How to upgrade Django to a newer version guide if you’re updating an existing\nproject.
\nDjango 2.0 supports Python 3.4, 3.5, 3.6, and 3.7. We highly recommend and\nonly officially support the latest release of each series.
\nThe Django 1.11.x series is the last to support Python 2.7.
\nDjango 2.0 will be the last release series to support Python 3.4. If you plan\na deployment of Python 3.4 beyond the end-of-life for Django 2.0 (April 2019),\nstick with Django 1.11 LTS (supported until April 2020) instead. Note, however,\nthat the end-of-life for Python 3.4 is March 2019.
\nFollowing the release of Django 2.0, we suggest that third-party app authors\ndrop support for all versions of Django prior to 1.11. At that time, you should\nbe able to run your package’s tests using python -Wd so that deprecation\nwarnings do appear. After making the deprecation warning fixes, your app should\nbe compatible with Django 2.0.
The new django.urls.path() function allows a simpler, more readable URL\nrouting syntax. For example, this example from previous Django releases:
url(r"^articles/(?P<year>[0-9]{4})/$", views.year_archive),\ncould be written as:
\npath("articles/<int:year>/", views.year_archive),\nThe new syntax supports type coercion of URL parameters. In the example, the\nview will receive the year keyword argument as an integer rather than as\na string. Also, the URLs that will match are slightly less constrained in the\nrewritten example. For example, the year 10000 will now match since the year\nintegers aren’t constrained to be exactly four digits long as they are in the\nregular expression.
The django.conf.urls.url() function from previous versions is now available\nas django.urls.re_path(). The old location remains for backwards\ncompatibility, without an imminent deprecation. The old\ndjango.conf.urls.include() function is now importable from django.urls\nso you can use from django.urls import include, path, re_path in your\nURLconfs.
The URL dispatcher document is rewritten to feature the new syntax\nand provide more details.
\ncontrib.adminLink to this heading#The admin is now responsive and supports all major mobile devices. Older\nbrowsers may experience varying levels of graceful degradation.
\nThe new Window expression allows\nadding an OVER clause to querysets. You can use window functions and aggregate functions in\nthe expression.
django.contrib.adminLink to this heading#The new ModelAdmin.autocomplete_fields attribute and\nModelAdmin.get_autocomplete_fields() method allow using a\nSelect2 search widget for ForeignKey and\nManyToManyField.
django.contrib.authLink to this heading#The default iteration count for the PBKDF2 password hasher is increased from\n36,000 to 100,000.
django.contrib.gisLink to this heading#Added MySQL support for the\nAsGeoJSON function,\nGeoHash function,\nIsValid function,\nisvalid lookup, and distance lookups.
Added the Azimuth and\nLineLocatePoint functions,\nsupported on PostGIS and SpatiaLite.
Any GEOSGeometry imported from GeoJSON now\nhas its SRID set.
Added the OSMWidget.default_zoom attribute to customize the map’s\ndefault zoom level.
Made metadata readable and editable on rasters through the\nmetadata,\ninfo, and\nmetadata attributes.
Allowed passing driver-specific creation options to\nGDALRaster objects using papsz_options.
Allowed creating GDALRaster objects in\nGDAL’s internal virtual filesystem. Rasters can now be created from and\nconverted to binary data in-memory.
The new GDALBand.color_interp() method returns the color\ninterpretation for the band.
django.contrib.postgresLink to this heading#The new distinct argument for\nArrayAgg determines if\nconcatenated values will be distinct.
The new RandomUUID database\nfunction returns a version 4 UUID. It requires use of PostgreSQL’s\npgcrypto extension which can be activated using the new\nCryptoExtension migration\noperation.
django.contrib.postgres.indexes.GinIndex now supports the\nfastupdate and gin_pending_list_limit parameters.
The new GistIndex class allows\ncreating GiST indexes in the database. The new\nBtreeGistExtension migration\noperation installs the btree_gist extension to add support for operator\nclasses that aren’t built-in.
inspectdb can now introspect JSONField and various\nRangeFields (django.contrib.postgres must be in INSTALLED_APPS).
django.contrib.sitemapsLink to this heading#Added the protocol keyword argument to the\nGenericSitemap constructor.
cache.set_many() now returns a list of keys that failed to be inserted.\nFor the built-in backends, failed inserts can only happen on memcached.
File.open() can be used as a context\nmanager, e.g. with file.open() as f:.
The new date_attrs and time_attrs arguments for\nSplitDateTimeWidget and\nSplitHiddenDateTimeWidget allow specifying different\nHTML attributes for the DateInput and TimeInput (or hidden)\nsubwidgets.
The new Form.errors.get_json_data() method returns form errors as\na dictionary suitable for including in a JSON response.
The new ContextMixin.extra_context attribute allows adding context\nin View.as_view().
inspectdb now translates MySQL’s unsigned integer columns to\nPositiveIntegerField or PositiveSmallIntegerField.
The new makemessages --add-location option controls the comment\nformat in .po files.
loaddata can now read from stdin.
The new diffsettings --output option allows formatting the output\nin a unified diff format.
On Oracle, inspectdb can now introspect AutoField if the\ncolumn is created as an identity column.
On MySQL, dbshell now supports client-side TLS certificates.
The new squashmigrations --squashed-name option allows naming the\nsquashed migration.
The new StrIndex database function\nfinds the starting index of a string inside another string.
On Oracle, AutoField and BigAutoField are now created as identity\ncolumns.
The new chunk_size parameter of QuerySet.iterator() controls the\nnumber of rows fetched by the Python database client when streaming results\nfrom the database. For databases that don’t support server-side cursors, it\ncontrols the number of results Django fetches from the database adapter.
QuerySet.earliest(), QuerySet.latest(), and\nMeta.get_latest_by now\nallow ordering by several fields.
Added the ExtractQuarter function to\nextract the quarter from DateField and\nDateTimeField, and exposed it through the\nquarter lookup.
Added the TruncQuarter function to\ntruncate DateField and\nDateTimeField to the first day of a quarter.
Added the db_tablespace parameter to\nclass-based indexes.
If the database supports a native duration field (Oracle and PostgreSQL),\nExtract now works with\nDurationField.
Added the of argument to QuerySet.select_for_update(), supported\non PostgreSQL and Oracle, to lock only rows from specific tables rather than\nall selected tables. It may be helpful particularly when\nselect_for_update() is used in conjunction with\nselect_related().
The new field_name parameter of QuerySet.in_bulk() allows fetching\nresults based on any unique model field.
CursorWrapper.callproc() now takes an optional dictionary of keyword\nparameters, if the backend supports this feature. Of Django’s built-in\nbackends, only Oracle supports it.
The new connection.execute_wrapper() method allows installing\nwrappers around execution of database queries.
The new filter argument for built-in aggregates allows adding\ndifferent conditionals to multiple aggregations\nover the same fields or relations.
Added support for expressions in Meta.ordering.
The new named parameter of QuerySet.values_list() allows fetching\nresults as named tuples.
The new FilteredRelation class allows adding an ON clause to\nquerysets.
Added Paginator.get_page()\nto provide the documented pattern of handling invalid page numbers.
The runserver web server supports HTTP 1.1.
To increase the usefulness of Engine.get_default() in third-party\napps, it now returns the first engine if multiple DjangoTemplates engines\nare configured in TEMPLATES rather than raising ImproperlyConfigured.
Custom template tags may now accept keyword-only arguments.
Added threading support to LiveServerTestCase.
Added settings that allow customizing the test tablespace parameters for\nOracle: DATAFILE_SIZE, DATAFILE_TMP_SIZE,\nDATAFILE_EXTSIZE, and DATAFILE_TMP_EXTSIZE.
The new ProhibitNullCharactersValidator disallows the null\ncharacter in the input of the CharField form field\nand its subclasses. Null character input was observed from vulnerability\nscanning tools. Most databases silently discard null characters, but\npsycopg2 2.7+ raises an exception when trying to save a null character to\na char/text field with PostgreSQL.
To support native Python 2 strings, older Django versions had to accept both\nbytestrings and Unicode strings. Now that Python 2 support is dropped,\nbytestrings should only be encountered around input/output boundaries (handling\nof binary fields or HTTP streams, for example). You might have to update your\ncode to limit bytestring usage to a minimum, as Django no longer accepts\nbytestrings in certain code paths. Python’s -b option may help detect\nthat mistake in your code.
For example, reverse() now uses str() instead of force_text() to\ncoerce the args and kwargs it receives, prior to their placement in\nthe URL. For bytestrings, this creates a string with an undesired b prefix\nas well as additional quotes (str(b'foo') is "b'foo'"). To adapt, call\ndecode() on the bytestring before passing it to reverse().
This section describes changes that may be needed in third-party database\nbackends.
\nThe DatabaseOperations.datetime_cast_date_sql(),\ndatetime_cast_time_sql(), datetime_trunc_sql(),\ndatetime_extract_sql(), and date_interval_sql() methods now return\nonly the SQL to perform the operation instead of SQL and a list of\nparameters.
Third-party database backends should add a DatabaseWrapper.display_name\nattribute with the name of the database that your backend works with. Django\nmay use it in various messages, such as in system checks.
The first argument of SchemaEditor._alter_column_type_sql() is now\nmodel rather than table.
The first argument of SchemaEditor._create_index_name() is now\ntable_name rather than model.
To enable FOR UPDATE OF support, set\nDatabaseFeatures.has_select_for_update_of = True. If the database\nrequires that the arguments to OF be columns rather than tables, set\nDatabaseFeatures.select_for_update_of_column = True.
To enable support for Window\nexpressions, set DatabaseFeatures.supports_over_clause to True. You\nmay need to customize the\nDatabaseOperations.window_start_rows_start_end() and/or\nwindow_start_range_start_end() methods.
Third-party database backends should add a\nDatabaseOperations.cast_char_field_without_max_length attribute with the\ndatabase data type that will be used in the\nCast function for a CharField if the\nmax_length argument isn’t provided.
The first argument of DatabaseCreation._clone_test_db() and\nget_test_db_clone_settings() is now suffix rather\nthan number (in case you want to rename the signatures in your backend\nfor consistency). django.test also now passes those values as strings\nrather than as integers.
Third-party database backends should add a\nDatabaseIntrospection.get_sequences() method based on the stub in\nBaseDatabaseIntrospection.
The end of upstream support for Oracle 11.2 is Dec. 2020. Django 1.11 will be\nsupported until April 2020 which almost reaches this date. Django 2.0\nofficially supports Oracle 12.1+.
\nMySQL’s default isolation level, repeatable read, may cause data loss in\ntypical Django usage. To prevent that and for consistency with other databases,\nthe default isolation level is now read committed. You can use the\nDATABASES setting to use a different isolation level, if needed.
AbstractUser.last_name max_length increased to 150Link to this heading#A migration for django.contrib.auth.models.User.last_name is included.\nIf you have a custom user model inheriting from AbstractUser, you’ll need\nto generate and apply a database migration for your user model.
If you want to preserve the 30 character limit for last names, use a custom\nform:
\nfrom django.contrib.auth.forms import UserChangeForm\n\n\nclass MyUserChangeForm(UserChangeForm):\n last_name = forms.CharField(max_length=30, required=False)\nIf you wish to keep this restriction in the admin when editing users, set\nUserAdmin.form to use this form:
from django.contrib.auth.admin import UserAdmin\nfrom django.contrib.auth.models import User\n\n\nclass MyUserAdmin(UserAdmin):\n form = MyUserChangeForm\n\n\nadmin.site.unregister(User)\nadmin.site.register(User, MyUserAdmin)\nQuerySet.reverse() and last() are prohibited after slicingLink to this heading#Calling QuerySet.reverse() or last() on a sliced queryset leads to\nunexpected results due to the slice being applied after reordering. This is\nnow prohibited, e.g.:
>>> Model.objects.all()[:2].reverse()\nTraceback (most recent call last):\n...\nTypeError: Cannot reverse a query once a slice has been taken.\nTo help prevent runtime errors due to incorrect ordering of form field\narguments, optional arguments of built-in form fields are no longer accepted\nas positional arguments. For example:
\nforms.IntegerField(25, 10)\nraises an exception and should be replaced with:
\nforms.IntegerField(max_value=25, min_value=10)\ncall_command() validates the options it receivesLink to this heading#call_command() now validates that the argument parser of the command being\ncalled defines all of the options passed to call_command().
For custom management commands that use options not created using\nparser.add_argument(), add a stealth_options attribute on the command:
class MyCommand(BaseCommand):\n stealth_options = ("option_name", ...)\nFor example:
\nmodels.Index(["headline", "-pub_date"], "index_name")\nraises an exception and should be replaced with:
\nmodels.Index(fields=["headline", "-pub_date"], name="index_name")\nThis will appear as a backwards-incompatible change (IntegrityError:\nFOREIGN KEY constraint failed) if attempting to save an existing model\ninstance that’s violating a foreign key constraint.
Foreign keys are now created with DEFERRABLE INITIALLY DEFERRED instead of\nDEFERRABLE IMMEDIATE. Thus, tables may need to be rebuilt to recreate\nforeign keys with the new definition, particularly if you’re using a pattern\nlike this:
from django.db import transaction\n\nwith transaction.atomic():\n Book.objects.create(author_id=1)\n Author.objects.create(id=1)\nIf you don’t recreate the foreign key as DEFERRED, the first create()\nwould fail now that foreign key constraints are enforced.
Backup your database first! After upgrading to Django 2.0, you can then\nrebuild tables using a script similar to this:
\nfrom django.apps import apps\nfrom django.db import connection\n\nfor app in apps.get_app_configs():\n for model in app.get_models(include_auto_created=True):\n if model._meta.managed and not (model._meta.proxy or model._meta.swapped):\n for base in model.__bases__:\n if hasattr(base, "_meta"):\n base._meta.local_many_to_many = []\n model._meta.local_many_to_many = []\n with connection.schema_editor() as editor:\n editor._remake_table(model)\nThis script hasn’t received extensive testing and needs adaption for various\ncases such as multiple databases. Feel free to contribute improvements.
\nIn addition, because of a table alteration limitation of SQLite, it’s\nprohibited to perform RenameModel and\nRenameField operations on models or\nfields referenced by other models in a transaction. In order to allow\nmigrations containing these operations to be applied, you must set the\nMigration.atomic attribute to False.
The SessionAuthenticationMiddleware class is removed. It provided no\nfunctionality since session authentication is unconditionally enabled in\nDjango 1.10.
The default HTTP error handlers (handler404, etc.) are now callables\ninstead of dotted Python path strings. Django favors callable references\nsince they provide better performance and debugging experience.
RedirectView no longer silences\nNoReverseMatch if the pattern_name doesn’t exist.
When USE_L10N is off, FloatField and\nDecimalField now respect DECIMAL_SEPARATOR\nand THOUSAND_SEPARATOR during validation. For example, with the\nsettings:
USE_L10N = False\nUSE_THOUSAND_SEPARATOR = True\nDECIMAL_SEPARATOR = ","\nTHOUSAND_SEPARATOR = "."\nan input of "1.345" is now converted to 1345 instead of 1.345.
Subclasses of AbstractBaseUser are no\nlonger required to implement get_short_name() and get_full_name().\n(The base implementations that raise NotImplementedError are removed.)\ndjango.contrib.admin uses these methods if implemented but doesn’t\nrequire them. Third-party apps that use these methods may want to adopt a\nsimilar approach.
The FIRST_DAY_OF_WEEK and NUMBER_GROUPING format settings are now\nkept as integers in JavaScript and JSON i18n view outputs.
assertNumQueries() now ignores\nconnection configuration queries. Previously, if a test opened a new database\nconnection, those queries could be included as part of the\nassertNumQueries() count.
The default size of the Oracle test tablespace is increased from 20M to 50M\nand the default autoextend size is increased from 10M to 25M.
To improve performance when streaming large result sets from the database,\nQuerySet.iterator() now fetches 2000 rows at a time instead of 100.\nThe old behavior can be restored using the chunk_size parameter. For\nexample:
Book.objects.iterator(chunk_size=100)\nProviding unknown package names in the packages argument of the\nJavaScriptCatalog view now raises ValueError\ninstead of passing silently.
A model instance’s primary key now appears in the default Model.__str__()\nmethod, e.g. Question object (1).
makemigrations now detects changes to the model field limit_choices_to\noption. Add this to your existing migrations or accept an auto-generated\nmigration for fields that use it.
Performing queries that require automatic spatial transformations now raises NotImplementedError\non MySQL instead of silently using non-transformed geometries.
django.core.exceptions.DjangoRuntimeWarning is removed. It was only used\nin the cache backend as an intermediate class in CacheKeyWarning’s\ninheritance of RuntimeWarning.
Renamed BaseExpression._output_field to output_field. You may need\nto update custom expressions.
In older versions, forms and formsets combine their Media with widget\nMedia by concatenating the two. The combining now tries to preserve\nthe relative order of elements in each list.\nMediaOrderConflictWarning is issued if the order can’t be preserved.
django.contrib.gis.gdal.OGRException is removed. It’s been an alias for\nGDALException since Django 1.8.
Support for GEOS 3.3.x is dropped.
The way data is selected for GeometryField is changed to improve\nperformance, and in raw SQL queries, those fields must now be wrapped in\nconnection.ops.select. See the Raw queries note in\nthe GIS tutorial for an example.
context argument of Field.from_db_value() and Expression.convert_value()Link to this heading#The context argument of Field.from_db_value() and\nExpression.convert_value() is unused as it’s always an empty dictionary.\nThe signature of both methods is now:
(self, value, expression, connection)\ninstead of:
\n(self, value, expression, connection, context)\nSupport for the old signature in custom fields and expressions remains until\nDjango 3.0.
\nThe django.db.backends.postgresql_psycopg2 module is deprecated in favor\nof django.db.backends.postgresql. It’s been an alias since Django 1.9.\nThis only affects code that imports from the module directly. The\nDATABASES setting can still use\n'django.db.backends.postgresql_psycopg2', though you can simplify that by\nusing the 'django.db.backends.postgresql' name added in Django 1.9.
django.shortcuts.render_to_response() is deprecated in favor of\ndjango.shortcuts.render(). render() takes the same arguments\nexcept that it also requires a request.
The DEFAULT_CONTENT_TYPE setting is deprecated. It doesn’t interact well\nwith third-party apps and is obsolete since HTML5 has mostly superseded\nXHTML.
HttpRequest.xreadlines() is deprecated in favor of iterating over the\nrequest.
The field_name keyword argument to QuerySet.earliest() and\nQuerySet.latest() is deprecated in favor of passing the field\nnames as arguments. Write .earliest('pub_date') instead of\n.earliest(field_name='pub_date').
These features have reached the end of their deprecation cycle and are removed\nin Django 2.0.
\nSee Features deprecated in 1.9 for details on these changes, including how\nto remove usage of these features.
\nThe weak argument to django.dispatch.signals.Signal.disconnect() is\nremoved.
django.db.backends.base.BaseDatabaseOperations.check_aggregate_support()\nis removed.
The django.forms.extras package is removed.
The assignment_tag helper is removed.
The host argument to SimpleTestCase.assertsRedirects() is removed.\nThe compatibility layer which allows absolute URLs to be considered equal to\nrelative ones when the path is identical is also removed.
Field.rel and Field.remote_field.to are removed.
The on_delete argument for ForeignKey and OneToOneField is now\nrequired in models and migrations. Consider squashing migrations so that you\nhave fewer of them to update.
django.db.models.fields.add_lazy_relation() is removed.
When time zone support is enabled, database backends that don’t support time\nzones no longer convert aware datetimes to naive values in UTC anymore when\nsuch values are passed as parameters to SQL queries executed outside of the\nORM, e.g. with cursor.execute().
django.contrib.auth.tests.utils.skipIfCustomUser() is removed.
The GeoManager and GeoQuerySet classes are removed.
The django.contrib.gis.geoip module is removed.
The supports_recursion check for template loaders is removed from:
django.template.engine.Engine.find_template()
django.template.loader_tags.ExtendsNode.find_template()
django.template.loaders.base.Loader.supports_recursion()
django.template.loaders.cached.Loader.supports_recursion()
The load_template and load_template_sources template loader methods\nare removed.
The template_dirs argument for template loaders is removed:
django.template.loaders.base.Loader.get_template()
django.template.loaders.cached.Loader.cache_key()
django.template.loaders.cached.Loader.get_template()
django.template.loaders.cached.Loader.get_template_sources()
django.template.loaders.filesystem.Loader.get_template_sources()
django.template.loaders.base.Loader.__call__() is removed.
Support for custom error views that don’t accept an exception parameter\nis removed.
The mime_type attribute of django.utils.feedgenerator.Atom1Feed and\ndjango.utils.feedgenerator.RssFeed is removed.
The app_name argument to include() is removed.
Support for passing a 3-tuple (including admin.site.urls) as the first\nargument to include() is removed.
Support for setting a URL instance namespace without an application namespace\nis removed.
Field._get_val_from_obj() is removed.
django.template.loaders.eggs.Loader is removed.
The current_app parameter to the contrib.auth function-based views is\nremoved.
The callable_obj keyword argument to\nSimpleTestCase.assertRaisesMessage() is removed.
Support for the allow_tags attribute on ModelAdmin methods is\nremoved.
The enclosure keyword argument to SyndicationFeed.add_item() is\nremoved.
The django.template.loader.LoaderOrigin and\ndjango.template.base.StringOrigin aliases for\ndjango.template.base.Origin are removed.
See Features deprecated in 1.10 for details on these changes.
\nThe makemigrations --exit option is removed.
Support for direct assignment to a reverse foreign key or many-to-many\nrelation is removed.
The get_srid() and set_srid() methods of\ndjango.contrib.gis.geos.GEOSGeometry are removed.
The get_x(), set_x(), get_y(), set_y(), get_z(), and\nset_z() methods of django.contrib.gis.geos.Point are removed.
The get_coords() and set_coords() methods of\ndjango.contrib.gis.geos.Point are removed.
The cascaded_union property of django.contrib.gis.geos.MultiPolygon\nis removed.
django.utils.functional.allow_lazy() is removed.
The shell --plain option is removed.
The django.core.urlresolvers module is removed in favor of its new\nlocation, django.urls.
CommaSeparatedIntegerField is removed, except for support in historical\nmigrations.
The template Context.has_key() method is removed.
Support for the django.core.files.storage.Storage.accessed_time(),\ncreated_time(), and modified_time() methods is removed.
Support for query lookups using the model name when\nMeta.default_related_name is set is removed.
The MySQL __search lookup is removed.
The shim for supporting custom related manager classes without a\n_apply_rel_filters() method is removed.
Using User.is_authenticated() and User.is_anonymous() as methods\nrather than properties is no longer supported.
The Model._meta.virtual_fields attribute is removed.
The keyword arguments virtual_only in Field.contribute_to_class() and\nvirtual in Model._meta.add_field() are removed.
The javascript_catalog() and json_catalog() views are removed.
django.contrib.gis.utils.precision_wkt() is removed.
In multi-table inheritance, implicit promotion of a OneToOneField to a\nparent_link is removed.
Support for Widget._format_value() is removed.
FileField methods get_directory_name() and get_filename() are\nremoved.
The mark_for_escaping() function and the classes it uses: EscapeData,\nEscapeBytes, EscapeText, EscapeString, and EscapeUnicode are\nremoved.
The escape filter now uses django.utils.html.conditional_escape().
Manager.use_for_related_fields is removed.
Model Manager inheritance follows MRO inheritance rules. The requirement\nto use Meta.manager_inheritance_from_future to opt-in to the behavior is\nremoved.
Support for old-style middleware using settings.MIDDLEWARE_CLASSES is\nremoved.