Debian Codegraph @

docs/releases/1.7.txt

raw
1 ========================
2 Django 1.7 release notes
3 ========================
4
5 *September 2, 2014*
6
7 Welcome to Django 1.7!
8
9 These release notes cover the :ref:`new features <whats-new-1.7>`, as well as
10 some :ref:`backwards incompatible changes <backwards-incompatible-1.7>` you'll
11 want to be aware of when upgrading from Django 1.6 or older versions. We've
12 :ref:`begun the deprecation process for some features
13 <deprecated-features-1.7>`, and some features have reached the end of their
14 deprecation process and :ref:`have been removed <removed-features-1.7>`.
15
16 Python compatibility
17 ====================
18
19 Django 1.7 requires Python 2.7, 3.2, 3.3, or 3.4. We **highly recommend** and
20 only officially support the latest release of each series.
21
22 The Django 1.6 series is the last to support Python 2.6. Django 1.7 is the
23 first release to support Python 3.4.
24
25 This change should affect only a small number of Django users, as most
26 operating-system vendors today are shipping Python 2.7 or newer as their default
27 version. If you're still using Python 2.6, however, you'll need to stick to
28 Django 1.6 until you can upgrade your Python version. Per :doc:`our support
29 policy </internals/release-process>`, Django 1.6 will continue to receive
30 security support until the release of Django 1.8.
31
32 .. _whats-new-1.7:
33
34 What's new in Django 1.7
35 ========================
36
37 Schema migrations
38 -----------------
39
40 Django now has built-in support for schema migrations. It allows models
41 to be updated, changed, and deleted by creating migration files that represent
42 the model changes and which can be run on any development, staging or production
43 database.
44
45 Migrations are covered in :doc:`their own documentation</topics/migrations>`,
46 but a few of the key features are:
47
48 * ``syncdb`` has been deprecated and replaced by ``migrate``. Don't worry -
49 calls to ``syncdb`` will still work as before.
50
51 * A new ``makemigrations`` command provides an easy way to autodetect changes
52 to your models and make migrations for them.
53
54 ``django.db.models.signals.pre_syncdb`` and
55 ``django.db.models.signals.post_syncdb`` have been deprecated,
56 to be replaced by :data:`~django.db.models.signals.pre_migrate` and
57 :data:`~django.db.models.signals.post_migrate` respectively. These
58 new signals have slightly different arguments. Check the
59 documentation for details.
60
61 * The ``allow_syncdb`` method on database routers is now called ``allow_migrate``,
62 but still performs the same function. Routers with ``allow_syncdb`` methods
63 will still work, but that method name is deprecated and you should change
64 it as soon as possible (nothing more than renaming is required).
65
66 * ``initial_data`` fixtures are no longer loaded for apps with migrations; if
67 you want to load initial data for an app, we suggest you create a migration for
68 your application and define a :class:`~django.db.migrations.operations.RunPython`
69 or :class:`~django.db.migrations.operations.RunSQL` operation in the ``operations`` section of the migration.
70
71 * Test rollback behavior is different for apps with migrations; in particular,
72 Django will no longer emulate rollbacks on non-transactional databases or
73 inside ``TransactionTestCase`` :ref:`unless specifically requested
74 <test-case-serialized-rollback>`.
75
76 * It is not advised to have apps without migrations depend on (have a
77 :class:`~django.db.models.ForeignKey` or
78 :class:`~django.db.models.ManyToManyField` to) apps with migrations.
79
80 .. _app-loading-refactor-17-release-note:
81
82 App-loading refactor
83 --------------------
84
85 Historically, Django applications were tightly linked to models. A singleton
86 known as the "app cache" dealt with both installed applications and models.
87 The models module was used as an identifier for applications in many APIs.
88
89 As the concept of :doc:`Django applications </ref/applications>` matured, this
90 code showed some shortcomings. It has been refactored into an "app registry"
91 where models modules no longer have a central role and where it's possible to
92 attach configuration data to applications.
93
94 Improvements thus far include:
95
96 * Applications can run code at startup, before Django does anything else, with
97 the :meth:`~django.apps.AppConfig.ready` method of their configuration.
98
99 * Application labels are assigned correctly to models even when they're
100 defined outside of ``models.py``. You don't have to set
101 :attr:`~django.db.models.Options.app_label` explicitly any more.
102
103 * It is possible to omit ``models.py`` entirely if an application doesn't
104 have any models.
105
106 * Applications can be relabeled with the :attr:`~django.apps.AppConfig.label`
107 attribute of application configurations, to work around label conflicts.
108
109 * The name of applications can be customized in the admin with the
110 :attr:`~django.apps.AppConfig.verbose_name` of application configurations.
111
112 * The admin automatically calls :func:`~django.contrib.admin.autodiscover()`
113 when Django starts. You can consequently remove this line from your
114 URLconf.
115
116 * Django imports all application configurations and models as soon as it
117 starts, through a deterministic and straightforward process. This should
118 make it easier to diagnose import issues such as import loops.
119
120 New method on Field subclasses
121 ------------------------------
122
123 To help power both schema migrations and to enable easier addition of
124 composite keys in future releases of Django, the
125 :class:`~django.db.models.Field` API now has a new required method:
126 ``deconstruct()``.
127
128 This method takes no arguments, and returns a tuple of four items:
129
130 * ``name``: The field's attribute name on its parent model, or ``None`` if it
131 is not part of a model
132 * ``path``: A dotted, Python path to the class of this field, including the class name.
133 * ``args``: Positional arguments, as a list
134 * ``kwargs``: Keyword arguments, as a dict
135
136 These four values allow any field to be serialized into a file, as well as
137 allowing the field to be copied safely, both essential parts of these new features.
138
139 This change should not affect you unless you write custom Field subclasses;
140 if you do, you may need to reimplement the ``deconstruct()`` method if your
141 subclass changes the method signature of ``__init__`` in any way. If your
142 field just inherits from a built-in Django field and doesn't override ``__init__``,
143 no changes are necessary.
144
145 If you do need to override ``deconstruct()``, a good place to start is the
146 built-in Django fields (``django/db/models/fields/__init__.py``) as several
147 fields, including ``DecimalField`` and ``DateField``, override it and show how
148 to call the method on the superclass and simply add or remove extra arguments.
149
150 This also means that all arguments to fields must themselves be serializable;
151 to see what we consider serializable, and to find out how to make your own
152 classes serializable, read the
153 :ref:`migration serialization documentation <migration-serializing>`.
154
155 Calling custom ``QuerySet`` methods from the ``Manager``
156 --------------------------------------------------------
157
158 Historically, the recommended way to make reusable model queries was to create
159 methods on a custom ``Manager`` class. The problem with this approach was that
160 after the first method call, you'd get back a ``QuerySet`` instance and
161 couldn't call additional custom manager methods.
162
163 Though not documented, it was common to work around this issue by creating a
164 custom ``QuerySet`` so that custom methods could be chained; but the solution
165 had a number of drawbacks:
166
167 * The custom ``QuerySet`` and its custom methods were lost after the first
168 call to ``values()`` or ``values_list()``.
169
170 * Writing a custom ``Manager`` was still necessary to return the custom
171 ``QuerySet`` class and all methods that were desired on the ``Manager``
172 had to be proxied to the ``QuerySet``. The whole process went against
173 the DRY principle.
174
175 The :meth:`QuerySet.as_manager() <django.db.models.query.QuerySet.as_manager>`
176 class method can now directly :ref:`create Manager with QuerySet methods
177 <create-manager-with-queryset-methods>`::
178
179 class FoodQuerySet(models.QuerySet):
180 def pizzas(self):
181 return self.filter(kind="pizza")
182
183 def vegetarian(self):
184 return self.filter(vegetarian=True)
185
186
187 class Food(models.Model):
188 kind = models.CharField(max_length=50)
189 vegetarian = models.BooleanField(default=False)
190 objects = FoodQuerySet.as_manager()
191
192
193 Food.objects.pizzas().vegetarian()
194
195 Using a custom manager when traversing reverse relations
196 --------------------------------------------------------
197
198 It is now possible to :ref:`specify a custom manager
199 <using-custom-reverse-manager>` when traversing a reverse relationship::
200
201 class Blog(models.Model):
202 pass
203
204
205 class Entry(models.Model):
206 blog = models.ForeignKey(Blog)
207
208 objects = models.Manager() # Default Manager
209 entries = EntryManager() # Custom Manager
210
211
212 b = Blog.objects.get(id=1)
213 b.entry_set(manager="entries").all()
214
215 New system check framework
216 --------------------------
217
218 We've added a new :doc:`System check framework </ref/checks>` for
219 detecting common problems (like invalid models) and providing hints for
220 resolving those problems. The framework is extensible so you can add your
221 own checks for your own apps and libraries.
222
223 To perform system checks, you use the :djadmin:`check` management command.
224 This command replaces the older ``validate`` management command.
225
226 New ``Prefetch`` object for advanced ``prefetch_related`` operations.
227 ---------------------------------------------------------------------
228
229 The new :class:`~django.db.models.Prefetch` object allows customizing
230 prefetch operations.
231
232 You can specify the ``QuerySet`` used to traverse a given relation
233 or customize the storage location of prefetch results.
234
235 This enables things like filtering prefetched relations, calling
236 :meth:`~django.db.models.query.QuerySet.select_related()` from a prefetched
237 relation, or prefetching the same relation multiple times with different
238 querysets. See :meth:`~django.db.models.query.QuerySet.prefetch_related()`
239 for more details.
240
241 Admin shortcuts support time zones
242 ----------------------------------
243
244 The "today" and "now" shortcuts next to date and time input widgets in the
245 admin are now operating in the :ref:`current time zone
246 <default-current-time-zone>`. Previously, they used the browser time zone,
247 which could result in saving the wrong value when it didn't match the current
248 time zone on the server.
249
250 In addition, the widgets now display a help message when the browser and
251 server time zone are different, to clarify how the value inserted in the field
252 will be interpreted.
253
254 Using database cursors as context managers
255 ------------------------------------------
256
257 Prior to Python 2.7, database cursors could be used as a context manager. The
258 specific backend's cursor defined the behavior of the context manager. The
259 behavior of magic method lookups was changed with Python 2.7 and cursors were
260 no longer usable as context managers.
261
262 Django 1.7 allows a cursor to be used as a context manager. That is,
263 the following can be used::
264
265 with connection.cursor() as c:
266 c.execute(...)
267
268 instead of::
269
270 c = connection.cursor()
271 try:
272 c.execute(...)
273 finally:
274 c.close()
275
276 Custom lookups
277 --------------
278
279 It is now possible to write custom lookups and transforms for the ORM.
280 Custom lookups work just like Django's built-in lookups (e.g. ``lte``,
281 ``icontains``) while transforms are a new concept.
282
283 The :class:`django.db.models.Lookup` class provides a way to add lookup
284 operators for model fields. As an example it is possible to add ``day_lte``
285 operator for ``DateFields``.
286
287 The :class:`django.db.models.Transform` class allows transformations of
288 database values prior to the final lookup. For example it is possible to
289 write a ``year`` transform that extracts year from the field's value.
290 Transforms allow for chaining. After the ``year`` transform has been added
291 to ``DateField`` it is possible to filter on the transformed value, for
292 example ``qs.filter(author__birthdate__year__lte=1981)``.
293
294 For more information about both custom lookups and transforms refer to
295 the :doc:`custom lookups </howto/custom-lookups>` documentation.
296
297 Improvements to ``Form`` error handling
298 ---------------------------------------
299
300 ``Form.add_error()``
301 ~~~~~~~~~~~~~~~~~~~~
302
303 Previously there were two main patterns for handling errors in forms:
304
305 * Raising a :exc:`~django.core.exceptions.ValidationError` from within certain
306 functions (e.g. ``Field.clean()``, ``Form.clean_<fieldname>()``, or
307 ``Form.clean()`` for non-field errors.)
308
309 * Fiddling with ``Form._errors`` when targeting a specific field in
310 ``Form.clean()`` or adding errors from outside of a "clean" method
311 (e.g. directly from a view).
312
313 Using the former pattern was straightforward since the form can guess from the
314 context (i.e. which method raised the exception) where the errors belong and
315 automatically process them. This remains the canonical way of adding errors
316 when possible. However the latter was fiddly and error-prone, since the burden
317 of handling edge cases fell on the user.
318
319 The new :meth:`~django.forms.Form.add_error()` method allows adding errors
320 to specific form fields from anywhere without having to worry about the details
321 such as creating instances of ``django.forms.utils.ErrorList`` or dealing with
322 ``Form.cleaned_data``. This new API replaces manipulating ``Form._errors``
323 which now becomes a private API.
324
325 See :ref:`validating-fields-with-clean` for an example using
326 ``Form.add_error()``.
327
328 Error metadata
329 ~~~~~~~~~~~~~~
330
331 The :exc:`~django.core.exceptions.ValidationError` constructor accepts metadata
332 such as error ``code`` or ``params`` which are then available for interpolating
333 into the error message (see :ref:`raising-validation-error` for more details);
334 however, before Django 1.7 those metadata were discarded as soon as the errors
335 were added to :attr:`Form.errors <django.forms.Form.errors>`.
336
337 :attr:`Form.errors <django.forms.Form.errors>` and
338 ``django.forms.utils.ErrorList`` now store the ``ValidationError`` instances
339 so these metadata can be retrieved at any time through the new
340 :meth:`Form.errors.as_data <django.forms.Form.errors.as_data()>` method.
341
342 The retrieved ``ValidationError`` instances can then be identified thanks to
343 their error ``code`` which enables things like rewriting the error's message
344 or writing custom logic in a view when a given error is present. It can also
345 be used to serialize the errors in a custom format such as XML.
346
347 The new :meth:`Form.errors.as_json() <django.forms.Form.errors.as_json()>`
348 method is a convenience method which returns error messages along with error
349 codes serialized as JSON. ``as_json()`` uses ``as_data()`` and gives an idea
350 of how the new system could be extended.
351
352 Error containers and backward compatibility
353 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
354
355 Heavy changes to the various error containers were necessary in order
356 to support the features above, specifically
357 :attr:`Form.errors <django.forms.Form.errors>`,
358 ``django.forms.utils.ErrorList``, and the internal storages of
359 :exc:`~django.core.exceptions.ValidationError`. These containers which used
360 to store error strings now store ``ValidationError`` instances and public APIs
361 have been adapted to make this as transparent as possible, but if you've been
362 using private APIs, some of the changes are backwards incompatible; see
363 :ref:`validation-error-constructor-and-internal-storage` for more details.
364
365 Minor features
366 --------------
367
368 :mod:`django.contrib.admin`
369 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
370
371 * You can now implement :attr:`~django.contrib.admin.AdminSite.site_header`,
372 :attr:`~django.contrib.admin.AdminSite.site_title`, and
373 :attr:`~django.contrib.admin.AdminSite.index_title` attributes on a custom
374 :class:`~django.contrib.admin.AdminSite` in order to easily change the admin
375 site's page title and header text. No more needing to override templates!
376
377 * Buttons in :mod:`django.contrib.admin` now use the ``border-radius`` CSS
378 property for rounded corners rather than GIF background images.
379
380 * Some admin templates now have ``app-<app_name>`` and ``model-<model_name>``
381 classes in their ``<body>`` tag to allow customizing the CSS per app or per
382 model.
383
384 * The admin changelist cells now have a ``field-<field_name>`` class in the
385 HTML to enable style customizations.
386
387 * The admin's search fields can now be customized per-request thanks to the new
388 :meth:`django.contrib.admin.ModelAdmin.get_search_fields` method.
389
390 * The :meth:`ModelAdmin.get_fields()
391 <django.contrib.admin.ModelAdmin.get_fields>` method may be overridden to
392 customize the value of :attr:`ModelAdmin.fields
393 <django.contrib.admin.ModelAdmin.fields>`.
394
395 * In addition to the existing ``admin.site.register`` syntax, you can use the
396 new :func:`~django.contrib.admin.register` decorator to register a
397 :class:`~django.contrib.admin.ModelAdmin`.
398
399 * You may specify :meth:`ModelAdmin.list_display_links
400 <django.contrib.admin.ModelAdmin.list_display_links>` ``= None`` to disable
401 links on the change list page grid.
402
403 * You may now specify :attr:`ModelAdmin.view_on_site
404 <django.contrib.admin.ModelAdmin.view_on_site>` to control whether or not to
405 display the "View on site" link.
406
407 * You can specify a descending ordering for a :attr:`ModelAdmin.list_display
408 <django.contrib.admin.ModelAdmin.list_display>` value by prefixing the
409 ``admin_order_field`` value with a hyphen.
410
411 * The :meth:`ModelAdmin.get_changeform_initial_data()
412 <django.contrib.admin.ModelAdmin.get_changeform_initial_data>` method may be
413 overridden to define custom behavior for setting initial change form data.
414
415 :mod:`django.contrib.auth`
416 ~~~~~~~~~~~~~~~~~~~~~~~~~~
417
418 * Any ``**kwargs`` passed to
419 :meth:`~django.contrib.auth.models.User.email_user()` are passed to the
420 underlying :func:`~django.core.mail.send_mail` call.
421
422 * The :func:`~django.contrib.auth.decorators.permission_required` decorator can
423 take a list of permissions as well as a single permission.
424
425 * You can override the new :meth:`AuthenticationForm.confirm_login_allowed()
426 <django.contrib.auth.forms.AuthenticationForm.confirm_login_allowed>` method
427 to more easily customize the login policy.
428
429 * ``django.contrib.auth.views.password_reset()`` takes an optional
430 ``html_email_template_name`` parameter used to send a multipart HTML email
431 for password resets.
432
433 * The :meth:`AbstractBaseUser.get_session_auth_hash()
434 <django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash>`
435 method was added and if your :setting:`AUTH_USER_MODEL` inherits from
436 :class:`~django.contrib.auth.models.AbstractBaseUser`, changing a user's
437 password now invalidates old sessions if the
438 ``django.contrib.auth.middleware.SessionAuthenticationMiddleware`` is
439 enabled. See :ref:`session-invalidation-on-password-change` for more details.
440
441 ``django.contrib.formtools``
442 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
443
444 * Calls to ``WizardView.done()`` now include a ``form_dict`` to allow easier
445 access to forms by their step name.
446
447 :mod:`django.contrib.gis`
448 ~~~~~~~~~~~~~~~~~~~~~~~~~
449
450 * The default OpenLayers library version included in widgets has been updated
451 from 2.11 to 2.13.
452
453 * Prepared geometries now also support the ``crosses``, ``disjoint``,
454 ``overlaps``, ``touches`` and ``within`` predicates, if GEOS 3.3 or later is
455 installed.
456
457 :mod:`django.contrib.messages`
458 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
459
460 * The backends for :mod:`django.contrib.messages` that use cookies, will now
461 follow the :setting:`SESSION_COOKIE_SECURE` and
462 :setting:`SESSION_COOKIE_HTTPONLY` settings.
463
464 * The :ref:`messages context processor <message-displaying>` now adds a
465 dictionary of default levels under the name ``DEFAULT_MESSAGE_LEVELS``.
466
467 * :class:`~django.contrib.messages.Message` objects now have a ``level_tag``
468 attribute that contains the string representation of the message level.
469
470 :mod:`django.contrib.redirects`
471 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
472
473 * :class:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware`
474 has two new attributes
475 (:attr:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware.response_gone_class`
476 and
477 :attr:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware.response_redirect_class`)
478 that specify the types of :class:`~django.http.HttpResponse` instances the
479 middleware returns.
480
481 :mod:`django.contrib.sessions`
482 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
483
484 * The ``"django.contrib.sessions.backends.cached_db"`` session backend now
485 respects :setting:`SESSION_CACHE_ALIAS`. In previous versions, it always used
486 the ``default`` cache.
487
488 :mod:`django.contrib.sitemaps`
489 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
490
491 * The :mod:`sitemap framework<django.contrib.sitemaps>` now makes use of
492 :attr:`~django.contrib.sitemaps.Sitemap.lastmod` to set a ``Last-Modified``
493 header in the response. This makes it possible for the
494 :class:`~django.middleware.http.ConditionalGetMiddleware` to handle
495 conditional ``GET`` requests for sitemaps which set ``lastmod``.
496
497 :mod:`django.contrib.sites`
498 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
499
500 * The new :class:`django.contrib.sites.middleware.CurrentSiteMiddleware` allows
501 setting the current site on each request.
502
503 :mod:`django.contrib.staticfiles`
504 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
505
506 * The :ref:`static files storage classes <staticfiles-storages>` may be
507 subclassed to override the permissions that collected static files and
508 directories receive by setting the
509 :attr:`~django.core.files.storage.FileSystemStorage.file_permissions_mode`
510 and :attr:`~django.core.files.storage.FileSystemStorage.directory_permissions_mode`
511 parameters. See :djadmin:`collectstatic` for example usage.
512
513 * The ``CachedStaticFilesStorage`` backend gets a sibling class called
514 :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage`
515 that doesn't use the cache system at all but instead a JSON file called
516 ``staticfiles.json`` for storing the mapping between the original file name
517 (e.g. ``css/styles.css``) and the hashed file name (e.g.
518 ``css/styles.55e7cbb9ba48.css``). The ``staticfiles.json`` file is created
519 when running the :djadmin:`collectstatic` management command and should
520 be a less expensive alternative for remote storages such as Amazon S3.
521
522 See the :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage`
523 docs for more information.
524
525 * :djadmin:`findstatic` now accepts verbosity flag level 2, meaning it will
526 show the relative paths of the directories it searched. See
527 :djadmin:`findstatic` for example output.
528
529 :mod:`django.contrib.syndication`
530 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
531
532 * The :class:`~django.utils.feedgenerator.Atom1Feed` syndication feed's
533 ``updated`` element now utilizes ``updateddate`` instead of ``pubdate``,
534 allowing the ``published`` element to be included in the feed (which
535 relies on ``pubdate``).
536
537 Cache
538 ~~~~~
539
540 * Access to caches configured in :setting:`CACHES` is now available via
541 :data:`django.core.cache.caches`. This dict-like object provides a different
542 instance per thread. It supersedes ``django.core.cache.get_cache()`` which
543 is now deprecated.
544
545 * If you instantiate cache backends directly, be aware that they aren't
546 thread-safe any more, as :data:`django.core.cache.caches` now yields
547 different instances per thread.
548
549 * Defining the :setting:`TIMEOUT <CACHES-TIMEOUT>` argument of the
550 :setting:`CACHES` setting as ``None`` will set the cache keys as
551 "non-expiring" by default. Previously, it was only possible to pass
552 ``timeout=None`` to the cache backend's ``set()`` method.
553
554 Cross Site Request Forgery
555 ~~~~~~~~~~~~~~~~~~~~~~~~~~
556
557 * The :setting:`CSRF_COOKIE_AGE` setting facilitates the use of session-based
558 CSRF cookies.
559
560 Email
561 ~~~~~
562
563 * :func:`~django.core.mail.send_mail` now accepts an ``html_message``
564 parameter for sending a multipart :mimetype:`text/plain` and
565 :mimetype:`text/html` email.
566
567 * The SMTP :class:`~django.core.mail.backends.smtp.EmailBackend` now accepts a
568 ``timeout`` parameter.
569
570 File Storage
571 ~~~~~~~~~~~~
572
573 * File locking on Windows previously depended on the PyWin32 package; if it
574 wasn't installed, file locking failed silently. That dependency has been
575 removed, and file locking is now implemented natively on both Windows
576 and Unix.
577
578 File Uploads
579 ~~~~~~~~~~~~
580
581 * The new :attr:`UploadedFile.content_type_extra
582 <django.core.files.uploadedfile.UploadedFile.content_type_extra>` attribute
583 contains extra parameters passed to the ``content-type`` header on a file
584 upload.
585
586 * The new :setting:`FILE_UPLOAD_DIRECTORY_PERMISSIONS` setting controls
587 the file system permissions of directories created during file upload, like
588 :setting:`FILE_UPLOAD_PERMISSIONS` does for the files themselves.
589
590 * The :attr:`FileField.upload_to <django.db.models.FileField.upload_to>`
591 attribute is now optional. If it is omitted or given ``None`` or an empty
592 string, a subdirectory won't be used for storing the uploaded files.
593
594 * Uploaded files are now explicitly closed before the response is delivered to
595 the client. Partially uploaded files are also closed as long as they are
596 named ``file`` in the upload handler.
597
598 * :meth:`Storage.get_available_name()
599 <django.core.files.storage.Storage.get_available_name>` now appends an
600 underscore plus a random 7 character alphanumeric string (e.g.
601 ``"_x3a1gho"``), rather than iterating through an underscore followed by a
602 number (e.g. ``"_1"``, ``"_2"``, etc.) to prevent a denial-of-service attack.
603 This change was also made in the 1.6.6, 1.5.9, and 1.4.14 security releases.
604
605 Forms
606 ~~~~~
607
608 * The ``<label>`` and ``<input>`` tags rendered by
609 :class:`~django.forms.RadioSelect` and
610 :class:`~django.forms.CheckboxSelectMultiple` when looping over the radio
611 buttons or checkboxes now include ``for`` and ``id`` attributes, respectively.
612 Each radio button or checkbox includes an ``id_for_label`` attribute to
613 output the element's ID.
614
615 * The ``<textarea>`` tags rendered by :class:`~django.forms.Textarea` now
616 include a ``maxlength`` attribute if the :class:`~django.db.models.TextField`
617 model field has a ``max_length``.
618
619 * :attr:`Field.choices<django.db.models.Field.choices>` now allows you to
620 customize the "empty choice" label by including a tuple with an empty string
621 or ``None`` for the key and the custom label as the value. The default blank
622 option ``"----------"`` will be omitted in this case.
623
624 * :class:`~django.forms.MultiValueField` allows optional subfields by setting
625 the ``require_all_fields`` argument to ``False``. The ``required`` attribute
626 for each individual field will be respected, and a new ``incomplete``
627 validation error will be raised when any required fields are empty.
628
629 * The :meth:`~django.forms.Form.clean` method on a form no longer needs to
630 return ``self.cleaned_data``. If it does return a changed dictionary then
631 that will still be used.
632
633 * After a temporary regression in Django 1.6, it's now possible again to make
634 :class:`~django.forms.TypedChoiceField` ``coerce`` method return an arbitrary
635 value.
636
637 * :attr:`SelectDateWidget.months
638 <django.forms.SelectDateWidget.months>` can be used to
639 customize the wording of the months displayed in the select widget.
640
641 * The ``min_num`` and ``validate_min`` parameters were added to
642 :func:`~django.forms.formsets.formset_factory` to allow validating
643 a minimum number of submitted forms.
644
645 * The metaclasses used by ``Form`` and ``ModelForm`` have been reworked to
646 support more inheritance scenarios. The previous limitation that prevented
647 inheriting from both ``Form`` and ``ModelForm`` simultaneously have been
648 removed as long as ``ModelForm`` appears first in the MRO.
649
650 * It's now possible to remove a field from a ``Form`` when subclassing by
651 setting the name to ``None``.
652
653 * It's now possible to customize the error messages for ``ModelForm``’s
654 ``unique``, ``unique_for_date``, and ``unique_together`` constraints.
655 In order to support ``unique_together`` or any other ``NON_FIELD_ERROR``,
656 ``ModelForm`` now looks for the ``NON_FIELD_ERROR`` key in the
657 ``error_messages`` dictionary of the ``ModelForm``’s inner ``Meta`` class.
658 See :ref:`considerations regarding model's error_messages
659 <considerations-regarding-model-errormessages>` for more details.
660
661 Internationalization
662 ~~~~~~~~~~~~~~~~~~~~
663
664 * The :attr:`django.middleware.locale.LocaleMiddleware.response_redirect_class`
665 attribute allows you to customize the redirects issued by the middleware.
666
667 * The :class:`~django.middleware.locale.LocaleMiddleware` now stores the user's
668 selected language with the session key ``_language``. This should only be
669 accessed using the ``LANGUAGE_SESSION_KEY`` constant. Previously it was
670 stored with the key ``django_language`` and the ``LANGUAGE_SESSION_KEY``
671 constant did not exist, but keys reserved for Django should start with an
672 underscore. For backwards compatibility ``django_language`` is still read
673 from in 1.7. Sessions will be migrated to the new key as they are written.
674
675 * The :ttag:`blocktrans` tag now supports a ``trimmed`` option. This
676 option will remove newline characters from the beginning and the end of the
677 content of the ``{% blocktrans %}`` tag, replace any whitespace at the
678 beginning and end of a line and merge all lines into one using a space
679 character to separate them. This is quite useful for indenting the content of
680 a ``{% blocktrans %}`` tag without having the indentation characters end up
681 in the corresponding entry in the ``.po`` file, which makes the translation
682 process easier.
683
684 * When you run :djadmin:`makemessages` from the root directory of your project,
685 any extracted strings will now be automatically distributed to the proper
686 app or project message file. See :ref:`how-to-create-language-files` for
687 details.
688
689 * The :djadmin:`makemessages` command now always adds the ``--previous``
690 command line flag to the ``msgmerge`` command, keeping previously translated
691 strings in ``.po`` files for fuzzy strings.
692
693 * The following settings to adjust the language cookie options were introduced:
694 :setting:`LANGUAGE_COOKIE_AGE`, :setting:`LANGUAGE_COOKIE_DOMAIN`
695 and :setting:`LANGUAGE_COOKIE_PATH`.
696
697 * Added :doc:`/topics/i18n/formatting` for Esperanto.
698
699 Management Commands
700 ~~~~~~~~~~~~~~~~~~~
701
702 * The new :option:`--no-color` option for ``django-admin`` disables the
703 colorization of management command output.
704
705 * The new :option:`dumpdata --natural-foreign` and :option:`dumpdata
706 --natural-primary` options, and the new ``use_natural_foreign_keys`` and
707 ``use_natural_primary_keys`` arguments for ``serializers.serialize()``, allow
708 the use of natural primary keys when serializing.
709
710 * It is no longer necessary to provide the cache table name or the
711 ``--database`` option for the :djadmin:`createcachetable` command.
712 Django takes this information from your settings file. If you have configured
713 multiple caches or multiple databases, all cache tables are created.
714
715 * The :djadmin:`runserver` command received several improvements:
716
717 * On Linux systems, if :pypi:`pyinotify` is installed, the development server
718 will reload immediately when a file is changed. Previously, it polled the
719 filesystem for changes every second. That caused a small delay before
720 reloads and reduced battery life on laptops.
721
722 * In addition, the development server automatically reloads when a
723 translation file is updated, i.e. after running
724 :djadmin:`compilemessages`.
725
726 * All HTTP requests are logged to the console, including requests for static
727 files or ``favicon.ico`` that used to be filtered out.
728
729 * Management commands can now produce syntax colored output under Windows if
730 the ANSICON third-party tool is installed and active.
731
732 * :djadmin:`collectstatic` command with symlink option is now supported on
733 Windows NT 6 (Windows Vista and newer).
734
735 * Initial SQL data now works better if the :pypi:`sqlparse` Python library is
736 installed.
737
738 Note that it's deprecated in favor of the
739 :class:`~django.db.migrations.operations.RunSQL` operation of migrations,
740 which benefits from the improved behavior.
741
742 Models
743 ~~~~~~
744
745 * The :meth:`QuerySet.update_or_create()
746 <django.db.models.query.QuerySet.update_or_create>` method was added.
747
748 * The new :attr:`~django.db.models.Options.default_permissions` model
749 ``Meta`` option allows you to customize (or disable) creation of the default
750 add, change, and delete permissions.
751
752 * Explicit :class:`~django.db.models.OneToOneField` for
753 :ref:`multi-table-inheritance` are now discovered in abstract classes.
754
755 * It is now possible to avoid creating a backward relation for
756 :class:`~django.db.models.OneToOneField` by setting its
757 :attr:`~django.db.models.ForeignKey.related_name` to
758 ``'+'`` or ending it with ``'+'``.
759
760 * :class:`F expressions <django.db.models.F>` support the power operator
761 (``**``).
762
763 * The ``remove()`` and ``clear()`` methods of the related managers created by
764 ``ForeignKey`` and ``GenericForeignKey`` now accept the ``bulk`` keyword
765 argument to control whether or not to perform operations in bulk
766 (i.e. using ``QuerySet.update()``). Defaults to ``True``.
767
768 * It is now possible to use ``None`` as a query value for the :lookup:`iexact`
769 lookup.
770
771 * It is now possible to pass a callable as value for the attribute
772 :attr:`~django.db.models.ForeignKey.limit_choices_to` when defining a
773 ``ForeignKey`` or ``ManyToManyField``.
774
775 * Calling :meth:`only() <django.db.models.query.QuerySet.only>` and
776 :meth:`defer() <django.db.models.query.QuerySet.defer>` on the result of
777 :meth:`QuerySet.values() <django.db.models.query.QuerySet.values>` now raises
778 an error (before that, it would either result in a database error or
779 incorrect data).
780
781 * You can use a single list for ``index_together`` (rather than a list of
782 lists) when specifying a single set of fields.
783
784 * Custom intermediate models having more than one foreign key to any of the
785 models participating in a many-to-many relationship are now permitted,
786 provided you explicitly specify which foreign keys should be used by setting
787 the new :attr:`ManyToManyField.through_fields <django.db.models.ManyToManyField.through_fields>`
788 argument.
789
790 * Assigning a model instance to a non-relation field will now throw an error.
791 Previously this used to work if the field accepted integers as input as it
792 took the primary key.
793
794 * Integer fields are now validated against database backend specific min and
795 max values based on their :meth:`internal_type <django.db.models.Field.get_internal_type>`.
796 Previously model field validation didn't prevent values out of their associated
797 column data type range from being saved resulting in an integrity error.
798
799 * It is now possible to explicitly :meth:`~django.db.models.query.QuerySet.order_by`
800 a relation ``_id`` field by using its attribute name.
801
802 Signals
803 ~~~~~~~
804
805 * The ``enter`` argument was added to the
806 :data:`~django.test.signals.setting_changed` signal.
807
808 * The model signals can be now be connected to using a ``str`` of the
809 ``'app_label.ModelName'`` form – just like related fields – to lazily
810 reference their senders.
811
812 Templates
813 ~~~~~~~~~
814
815 * The :meth:`Context.push() <django.template.Context.push>` method now returns
816 a context manager which automatically calls :meth:`pop()
817 <django.template.Context.pop>` upon exiting the ``with`` statement.
818 Additionally, :meth:`push() <django.template.Context.push>` now accepts
819 parameters that are passed to the ``dict`` constructor used to build the new
820 context level.
821
822 * The new :meth:`Context.flatten() <django.template.Context.flatten>` method
823 returns a ``Context``'s stack as one flat dictionary.
824
825 * ``Context`` objects can now be compared for equality (internally, this
826 uses :meth:`Context.flatten() <django.template.Context.flatten>` so the
827 internal structure of each ``Context``'s stack doesn't matter as long as their
828 flattened version is identical).
829
830 * The :ttag:`widthratio` template tag now accepts an ``"as"`` parameter to
831 capture the result in a variable.
832
833 * The :ttag:`include` template tag will now also accept anything with a
834 ``render()`` method (such as a ``Template``) as an argument. String
835 arguments will be looked up using
836 :func:`~django.template.loader.get_template` as always.
837
838 * It is now possible to :ttag:`include` templates recursively.
839
840 * Template objects now have an origin attribute set when
841 ``TEMPLATE_DEBUG`` is ``True``. This allows template origins to be
842 inspected and logged outside of the ``django.template`` infrastructure.
843
844 * ``TypeError`` exceptions are no longer silenced when raised during the
845 rendering of a template.
846
847 * The following functions now accept a ``dirs`` parameter which is a list or
848 tuple to override ``TEMPLATE_DIRS``:
849
850 * :func:`django.template.loader.get_template()`
851 * :func:`django.template.loader.select_template()`
852 * :func:`django.shortcuts.render()`
853 * ``django.shortcuts.render_to_response()``
854
855 * The :tfilter:`time` filter now accepts timezone-related :ref:`format
856 specifiers <date-and-time-formatting-specifiers>` ``'e'``, ``'O'`` , ``'T'``
857 and ``'Z'`` and is able to digest :ref:`time-zone-aware
858 <naive_vs_aware_datetimes>` ``datetime`` instances performing the expected
859 rendering.
860
861 * The :ttag:`cache` tag will now try to use the cache called
862 "template_fragments" if it exists and fall back to using the default cache
863 otherwise. It also now accepts an optional ``using`` keyword argument to
864 control which cache it uses.
865
866 * The new :tfilter:`truncatechars_html` filter truncates a string to be no
867 longer than the specified number of characters, taking HTML into account.
868
869 Requests and Responses
870 ~~~~~~~~~~~~~~~~~~~~~~
871
872 * The new :attr:`HttpRequest.scheme <django.http.HttpRequest.scheme>` attribute
873 specifies the scheme of the request (``http`` or ``https`` normally).
874
875
876 * The shortcut :func:`redirect() <django.shortcuts.redirect>` now supports
877 relative URLs.
878
879 * The new :class:`~django.http.JsonResponse` subclass of
880 :class:`~django.http.HttpResponse` helps easily create JSON-encoded responses.
881
882 Tests
883 ~~~~~
884
885 * :class:`~django.test.runner.DiscoverRunner` has two new attributes,
886 :attr:`~django.test.runner.DiscoverRunner.test_suite` and
887 :attr:`~django.test.runner.DiscoverRunner.test_runner`, which facilitate
888 overriding the way tests are collected and run.
889
890 * The ``fetch_redirect_response`` argument was added to
891 :meth:`~django.test.SimpleTestCase.assertRedirects`. Since the test
892 client can't fetch externals URLs, this allows you to use ``assertRedirects``
893 with redirects that aren't part of your Django app.
894
895 * Correct handling of scheme when making comparisons in
896 :meth:`~django.test.SimpleTestCase.assertRedirects`.
897
898 * The ``secure`` argument was added to all the request methods of
899 :class:`~django.test.Client`. If ``True``, the request will be made
900 through HTTPS.
901
902 * :meth:`~django.test.TransactionTestCase.assertNumQueries` now prints
903 out the list of executed queries if the assertion fails.
904
905 * The ``WSGIRequest`` instance generated by the test handler is now attached to
906 the :attr:`django.test.Response.wsgi_request` attribute.
907
908 * The database settings for testing have been collected into a dictionary
909 named :setting:`TEST <DATABASE-TEST>`.
910
911 Utilities
912 ~~~~~~~~~
913
914 * Improved :func:`~django.utils.html.strip_tags` accuracy (but it still cannot
915 guarantee an HTML-safe result, as stated in the documentation).
916
917 Validators
918 ~~~~~~~~~~
919
920 * :class:`~django.core.validators.RegexValidator` now accepts the optional
921 :attr:`~django.core.validators.RegexValidator.flags` and
922 Boolean :attr:`~django.core.validators.RegexValidator.inverse_match` arguments.
923 The :attr:`~django.core.validators.RegexValidator.inverse_match` attribute
924 determines if the :exc:`~django.core.exceptions.ValidationError` should
925 be raised when the regular expression pattern matches (``True``) or does not
926 match (``False``, by default) the provided ``value``. The
927 :attr:`~django.core.validators.RegexValidator.flags` attribute sets the flags
928 used when compiling a regular expression string.
929
930 * :class:`~django.core.validators.URLValidator` now accepts an optional
931 ``schemes`` argument which allows customization of the accepted URI schemes
932 (instead of the defaults ``http(s)`` and ``ftp(s)``).
933
934 * :func:`~django.core.validators.validate_email` now accepts addresses with
935 IPv6 literals, like ``example@[2001:db8::1]``, as specified in RFC 5321.
936
937 .. _backwards-incompatible-1.7:
938
939 Backwards incompatible changes in 1.7
940 =====================================
941
942 .. warning::
943
944 In addition to the changes outlined in this section, be sure to review the
945 :ref:`deprecation plan <deprecation-removed-in-1.7>` for any features that
946 have been removed. If you haven't updated your code within the
947 deprecation timeline for a given feature, its removal may appear as a
948 backwards incompatible change.
949
950 ``allow_syncdb`` / ``allow_migrate``
951 ------------------------------------
952
953 While Django will still look at ``allow_syncdb`` methods even though they
954 should be renamed to ``allow_migrate``, there is a subtle difference in which
955 models get passed to these methods.
956
957 For apps with migrations, ``allow_migrate`` will now get passed
958 :ref:`historical models <historical-models>`, which are special versioned models
959 without custom attributes, methods or managers. Make sure your ``allow_migrate``
960 methods are only referring to fields or other items in ``model._meta``.
961
962 initial_data
963 ------------
964
965 Apps with migrations will not load ``initial_data`` fixtures when they have
966 finished migrating. Apps without migrations will continue to load these fixtures
967 during the phase of ``migrate`` which emulates the old ``syncdb`` behavior,
968 but any new apps will not have this support.
969
970 Instead, you are encouraged to load initial data in migrations if you need it
971 (using the ``RunPython`` operation and your model classes);
972 this has the added advantage that your initial data will not need updating
973 every time you change the schema.
974
975 Additionally, like the rest of Django's old ``syncdb`` code, ``initial_data``
976 has been started down the deprecation path and will be removed in Django 1.9.
977
978 ``deconstruct()`` and serializability
979 -------------------------------------
980
981 Django now requires all Field classes and all of their constructor arguments
982 to be serializable. If you modify the constructor signature in your custom
983 Field in any way, you'll need to implement a ``deconstruct()`` method;
984 we've expanded the custom field documentation with :ref:`instructions
985 on implementing this method <custom-field-deconstruct-method>`.
986
987 The requirement for all field arguments to be
988 :ref:`serializable <migration-serializing>` means that any custom class
989 instances being passed into Field constructors - things like custom Storage
990 subclasses, for instance - need to have a :ref:`deconstruct method defined on
991 them as well <custom-deconstruct-method>`, though Django provides a handy
992 class decorator that will work for most applications.
993
994 App-loading changes
995 -------------------
996
997 Start-up sequence
998 ~~~~~~~~~~~~~~~~~
999
1000 Django 1.7 loads application configurations and models as soon as it starts.
1001 While this behavior is more straightforward and is believed to be more robust,
1002 regressions cannot be ruled out. See :ref:`applications-troubleshooting` for
1003 solutions to some problems you may encounter.
1004
1005 Standalone scripts
1006 ~~~~~~~~~~~~~~~~~~
1007
1008 If you're using Django in a plain Python script — rather than a management
1009 command — and you rely on the :envvar:`DJANGO_SETTINGS_MODULE` environment
1010 variable, you must now explicitly initialize Django at the beginning of your
1011 script with:
1012
1013 .. code-block:: pycon
1014
1015 >>> import django
1016 >>> django.setup()
1017
1018 Otherwise, you will hit an ``AppRegistryNotReady`` exception.
1019
1020 WSGI scripts
1021 ~~~~~~~~~~~~
1022
1023 Until Django 1.3, the recommended way to create a WSGI application was::
1024
1025 import django.core.handlers.wsgi
1026
1027 application = django.core.handlers.wsgi.WSGIHandler()
1028
1029 In Django 1.4, support for WSGI was improved and the API changed to::
1030
1031 from django.core.wsgi import get_wsgi_application
1032
1033 application = get_wsgi_application()
1034
1035 If you're still using the former style in your WSGI script, you need to
1036 upgrade to the latter, or you will hit an ``AppRegistryNotReady`` exception.
1037
1038 App registry consistency
1039 ~~~~~~~~~~~~~~~~~~~~~~~~
1040
1041 It is no longer possible to have multiple installed applications with the same
1042 label. In previous versions of Django, this didn't always work correctly, but
1043 didn't crash outright either.
1044
1045 If you have two apps with the same label, you should create an
1046 :class:`~django.apps.AppConfig` for one of them and override its
1047 :class:`~django.apps.AppConfig.label` there. You should then adjust your code
1048 wherever it references this application or its models with the old label.
1049
1050 It isn't possible to import the same model twice through different paths any
1051 more. As of Django 1.6, this may happen only if you're manually putting a
1052 directory and a subdirectory on :envvar:`PYTHONPATH`. Refer to the section on
1053 the new project layout in the :doc:`1.4 release notes </releases/1.4>` for
1054 migration instructions.
1055
1056 You should make sure that:
1057
1058 * All models are defined in applications that are listed in
1059 :setting:`INSTALLED_APPS` or have an explicit
1060 :attr:`~django.db.models.Options.app_label`.
1061
1062 * Models aren't imported as a side-effect of loading their application.
1063 Specifically, you shouldn't import models in the root module of an
1064 application nor in the module that define its configuration class.
1065
1066 Django will enforce these requirements as of version 1.9, after a deprecation
1067 period.
1068
1069 Subclassing AppCommand
1070 ~~~~~~~~~~~~~~~~~~~~~~
1071
1072 Subclasses of :class:`~django.core.management.AppCommand` must now implement a
1073 :meth:`~django.core.management.AppCommand.handle_app_config` method instead of
1074 ``handle_app()``. This method receives an :class:`~django.apps.AppConfig`
1075 instance instead of a models module.
1076
1077 Introspecting applications
1078 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1079
1080 Since :setting:`INSTALLED_APPS` now supports application configuration classes
1081 in addition to application modules, you should review code that accesses this
1082 setting directly and use the app registry (:attr:`django.apps.apps`) instead.
1083
1084 The app registry has preserved some features of the old app cache. Even though
1085 the app cache was a private API, obsolete methods and arguments will be
1086 removed through a standard deprecation path, with the exception of the
1087 following changes that take effect immediately:
1088
1089 * ``get_model`` raises :exc:`LookupError` instead of returning ``None`` when no
1090 model is found.
1091
1092 * The ``only_installed`` argument of ``get_model`` and ``get_models`` no
1093 longer exists, nor does the ``seed_cache`` argument of ``get_model``.
1094
1095 Management commands and order of :setting:`INSTALLED_APPS`
1096 ----------------------------------------------------------
1097
1098 When several applications provide management commands with the same name,
1099 Django loads the command from the application that comes first in
1100 :setting:`INSTALLED_APPS`. Previous versions loaded the command from the
1101 application that came last.
1102
1103 This brings discovery of management commands in line with other parts of
1104 Django that rely on the order of :setting:`INSTALLED_APPS`, such as static
1105 files, templates, and translations.
1106
1107 .. _validation-error-constructor-and-internal-storage:
1108
1109 ``ValidationError`` constructor and internal storage
1110 ----------------------------------------------------
1111
1112 The behavior of the ``ValidationError`` constructor has changed when it
1113 receives a container of errors as an argument (e.g. a ``list`` or an
1114 ``ErrorList``):
1115
1116 * It converts any strings it finds to instances of ``ValidationError``
1117 before adding them to its internal storage.
1118
1119 * It doesn't store the given container but rather copies its content to its
1120 own internal storage; previously the container itself was added to the
1121 ``ValidationError`` instance and used as internal storage.
1122
1123 This means that if you access the ``ValidationError`` internal storages, such
1124 as ``error_list``; ``error_dict``; or the return value of
1125 ``update_error_dict()`` you may find instances of ``ValidationError`` where you
1126 would have previously found strings.
1127
1128 Also if you directly assigned the return value of ``update_error_dict()``
1129 to ``Form._errors`` you may inadvertently add ``list`` instances where
1130 ``ErrorList`` instances are expected. This is a problem because unlike a
1131 simple ``list``, an ``ErrorList`` knows how to handle instances of
1132 ``ValidationError``.
1133
1134 Most use-cases that warranted using these private APIs are now covered by
1135 the newly introduced :meth:`Form.add_error() <django.forms.Form.add_error()>`
1136 method::
1137
1138 # Old pattern:
1139 try:
1140 ...
1141 except ValidationError as e:
1142 self._errors = e.update_error_dict(self._errors)
1143
1144 # New pattern:
1145 try:
1146 ...
1147 except ValidationError as e:
1148 self.add_error(None, e)
1149
1150 If you need both Django <= 1.6 and 1.7 compatibility you can't use
1151 :meth:`Form.add_error() <django.forms.Form.add_error()>` since it
1152 wasn't available before Django 1.7, but you can use the following
1153 workaround to convert any ``list`` into ``ErrorList``::
1154
1155 try:
1156 ...
1157 except ValidationError as e:
1158 self._errors = e.update_error_dict(self._errors)
1159
1160 # Additional code to ensure ``ErrorDict`` is exclusively
1161 # composed of ``ErrorList`` instances.
1162 for field, error_list in self._errors.items():
1163 if not isinstance(error_list, self.error_class):
1164 self._errors[field] = self.error_class(error_list)
1165
1166 Behavior of ``LocMemCache`` regarding pickle errors
1167 ---------------------------------------------------
1168
1169 An inconsistency existed in previous versions of Django regarding how pickle
1170 errors are handled by different cache backends.
1171 ``django.core.cache.backends.locmem.LocMemCache`` used to fail silently when
1172 such an error occurs, which is inconsistent with other backends and leads to
1173 cache-specific errors. This has been fixed in Django 1.7, see
1174 :ticket:`21200` for more details.
1175
1176 Cache keys are now generated from the request's absolute URL
1177 ------------------------------------------------------------
1178
1179 Previous versions of Django generated cache keys using a request's path and
1180 query string but not the scheme or host. If a Django application was serving
1181 multiple subdomains or domains, cache keys could collide. In Django 1.7, cache
1182 keys vary by the absolute URL of the request including scheme, host, path, and
1183 query string. For example, the URL portion of a cache key is now generated from
1184 ``https://www.example.com/path/to/?key=val`` rather than ``/path/to/?key=val``.
1185 The cache keys generated by Django 1.7 will be different from the keys
1186 generated by older versions of Django. After upgrading to Django 1.7, the first
1187 request to any previously cached URL will be a cache miss.
1188
1189 Passing ``None`` to ``Manager.db_manager()``
1190 --------------------------------------------
1191
1192 In previous versions of Django, it was possible to use
1193 ``db_manager(using=None)`` on a model manager instance to obtain a manager
1194 instance using default routing behavior, overriding any manually specified
1195 database routing. In Django 1.7, a value of ``None`` passed to db_manager will
1196 produce a router that *retains* any manually assigned database routing -- the
1197 manager will *not* be reset. This was necessary to resolve an inconsistency in
1198 the way routing information cascaded over joins. See :ticket:`13724` for more
1199 details.
1200
1201 ``pytz`` may be required
1202 ------------------------
1203
1204 If your project handles datetimes before 1970 or after 2037 and Django raises
1205 a :exc:`ValueError` when encountering them, you will have to install
1206 :pypi:`pytz`. You may be affected by this problem if you use Django's time
1207 zone-related date formats or :mod:`django.contrib.syndication`.
1208
1209 ``remove()`` and ``clear()`` methods of related managers
1210 --------------------------------------------------------
1211
1212 The ``remove()`` and ``clear()`` methods of the related managers created by
1213 ``ForeignKey``, ``GenericForeignKey``, and ``ManyToManyField`` suffered from a
1214 number of issues. Some operations ran multiple data modifying queries without
1215 wrapping them in a transaction, and some operations didn't respect default
1216 filtering when it was present (i.e. when the default manager on the related
1217 model implemented a custom ``get_queryset()``).
1218
1219 Fixing the issues introduced some backward incompatible changes:
1220
1221 - The default implementation of ``remove()`` for ``ForeignKey`` related managers
1222 changed from a series of ``Model.save()`` calls to a single
1223 ``QuerySet.update()`` call. The change means that ``pre_save`` and
1224 ``post_save`` signals aren't sent anymore. You can use the ``bulk=False``
1225 keyword argument to revert to the previous behavior.
1226
1227 - The ``remove()`` and ``clear()`` methods for ``GenericForeignKey`` related
1228 managers now perform bulk delete. The ``Model.delete()`` method isn't called
1229 on each instance anymore. You can use the ``bulk=False`` keyword argument to
1230 revert to the previous behavior.
1231
1232 - The ``remove()`` and ``clear()`` methods for ``ManyToManyField`` related
1233 managers perform nested queries when filtering is involved, which may or
1234 may not be an issue depending on your database and your data itself.
1235 See :ref:`this note <nested-queries-performance>` for more details.
1236
1237 Admin login redirection strategy
1238 --------------------------------
1239
1240 Historically, the Django admin site passed the request from an unauthorized or
1241 unauthenticated user directly to the login view, without HTTP redirection. In
1242 Django 1.7, this behavior changed to conform to a more traditional workflow
1243 where any unauthorized request to an admin page will be redirected (by HTTP
1244 status code 302) to the login page, with the ``next`` parameter set to the
1245 referring path. The user will be redirected there after a successful login.
1246
1247 Note also that the admin login form has been updated to not contain the
1248 ``this_is_the_login_form`` field (now unused) and the ``ValidationError`` code
1249 has been set to the more regular ``invalid_login`` key.
1250
1251 ``select_for_update()`` requires a transaction
1252 ----------------------------------------------
1253
1254 Historically, queries that use
1255 :meth:`~django.db.models.query.QuerySet.select_for_update()` could be
1256 executed in autocommit mode, outside of a transaction. Before Django
1257 1.6, Django's automatic transactions mode allowed this to be used to
1258 lock records until the next write operation. Django 1.6 introduced
1259 database-level autocommit; since then, execution in such a context
1260 voids the effect of ``select_for_update()``. It is, therefore, assumed
1261 now to be an error and raises an exception.
1262
1263 This change was made because such errors can be caused by including an
1264 app which expects global transactions (e.g. :setting:`ATOMIC_REQUESTS
1265 <DATABASE-ATOMIC_REQUESTS>` set to ``True``), or Django's old autocommit
1266 behavior, in a project which runs without them; and further, such
1267 errors may manifest as data-corruption bugs. It was also made in
1268 Django 1.6.3.
1269
1270 This change may cause test failures if you use ``select_for_update()``
1271 in a test class which is a subclass of
1272 :class:`~django.test.TransactionTestCase` rather than
1273 :class:`~django.test.TestCase`.
1274
1275 Contrib middleware removed from default ``MIDDLEWARE_CLASSES``
1276 --------------------------------------------------------------
1277
1278 The :ref:`app-loading refactor <app-loading-refactor-17-release-note>`
1279 deprecated using models from apps which are not part of the
1280 :setting:`INSTALLED_APPS` setting. This exposed an incompatibility between
1281 the default :setting:`INSTALLED_APPS` and ``MIDDLEWARE_CLASSES`` in the
1282 global defaults (``django.conf.global_settings``). To bring these settings in
1283 sync and prevent deprecation warnings when doing things like testing reusable
1284 apps with minimal settings,
1285 :class:`~django.contrib.sessions.middleware.SessionMiddleware`,
1286 :class:`~django.contrib.auth.middleware.AuthenticationMiddleware`, and
1287 :class:`~django.contrib.messages.middleware.MessageMiddleware` were removed
1288 from the defaults. These classes will still be included in the default settings
1289 generated by :djadmin:`startproject`. Most projects will not be affected by
1290 this change but if you were not previously declaring the
1291 ``MIDDLEWARE_CLASSES`` in your project settings and relying on the
1292 global default you should ensure that the new defaults are in line with your
1293 project's needs. You should also check for any code that accesses
1294 ``django.conf.global_settings.MIDDLEWARE_CLASSES`` directly.
1295
1296 Miscellaneous
1297 -------------
1298
1299 * The :meth:`django.core.files.uploadhandler.FileUploadHandler.new_file()`
1300 method is now passed an additional ``content_type_extra`` parameter. If you
1301 have a custom :class:`~django.core.files.uploadhandler.FileUploadHandler`
1302 that implements ``new_file()``, be sure it accepts this new parameter.
1303
1304 * :class:`ModelFormSet<django.forms.models.BaseModelFormSet>`\s no longer
1305 delete instances when ``save(commit=False)`` is called. See
1306 :attr:`~django.forms.formsets.BaseFormSet.can_delete` for instructions on how
1307 to manually delete objects from deleted forms.
1308
1309 * Loading empty fixtures emits a ``RuntimeWarning`` rather than raising
1310 :exc:`~django.core.management.CommandError`.
1311
1312 * :func:`django.contrib.staticfiles.views.serve` will now raise an
1313 :exc:`~django.http.Http404` exception instead of
1314 :exc:`~django.core.exceptions.ImproperlyConfigured` when :setting:`DEBUG`
1315 is ``False``. This change removes the need to conditionally add the view to
1316 your root URLconf, which in turn makes it safe to reverse by name. It also
1317 removes the ability for visitors to generate spurious HTTP 500 errors by
1318 requesting static files that don't exist or haven't been collected yet.
1319
1320 * The :meth:`django.db.models.Model.__eq__` method is now defined in a
1321 way where instances of a proxy model and its base model are considered
1322 equal when primary keys match. Previously only instances of exact same
1323 class were considered equal on primary key match.
1324
1325 * The :meth:`django.db.models.Model.__eq__` method has changed such that
1326 two ``Model`` instances without primary key values won't be considered
1327 equal (unless they are the same instance).
1328
1329 * The :meth:`django.db.models.Model.__hash__` method will now raise ``TypeError``
1330 when called on an instance without a primary key value. This is done to
1331 avoid mutable ``__hash__`` values in containers.
1332
1333 * :class:`~django.db.models.AutoField` columns in SQLite databases will now be
1334 created using the ``AUTOINCREMENT`` option, which guarantees monotonic
1335 increments. This will cause primary key numbering behavior to change on
1336 SQLite, becoming consistent with most other SQL databases. This will only
1337 apply to newly created tables. If you have a database created with an older
1338 version of Django, you will need to migrate it to take advantage of this
1339 feature. For example, you could do the following:
1340
1341 #) Use :djadmin:`dumpdata` to save your data.
1342 #) Rename the existing database file (keep it as a backup).
1343 #) Run :djadmin:`migrate` to create the updated schema.
1344 #) Use :djadmin:`loaddata` to import the fixtures you exported in (1).
1345
1346 * ``django.contrib.auth.models.AbstractUser`` no longer defines a
1347 :meth:`~django.db.models.Model.get_absolute_url()` method. The old definition
1348 returned ``"/users/%s/" % urlquote(self.username)`` which was arbitrary
1349 since applications may or may not define such a url in ``urlpatterns``.
1350 Define a ``get_absolute_url()`` method on your own custom user object or use
1351 :setting:`ABSOLUTE_URL_OVERRIDES` if you want a URL for your user.
1352
1353 * The static asset-serving functionality of the
1354 :class:`django.test.LiveServerTestCase` class has been simplified: Now it's
1355 only able to serve content already present in :setting:`STATIC_ROOT` when
1356 tests are run. The ability to transparently serve all the static assets
1357 (similarly to what one gets with :setting:`DEBUG = True <DEBUG>` at
1358 development-time) has been moved to a new class that lives in the
1359 ``staticfiles`` application (the one actually in charge of such feature):
1360 :class:`django.contrib.staticfiles.testing.StaticLiveServerTestCase`. In other
1361 words, ``LiveServerTestCase`` itself is less powerful but at the same time
1362 has less magic.
1363
1364 Rationale behind this is removal of dependency of non-contrib code on
1365 contrib applications.
1366
1367 * The old cache URI syntax (e.g. ``"locmem://"``) is no longer supported. It
1368 still worked, even though it was not documented or officially supported. If
1369 you're still using it, please update to the current :setting:`CACHES` syntax.
1370
1371 * The default ordering of ``Form`` fields in case of inheritance has changed to
1372 follow normal Python MRO. Fields are now discovered by iterating through the
1373 MRO in reverse with the topmost class coming last. This only affects you if
1374 you relied on the default field ordering while having fields defined on both
1375 the current class *and* on a parent ``Form``.
1376
1377 * The ``required`` argument of
1378 :class:`~django.forms.SelectDateWidget` has been removed.
1379 This widget now respects the form field's ``is_required`` attribute like
1380 other widgets.
1381
1382 * ``Widget.is_hidden`` is now a read-only property, getting its value by
1383 introspecting the presence of ``input_type == 'hidden'``.
1384
1385 * :meth:`~django.db.models.query.QuerySet.select_related` now chains in the
1386 same way as other similar calls like ``prefetch_related``. That is,
1387 ``select_related('foo', 'bar')`` is equivalent to
1388 ``select_related('foo').select_related('bar')``. Previously the latter would
1389 have been equivalent to ``select_related('bar')``.
1390
1391 * GeoDjango dropped support for GEOS < 3.1.
1392
1393 * The ``init_connection_state`` method of database backends now executes in
1394 autocommit mode (unless you set :setting:`AUTOCOMMIT <DATABASE-AUTOCOMMIT>`
1395 to ``False``). If you maintain a custom database backend, you should check
1396 that method.
1397
1398 * The ``django.db.backends.BaseDatabaseFeatures.allows_primary_key_0``
1399 attribute has been renamed to ``allows_auto_pk_0`` to better describe it.
1400 It's ``True`` for all database backends included with Django except MySQL
1401 which does allow primary keys with value 0. It only forbids *autoincrement*
1402 primary keys with value 0.
1403
1404 * Shadowing model fields defined in a parent model has been forbidden as this
1405 creates ambiguity in the expected model behavior. In addition, clashing
1406 fields in the model inheritance hierarchy result in a system check error.
1407 For example, if you use multi-inheritance, you need to define custom primary
1408 key fields on parent models, otherwise the default ``id`` fields will clash.
1409 See :ref:`model-multiple-inheritance-topic` for details.
1410
1411 * ``django.utils.translation.parse_accept_lang_header()`` now returns
1412 lowercase locales, instead of the case as it was provided. As locales should
1413 be treated case-insensitive this allows us to speed up locale detection.
1414
1415 * ``django.utils.translation.get_language_from_path()`` and
1416 ``django.utils.translation.trans_real.get_supported_language_variant()``
1417 now no longer have a ``supported`` argument.
1418
1419 * The ``shortcut`` view in ``django.contrib.contenttypes.views`` now supports
1420 protocol-relative URLs (e.g. ``//example.com``).
1421
1422 * :class:`~django.contrib.contenttypes.fields.GenericRelation` now supports an
1423 optional ``related_query_name`` argument. Setting ``related_query_name`` adds
1424 a relation from the related object back to the content type for filtering,
1425 ordering and other query operations.
1426
1427 * When running tests on PostgreSQL, the :setting:`USER` will need read access
1428 to the built-in ``postgres`` database. This is in lieu of the previous
1429 behavior of connecting to the actual non-test database.
1430
1431 * As part of the :doc:`System check framework </ref/checks>`, :ref:`fields,
1432 models, and model managers <field-checking>` all implement a ``check()``
1433 method that is registered with the check framework. If you have an existing
1434 method called ``check()`` on one of these objects, you will need to rename it.
1435
1436 * As noted above in the "Cache" section of "Minor Features", defining the
1437 :setting:`TIMEOUT <CACHES-TIMEOUT>` argument of the
1438 :setting:`CACHES` setting as ``None`` will set the cache keys as
1439 "non-expiring". Previously, with the memcache backend, a
1440 :setting:`TIMEOUT <CACHES-TIMEOUT>` of ``0`` would set non-expiring keys,
1441 but this was inconsistent with the set-and-expire (i.e. no caching) behavior
1442 of ``set("key", "value", timeout=0)``. If you want non-expiring keys,
1443 please update your settings to use ``None`` instead of ``0`` as the latter
1444 now designates set-and-expire in the settings as well.
1445
1446 * The ``sql*`` management commands now respect the ``allow_migrate()`` method
1447 of :setting:`DATABASE_ROUTERS`. If you have models synced to non-default
1448 databases, use the ``--database`` flag to get SQL for those models
1449 (previously they would always be included in the output).
1450
1451 * Decoding the query string from URLs now falls back to the ISO-8859-1 encoding
1452 when the input is not valid UTF-8.
1453
1454 * With the addition of the
1455 ``django.contrib.auth.middleware.SessionAuthenticationMiddleware`` to
1456 the default project template (pre-1.7.2 only), a database must be created
1457 before accessing a page using :djadmin:`runserver`.
1458
1459 * The addition of the ``schemes`` argument to ``URLValidator`` will appear
1460 as a backwards-incompatible change if you were previously using a custom
1461 regular expression to validate schemes. Any scheme not listed in ``schemes``
1462 will fail validation, even if the regular expression matches the given URL.
1463
1464 .. _deprecated-features-1.7:
1465
1466 Features deprecated in 1.7
1467 ==========================
1468
1469 ``django.core.cache.get_cache``
1470 -------------------------------
1471
1472 ``django.core.cache.get_cache`` has been supplanted by
1473 :data:`django.core.cache.caches`.
1474
1475 ``django.utils.dictconfig``/``django.utils.importlib``
1476 ------------------------------------------------------
1477
1478 ``django.utils.dictconfig`` and ``django.utils.importlib`` were copies of
1479 respectively :mod:`logging.config` and :mod:`importlib` provided for Python
1480 versions prior to 2.7. They have been deprecated.
1481
1482 ``django.utils.module_loading.import_by_path``
1483 ----------------------------------------------
1484
1485 The current ``django.utils.module_loading.import_by_path`` function
1486 catches ``AttributeError``, ``ImportError``, and ``ValueError`` exceptions,
1487 and re-raises :exc:`~django.core.exceptions.ImproperlyConfigured`. Such
1488 exception masking makes it needlessly hard to diagnose circular import
1489 problems, because it makes it look like the problem comes from inside Django.
1490 It has been deprecated in favor of
1491 :meth:`~django.utils.module_loading.import_string`.
1492
1493 ``django.utils.tzinfo``
1494 -----------------------
1495
1496 ``django.utils.tzinfo`` provided two :class:`~datetime.tzinfo` subclasses,
1497 ``LocalTimezone`` and ``FixedOffset``. They've been deprecated in favor of
1498 more correct alternatives provided by :mod:`django.utils.timezone`,
1499 :func:`django.utils.timezone.get_default_timezone` and
1500 :func:`django.utils.timezone.get_fixed_timezone`.
1501
1502 ``django.utils.unittest``
1503 -------------------------
1504
1505 ``django.utils.unittest`` provided uniform access to the ``unittest2`` library
1506 on all Python versions. Since ``unittest2`` became the standard library's
1507 :mod:`unittest` module in Python 2.7, and Django 1.7 drops support for older
1508 Python versions, this module isn't useful anymore. It has been deprecated. Use
1509 :mod:`unittest` instead.
1510
1511 ``django.utils.datastructures.SortedDict``
1512 ------------------------------------------
1513
1514 As :class:`~collections.OrderedDict` was added to the standard library in
1515 Python 2.7, ``SortedDict`` is no longer needed and has been deprecated.
1516
1517 The two additional, deprecated methods provided by ``SortedDict`` (``insert()``
1518 and ``value_for_index()``) have been removed. If you relied on these methods to
1519 alter structures like form fields, you should now treat these ``OrderedDict``\s
1520 as immutable objects and override them to change their content.
1521
1522 For example, you might want to override ``MyFormClass.base_fields`` (although
1523 this attribute isn't considered a public API) to change the ordering of fields
1524 for all ``MyFormClass`` instances; or similarly, you could override
1525 ``self.fields`` from inside ``MyFormClass.__init__()``, to change the fields
1526 for a particular form instance. For example (from Django itself)::
1527
1528 PasswordChangeForm.base_fields = OrderedDict(
1529 (k, PasswordChangeForm.base_fields[k])
1530 for k in ["old_password", "new_password1", "new_password2"]
1531 )
1532
1533 Custom SQL location for models package
1534 --------------------------------------
1535
1536 Previously, if models were organized in a package (``myapp/models/``) rather
1537 than simply ``myapp/models.py``, Django would look for initial SQL data in
1538 ``myapp/models/sql/``. This bug has been fixed so that Django
1539 will search ``myapp/sql/`` as documented. After this issue was fixed, migrations
1540 were added which deprecates initial SQL data. Thus, while this change still
1541 exists, the deprecation is irrelevant as the entire feature will be removed in
1542 Django 1.9.
1543
1544 Reorganization of ``django.contrib.sites``
1545 ------------------------------------------
1546
1547 ``django.contrib.sites`` provides reduced functionality when it isn't in
1548 :setting:`INSTALLED_APPS`. The app-loading refactor adds some constraints in
1549 that situation. As a consequence, two objects were moved, and the old
1550 locations are deprecated:
1551
1552 * :class:`~django.contrib.sites.requests.RequestSite` now lives in
1553 ``django.contrib.sites.requests``.
1554 * :func:`~django.contrib.sites.shortcuts.get_current_site` now lives in
1555 ``django.contrib.sites.shortcuts``.
1556
1557 ``declared_fieldsets`` attribute on ``ModelAdmin``
1558 --------------------------------------------------
1559
1560 ``ModelAdmin.declared_fieldsets`` has been deprecated. Despite being a private
1561 API, it will go through a regular deprecation path. This attribute was mostly
1562 used by methods that bypassed ``ModelAdmin.get_fieldsets()`` but this was
1563 considered a bug and has been addressed.
1564
1565 Reorganization of ``django.contrib.contenttypes``
1566 -------------------------------------------------
1567
1568 Since ``django.contrib.contenttypes.generic`` defined both admin and model
1569 related objects, an import of this module could trigger unexpected side effects.
1570 As a consequence, its contents were split into :mod:`~django.contrib.contenttypes`
1571 submodules and the ``django.contrib.contenttypes.generic`` module is deprecated:
1572
1573 * :class:`~django.contrib.contenttypes.fields.GenericForeignKey` and
1574 :class:`~django.contrib.contenttypes.fields.GenericRelation` now live in
1575 :mod:`~django.contrib.contenttypes.fields`.
1576 * :class:`~django.contrib.contenttypes.forms.BaseGenericInlineFormSet` and
1577 :func:`~django.contrib.contenttypes.forms.generic_inlineformset_factory` now
1578 live in :mod:`~django.contrib.contenttypes.forms`.
1579 * :class:`~django.contrib.contenttypes.admin.GenericInlineModelAdmin`,
1580 :class:`~django.contrib.contenttypes.admin.GenericStackedInline` and
1581 :class:`~django.contrib.contenttypes.admin.GenericTabularInline` now live in
1582 :mod:`~django.contrib.contenttypes.admin`.
1583
1584 ``syncdb``
1585 ----------
1586
1587 The ``syncdb`` command has been deprecated in favor of the new :djadmin:`migrate`
1588 command. ``migrate`` takes the same arguments as ``syncdb`` used to plus a few
1589 more, so it's safe to just change the name you're calling and nothing else.
1590
1591 ``util`` modules renamed to ``utils``
1592 -------------------------------------
1593
1594 The following instances of ``util.py`` in the Django codebase have been renamed
1595 to ``utils.py`` in an effort to unify all util and utils references:
1596
1597 * ``django.contrib.admin.util``
1598 * ``django.contrib.gis.db.backends.util``
1599 * ``django.db.backends.util``
1600 * ``django.forms.util``
1601
1602 ``get_formsets`` method on ``ModelAdmin``
1603 -----------------------------------------
1604
1605 ``ModelAdmin.get_formsets`` has been deprecated in favor of the new
1606 :meth:`~django.contrib.admin.ModelAdmin.get_formsets_with_inlines`, in order to
1607 better handle the case of selectively showing inlines on a ``ModelAdmin``.
1608
1609 ``IPAddressField``
1610 ------------------
1611
1612 The ``django.db.models.IPAddressField`` and ``django.forms.IPAddressField``
1613 fields have been deprecated in favor of
1614 :class:`django.db.models.GenericIPAddressField` and
1615 :class:`django.forms.GenericIPAddressField`.
1616
1617 ``BaseMemcachedCache._get_memcache_timeout`` method
1618 ---------------------------------------------------
1619
1620 The ``BaseMemcachedCache._get_memcache_timeout()`` method has been renamed to
1621 ``get_backend_timeout()``. Despite being a private API, it will go through the
1622 normal deprecation.
1623
1624 Natural key serialization options
1625 ---------------------------------
1626
1627 The ``--natural`` and ``-n`` options for :djadmin:`dumpdata` have been
1628 deprecated. Use :option:`dumpdata --natural-foreign` instead.
1629
1630 Similarly, the ``use_natural_keys`` argument for ``serializers.serialize()``
1631 has been deprecated. Use ``use_natural_foreign_keys`` instead.
1632
1633 Merging of ``POST`` and ``GET`` arguments into ``WSGIRequest.REQUEST``
1634 ----------------------------------------------------------------------
1635
1636 It was already strongly suggested that you use ``GET`` and ``POST`` instead of
1637 ``REQUEST``, because the former are more explicit. The property ``REQUEST`` is
1638 deprecated and will be removed in Django 1.9.
1639
1640 ``django.utils.datastructures.MergeDict`` class
1641 -----------------------------------------------
1642
1643 ``MergeDict`` exists primarily to support merging ``POST`` and ``GET``
1644 arguments into a ``REQUEST`` property on ``WSGIRequest``. To merge
1645 dictionaries, use ``dict.update()`` instead. The class ``MergeDict`` is
1646 deprecated and will be removed in Django 1.9.
1647
1648 Language codes ``zh-cn``, ``zh-tw`` and ``fy-nl``
1649 -------------------------------------------------
1650
1651 The currently used language codes for Simplified Chinese ``zh-cn``,
1652 Traditional Chinese ``zh-tw`` and (Western) Frysian ``fy-nl`` are deprecated
1653 and should be replaced by the language codes ``zh-hans``, ``zh-hant`` and
1654 ``fy`` respectively. If you use these language codes, you should rename the
1655 locale directories and update your settings to reflect these changes. The
1656 deprecated language codes will be removed in Django 1.9.
1657
1658 ``django.utils.functional.memoize`` function
1659 --------------------------------------------
1660
1661 The function ``memoize`` is deprecated and should be replaced by the
1662 ``functools.lru_cache`` decorator (available from Python 3.2 onward).
1663
1664 Django ships a backport of this decorator for older Python versions and it's
1665 available at ``django.utils.lru_cache.lru_cache``. The deprecated function will
1666 be removed in Django 1.9.
1667
1668 Geo Sitemaps
1669 ------------
1670
1671 Google has retired support for the Geo Sitemaps format. Hence Django support
1672 for Geo Sitemaps is deprecated and will be removed in Django 1.8.
1673
1674 Passing callable arguments to queryset methods
1675 ----------------------------------------------
1676
1677 Callable arguments for querysets were an undocumented feature that was
1678 unreliable. It's been deprecated and will be removed in Django 1.9.
1679
1680 Callable arguments were evaluated when a queryset was constructed rather than
1681 when it was evaluated, thus this feature didn't offer any benefit compared to
1682 evaluating arguments before passing them to queryset and created confusion that
1683 the arguments may have been evaluated at query time.
1684
1685 ``ADMIN_FOR`` setting
1686 ---------------------
1687
1688 The ``ADMIN_FOR`` feature, part of the admindocs, has been removed. You can
1689 remove the setting from your configuration at your convenience.
1690
1691 ``SplitDateTimeWidget`` with ``DateTimeField``
1692 ----------------------------------------------
1693
1694 ``SplitDateTimeWidget`` support in :class:`~django.forms.DateTimeField` is
1695 deprecated, use ``SplitDateTimeWidget`` with
1696 :class:`~django.forms.SplitDateTimeField` instead.
1697
1698 ``validate``
1699 ------------
1700
1701 The ``validate`` management command is deprecated in favor of the
1702 :djadmin:`check` command.
1703
1704 ``django.core.management.BaseCommand``
1705 --------------------------------------
1706
1707 ``requires_model_validation`` is deprecated in favor of a new
1708 ``requires_system_checks`` flag. If the latter flag is missing, then the
1709 value of the former flag is used. Defining both ``requires_system_checks`` and
1710 ``requires_model_validation`` results in an error.
1711
1712 The ``check()`` method has replaced the old ``validate()`` method.
1713
1714 ``ModelAdmin`` validators
1715 -------------------------
1716
1717 The ``ModelAdmin.validator_class`` and ``default_validator_class`` attributes
1718 are deprecated in favor of the new ``checks_class`` attribute.
1719
1720 The ``ModelAdmin.validate()`` method is deprecated in favor of
1721 ``ModelAdmin.check()``.
1722
1723 The ``django.contrib.admin.validation`` module is deprecated.
1724
1725 ``django.db.backends.DatabaseValidation.validate_field``
1726 --------------------------------------------------------
1727
1728 This method is deprecated in favor of a new ``check_field`` method.
1729 The functionality required by ``check_field()`` is the same as that provided
1730 by ``validate_field()``, but the output format is different. Third-party database
1731 backends needing this functionality should provide an implementation of
1732 ``check_field()``.
1733
1734 Loading ``ssi`` and ``url`` template tags from ``future`` library
1735 -----------------------------------------------------------------
1736
1737 Django 1.3 introduced ``{% load ssi from future %}`` and
1738 ``{% load url from future %}`` syntax for forward compatibility of the
1739 ``ssi`` and :ttag:`url` template tags. This syntax is now deprecated and
1740 will be removed in Django 1.9. You can simply remove the
1741 ``{% load ... from future %}`` tags.
1742
1743 ``django.utils.text.javascript_quote``
1744 --------------------------------------
1745
1746 ``javascript_quote()`` was an undocumented function present in ``django.utils.text``.
1747 It was used internally in the ``javascript_catalog()`` view
1748 whose implementation was changed to make use of ``json.dumps()`` instead.
1749 If you were relying on this function to provide safe output from untrusted
1750 strings, you should use ``django.utils.html.escapejs`` or the
1751 :tfilter:`escapejs` template filter.
1752 If all you need is to generate valid JavaScript strings, you can simply use
1753 ``json.dumps()``.
1754
1755 ``fix_ampersands`` utils method and template filter
1756 ---------------------------------------------------
1757
1758 The ``django.utils.html.fix_ampersands`` method and the ``fix_ampersands``
1759 template filter are deprecated, as the escaping of ampersands is already taken care
1760 of by Django's standard HTML escaping features. Combining this with ``fix_ampersands``
1761 would either result in double escaping, or, if the output is assumed to be safe,
1762 a risk of introducing XSS vulnerabilities. Along with ``fix_ampersands``,
1763 ``django.utils.html.clean_html`` is deprecated, an undocumented function that calls
1764 ``fix_ampersands``.
1765 As this is an accelerated deprecation, ``fix_ampersands`` and ``clean_html``
1766 will be removed in Django 1.8.
1767
1768 Reorganization of database test settings
1769 ----------------------------------------
1770
1771 All database settings with a ``TEST_`` prefix have been deprecated in favor of
1772 entries in a :setting:`TEST <DATABASE-TEST>` dictionary in the database
1773 settings. The old settings will be supported until Django 1.9. For backwards
1774 compatibility with older versions of Django, you can define both versions of
1775 the settings as long as they match.
1776
1777 FastCGI support
1778 ---------------
1779
1780 FastCGI support via the ``runfcgi`` management command will be removed in
1781 Django 1.9. Please deploy your project using WSGI.
1782
1783 Moved objects in ``contrib.sites``
1784 ----------------------------------
1785
1786 Following the app-loading refactor, two objects in
1787 ``django.contrib.sites.models`` needed to be moved because they must be
1788 available without importing ``django.contrib.sites.models`` when
1789 ``django.contrib.sites`` isn't installed. Import ``RequestSite`` from
1790 ``django.contrib.sites.requests`` and ``get_current_site()`` from
1791 ``django.contrib.sites.shortcuts``. The old import locations will work until
1792 Django 1.9.
1793
1794 ``django.forms.forms.get_declared_fields()``
1795 --------------------------------------------
1796
1797 Django no longer uses this functional internally. Even though it's a private
1798 API, it'll go through the normal deprecation cycle.
1799
1800 Private Query Lookup APIs
1801 -------------------------
1802
1803 Private APIs ``django.db.models.sql.where.WhereNode.make_atom()`` and
1804 ``django.db.models.sql.where.Constraint`` are deprecated in favor of the new
1805 :doc:`custom lookups API </ref/models/lookups>`.
1806
1807 .. _removed-features-1.7:
1808
1809 Features removed in 1.7
1810 =======================
1811
1812 These features have reached the end of their deprecation cycle and are removed
1813 in Django 1.7. See :ref:`deprecated-features-1.5` for details, including how to
1814 remove usage of these features.
1815
1816 * ``django.utils.simplejson`` is removed.
1817
1818 * ``django.utils.itercompat.product`` is removed.
1819
1820 * INSTALLED_APPS and TEMPLATE_DIRS are no longer corrected from a plain
1821 string into a tuple.
1822
1823 * :class:`~django.http.HttpResponse`,
1824 :class:`~django.template.response.SimpleTemplateResponse`,
1825 :class:`~django.template.response.TemplateResponse`,
1826 ``render_to_response()``, :func:`~django.contrib.sitemaps.views.index`, and
1827 :func:`~django.contrib.sitemaps.views.sitemap` no longer take a ``mimetype``
1828 argument
1829
1830 * :class:`~django.http.HttpResponse` immediately consumes its content if it's
1831 an iterator.
1832
1833 * The ``AUTH_PROFILE_MODULE`` setting, and the ``get_profile()`` method on
1834 the User model are removed.
1835
1836 * The ``cleanup`` management command is removed.
1837
1838 * The ``daily_cleanup.py`` script is removed.
1839
1840 * :meth:`~django.db.models.query.QuerySet.select_related` no longer has a
1841 ``depth`` keyword argument.
1842
1843 * The ``get_warnings_state()``/``restore_warnings_state()``
1844 functions from :mod:`django.test.utils` and the ``save_warnings_state()``/
1845 ``restore_warnings_state()``
1846 :ref:`django.test.*TestCase <django-testcase-subclasses>` are removed.
1847
1848 * The ``check_for_test_cookie`` method in
1849 :class:`~django.contrib.auth.forms.AuthenticationForm` is removed.
1850
1851 * The version of ``django.contrib.auth.views.password_reset_confirm()`` that
1852 supports base36 encoded user IDs
1853 (``django.contrib.auth.views.password_reset_confirm_uidb36``) is removed.
1854
1855 * The ``django.utils.encoding.StrAndUnicode`` mix-in is removed.