| 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. |