April 1, 2015
\nWelcome to Django 1.8!
\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.7 or older versions. We’ve\nalso begun the deprecation process for some features, and some features have reached the end of their\ndeprecation process and have been removed.
\nSee the How to upgrade Django to a newer version guide if you’re updating an existing\nproject.
\nDjango 1.8 has been designated as Django’s second long-term support\nrelease. It will receive security updates for at\nleast three years after its release. Support for the previous LTS, Django 1.4,\nwill end 6 months from the release date of Django 1.8.
\nDjango 1.8 requires Python 2.7, 3.2, 3.3, 3.4, or 3.5. We highly recommend\nand only officially support the latest release of each series.
\nDjango 1.8 is the first release to support Python 3.5.
\nDue to the end of upstream support for Python 3.2 in February 2016, we won’t\ntest Django 1.8.x on Python 3.2 after the end of 2016.
\nModel._meta APILink to this heading#Django now has a formalized API for Model._meta,\nproviding an officially supported way to retrieve fields and filter fields based on their attributes.
\nThe Model._meta object has been part of Django since the days of pre-0.96\n“Magic Removal” – it just wasn’t an official, stable API. In recognition of\nthis, we’ve endeavored to maintain backwards-compatibility with the old\nAPI endpoint where possible. However, API endpoints that aren’t part of the\nnew official API have been deprecated and will eventually be removed.
Django 1.8 defines a stable API for integrating template backends. It includes\nbuilt-in support for the Django template language and for\nJinja2. It supports rendering\ntemplates with multiple engines within the same project. Learn more about the\nnew features in the topic guide and check the\nupgrade instructions in older versions of the documentation.
Several features of the django-secure third-party library have been\nintegrated into Django. django.middleware.security.SecurityMiddleware\nprovides several security enhancements to the request/response cycle. The new\ncheck --deploy option allows you to check your production settings\nfile for ways to increase the security of your site.
Django now has a module with extensions for PostgreSQL specific features, such\nas ArrayField,\nHStoreField, Range Fields, and\nunaccent lookup. A full breakdown of the features is available\nin the documentation.
Django now has a UUIDField for storing\nuniversally unique identifiers. It is stored as the native uuid data type\non PostgreSQL and as a fixed length character field on other backends. There\nis a corresponding form field.
Django now has a DurationField for storing periods\nof time - modeled in Python by timedelta. It is\nstored in the native interval data type on PostgreSQL, as a INTERVAL\nDAY(9) TO SECOND(6) on Oracle, and as a bigint of microseconds on other\nbackends. Date and time related arithmetic has also been improved on all\nbackends. There is a corresponding form field.
Query Expressions allow you to create,\ncustomize, and compose complex SQL expressions. This has enabled annotate\nto accept expressions other than aggregates. Aggregates are now able to\nreference multiple fields, as well as perform arithmetic, similar to F()\nobjects. order_by() has also gained the\nability to accept expressions.
Conditional Expressions allow\nyou to use if … elif … else logic within\nqueries.
A collection of database functions is\nalso included with functionality such as\nCoalesce,\nConcat, and\nSubstr.
TestCase data setupLink to this heading#TestCase has been refactored to allow for data\ninitialization at the class level using transactions and savepoints. Database\nbackends which do not support transactions, like MySQL with the MyISAM storage\nengine, will still be able to run these tests but won’t benefit from the\nimprovements. Tests are now run within two nested\natomic() blocks: one for the whole class and one\nfor each test.
The class method\nTestCase.setUpTestData() adds\nthe ability to set up test data at the class level. Using this technique can\nspeed up the tests as compared to using setUp().
Fixture loading within TestCase is now performed once for the whole\nTestCase.
django.contrib.adminLink to this heading#ModelAdmin now has a\nhas_module_permission()\nmethod to allow limiting access to the module on the admin index page.
InlineModelAdmin now has an attribute\nshow_change_link that\nsupports showing a link to an inline object’s change form.
Use the new django.contrib.admin.RelatedOnlyFieldListFilter in\nModelAdmin.list_filter\nto limit the list_filter choices to foreign objects which are attached to\nthose from the ModelAdmin.
The ModelAdmin.delete_view() displays a summary of objects\nto be deleted on the deletion confirmation page.
The jQuery library embedded in the admin has been upgraded to version 1.11.2.
You can now specify AdminSite.site_url in order to display a link to the\nfront-end site.
You can now specify ModelAdmin.show_full_result_count to control whether\nor not the full count of objects should be displayed on a filtered admin\npage.
The AdminSite.password_change() method now has an extra_context\nparameter.
You can now control who may login to the admin site by overriding only\nAdminSite.has_permission() and\nAdminSite.login_form.\nThe base.html template has a new block usertools which contains the\nuser-specific header. A new context variable has_permission, which gets\nits value from has_permission(),\nindicates whether the user may access the site.
Foreign key dropdowns now have buttons for changing or deleting related\nobjects using a popup.
django.contrib.admindocsLink to this heading#reStructuredText is now parsed in model docstrings.
django.contrib.authLink to this heading#Authorization backends can now raise\nPermissionDenied in\nhas_perm()\nand has_module_perms()\nto short-circuit permission checking.
PasswordResetForm now\nhas a method send_mail()\nthat can be overridden to customize the mail to be sent.
The max_length of Permission.name has been increased from 50 to\n255 characters. Please run the database migration.
USERNAME_FIELD and\nREQUIRED_FIELDS now supports\nForeignKeys.
The default iteration count for the PBKDF2 password hasher has been\nincreased by 33%. This backwards compatible change will not affect users who\nhave subclassed django.contrib.auth.hashers.PBKDF2PasswordHasher to\nchange the default value.
django.contrib.gisLink to this heading#A new GeoJSON serializer is now\navailable.
It is now allowed to include a subquery as a geographic lookup argument, for\nexample\nCity.objects.filter(point__within=Country.objects.filter(continent='Africa').values('mpoly')).
The SpatiaLite backend now supports Collect and Extent aggregates\nwhen the database version is 3.0 or later.
The PostGIS 2 CREATE EXTENSION postgis and the SpatiaLite\nSELECT InitSpatialMetaData initialization commands are now automatically\nrun by migrate.
The GDAL interface now supports retrieving properties of\nraster (image) data file.
Compatibility shims for SpatialRefSys and GeometryColumns changed in\nDjango 1.2 have been removed.
All GDAL-related exceptions are now raised with GDALException. The former\nOGRException has been kept for backwards compatibility but should not be\nused any longer.
django.contrib.sessionsLink to this heading#Session cookie is now deleted after\nflush() is called.
django.contrib.sitemapsLink to this heading#The new Sitemap.i18n attribute\nallows you to generate a sitemap based on the LANGUAGES setting.
django.contrib.sitesLink to this heading#get_current_site() will now lookup\nthe current site based on request.get_host() if the SITE_ID setting is not\ndefined.
The default Site created when running\nmigrate now respects the SITE_ID setting (instead of always\nusing pk=1).
The incr() method of the\ndjango.core.cache.backends.locmem.LocMemCache backend is now thread-safe.
The max_age parameter of the\ndjango.core.signing.TimestampSigner.unsign() method now also accepts a\ndatetime.timedelta object.
The MySQL backend no longer strips microseconds from datetime values as\nMySQL 5.6.4 and up supports fractional seconds depending on the declaration\nof the datetime field (when DATETIME includes fractional precision\ngreater than 0). New datetime database columns created with Django 1.8 and\nMySQL 5.6.4 and up will support microseconds. See the MySQL database\nnotes for more details.
The MySQL backend no longer creates explicit indexes for foreign keys when\nusing the InnoDB storage engine, as MySQL already creates them automatically.
The Oracle backend no longer defines the connection_persists_old_columns\nfeature as True. Instead, Oracle will now include a cache busting clause\nwhen getting the description of a table.
Email backends now support the context manager\nprotocol for opening and closing connections.
The SMTP email backend now supports keyfile and certfile\nauthentication with the EMAIL_SSL_CERTFILE and\nEMAIL_SSL_KEYFILE settings.
The SMTP EmailBackend now supports\nsetting the timeout parameter with the EMAIL_TIMEOUT setting.
EmailMessage and EmailMultiAlternatives now\nsupport the reply_to parameter.
Storage.get_available_name() and\nStorage.save()\nnow take a max_length argument to implement storage-level maximum\nfilename length constraints. Filenames exceeding this argument will get\ntruncated. This prevents a database error when appending a unique suffix to a\nlong filename that already exists on the storage. See the deprecation\nnote about adding this argument to your custom\nstorage classes.
Form widgets now render attributes with a value of True or False\nas HTML5 boolean attributes.
The new has_error() method allows checking\nif a specific error has happened.
If required_css_class is defined on a form, then\nthe <label> tags for required fields will have this class present in its\nattributes.
The rendering of non-field errors in unordered lists (<ul>) now includes\nnonfield in its list of classes to distinguish them from field-specific\nerrors.
Field now accepts a\nlabel_suffix argument, which will override the\nform’s label_suffix. This enables customizing the\nsuffix on a per-field basis — previously it wasn’t possible to override\na form’s label_suffix while using shortcuts such\nas {{ form.as_p }} in templates.
SelectDateWidget now accepts an\nempty_label argument, which will\noverride the top list choice label when DateField\nis not required.
After an ImageField has been cleaned and validated,\nthe UploadedFile object will have an additional image attribute\ncontaining the Pillow Image instance used to check if the file was a\nvalid image. It will also update UploadedFile.content_type with the\nimage’s content type as determined by Pillow.
You can now pass a callable that returns an iterable of choices when\ninstantiating a ChoiceField.
Generic views that use\nMultipleObjectMixin may now specify the\nordering applied to the\nqueryset by setting\nordering or overriding\nget_ordering().
The new SingleObjectMixin.query_pk_and_slug\nattribute allows changing the behavior of\nget_object()\nso that it’ll perform its lookup using both the primary key and the slug.
The get_form() method doesn’t\nrequire a form_class to be provided anymore. If not provided\nform_class defaults to\nget_form_class().
Placeholders in ModelFormMixin.success_url now support the\nPython str.format() syntax. The legacy %(<foo>)s syntax is still\nsupported but will be removed in Django 1.10.
FORMAT_MODULE_PATH can now be a list of strings representing\nmodule paths. This allows importing several format modules from different\nreusable apps. It also allows overriding those custom formats in your main\nDjango project.
The django.utils.log.AdminEmailHandler class now has a\nsend_mail() method to make it more\nsubclass friendly.
Database connections are now always closed after a management command called\nfrom the command line has finished doing its job.
Commands from alternate package formats like eggs are now also discovered.
The new dumpdata --output option allows specifying a file to which\nthe serialized data is written.
The new makemessages --exclude and compilemessages\n--exclude options allow excluding specific locales from processing.
compilemessages now has a --use-fuzzy or -f option which\nincludes fuzzy translations into compiled files.
The loaddata --ignorenonexistent option now ignores data for models\nthat no longer exist.
runserver now uses daemon threads for faster reloading.
inspectdb now outputs Meta.unique_together. It is also able to\nintrospect AutoField for MySQL and PostgreSQL\ndatabases.
When calling management commands with options using\ncall_command(), the option name can match the\ncommand line option name (without the initial dashes) or the final option\ndestination variable name, but in either case, the resulting option received\nby the command is now always the dest name specified in the command\noption definition (as long as the command uses the argparse module).
The dbshell command now supports MySQL’s optional SSL certificate\nauthority setting (--ssl-ca).
The new makemigrations --name allows giving the migration(s) a\ncustom name instead of a generated one.
The loaddata command now prevents repeated fixture loading. If\nFIXTURE_DIRS contains duplicates or a default fixture directory\npath (app_name/fixtures), an exception is raised.
The new makemigrations --exit option allows exiting with an error\ncode if no migrations are created.
The new showmigrations command allows listing all migrations and\ntheir dependencies in a project.
The CommonMiddleware.response_redirect_class\nattribute allows you to customize the redirects issued by the middleware.
A debug message will be logged to the django.request logger when a\nmiddleware raises a MiddlewareNotUsed\nexception in DEBUG mode.
The RunSQL operation can now handle\nparameters passed to the SQL statements.
It is now possible to have migrations (most probably data migrations) for applications without models.
Migrations can now serialize model managers as part of the model state.
A generic mechanism to handle the deprecation of model fields was added.
The RunPython.noop()\nand RunSQL.noop class\nmethod/attribute were added to ease in making RunPython and RunSQL\noperations reversible.
The migration operations RunPython\nand RunSQL now call the\nallow_migrate() method of database routers. The router can use the\nnewly introduced app_label and hints arguments to make a routing\ndecision. To take advantage of this feature you need to update the router to\nthe new allow_migrate signature, see the deprecation section for more details.
Django now logs at most 9000 queries in connections.queries, in order\nto prevent excessive memory usage in long-running processes in debug mode.
There is now a model Meta option to define a\ndefault related name\nfor all relational fields of a model.
Pickling models and querysets across different versions of Django isn’t\nofficially supported (it may work, but there’s no guarantee). An extra\nvariable that specifies the current Django version is now added to the\npickled state of models and querysets, and Django raises a RuntimeWarning\nwhen these objects are unpickled in a different version than the one in\nwhich they were pickled.
Added Model.from_db() which\nDjango uses whenever objects are loaded using the ORM. The method allows\ncustomizing model loading behavior.
extra(select={...}) now allows you to escape a literal %s sequence\nusing %%s.
Custom Lookups can now be registered using\na decorator pattern.
The new Transform.bilateral\nattribute allows creating bilateral transformations. These transformations\nare applied to both lhs and rhs when used in a lookup expression,\nproviding opportunities for more sophisticated lookups.
SQL special characters (, %, _) are now escaped properly when a pattern\nlookup (e.g. contains, startswith, etc.) is used with an F()\nexpression as the right-hand side. In those cases, the escaping is performed\nby the database, which can lead to somewhat complex queries involving nested\nREPLACE function calls.
You can now refresh model instances by using Model.refresh_from_db().
You can now get the set of deferred fields for a model using\nModel.get_deferred_fields().
Model field default’s are now used when primary key field’s are set to\nNone.
Exceptions from the (receiver, exception) tuples returned by\nSignal.send_robust() now have\ntheir traceback attached as a __traceback__ attribute.
The environ argument, which contains the WSGI environment structure from\nthe request, was added to the request_started\nsignal.
You can now import the setting_changed() signal\nfrom django.core.signals to avoid loading django.test in non-test\nsituations. Django no longer does so itself.
register can now be used as a function.
urlize now supports domain-only links that include characters\nafter the top-level domain (e.g. djangoproject.com/ and\ndjangoproject.com/download/).
urlize doesn’t treat exclamation marks at the end of a domain or\nits query string as part of the URL (the URL in e.g. 'djangoproject.com!\nis djangoproject.com)
Added a locmem.Loader\nclass that loads Django templates from a Python dictionary.
The now tag can now store its output in a context variable with the\nusual syntax: {% now 'j n Y' as varname %}.
WSGIRequest now respects paths starting with //.
The HttpRequest.build_absolute_uri() method now handles paths\nstarting with // correctly.
If DEBUG is True and a request raises a\nSuspiciousOperation, the response will be\nrendered with a detailed error page.
The query_string argument of QueryDict is now\noptional, defaulting to None, so a blank QueryDict can now be\ninstantiated with QueryDict() instead of QueryDict(None) or\nQueryDict('').
The GET and POST attributes of an HttpRequest\nobject are now QueryDicts rather than dictionaries,\nand the FILES attribute is now a MultiValueDict.\nThis brings this class into line with the documentation and with\nWSGIRequest.
The HttpResponse.charset attribute\nwas added.
WSGIRequestHandler now follows RFC in converting URI to IRI, using\nuri_to_iri().
The HttpRequest.get_full_path() method now escapes unsafe characters\nfrom the path portion of a Uniform Resource Identifier (URI) properly.
HttpResponse now implements a few additional methods\nlike getvalue() so that instances can be used\nas stream objects.
The new HttpResponse.setdefault() method allows setting a header unless\nit has already been set.
You can use the new FileResponse to stream files.
The condition() decorator for\nconditional view processing now supports the If-unmodified-since header.
The RequestFactory.trace()\nand Client.trace() methods were\nimplemented, allowing you to create TRACE requests in your tests.
The count argument was added to\nassertTemplateUsed(). This allows you to\nassert that a template was rendered a specific number of times.
The new assertJSONNotEqual() assertion\nallows you to test that two JSON fragments are not equal.
Added options to the test command to preserve the test database\n(--keepdb), to run the test cases in reverse order\n(--reverse), and to enable SQL logging for failing\ntests (--debug-sql).
Added the resolver_match attribute to test\nclient responses.
Added several settings that allow customization of test tablespace parameters\nfor Oracle: DATAFILE, DATAFILE_TMP,\nDATAFILE_MAXSIZE and DATAFILE_TMP_MAXSIZE.
The override_settings() decorator can now affect the\nmaster router in DATABASE_ROUTERS.
Added test client support for file uploads with file-like objects.
A shared cache is now used when testing with an SQLite in-memory database\nwhen using Python 3.4+ and SQLite 3.7.13+. This allows sharing the database\nbetween threads.
URLValidator now supports IPv6 addresses,\nUnicode domains, and URLs containing authentication data.
Assigning unsaved objects to a ForeignKey,\nGenericForeignKey, and\nOneToOneField now raises a ValueError.
Previously, the assignment of an unsaved object would be silently ignored.\nFor example:
\n>>> book = Book.objects.create(name="Django")\n>>> book.author = Author(name="John")\n>>> book.author.save()\n>>> book.save()\n\n>>> Book.objects.get(name="Django")\n>>> book.author\n>>>\nNow, an error will be raised to prevent data loss:
\n>>> book.author = Author(name="john")\nTraceback (most recent call last):\n...\nValueError: Cannot assign "<Author: John>": "Author" instance isn't saved in the database.\nIf you require allowing the assignment of unsaved instances (the old behavior)\nand aren’t concerned about the data loss possibility (e.g. you never save the\nobjects to the database), you can disable this check by using the\nForeignKey.allow_unsaved_instance_assignment attribute. (This attribute was\nremoved in 1.8.4 as it’s no longer relevant.)
If you have written a custom management command that only accepts positional\narguments and you didn’t specify the args command variable, you might get\nan error like Error: unrecognized arguments: ..., as variable parsing is\nnow based on argparse which doesn’t implicitly accept positional\narguments. You can make your command backwards compatible by simply setting the\nargs class variable. However, if you don’t have to keep compatibility with\nolder Django versions, it’s better to implement the new\nadd_arguments() method as described\nin How to create custom django-admin commands.
The method to add custom arguments to the test management command through\nthe test runner has changed. Previously, you could provide an option_list\nclass variable on the test runner to add more arguments (à la\noptparse). Now to implement the same behavior, you have to create an\nadd_arguments(cls, parser) class method on the test runner and call\nparser.add_argument to add any custom arguments, as parser is now an\nargparse.ArgumentParser instance.
A field name that’s longer than the column name length supported by a database\ncan create problems. For example, with MySQL you’ll get an exception trying to\ncreate the column, and with PostgreSQL the column name is truncated by the\ndatabase (you may see a warning in the PostgreSQL logs).
\nA model check has been introduced to better alert users to this scenario before\nthe actual creation of database tables.
\nIf you have an existing model where this check seems to be a false positive,\nfor example on PostgreSQL where the name was already being truncated, simply\nuse db_column to specify the name that’s being\nused.
The check also applies to the columns generated in an implicit\nManyToManyField.through model. If you run into an issue there, use\nthrough to create an explicit model\nand then specify db_column on its column(s)\nas needed.
Querying for model lookups now checks if the object passed is of correct type\nand raises a ValueError if not. Previously, Django didn’t care if the\nobject was of correct type; it just used the object’s related field attribute\n(e.g. id) for the lookup. Now, an error is raised to prevent incorrect\nlookups:
>>> book = Book.objects.create(name="Django")\n>>> book = Book.objects.filter(author=book)\nTraceback (most recent call last):\n...\nValueError: Cannot query "<Book: Django>": Must be "Author" instance.\nEmailField.max_length increased to 254Link to this heading#The old default 75 character max_length was not capable of storing all\npossible RFC3696/5321-compliant email addresses. In order to store all\npossible valid email addresses, the max_length has been increased to 254\ncharacters. You will need to generate and apply database migrations for your\naffected models (or add max_length=75 if you wish to keep the length on\nyour current fields). A migration for\ndjango.contrib.auth.models.User.email is included.
The end of upstream support periods was reached in July 2014 for PostgreSQL\n8.4. As a consequence, Django 1.8 sets 9.0 as the minimum PostgreSQL version it\nofficially supports.
\nThis also includes dropping support for PostGIS 1.3 and 1.4 as these versions\nare not supported on versions of PostgreSQL later than 8.4.
\nDjango also now requires the use of Psycopg2 version 2.4.5 or higher (or 2.5+\nif you want to use django.contrib.postgres).
The end of upstream support periods was reached in January 2012 for MySQL 5.0\nand December 2013 for MySQL 5.1. As a consequence, Django 1.8 sets 5.5 as the\nminimum MySQL version it officially supports.
\nThe end of upstream support periods was reached in July 2010 for Oracle 9.2,\nJanuary 2012 for Oracle 10.1, and July 2013 for Oracle 10.2. As a consequence,\nDjango 1.8 sets 11.1 as the minimum Oracle version it officially supports.
\nEarlier versions of Django granted the CONNECT and RESOURCE roles to the test\nuser on Oracle. These roles have been deprecated, so Django 1.8 uses the\nspecific underlying privileges instead. This changes the privileges required\nof the main user for running tests (unless the project is configured to avoid\ncreating a test user). The exact privileges required now are detailed in\nOracle notes.
\nAbstractUser.last_login allows null valuesLink to this heading#The AbstractUser.last_login field now allows null values.\nPreviously, it defaulted to the time when the user was created which was\nmisleading if the user never logged in. If you are using the default user\n(django.contrib.auth.models.User), run the database migration included\nin contrib.auth.
If you are using a custom user model that inherits from AbstractUser,\nyou’ll need to run makemigrations and generate a migration for your\napp that contains that model. Also, if wish to set last_login to NULL\nfor users who haven’t logged in, you can run this query:
from django.db import models\nfrom django.contrib.auth import get_user_model\nfrom django.contrib.auth.models import AbstractBaseUser\n\nUserModel = get_user_model()\nif issubclass(UserModel, AbstractBaseUser):\n UserModel._default_manager.filter(last_login=models.F("date_joined")).update(\n last_login=None\n )\ndjango.contrib.gisLink to this heading#Support for GEOS 3.1 and GDAL 1.6 has been dropped.
Support for SpatiaLite < 2.4 has been dropped.
GIS-specific lookups have been refactored to use the\ndjango.db.models.Lookup API.
The default str representation of\nGEOSGeometry objects has been changed from\nWKT to EWKT format (including the SRID). As this representation is used in\nthe serialization framework, that means that dumpdata output will now\ncontain the SRID value of geometry objects.
TemplateResponse brought in line with renderLink to this heading#The TemplateResponse constructor is designed\nto be a drop-in replacement for the render() function.\nHowever, it had a slight incompatibility, in that for TemplateResponse,\ncontext data from the passed in context dictionary could be shadowed by context\ndata returned from context processors, whereas for render it was the other\nway around. This was a bug, and the behavior of render is more appropriate,\nsince it allows the globally defined context processors to be overridden\nlocally in the view. If you were relying on the fact context data in a\nTemplateResponse could be overridden using a context processor, you will\nneed to change your code.
setUpClass / tearDownClass in test casesLink to this heading#The decorators override_settings() and\nmodify_settings() now act at the class level when used as\nclass decorators. As a consequence, when overriding setUpClass() or\ntearDownClass(), the super implementation should always be called.
django.contrib.formtoolsLink to this heading#The formtools contrib app has been moved to a separate package and the\nrelevant documentation pages have been updated or removed.
\nThe new package is available on GitHub and on PyPI.
\nDjango previously closed database connections between each test within a\nTestCase. This is no longer the case as Django now wraps the whole\nTestCase within a transaction. If some of your tests relied on the old\nbehavior, you should have them inherit from TransactionTestCase instead.
django.template namespaceLink to this heading#If you’ve been relying on private APIs exposed in the django.template\nmodule, you may have to import them from django.template.base instead.
Also private APIs django.template.base.compile_string(),\ndjango.template.loader.find_template(), and\ndjango.template.loader.get_template_from_string() were removed.
model attribute on private model relationsLink to this heading#In earlier versions of Django, on a model with a reverse foreign key\nrelationship (for example), model._meta.get_all_related_objects() returned\nthe relationship as a django.db.models.related.RelatedObject with the\nmodel attribute set to the source of the relationship. Now, this method\nreturns the relationship as django.db.models.fields.related.ManyToOneRel\n(private API RelatedObject has been removed), and the model attribute\nis set to the target of the relationship instead of the source. The source\nmodel is accessible on the related_model attribute instead.
Consider this example from the tutorial in Django 1.8:
\n>>> p = Poll.objects.get(pk=1)\n>>> p._meta.get_all_related_objects()\n[<ManyToOneRel: polls.choice>]\n>>> p._meta.get_all_related_objects()[0].model\n<class 'polls.models.Poll'>\n>>> p._meta.get_all_related_objects()[0].related_model\n<class 'polls.models.Choice'>\nand compare it to the behavior on older versions:
\n>>> p._meta.get_all_related_objects()\n[<RelatedObject: polls:choice related to poll>]\n>>> p._meta.get_all_related_objects()[0].model\n<class 'polls.models.Choice'>\nTo access the source model, you can use a pattern like this to write code that\nwill work with both Django 1.8 and older versions:
\nfor relation in opts.get_all_related_objects():\n to_model = getattr(relation, "related_model", relation.model)\nAlso note that get_all_related_objects() is deprecated in 1.8.
The following changes to the database backend API are documented to assist\nthose writing third-party backends in updating their code:
\nBaseDatabaseXXX classes have been moved to django.db.backends.base.\nPlease import them from the new locations:
from django.db.backends.base.base import BaseDatabaseWrapper\nfrom django.db.backends.base.client import BaseDatabaseClient\nfrom django.db.backends.base.creation import BaseDatabaseCreation\nfrom django.db.backends.base.features import BaseDatabaseFeatures\nfrom django.db.backends.base.introspection import BaseDatabaseIntrospection\nfrom django.db.backends.base.introspection import FieldInfo, TableInfo\nfrom django.db.backends.base.operations import BaseDatabaseOperations\nfrom django.db.backends.base.schema import BaseDatabaseSchemaEditor\nfrom django.db.backends.base.validation import BaseDatabaseValidation\nThe data_types, data_types_suffix, and\ndata_type_check_constraints attributes have moved from the\nDatabaseCreation class to DatabaseWrapper.
The SQLCompiler.as_sql() method now takes a subquery parameter\n(#24164).
The BaseDatabaseOperations.date_interval_sql() method now only takes a\ntimedelta parameter.
django.contrib.adminLink to this heading#AdminSite no longer takes an app_name argument and its app_name\nattribute has been removed. The application name is always admin (as\nopposed to the instance name which you can still customize using\nAdminSite(name="...")).
The ModelAdmin.get_object() method (private API) now takes a third\nargument named from_field in order to specify which field should match\nthe provided object_id.
The ModelAdmin.response_delete() method\nnow takes a second argument named obj_id which is the serialized\nidentifier used to retrieve the object before deletion.
django.template.defaultfiltersLink to this heading#In order to make built-in template filters that output HTML “safe by default”\nwhen calling them in Python code, the following functions in\ndjango.template.defaultfilters have been changed to automatically escape\ntheir input value:
join
linebreaksbr
linebreaks_filter
linenumbers
unordered_list
urlize
urlizetrunc
You can revert to the old behavior by specifying autoescape=False if you\nare passing trusted content. This change doesn’t have any effect when using\nthe corresponding filters in templates.
connections.queries is now a read-only attribute.
Database connections are considered equal only if they’re the same object.\nThey aren’t hashable any more.
GZipMiddleware used to disable compression\nfor some content types when the request is from Internet Explorer, in order\nto work around a bug in IE6 and earlier. This behavior could affect\nperformance on IE7 and later. It was removed.
URLField.to_python no longer adds a trailing slash to pathless URLs.
The length template filter now returns 0 for an undefined\nvariable, rather than an empty string.
ForeignKey.default_error_message['invalid'] has been changed from\n'%(model)s instance with pk %(pk)r does not exist.' to\n'%(model)s instance with %(field)s %(value)r does not exist.' If you are\nusing this message in your own code, please update the list of interpolated\nparameters. Internally, Django will continue to provide the\npk parameter in params for backwards compatibility.
UserCreationForm.error_messages['duplicate_username'] is no longer used.\nIf you wish to customize that error message, override it on the form using the 'unique' key in\nMeta.error_messages['username'] or, if you have a custom form field for\n'username', using the 'unique' key in its\nerror_messages argument.
The block usertools in the base.html template of\ndjango.contrib.admin now requires the has_permission context\nvariable to be set. If you have any custom admin views that use this\ntemplate, update them to pass AdminSite.has_permission() as this new variable’s\nvalue or simply include AdminSite.each_context(request) in the context.
Internal changes were made to the ClearableFileInput\nwidget to allow more customization. The undocumented url_markup_template\nattribute was removed in favor of template_with_initial.
For consistency with other major vendors, the en_GB locale now has Monday\nas the first day of the week.
Seconds have been removed from any locales that had them in TIME_FORMAT,\nDATETIME_FORMAT, or SHORT_DATETIME_FORMAT.
The default max size of the Oracle test tablespace has increased from 300M\n(or 200M, before 1.7.2) to 500M.
reverse() and reverse_lazy() now return Unicode strings instead of\nbytestrings.
The CacheClass shim has been removed from all cache backends.\nThese aliases were provided for backwards compatibility with Django 1.3.\nIf you are still using them, please update your project to use the real\nclass name found in the BACKEND key of the\nCACHES setting.
By default, call_command() now always skips the\ncheck framework (unless you pass it skip_checks=False).
When iterating over lines, File now uses\nuniversal newlines. The following are recognized as ending a\nline: the Unix end-of-line convention '\\n', the Windows convention\n'\\r\\n', and the old Macintosh convention '\\r'.
The Memcached cache backends MemcachedCache and PyLibMCCache will\ndelete a key if set() fails. This is necessary to ensure the cache_db\nsession store always fetches the most current session data.
Private APIs override_template_loaders and override_with_test_loader\nin django.test.utils were removed. Override TEMPLATES with\noverride_settings instead.
Warnings from the MySQL database backend are no longer converted to\nexceptions when DEBUG is True.
HttpRequest now has a simplified repr (e.g.\n<WSGIRequest: GET '/somepath/'>). This won’t change the behavior of\nthe SafeExceptionReporterFilter class.
Class-based views that use ModelFormMixin\nwill raise an ImproperlyConfigured exception\nwhen both the fields and form_class attributes are specified.\nPreviously, fields was silently ignored.
When following redirects, the test client now raises\nRedirectCycleError if it detects a loop or hits a\nmaximum redirect limit (rather than passing silently).
Translatable strings set as the default parameter of the field are cast\nto concrete strings later, so the return type of Field.get_default() is\ndifferent in some cases. There is no change to default values which are the\nresult of a callable.
GenericIPAddressField.empty_strings_allowed is now False. Database\nbackends that interpret empty strings as null (only Oracle among the backends\nthat Django includes) will no longer convert null values back to an empty\nstring. This is consistent with other backends.
When the BaseCommand.leave_locale_alone\nattribute is False, translations are now deactivated instead of forcing\nthe “en-us” locale. In the case your models contained non-English strings and\nyou counted on English translations to be activated in management commands,\nthis will not happen any longer. It might be that new database migrations are\ngenerated (once) after migrating to 1.8.
django.utils.translation.get_language() now returns None instead\nof LANGUAGE_CODE when translations are temporarily deactivated.
When a translation doesn’t exist for a specific literal, the fallback is now\ntaken from the LANGUAGE_CODE language (instead of from the\nuntranslated msgid message).
The name field of django.contrib.contenttypes.models.ContentType\nhas been removed by a migration and replaced by a property. That means it’s\nnot possible to query or filter a ContentType by this field any longer.
Be careful if you upgrade to Django 1.8 and skip Django 1.7. If you run\nmanage.py migrate --fake, this migration will be skipped and you’ll see\na RuntimeError: Error creating new content types. exception because the\nname column won’t be dropped from the database. Use manage.py migrate\n--fake-initial to fake only the initial migration instead.
The new migrate --fake-initial option allows faking initial\nmigrations. In 1.7, initial migrations were always automatically faked if all\ntables created in an initial migration already existed.
An app without migrations with a ForeignKey to an app with migrations\nmay now result in a foreign key constraint error when migrating the database\nor running tests. In Django 1.7, this could fail silently and result in a\nmissing constraint. To resolve the error, add migrations to the app without\nthem.
django.db.models.options.OptionsLink to this heading#As part of the formalization of the Model._meta API (from the\ndjango.db.models.options.Options class), a number of methods have been\ndeprecated and will be removed in Django 1.10:
get_all_field_names()
get_all_related_objects()
get_all_related_objects_with_model()
get_all_related_many_to_many_objects()
get_all_related_m2m_objects_with_model()
get_concrete_fields_with_model()
get_field_by_name()
get_fields_with_model()
get_m2m_with_model()
django.conf.urls.patterns()Link to this heading#In the olden days of Django, it was encouraged to reference views as strings\nin urlpatterns:
urlpatterns = patterns(\n "",\n url("^$", "myapp.views.myview"),\n)\nand Django would magically import myapp.views.myview internally and turn\nthe string into a real function reference. In order to reduce repetition when\nreferencing many views from the same module, the patterns() function takes\na required initial prefix argument which is prepended to all\nviews-as-strings in that set of urlpatterns:
urlpatterns = patterns(\n "myapp.views",\n url("^$", "myview"),\n url("^other/$", "otherview"),\n)\nIn the modern era, we have updated the tutorial to instead recommend importing\nyour views module and referencing your view functions (or classes) directly.\nThis has a number of advantages, all deriving from the fact that we are using\nnormal Python in place of “Django String Magic”: the errors when you mistype a\nview name are less obscure, IDEs can help with autocompletion of view names,\netc.
\nSo these days, the above use of the prefix arg is much more likely to be\nwritten (and is better written) as:
from myapp import views\n\nurlpatterns = patterns(\n "",\n url("^$", views.myview),\n url("^other/$", views.otherview),\n)\nThus patterns() serves little purpose and is a burden when teaching new\nusers (answering the newbie’s question “why do I need this empty string as the\nfirst argument to patterns()?”). For these reasons, we are deprecating it.\nUpdating your code is as simple as ensuring that urlpatterns is a list of\ndjango.conf.urls.url() instances. For example:
from django.conf.urls import url\nfrom myapp import views\n\nurlpatterns = [\n url("^$", views.myview),\n url("^other/$", views.otherview),\n]\nview to django.conf.urls.url()Link to this heading#Related to the previous item, referencing views as strings in the url()\nfunction is deprecated. Pass the callable view as described in the previous\nsection instead.
django.core.context_processorsLink to this heading#Built-in template context processors have been moved to\ndjango.template.context_processors.
django.test.SimpleTestCase.urlsLink to this heading#The attribute SimpleTestCase.urls for specifying URLconf configuration in\ntests has been deprecated and will be removed in Django 1.10. Use\n@override_settings(ROOT_URLCONF=...)\ninstead.
prefix argument to i18n_patterns()Link to this heading#Related to the previous item, the prefix argument to\ndjango.conf.urls.i18n.i18n_patterns() has been deprecated. Simply pass a\nlist of django.conf.urls.url() instances instead.
for template tagLink to this heading#Using an incorrect count of unpacked values in for tag will raise an\nexception rather than fail silently in Django 1.10.
reverse() and urlLink to this heading#Reversing URLs by Python path is an expensive operation as it causes the\npath being reversed to be imported. This behavior has also resulted in a\nsecurity issue. Use named URL patterns\nfor reversing instead.
\nIf you are using django.contrib.sitemaps, add the name argument to\nthe url that references django.contrib.sitemaps.views.sitemap():
from django.contrib.sitemaps.views import sitemap\n\nurl(\n r"^sitemap\\.xml$",\n sitemap,\n {"sitemaps": sitemaps},\n name="django.contrib.sitemaps.views.sitemap",\n)\nto ensure compatibility when reversing by Python path is removed in Django\n1.10.
\nSimilarly for GIS sitemaps, add\nname='django.contrib.gis.sitemaps.views.kml' or\nname='django.contrib.gis.sitemaps.views.kmz'.
If you are using a Python path for the LOGIN_URL or\nLOGIN_REDIRECT_URL setting, use the name of the url() instead.
The django.db.models.sql.aggregates and\ndjango.contrib.gis.db.models.sql.aggregates modules (both private API),\nhave been deprecated as django.db.models.aggregates and\ndjango.contrib.gis.db.models.aggregates are now also responsible for SQL\ngeneration. The old modules will be removed in Django 1.10.
If you were using the old modules, see Query Expressions for instructions on rewriting custom aggregates\nusing the new stable API.
\nThe following methods and properties of django.db.models.sql.query.Query\nhave also been deprecated and the backwards compatibility shims will be removed\nin Django 1.10:
Query.aggregates, replaced by annotations.
Query.aggregate_select, replaced by annotation_select.
Query.add_aggregate(), replaced by add_annotation().
Query.set_aggregate_mask(), replaced by set_annotation_mask().
Query.append_aggregate_mask(), replaced by append_annotation_mask().
Command.option_listLink to this heading#Management commands now use argparse instead of optparse to\nparse command-line arguments passed to commands. This also means that the way\nto add custom arguments to commands has changed: instead of extending the\noption_list class list, you should now override the\nadd_arguments() method and add\narguments through argparse.add_argument(). See\nthis example for more details.
django.core.management.NoArgsCommandLink to this heading#The class NoArgsCommand is now deprecated and will be removed in Django\n1.10. Use BaseCommand instead, which takes no\narguments by default.
The --list option of the migrate management command is\ndeprecated and will be removed in Django 1.10. Use showmigrations\ninstead.
cache_choices option of ModelChoiceField and ModelMultipleChoiceFieldLink to this heading#ModelChoiceField and\nModelMultipleChoiceField took an undocumented, untested\noption cache_choices. This cached querysets between multiple renderings of\nthe same Form object. This option is subject to an accelerated deprecation\nand will be removed in Django 1.9.
django.template.resolve_variable()Link to this heading#The function has been informally marked as “Deprecated” for some time. Replace\nresolve_variable(path, context) with\ndjango.template.Variable(path).resolve(context).
django.contrib.webdesignLink to this heading#It provided the lorem template tag which is now included in the\nbuilt-in tags. Simply remove 'django.contrib.webdesign' from\nINSTALLED_APPS and {% load webdesign %} from your templates.
error_message argument to django.forms.RegexFieldLink to this heading#It provided backwards compatibility for pre-1.0 code, but its functionality is\nredundant. Use Field.error_messages['invalid'] instead.
unordered_list syntaxLink to this heading#An older (pre-1.0), more restrictive and verbose input format for the\nunordered_list template filter has been deprecated:
["States", [["Kansas", [["Lawrence", []], ["Topeka", []]]], ["Illinois", []]]]\nUsing the new syntax, this becomes:
\n["States", ["Kansas", ["Lawrence", "Topeka"], "Illinois"]]\ndjango.forms.Field._has_changed()Link to this heading#Rename this method to has_changed() by removing the\nleading underscore. The old name will still work until Django 1.10.
is_admin_site argument to django.contrib.auth.views.password_reset()Link to this heading#It’s a legacy option that should no longer be necessary.
\nSubfieldBaseLink to this heading#django.db.models.fields.subclassing.SubfieldBase has been deprecated and\nwill be removed in Django 1.10. Historically, it was used to handle fields\nwhere type conversion was needed when loading from the database, but it was not\nused in .values() calls or in aggregates. It has been replaced with\nfrom_db_value().
The new approach doesn’t call the to_python()\nmethod on assignment as was the case with SubfieldBase. If you need that\nbehavior, reimplement the Creator class from Django’s source code\nin your project.
django.utils.checksumsLink to this heading#The django.utils.checksums module has been deprecated and will be removed\nin Django 1.10. The functionality it provided (validating checksum using the\nLuhn algorithm) was undocumented and not used in Django. The module has been\nmoved to the django-localflavor package (version 1.1+).
InlineAdminForm.original_content_type_idLink to this heading#The original_content_type_id attribute on InlineAdminForm has been\ndeprecated and will be removed in Django 1.10. Historically, it was used\nto construct the “view on site” URL. This URL is now accessible using the\nabsolute_url attribute of the form.
django.views.generic.edit.FormMixin.get_form()’s form_class argumentLink to this heading#FormMixin subclasses that override the get_form() method should make\nsure to provide a default value for the form_class argument since it’s\nnow optional.
get_template() with a ContextLink to this heading#The return type of get_template() has changed\nin Django 1.8: instead of a django.template.Template, it returns a\nTemplate instance whose exact type depends on which backend loaded it.
Both classes provide a render() method, however, the former takes a\ndjango.template.Context as an argument while the latter expects a\ndict. This change is enforced through a deprecation path for Django\ntemplates.
All this also applies to select_template().
Template and Context classes in template responsesLink to this heading#Some methods of SimpleTemplateResponse and\nTemplateResponse accepted\ndjango.template.Context and django.template.Template objects\nas arguments. They should now receive dict and backend-dependent\ntemplate objects respectively.
This also applies to the return types if you have subclassed either template\nresponse class.
\nCheck the template response API documentation\nfor details.
\ndictionary and context_instance arguments of rendering functionsLink to this heading#The following functions will no longer accept the dictionary and\ncontext_instance parameters in Django 1.10:
django.shortcuts.render()
django.shortcuts.render_to_response()
django.template.loader.render_to_string()
Use the context parameter instead. When dictionary is passed as a\npositional argument, which is the most common idiom, no changes are needed.
If you’re passing a Context in context_instance,\npass a dict in the context parameter instead. If you’re passing a\nRequestContext, pass the request separately in the\nrequest parameter.
dirs argument of template-finding functionsLink to this heading#The following functions will no longer accept a dirs parameter to override\nTEMPLATE_DIRS in Django 1.10:
django.shortcuts.render_to_response()
The parameter didn’t work consistently across different template loaders and\ndidn’t work for included templates.
\ndjango.template.loader.BaseLoaderLink to this heading#django.template.loader.BaseLoader was renamed to\ndjango.template.loaders.base.Loader. If you’ve written a custom template\nloader that inherits BaseLoader, you must inherit Loader instead.
django.test.utils.TestTemplateLoaderLink to this heading#Private API django.test.utils.TestTemplateLoader is deprecated in favor of\ndjango.template.loaders.locmem.Loader and will be removed in Django 1.9.
max_length argument on custom Storage classesLink to this heading#Storage subclasses should add max_length=None as a parameter to\nget_available_name() and/or\nsave() if they override either method.\nSupport for storages that do not accept this argument will be removed in\nDjango 1.10.
qn replaced by compilerLink to this heading#In previous Django versions, various internal ORM methods (mostly as_sql\nmethods) accepted a qn (for “quote name”) argument, which was a reference\nto a function that quoted identifiers for sending to the database. In Django\n1.8, that argument has been renamed to compiler and is now a full\nSQLCompiler instance. For backwards-compatibility, calling a\nSQLCompiler instance performs the same name-quoting that the qn\nfunction used to. However, this backwards-compatibility shim is immediately\ndeprecated: you should rename your qn arguments to compiler, and call\ncompiler.quote_name_unless_alias(...) where you previously called\nqn(...).
RedirectView.permanentLink to this heading#The default value of the RedirectView.permanent attribute will change from\nTrue to False in Django 1.9.
AuthenticationMiddleware without SessionAuthenticationMiddlewareLink to this heading#django.contrib.auth.middleware.SessionAuthenticationMiddleware was added in\nDjango 1.7. In Django 1.7.2, its functionality was moved to auth.get_user()\nand, for backwards compatibility, enabled only if\n'django.contrib.auth.middleware.SessionAuthenticationMiddleware' appears in\nMIDDLEWARE_CLASSES.
In Django 1.10, session verification will be enabled regardless of whether or\nnot SessionAuthenticationMiddleware is enabled (at which point\nSessionAuthenticationMiddleware will have no significance). You can add it\nto your MIDDLEWARE_CLASSES sometime before then to opt-in. Please read the\nupgrade considerations first.
django.contrib.sitemaps.FlatPageSitemapLink to this heading#django.contrib.sitemaps.FlatPageSitemap has moved to\ndjango.contrib.flatpages.sitemaps.FlatPageSitemap. The old import location\nis deprecated and will be removed in Django 1.9.
ssi template tagLink to this heading#The ssi template tag allows files to be included in a template by\nabsolute path. This is of limited use in most deployment situations, and\nthe include tag often makes more sense. This tag is now deprecated and\nwill be removed in Django 1.10.
= as comparison operator in if template tagLink to this heading#Using a single equals sign with the {% if %} template tag for equality\ntesting was undocumented and untested. It’s now deprecated in favor of ==.
%(<foo>)s syntax in ModelFormMixin.success_urlLink to this heading#The legacy %(<foo>)s syntax in ModelFormMixin.success_url is deprecated and\nwill be removed in Django 1.10.
GeoQuerySet aggregate methodsLink to this heading#The collect(), extent(), extent3d(), make_line(), and\nunionagg() aggregate methods are deprecated and should be replaced by their\nfunction-based aggregate equivalents (Collect, Extent, Extent3D,\nMakeLine, and Union).
allow_migrate router methodLink to this heading#The signature of the allow_migrate() method of database routers has\nchanged from allow_migrate(db, model) to\nallow_migrate(db, app_label, model_name=None, **hints).
When model_name is set, the value that was previously given through the\nmodel positional argument may now be found inside the hints dictionary\nunder the key 'model'.
After switching to the new signature the router will also be called by the\nRunPython and\nRunSQL operations.
These features have reached the end of their deprecation cycle and are removed\nin Django 1.8. See Features deprecated in 1.6 for details, including how to\nremove usage of these features.
\ndjango.contrib.comments is removed.
The following transaction management APIs are removed:
\nTransactionMiddleware
the decorators and context managers autocommit, commit_on_success,\nand commit_manually, defined in django.db.transaction
the functions commit_unless_managed and rollback_unless_managed,\nalso defined in django.db.transaction
the TRANSACTIONS_MANAGED setting
The cycle and firstof template tags auto-escape their\narguments.
The SEND_BROKEN_LINK_EMAILS setting is removed.
django.middleware.doc.XViewMiddleware is removed.
The Model._meta.module_name alias is removed.
The backward compatible shims introduced to rename get_query_set\nand similar queryset methods are removed. This affects the following classes:\nBaseModelAdmin, ChangeList, BaseCommentNode,\nGenericForeignKey, Manager, SingleRelatedObjectDescriptor and\nReverseSingleRelatedObjectDescriptor.
The backward compatible shims introduced to rename the attributes\nChangeList.root_query_set and ChangeList.query_set are removed.
django.views.defaults.shortcut and django.conf.urls.shortcut are\nremoved.
Support for the Python Imaging Library (PIL) module is removed.
The following private APIs are removed:
\ndjango.db.backend
django.db.close_connection()
django.db.backends.creation.BaseDatabaseCreation.set_autocommit()
django.db.transaction.is_managed()
django.db.transaction.managed()
django.forms.widgets.RadioInput is removed.
The module django.test.simple and the class\ndjango.test.simple.DjangoTestSuiteRunner are removed.
The module django.test._doctest is removed.
The CACHE_MIDDLEWARE_ANONYMOUS_ONLY setting is removed. This change\naffects both django.middleware.cache.CacheMiddleware and\ndjango.middleware.cache.UpdateCacheMiddleware despite the lack of a\ndeprecation warning in the latter class.
Usage of the hardcoded Hold down “Control”, or “Command” on a Mac, to select\nmore than one. string to override or append to user-provided help_text\nin forms for ManyToMany model fields is not performed by Django anymore\neither at the model or forms layer.
The Model._meta.get_(add|change|delete)_permission methods are removed.
The session key django_language is no longer read for backwards\ncompatibility.
Geographic Sitemaps are removed\n(django.contrib.gis.sitemaps.views.index and\ndjango.contrib.gis.sitemaps.views.sitemap).
django.utils.html.fix_ampersands, the fix_ampersands template filter,\nand django.utils.html.clean_html are removed.