Debian Codegraph @

docs/releases/2.0.txt

raw
1 ========================
2 Django 2.0 release notes
3 ========================
4
5 *December 2, 2017*
6
7 Welcome to Django 2.0!
8
9 These release notes cover the :ref:`new features <whats-new-2.0>`, as well as
10 some :ref:`backwards incompatible changes <backwards-incompatible-2.0>` you'll
11 want to be aware of when upgrading from Django 1.11 or earlier. We've
12 :ref:`dropped some features<removed-features-2.0>` that have reached the end of
13 their deprecation cycle, and we've :ref:`begun the deprecation process for some
14 features <deprecated-features-2.0>`.
15
16 This release starts Django's use of a :ref:`loose form of semantic versioning
17 <internal-release-cadence>`, but there aren't any major backwards incompatible
18 changes that might be expected of a 2.0 release. Upgrading should be a similar
19 amount of effort as past feature releases.
20
21 See the :doc:`/howto/upgrade-version` guide if you're updating an existing
22 project.
23
24 Python compatibility
25 ====================
26
27 Django 2.0 supports Python 3.4, 3.5, 3.6, and 3.7. We **highly recommend** and
28 only officially support the latest release of each series.
29
30 The Django 1.11.x series is the last to support Python 2.7.
31
32 Django 2.0 will be the last release series to support Python 3.4. If you plan
33 a deployment of Python 3.4 beyond the end-of-life for Django 2.0 (April 2019),
34 stick with Django 1.11 LTS (supported until April 2020) instead. Note, however,
35 that the end-of-life for Python 3.4 is March 2019.
36
37 Third-party library support for older version of Django
38 =======================================================
39
40 Following the release of Django 2.0, we suggest that third-party app authors
41 drop support for all versions of Django prior to 1.11. At that time, you should
42 be able to run your package's tests using ``python -Wd`` so that deprecation
43 warnings do appear. After making the deprecation warning fixes, your app should
44 be compatible with Django 2.0.
45
46 .. _whats-new-2.0:
47
48 What's new in Django 2.0
49 ========================
50
51 Simplified URL routing syntax
52 -----------------------------
53
54 The new :func:`django.urls.path()` function allows a simpler, more readable URL
55 routing syntax. For example, this example from previous Django releases::
56
57 url(r"^articles/(?P<year>[0-9]{4})/$", views.year_archive),
58
59 could be written as::
60
61 path("articles/<int:year>/", views.year_archive),
62
63 The new syntax supports type coercion of URL parameters. In the example, the
64 view will receive the ``year`` keyword argument as an integer rather than as
65 a string. Also, the URLs that will match are slightly less constrained in the
66 rewritten example. For example, the year 10000 will now match since the year
67 integers aren't constrained to be exactly four digits long as they are in the
68 regular expression.
69
70 The ``django.conf.urls.url()`` function from previous versions is now available
71 as :func:`django.urls.re_path`. The old location remains for backwards
72 compatibility, without an imminent deprecation. The old
73 ``django.conf.urls.include()`` function is now importable from ``django.urls``
74 so you can use ``from django.urls import include, path, re_path`` in your
75 URLconfs.
76
77 The :doc:`/topics/http/urls` document is rewritten to feature the new syntax
78 and provide more details.
79
80 Mobile-friendly ``contrib.admin``
81 ---------------------------------
82
83 The admin is now responsive and supports all major mobile devices. Older
84 browsers may experience varying levels of graceful degradation.
85
86 Window expressions
87 ------------------
88
89 The new :class:`~django.db.models.expressions.Window` expression allows
90 adding an ``OVER`` clause to querysets. You can use :ref:`window functions
91 <window-functions>` and :ref:`aggregate functions <aggregation-functions>` in
92 the expression.
93
94 Minor features
95 --------------
96
97 :mod:`django.contrib.admin`
98 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
99
100 * The new :attr:`.ModelAdmin.autocomplete_fields` attribute and
101 :meth:`.ModelAdmin.get_autocomplete_fields` method allow using a
102 `Select2 <https://select2.org/>`_ search widget for ``ForeignKey`` and
103 ``ManyToManyField``.
104
105 :mod:`django.contrib.auth`
106 ~~~~~~~~~~~~~~~~~~~~~~~~~~
107
108 * The default iteration count for the PBKDF2 password hasher is increased from
109 36,000 to 100,000.
110
111 :mod:`django.contrib.gis`
112 ~~~~~~~~~~~~~~~~~~~~~~~~~
113
114 * Added MySQL support for the
115 :class:`~django.contrib.gis.db.models.functions.AsGeoJSON` function,
116 :class:`~django.contrib.gis.db.models.functions.GeoHash` function,
117 :class:`~django.contrib.gis.db.models.functions.IsValid` function,
118 :lookup:`isvalid` lookup, and :ref:`distance lookups <distance-lookups>`.
119
120 * Added the :class:`~django.contrib.gis.db.models.functions.Azimuth` and
121 :class:`~django.contrib.gis.db.models.functions.LineLocatePoint` functions,
122 supported on PostGIS and SpatiaLite.
123
124 * Any :class:`~django.contrib.gis.geos.GEOSGeometry` imported from GeoJSON now
125 has its SRID set.
126
127 * Added the :attr:`.OSMWidget.default_zoom` attribute to customize the map's
128 default zoom level.
129
130 * Made metadata readable and editable on rasters through the
131 :attr:`~django.contrib.gis.gdal.GDALRaster.metadata`,
132 :attr:`~django.contrib.gis.gdal.GDALRaster.info`, and
133 :attr:`~django.contrib.gis.gdal.GDALBand.metadata` attributes.
134
135 * Allowed passing driver-specific creation options to
136 :class:`~django.contrib.gis.gdal.GDALRaster` objects using ``papsz_options``.
137
138 * Allowed creating :class:`~django.contrib.gis.gdal.GDALRaster` objects in
139 GDAL's internal virtual filesystem. Rasters can now be :ref:`created from and
140 converted to binary data <gdal-raster-vsimem>` in-memory.
141
142 * The new :meth:`GDALBand.color_interp()
143 <django.contrib.gis.gdal.GDALBand.color_interp>` method returns the color
144 interpretation for the band.
145
146 :mod:`django.contrib.postgres`
147 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
148
149 * The new ``distinct`` argument for
150 :class:`~django.contrib.postgres.aggregates.ArrayAgg` determines if
151 concatenated values will be distinct.
152
153 * The new :class:`~django.contrib.postgres.functions.RandomUUID` database
154 function returns a version 4 UUID. It requires use of PostgreSQL's
155 ``pgcrypto`` extension which can be activated using the new
156 :class:`~django.contrib.postgres.operations.CryptoExtension` migration
157 operation.
158
159 * :class:`django.contrib.postgres.indexes.GinIndex` now supports the
160 ``fastupdate`` and ``gin_pending_list_limit`` parameters.
161
162 * The new :class:`~django.contrib.postgres.indexes.GistIndex` class allows
163 creating ``GiST`` indexes in the database. The new
164 :class:`~django.contrib.postgres.operations.BtreeGistExtension` migration
165 operation installs the ``btree_gist`` extension to add support for operator
166 classes that aren't built-in.
167
168 * :djadmin:`inspectdb` can now introspect ``JSONField`` and various
169 ``RangeField``\s (``django.contrib.postgres`` must be in ``INSTALLED_APPS``).
170
171 :mod:`django.contrib.sitemaps`
172 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
173
174 * Added the ``protocol`` keyword argument to the
175 :class:`~django.contrib.sitemaps.GenericSitemap` constructor.
176
177 Cache
178 ~~~~~
179
180 * ``cache.set_many()`` now returns a list of keys that failed to be inserted.
181 For the built-in backends, failed inserts can only happen on memcached.
182
183 File Storage
184 ~~~~~~~~~~~~
185
186 * :meth:`File.open() <django.core.files.File.open>` can be used as a context
187 manager, e.g. ``with file.open() as f:``.
188
189 Forms
190 ~~~~~
191
192 * The new ``date_attrs`` and ``time_attrs`` arguments for
193 :class:`~django.forms.SplitDateTimeWidget` and
194 :class:`~django.forms.SplitHiddenDateTimeWidget` allow specifying different
195 HTML attributes for the ``DateInput`` and ``TimeInput`` (or hidden)
196 subwidgets.
197
198 * The new :meth:`Form.errors.get_json_data()
199 <django.forms.Form.errors.get_json_data>` method returns form errors as
200 a dictionary suitable for including in a JSON response.
201
202 Generic Views
203 ~~~~~~~~~~~~~
204
205 * The new :attr:`.ContextMixin.extra_context` attribute allows adding context
206 in ``View.as_view()``.
207
208 Management Commands
209 ~~~~~~~~~~~~~~~~~~~
210
211 * :djadmin:`inspectdb` now translates MySQL's unsigned integer columns to
212 ``PositiveIntegerField`` or ``PositiveSmallIntegerField``.
213
214 * The new :option:`makemessages --add-location` option controls the comment
215 format in ``.po`` files.
216
217 * :djadmin:`loaddata` can now :ref:`read from stdin <loading-fixtures-stdin>`.
218
219 * The new :option:`diffsettings --output` option allows formatting the output
220 in a unified diff format.
221
222 * On Oracle, :djadmin:`inspectdb` can now introspect ``AutoField`` if the
223 column is created as an identity column.
224
225 * On MySQL, :djadmin:`dbshell` now supports client-side TLS certificates.
226
227 Migrations
228 ~~~~~~~~~~
229
230 * The new :option:`squashmigrations --squashed-name` option allows naming the
231 squashed migration.
232
233 Models
234 ~~~~~~
235
236 * The new :class:`~django.db.models.functions.StrIndex` database function
237 finds the starting index of a string inside another string.
238
239 * On Oracle, ``AutoField`` and ``BigAutoField`` are now created as `identity
240 columns <https://docs.oracle.com/en/database/oracle/oracle-database/21/drdaa/
241 intro-to-tools-and-products-supporting-migraiton.html#GUID-14E4817B-F3BC-4D99
242 -B471-A0ACDC303CC9>`__.
243
244 * The new ``chunk_size`` parameter of :meth:`.QuerySet.iterator` controls the
245 number of rows fetched by the Python database client when streaming results
246 from the database. For databases that don't support server-side cursors, it
247 controls the number of results Django fetches from the database adapter.
248
249 * :meth:`.QuerySet.earliest`, :meth:`.QuerySet.latest`, and
250 :attr:`Meta.get_latest_by <django.db.models.Options.get_latest_by>` now
251 allow ordering by several fields.
252
253 * Added the :class:`~django.db.models.functions.ExtractQuarter` function to
254 extract the quarter from :class:`~django.db.models.DateField` and
255 :class:`~django.db.models.DateTimeField`, and exposed it through the
256 :lookup:`quarter` lookup.
257
258 * Added the :class:`~django.db.models.functions.TruncQuarter` function to
259 truncate :class:`~django.db.models.DateField` and
260 :class:`~django.db.models.DateTimeField` to the first day of a quarter.
261
262 * Added the :attr:`~django.db.models.Index.db_tablespace` parameter to
263 class-based indexes.
264
265 * If the database supports a native duration field (Oracle and PostgreSQL),
266 :class:`~django.db.models.functions.Extract` now works with
267 :class:`~django.db.models.DurationField`.
268
269 * Added the ``of`` argument to :meth:`.QuerySet.select_for_update()`, supported
270 on PostgreSQL and Oracle, to lock only rows from specific tables rather than
271 all selected tables. It may be helpful particularly when
272 :meth:`~.QuerySet.select_for_update()` is used in conjunction with
273 :meth:`~.QuerySet.select_related()`.
274
275 * The new ``field_name`` parameter of :meth:`.QuerySet.in_bulk` allows fetching
276 results based on any unique model field.
277
278 * :meth:`.CursorWrapper.callproc()` now takes an optional dictionary of keyword
279 parameters, if the backend supports this feature. Of Django's built-in
280 backends, only Oracle supports it.
281
282 * The new :meth:`connection.execute_wrapper()
283 <django.db.backends.base.DatabaseWrapper.execute_wrapper>` method allows
284 :doc:`installing wrappers around execution of database queries
285 </topics/db/instrumentation>`.
286
287 * The new ``filter`` argument for built-in aggregates allows :ref:`adding
288 different conditionals <conditional-aggregation>` to multiple aggregations
289 over the same fields or relations.
290
291 * Added support for expressions in :attr:`Meta.ordering
292 <django.db.models.Options.ordering>`.
293
294 * The new ``named`` parameter of :meth:`.QuerySet.values_list` allows fetching
295 results as named tuples.
296
297 * The new :class:`.FilteredRelation` class allows adding an ``ON`` clause to
298 querysets.
299
300 Pagination
301 ~~~~~~~~~~
302
303 * Added :meth:`Paginator.get_page() <django.core.paginator.Paginator.get_page>`
304 to provide the documented pattern of handling invalid page numbers.
305
306 Requests and Responses
307 ~~~~~~~~~~~~~~~~~~~~~~
308
309 * The :djadmin:`runserver` web server supports HTTP 1.1.
310
311 Templates
312 ~~~~~~~~~
313
314 * To increase the usefulness of :meth:`.Engine.get_default` in third-party
315 apps, it now returns the first engine if multiple ``DjangoTemplates`` engines
316 are configured in ``TEMPLATES`` rather than raising ``ImproperlyConfigured``.
317
318 * Custom template tags may now accept keyword-only arguments.
319
320 Tests
321 ~~~~~
322
323 * Added threading support to :class:`~django.test.LiveServerTestCase`.
324
325 * Added settings that allow customizing the test tablespace parameters for
326 Oracle: :setting:`DATAFILE_SIZE`, :setting:`DATAFILE_TMP_SIZE`,
327 :setting:`DATAFILE_EXTSIZE`, and :setting:`DATAFILE_TMP_EXTSIZE`.
328
329 Validators
330 ~~~~~~~~~~
331
332 * The new :class:`.ProhibitNullCharactersValidator` disallows the null
333 character in the input of the :class:`~django.forms.CharField` form field
334 and its subclasses. Null character input was observed from vulnerability
335 scanning tools. Most databases silently discard null characters, but
336 psycopg2 2.7+ raises an exception when trying to save a null character to
337 a char/text field with PostgreSQL.
338
339 .. _backwards-incompatible-2.0:
340
341 Backwards incompatible changes in 2.0
342 =====================================
343
344 Removed support for bytestrings in some places
345 ----------------------------------------------
346
347 To support native Python 2 strings, older Django versions had to accept both
348 bytestrings and Unicode strings. Now that Python 2 support is dropped,
349 bytestrings should only be encountered around input/output boundaries (handling
350 of binary fields or HTTP streams, for example). You might have to update your
351 code to limit bytestring usage to a minimum, as Django no longer accepts
352 bytestrings in certain code paths. Python's :option:`-b` option may help detect
353 that mistake in your code.
354
355 For example, ``reverse()`` now uses ``str()`` instead of ``force_text()`` to
356 coerce the ``args`` and ``kwargs`` it receives, prior to their placement in
357 the URL. For bytestrings, this creates a string with an undesired ``b`` prefix
358 as well as additional quotes (``str(b'foo')`` is ``"b'foo'"``). To adapt, call
359 ``decode()`` on the bytestring before passing it to ``reverse()``.
360
361 Database backend API
362 --------------------
363
364 This section describes changes that may be needed in third-party database
365 backends.
366
367 * The ``DatabaseOperations.datetime_cast_date_sql()``,
368 ``datetime_cast_time_sql()``, ``datetime_trunc_sql()``,
369 ``datetime_extract_sql()``, and ``date_interval_sql()`` methods now return
370 only the SQL to perform the operation instead of SQL and a list of
371 parameters.
372
373 * Third-party database backends should add a ``DatabaseWrapper.display_name``
374 attribute with the name of the database that your backend works with. Django
375 may use it in various messages, such as in system checks.
376
377 * The first argument of ``SchemaEditor._alter_column_type_sql()`` is now
378 ``model`` rather than ``table``.
379
380 * The first argument of ``SchemaEditor._create_index_name()`` is now
381 ``table_name`` rather than ``model``.
382
383 * To enable ``FOR UPDATE OF`` support, set
384 ``DatabaseFeatures.has_select_for_update_of = True``. If the database
385 requires that the arguments to ``OF`` be columns rather than tables, set
386 ``DatabaseFeatures.select_for_update_of_column = True``.
387
388 * To enable support for :class:`~django.db.models.expressions.Window`
389 expressions, set ``DatabaseFeatures.supports_over_clause`` to ``True``. You
390 may need to customize the ``DatabaseOperations.window_start_rows_start_end()``
391 and/or ``window_start_range_start_end()`` methods.
392
393 * Third-party database backends should add a
394 ``DatabaseOperations.cast_char_field_without_max_length`` attribute with the
395 database data type that will be used in the
396 :class:`~django.db.models.functions.Cast` function for a ``CharField`` if the
397 ``max_length`` argument isn't provided.
398
399 * The first argument of ``DatabaseCreation._clone_test_db()`` and
400 ``get_test_db_clone_settings()`` is now ``suffix`` rather
401 than ``number`` (in case you want to rename the signatures in your backend
402 for consistency). ``django.test`` also now passes those values as strings
403 rather than as integers.
404
405 * Third-party database backends should add a
406 ``DatabaseIntrospection.get_sequences()`` method based on the stub in
407 ``BaseDatabaseIntrospection``.
408
409 Dropped support for Oracle 11.2
410 -------------------------------
411
412 The end of upstream support for Oracle 11.2 is Dec. 2020. Django 1.11 will be
413 supported until April 2020 which almost reaches this date. Django 2.0
414 officially supports Oracle 12.1+.
415
416 Default MySQL isolation level is read committed
417 -----------------------------------------------
418
419 MySQL's default isolation level, repeatable read, may cause data loss in
420 typical Django usage. To prevent that and for consistency with other databases,
421 the default isolation level is now read committed. You can use the
422 :setting:`DATABASES` setting to :ref:`use a different isolation level
423 <mysql-isolation-level>`, if needed.
424
425 :attr:`AbstractUser.last_name <django.contrib.auth.models.User.last_name>` ``max_length`` increased to 150
426 ----------------------------------------------------------------------------------------------------------
427
428 A migration for :attr:`django.contrib.auth.models.User.last_name` is included.
429 If you have a custom user model inheriting from ``AbstractUser``, you'll need
430 to generate and apply a database migration for your user model.
431
432 If you want to preserve the 30 character limit for last names, use a custom
433 form::
434
435 from django.contrib.auth.forms import UserChangeForm
436
437
438 class MyUserChangeForm(UserChangeForm):
439 last_name = forms.CharField(max_length=30, required=False)
440
441 If you wish to keep this restriction in the admin when editing users, set
442 ``UserAdmin.form`` to use this form::
443
444 from django.contrib.auth.admin import UserAdmin
445 from django.contrib.auth.models import User
446
447
448 class MyUserAdmin(UserAdmin):
449 form = MyUserChangeForm
450
451
452 admin.site.unregister(User)
453 admin.site.register(User, MyUserAdmin)
454
455 ``QuerySet.reverse()`` and ``last()`` are prohibited after slicing
456 ------------------------------------------------------------------
457
458 Calling ``QuerySet.reverse()`` or ``last()`` on a sliced queryset leads to
459 unexpected results due to the slice being applied after reordering. This is
460 now prohibited, e.g.:
461
462 .. code-block:: pycon
463
464 >>> Model.objects.all()[:2].reverse()
465 Traceback (most recent call last):
466 ...
467 TypeError: Cannot reverse a query once a slice has been taken.
468
469 Form fields no longer accept optional arguments as positional arguments
470 -----------------------------------------------------------------------
471
472 To help prevent runtime errors due to incorrect ordering of form field
473 arguments, optional arguments of built-in form fields are no longer accepted
474 as positional arguments. For example::
475
476 forms.IntegerField(25, 10)
477
478 raises an exception and should be replaced with::
479
480 forms.IntegerField(max_value=25, min_value=10)
481
482 ``call_command()`` validates the options it receives
483 ----------------------------------------------------
484
485 ``call_command()`` now validates that the argument parser of the command being
486 called defines all of the options passed to ``call_command()``.
487
488 For custom management commands that use options not created using
489 ``parser.add_argument()``, add a ``stealth_options`` attribute on the command::
490
491 class MyCommand(BaseCommand):
492 stealth_options = ("option_name", ...)
493
494 Indexes no longer accept positional arguments
495 ---------------------------------------------
496
497 For example::
498
499 models.Index(["headline", "-pub_date"], "index_name")
500
501 raises an exception and should be replaced with::
502
503 models.Index(fields=["headline", "-pub_date"], name="index_name")
504
505 Foreign key constraints are now enabled on SQLite
506 -------------------------------------------------
507
508 This will appear as a backwards-incompatible change (``IntegrityError:
509 FOREIGN KEY constraint failed``) if attempting to save an existing model
510 instance that's violating a foreign key constraint.
511
512 Foreign keys are now created with ``DEFERRABLE INITIALLY DEFERRED`` instead of
513 ``DEFERRABLE IMMEDIATE``. Thus, tables may need to be rebuilt to recreate
514 foreign keys with the new definition, particularly if you're using a pattern
515 like this::
516
517 from django.db import transaction
518
519 with transaction.atomic():
520 Book.objects.create(author_id=1)
521 Author.objects.create(id=1)
522
523 If you don't recreate the foreign key as ``DEFERRED``, the first ``create()``
524 would fail now that foreign key constraints are enforced.
525
526 Backup your database first! After upgrading to Django 2.0, you can then
527 rebuild tables using a script similar to this::
528
529 from django.apps import apps
530 from django.db import connection
531
532 for app in apps.get_app_configs():
533 for model in app.get_models(include_auto_created=True):
534 if model._meta.managed and not (model._meta.proxy or model._meta.swapped):
535 for base in model.__bases__:
536 if hasattr(base, "_meta"):
537 base._meta.local_many_to_many = []
538 model._meta.local_many_to_many = []
539 with connection.schema_editor() as editor:
540 editor._remake_table(model)
541
542 This script hasn't received extensive testing and needs adaption for various
543 cases such as multiple databases. Feel free to contribute improvements.
544
545 In addition, because of a table alteration limitation of SQLite, it's prohibited
546 to perform :class:`~django.db.migrations.operations.RenameModel` and
547 :class:`~django.db.migrations.operations.RenameField` operations on models or
548 fields referenced by other models in a transaction. In order to allow migrations
549 containing these operations to be applied, you must set the
550 ``Migration.atomic`` attribute to ``False``.
551
552 Miscellaneous
553 -------------
554
555 * The ``SessionAuthenticationMiddleware`` class is removed. It provided no
556 functionality since session authentication is unconditionally enabled in
557 Django 1.10.
558
559 * The default HTTP error handlers (``handler404``, etc.) are now callables
560 instead of dotted Python path strings. Django favors callable references
561 since they provide better performance and debugging experience.
562
563 * :class:`~django.views.generic.base.RedirectView` no longer silences
564 ``NoReverseMatch`` if the ``pattern_name`` doesn't exist.
565
566 * When ``USE_L10N`` is off, :class:`~django.forms.FloatField` and
567 :class:`~django.forms.DecimalField` now respect :setting:`DECIMAL_SEPARATOR`
568 and :setting:`THOUSAND_SEPARATOR` during validation. For example, with the
569 settings::
570
571 USE_L10N = False
572 USE_THOUSAND_SEPARATOR = True
573 DECIMAL_SEPARATOR = ","
574 THOUSAND_SEPARATOR = "."
575
576 an input of ``"1.345"`` is now converted to ``1345`` instead of ``1.345``.
577
578 * Subclasses of :class:`~django.contrib.auth.models.AbstractBaseUser` are no
579 longer required to implement ``get_short_name()`` and ``get_full_name()``.
580 (The base implementations that raise ``NotImplementedError`` are removed.)
581 ``django.contrib.admin`` uses these methods if implemented but doesn't
582 require them. Third-party apps that use these methods may want to adopt a
583 similar approach.
584
585 * The ``FIRST_DAY_OF_WEEK`` and ``NUMBER_GROUPING`` format settings are now
586 kept as integers in JavaScript and JSON i18n view outputs.
587
588 * :meth:`~django.test.TransactionTestCase.assertNumQueries` now ignores
589 connection configuration queries. Previously, if a test opened a new database
590 connection, those queries could be included as part of the
591 ``assertNumQueries()`` count.
592
593 * The default size of the Oracle test tablespace is increased from 20M to 50M
594 and the default autoextend size is increased from 10M to 25M.
595
596 * To improve performance when streaming large result sets from the database,
597 :meth:`.QuerySet.iterator` now fetches 2000 rows at a time instead of 100.
598 The old behavior can be restored using the ``chunk_size`` parameter. For
599 example::
600
601 Book.objects.iterator(chunk_size=100)
602
603 * Providing unknown package names in the ``packages`` argument of the
604 :class:`~django.views.i18n.JavaScriptCatalog` view now raises ``ValueError``
605 instead of passing silently.
606
607 * A model instance's primary key now appears in the default ``Model.__str__()``
608 method, e.g. ``Question object (1)``.
609
610 * ``makemigrations`` now detects changes to the model field ``limit_choices_to``
611 option. Add this to your existing migrations or accept an auto-generated
612 migration for fields that use it.
613
614 * Performing queries that require :ref:`automatic spatial transformations
615 <automatic-spatial-transformations>` now raises ``NotImplementedError``
616 on MySQL instead of silently using non-transformed geometries.
617
618 * ``django.core.exceptions.DjangoRuntimeWarning`` is removed. It was only used
619 in the cache backend as an intermediate class in ``CacheKeyWarning``'s
620 inheritance of ``RuntimeWarning``.
621
622 * Renamed ``BaseExpression._output_field`` to ``output_field``. You may need
623 to update custom expressions.
624
625 * In older versions, forms and formsets combine their ``Media`` with widget
626 ``Media`` by concatenating the two. The combining now tries to :ref:`preserve
627 the relative order of elements in each list <form-media-asset-order>`.
628 ``MediaOrderConflictWarning`` is issued if the order can't be preserved.
629
630 * ``django.contrib.gis.gdal.OGRException`` is removed. It's been an alias for
631 ``GDALException`` since Django 1.8.
632
633 * Support for GEOS 3.3.x is dropped.
634
635 * The way data is selected for ``GeometryField`` is changed to improve
636 performance, and in raw SQL queries, those fields must now be wrapped in
637 ``connection.ops.select``. See the :ref:`Raw queries note<gis-raw-sql>` in
638 the GIS tutorial for an example.
639
640 .. _deprecated-features-2.0:
641
642 Features deprecated in 2.0
643 ==========================
644
645 ``context`` argument of ``Field.from_db_value()`` and ``Expression.convert_value()``
646 ------------------------------------------------------------------------------------
647
648 The ``context`` argument of ``Field.from_db_value()`` and
649 ``Expression.convert_value()`` is unused as it's always an empty dictionary.
650 The signature of both methods is now::
651
652 (self, value, expression, connection)
653
654 instead of::
655
656 (self, value, expression, connection, context)
657
658 Support for the old signature in custom fields and expressions remains until
659 Django 3.0.
660
661 Miscellaneous
662 -------------
663
664 * The ``django.db.backends.postgresql_psycopg2`` module is deprecated in favor
665 of ``django.db.backends.postgresql``. It's been an alias since Django 1.9.
666 This only affects code that imports from the module directly. The
667 ``DATABASES`` setting can still use
668 ``'django.db.backends.postgresql_psycopg2'``, though you can simplify that by
669 using the ``'django.db.backends.postgresql'`` name added in Django 1.9.
670
671 * ``django.shortcuts.render_to_response()`` is deprecated in favor of
672 :func:`django.shortcuts.render`. ``render()`` takes the same arguments
673 except that it also requires a ``request``.
674
675 * The ``DEFAULT_CONTENT_TYPE`` setting is deprecated. It doesn't interact well
676 with third-party apps and is obsolete since HTML5 has mostly superseded
677 XHTML.
678
679 * ``HttpRequest.xreadlines()`` is deprecated in favor of iterating over the
680 request.
681
682 * The ``field_name`` keyword argument to :meth:`.QuerySet.earliest` and
683 :meth:`.QuerySet.latest` is deprecated in favor of passing the field
684 names as arguments. Write ``.earliest('pub_date')`` instead of
685 ``.earliest(field_name='pub_date')``.
686
687 .. _removed-features-2.0:
688
689 Features removed in 2.0
690 =======================
691
692 These features have reached the end of their deprecation cycle and are removed
693 in Django 2.0.
694
695 See :ref:`deprecated-features-1.9` for details on these changes, including how
696 to remove usage of these features.
697
698 * The ``weak`` argument to ``django.dispatch.signals.Signal.disconnect()`` is
699 removed.
700
701 * ``django.db.backends.base.BaseDatabaseOperations.check_aggregate_support()``
702 is removed.
703
704 * The ``django.forms.extras`` package is removed.
705
706 * The ``assignment_tag`` helper is removed.
707
708 * The ``host`` argument to ``SimpleTestCase.assertsRedirects()`` is removed.
709 The compatibility layer which allows absolute URLs to be considered equal to
710 relative ones when the path is identical is also removed.
711
712 * ``Field.rel`` and ``Field.remote_field.to`` are removed.
713
714 * The ``on_delete`` argument for ``ForeignKey`` and ``OneToOneField`` is now
715 required in models and migrations. Consider squashing migrations so that you
716 have fewer of them to update.
717
718 * ``django.db.models.fields.add_lazy_relation()`` is removed.
719
720 * When time zone support is enabled, database backends that don't support time
721 zones no longer convert aware datetimes to naive values in UTC anymore when
722 such values are passed as parameters to SQL queries executed outside of the
723 ORM, e.g. with ``cursor.execute()``.
724
725 * ``django.contrib.auth.tests.utils.skipIfCustomUser()`` is removed.
726
727 * The ``GeoManager`` and ``GeoQuerySet`` classes are removed.
728
729 * The ``django.contrib.gis.geoip`` module is removed.
730
731 * The ``supports_recursion`` check for template loaders is removed from:
732
733 * ``django.template.engine.Engine.find_template()``
734 * ``django.template.loader_tags.ExtendsNode.find_template()``
735 * ``django.template.loaders.base.Loader.supports_recursion()``
736 * ``django.template.loaders.cached.Loader.supports_recursion()``
737
738 * The ``load_template`` and ``load_template_sources`` template loader methods
739 are removed.
740
741 * The ``template_dirs`` argument for template loaders is removed:
742
743 * ``django.template.loaders.base.Loader.get_template()``
744 * ``django.template.loaders.cached.Loader.cache_key()``
745 * ``django.template.loaders.cached.Loader.get_template()``
746 * ``django.template.loaders.cached.Loader.get_template_sources()``
747 * ``django.template.loaders.filesystem.Loader.get_template_sources()``
748
749 * ``django.template.loaders.base.Loader.__call__()`` is removed.
750
751 * Support for custom error views that don't accept an ``exception`` parameter
752 is removed.
753
754 * The ``mime_type`` attribute of ``django.utils.feedgenerator.Atom1Feed`` and
755 ``django.utils.feedgenerator.RssFeed`` is removed.
756
757 * The ``app_name`` argument to ``include()`` is removed.
758
759 * Support for passing a 3-tuple (including ``admin.site.urls``) as the first
760 argument to ``include()`` is removed.
761
762 * Support for setting a URL instance namespace without an application namespace
763 is removed.
764
765 * ``Field._get_val_from_obj()`` is removed.
766
767 * ``django.template.loaders.eggs.Loader`` is removed.
768
769 * The ``current_app`` parameter to the ``contrib.auth`` function-based views is
770 removed.
771
772 * The ``callable_obj`` keyword argument to
773 ``SimpleTestCase.assertRaisesMessage()`` is removed.
774
775 * Support for the ``allow_tags`` attribute on ``ModelAdmin`` methods is
776 removed.
777
778 * The ``enclosure`` keyword argument to ``SyndicationFeed.add_item()`` is
779 removed.
780
781 * The ``django.template.loader.LoaderOrigin`` and
782 ``django.template.base.StringOrigin`` aliases for
783 ``django.template.base.Origin`` are removed.
784
785 See :ref:`deprecated-features-1.10` for details on these changes.
786
787 * The ``makemigrations --exit`` option is removed.
788
789 * Support for direct assignment to a reverse foreign key or many-to-many
790 relation is removed.
791
792 * The ``get_srid()`` and ``set_srid()`` methods of
793 ``django.contrib.gis.geos.GEOSGeometry`` are removed.
794
795 * The ``get_x()``, ``set_x()``, ``get_y()``, ``set_y()``, ``get_z()``, and
796 ``set_z()`` methods of ``django.contrib.gis.geos.Point`` are removed.
797
798 * The ``get_coords()`` and ``set_coords()`` methods of
799 ``django.contrib.gis.geos.Point`` are removed.
800
801 * The ``cascaded_union`` property of ``django.contrib.gis.geos.MultiPolygon``
802 is removed.
803
804 * ``django.utils.functional.allow_lazy()`` is removed.
805
806 * The ``shell --plain`` option is removed.
807
808 * The ``django.core.urlresolvers`` module is removed in favor of its new
809 location, ``django.urls``.
810
811 * ``CommaSeparatedIntegerField`` is removed, except for support in historical
812 migrations.
813
814 * The template ``Context.has_key()`` method is removed.
815
816 * Support for the ``django.core.files.storage.Storage.accessed_time()``,
817 ``created_time()``, and ``modified_time()`` methods is removed.
818
819 * Support for query lookups using the model name when
820 ``Meta.default_related_name`` is set is removed.
821
822 * The MySQL ``__search`` lookup is removed.
823
824 * The shim for supporting custom related manager classes without a
825 ``_apply_rel_filters()`` method is removed.
826
827 * Using ``User.is_authenticated()`` and ``User.is_anonymous()`` as methods
828 rather than properties is no longer supported.
829
830 * The ``Model._meta.virtual_fields`` attribute is removed.
831
832 * The keyword arguments ``virtual_only`` in ``Field.contribute_to_class()`` and
833 ``virtual`` in ``Model._meta.add_field()`` are removed.
834
835 * The ``javascript_catalog()`` and ``json_catalog()`` views are removed.
836
837 * ``django.contrib.gis.utils.precision_wkt()`` is removed.
838
839 * In multi-table inheritance, implicit promotion of a ``OneToOneField`` to a
840 ``parent_link`` is removed.
841
842 * Support for ``Widget._format_value()`` is removed.
843
844 * ``FileField`` methods ``get_directory_name()`` and ``get_filename()`` are
845 removed.
846
847 * The ``mark_for_escaping()`` function and the classes it uses: ``EscapeData``,
848 ``EscapeBytes``, ``EscapeText``, ``EscapeString``, and ``EscapeUnicode`` are
849 removed.
850
851 * The ``escape`` filter now uses ``django.utils.html.conditional_escape()``.
852
853 * ``Manager.use_for_related_fields`` is removed.
854
855 * Model ``Manager`` inheritance follows MRO inheritance rules. The requirement
856 to use ``Meta.manager_inheritance_from_future`` to opt-in to the behavior is
857 removed.
858
859 * Support for old-style middleware using ``settings.MIDDLEWARE_CLASSES`` is
860 removed.