Django 1.9 リリースノート¶
December 1, 2015
Django 1.9 へようこそ!
このリリースノートでは、 バージョン 1.9 の新機能 と、Django 1.8 以前からアップグレードする際に注意が必要な 後方互換性が失われた変更点 について説明します。私たちは、非推奨の期間が終了した いくつかの機能の廃止 を行い、さらに いくつかの機能に対する新しい非推奨期間 を開始しました。
既存のプロジェクトをアップデートするときは、 Django の新しいバージョンへの更新 ガイドに従ってください。
Python バージョン間の互換性¶
Django 1.9 の動作には Python 2.7, 3.4, 3.5 のいずれかが必要です。各バージョン系列の最終リリースの Python を使用することを 強く推奨 し、公式には最終リリースしかサポートしません。
Django 1.8 シリーズが Python 3.2 および 3.3 をサポートする最後のバージョンになります。
Django 1.9 で新しくなったこと¶
トランザクションのコミット後にアクションを実行する機能¶
新しく追加された on_commit()
フックを使えば、データベースのトランザクションが成功した時点で好きなアクションが実行できます。この機能は、メール通知を送信したり、新しいタスクキューを作成したり、キャッシュを無効化するのに便利です。
This functionality from the django-transaction-hooks package has been integrated into Django.
パスワードの妥当性検証¶
Django は新しくパスワード検証機能を提供します。これによりユーザーが弱いパスワードを使用するのを防けるようになります。検証機能は同梱のパスワードの変更・リセットフォームに統合されているので、他のコードと組み合わせるのも簡単です。検証は1つ以上の検証器 (validator) で実行され、新しい AUTH_PASSWORD_VALIDATORS
設定でカスタマイズすることができます。
Django には4つの検証器が組み込まれています。それぞれ、パスワードの最小長の強制、名前などのユーザーの属性とパスワードとの比較、数字のみのパスワードでないかの確認、よく使われるパスワードのリストに含まれていないかのチェックを実行します。複数の検証器を組み合わせることが可能で、設定オプションをカスタマイズできる検証器もあります。たとえば、よくあるパスワードのリストとして自前のリストを渡すことができます。各検証器は、ユーザーに対して必要な条件を説明するヘルプテキストを返します。
デフォルトでは、検証は実行されずにすべてのパスワードが許可されます。そのため、 AUTH_PASSWORD_VALIDATORS
を設定しなければ、何も変更する必要はありません。デフォルトの startproject
テンプレートを使用して新しいプロジェクトを作成すると、基本的な検証機が有効になります。既存のプロジェクトの認証フォームで基本的な検証を有効にするには、たとえば次のように設定します。
AUTH_PASSWORD_VALIDATORS = [
{
"NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator",
},
{
"NAME": "django.contrib.auth.password_validation.MinimumLengthValidator",
},
{
"NAME": "django.contrib.auth.password_validation.CommonPasswordValidator",
},
{
"NAME": "django.contrib.auth.password_validation.NumericPasswordValidator",
},
]
詳しくは パスワードの妥当性検証 を読んでください。
クラスベースのビューに対するミックスインの許可¶
Django は新しく次のミックスインを同梱するようになりました。 AccessMixin
, LoginRequiredMixin
, PermissionRequiredMixin
, そして UserPassesTestMixin
です。これらを使えば、クラスベースのビューに対して、 django.contrib.auth.decorators
の機能を使用できるようになります。これらのミックスインは django-braces プロジェクトにインスパイアされて実装されました。
ただし、Django と django-braces
の実装には次のような相違点があります。
raise_exception
属性はTrue
またはFalse
のいずれかのみであり、カスタムの例外や callable はサポートしない。handle_no_permission()
メソッドはrequest
引数を取らない。現在の request はself.request
でアクセス可能である。UserPassesTestMixin
のカスタムのtest_func()
はuser
引数を取らない。現在のユーザーはself.request.user
でアクセス可能である。permission_required
属性は文字列 (1つのパーミッションを定義する) または文字列のリストかタプル (複数のパーミッションを定義する) をサポートする。この属性はアクセス権限を得るために必要である。- 新しい
permission_denied_message
属性を使えば、PermissionDenied
例外にメッセージを送ることができる。
contrib.admin
への新しいスタイルの導入¶
admin は新たにモダンなフラットデザインをまといました。これには HiDPI スクリーンでも美しく表示できる SVG アイコンも含まれます。YUI's A-grade ブラウザの完全な機能体験を提供します。古いブラウザによっては、一部の機能体験のレベルが下がることがあります。
テストの並列実行¶
test
コマンドは新たに、プロジェクトのテストをマルチプロセスで実行する --parallel
オプションをサポートします。
各プロセスごとに個別のデータベースを持つため、異なるテストケースが同じリソースにアクセスしないように注意が必要です。たとえば、複数のテストケースがファイルシステムにアクセスするような場合には、各テストケースごとに個別に一時ディレクトリを作成するようにしてください。
このオプションは、Django 自身のテストスイートでは、以下の条件下で有効になります。
- Windows を除く全ての OS
- Oracle 以外のすべてのデータベースバックエンド
マイナーな機能¶
django.contrib.admin
¶
- admin ビューは新たに
model_admin
またはadmin_site
属性を持ちます。 - admin change ビューの URL が変更されました (デフォルトで
/admin/<app>/<model>/<pk>/
にありましたが、新しく/admin/<app>/<model>/<pk>/change/
に変わりました)。admin の URL をハードコードしていない限り、既存のアプリケーションで問題は起こらないはずです。ハードコードしてしまっていた場合、リンクの代わりに admin URL の逆リンク を使用してください。後方互換性を確保するために、古い URL は新しい URL にリダイレクトされていますが、将来のバージョンではリダイレクトは削除される予定なので気をつけてください。 ModelAdmin.get_list_select_related()
が追加され、 admin changelist クエリで使われていたselect_related()
の値をリクエストに基づいて変更できるようになりました。- 現在のユーザーが使用可能なアプリケーションのリストを値として持つ
available_apps
コンテキスト変数が、新たにAdminSite.each_context()
メソッドに追加されました。 AdminSite.empty_value_display
およびModelAdmin.empty_value_display
が追加され、admin change list の中の空の値の表示を上書きすることができるようになりました。また、各フィールドの値をカスタマイズすることもできます。- change form ページに inline form の追加または削除時 に発生する jQuery イベントが追加されました。
- The time picker widget includes a '6 p.m' option for consistency of having predefined options every 6 hours.
- JavaScript slug 生成機能が、新しくルーマニア語の文字をサポートするようになりました。
django.contrib.admindocs
¶
- The model section of the
admindocs
now also describes methods that take arguments, rather than ignoring them.
django.contrib.auth
¶
- The default iteration count for the PBKDF2 password hasher has been increased
by 20%. This backwards compatible change will not affect users who have
subclassed
django.contrib.auth.hashers.PBKDF2PasswordHasher
to change the default value. - The
BCryptSHA256PasswordHasher
will now update passwords if itsrounds
attribute is changed. AbstractBaseUser
andBaseUserManager
were moved to a newdjango.contrib.auth.base_user
module so that they can be imported without includingdjango.contrib.auth
inINSTALLED_APPS
(doing so raised a deprecation warning in older versions and is no longer supported in Django 1.9).- The permission argument of
permission_required()
accepts all kinds of iterables, not only list and tuples. - The new
PersistentRemoteUserMiddleware
makes it possible to useREMOTE_USER
for setups where the header is only populated on login pages instead of every request in the session. - The
django.contrib.auth.views.password_reset()
view accepts anextra_email_context
parameter.
django.contrib.contenttypes
¶
order_with_respect_to
がGenericForeignKey
とともに使用できるようになりました。
django.contrib.gis
¶
- すべての
GeoQuerySet
メソッドが廃止され、 等価なデータベース関数 で置き換えられました。コードで使用している古いメソッドを置き換えるとともに、GIS が有効なクラスから特別なGeoManager
を削除しなければなりません。 - GDAL インターフェイスが、raw データからファイルベースでインメモリの GDALRaster オブジェクト のインスタンス化をサポートしました。projection や pixel の値などのラスター属性の setter が追加されました。
- PostGIS のユーザは、
RasterField
により GDALRaster オブジェクトの保存 ができるようになりました。このクラスはモデル保存時の自動的な spatial index の作成や reprojection をサポートします。spatial querying はまだサポートしていません。 - The new
GDALRaster.warp()
method allows warping a raster by specifying target raster properties such as origin, width, height, or pixel size (among others). - The new
GDALRaster.transform()
method allows transforming a raster into a different spatial reference system by specifying a targetsrid
. - 新しい
GeoIP2
クラスが、IPv6 アドレスをサポートする MaxMind の GeoLite2 データベースを扱えるようになりました。 - ウィジェットに含まれるデフォルトの OpenLayers ライブラリのバージョンが 2.13 から 2.13.1 にアップデートされました。
django.contrib.postgres
¶
- range フィールドに対応するいくつかのビルトインのフィールドに対する
rangefield.contained_by
lookup のサポートが追加されました。 - Added
django.contrib.postgres.fields.JSONField
. - PostgreSQL 固有の集計関数 が追加されました。
TransactionNow
データベース関数が追加されました。
django.contrib.sessions
¶
db
とcached_db
バックエンドの session モデルとSessionStore
クラスをリファクタリングし、カスタムのデータベース session バックエンドをその上に構築することができるようになりました。詳しくは データベースを使ったセッションを拡張する を読んでください。
django.contrib.sites
¶
get_current_site()
が新たにrequest.get_host()
がdomain:port
という形式 (例:example.com:80
) の値を返す場合でもハンドリングできるようになりました。host がデータベースレコードとマッチせず、host が port を持っているせいで lookup が失敗する場合、ドメイン部分だけを使用して lookup を再試行します。
django.contrib.syndication
¶
- 各フィードアイテムごとの複数の enclosure のサポートが追加されました。Atom フィードとは違い、RSS はフィードアイテムごとの複数の enclosure をサポートしないため、RSS フィードで使用すると例外が発生します。
キャッシュ¶
- 新しく
django.core.cache.backends.base.BaseCache
がget_or_set()
メソッドを持つようになりました。 - キャッシュされることををより確実に防ぐため、
django.views.decorators.cache.never_cache()
がより積極的にヘッダを追加するようになりました (no-cache, no-store, must-revalidate
がCache-Control
に追加されます)。この関数は Django 1.8.8 で追加されました。
CSRF¶
- CSRF 認証に使われる request ヘッダの名前が
CSRF_HEADER_NAME
で設定できるようになりました。 CSRF_COOKIE_DOMAIN
設定が設定されているかどうかにかかわらず、CSRF referer ヘッダが検証されるようになりました。詳しくは しくみ を見てください。CSRF_TRUSTED_ORIGINS
設定を使うことで、HTTPS 経由の cross-origin unsafe requests (例:POST
) を行えるようになりました。
データベースバックエンド¶
- PostgreSQL バックエンド (
django.db.backends.postgresql_psycopg2
) がdjango.db.backends.postgresql
から使用できるようになりました。後方互換性を確保するため、古い名前もそのまま使用できます。
ファイルストレージ¶
upload_to
が callable の場合にStorage.get_valid_name()
が呼ばれるようになりました。- Python 3 を使用している場合に
File
がseekable()
メソッドを使えるようになりました。
フォーム¶
ModelForm
が新しいMeta
オプションとしてfield_classes
を使えるようになりました。これにより、フィールドの種類をカスタマイズできるようになります。詳しくは デフォルトのフィールドをオーバライドする を読んでください。field_order
属性、field_order
コンストラクタの引数、order_fields()
メソッドのいずれかを使用して、form のフィールドをレンダリングする順番を指定できるようになりました。- form prefix が、form のインスタンス化の時だけでなく form クラスの内部でも指定できるようになりました。詳しくは フォームのプレフィックス を読んでください。
- formset 内の form のコンストラクタに渡したい キーワード引数を指定する ことができるようになりました。
SlugField
でallow_unicode
引数を使うことで、Unicode 文字を slug 内で使用できるようになりました。CharField
がstrip
引数を取れるようになり、前後のホワイトスペースを取り除けるようになりました。この値はデフォルトでTrue
なので、過去のリリースと異なる動作をすることになります。- Form フィールドが
disabled
引数をサポートするようになり、ブラウザで disabled の状態でウィジェットを表示できるようになりました。 - フィールドの
get_bound_field()
メソッドをオーバーライドすることで、フィールドの境界線をカスタマイズすることができるようになりました。
ジェネリックビュー (汎用ビュー)¶
as_view()
メソッドで生成されたクラスベースのビューにview_class
とview_initkwargs
属性が追加されました。method_decorator()
がデコレータのタプルまたはリストで呼び出せるようになりました。 メソッドの代わりにデコレートしたクラス に使用することもできます。
国際化 (internationalization)¶
- 利用可能な場合、
django.views.i18n.set_language()
ビューが、適切な 翻訳 URL にリダイレクトされるようになりました。 - The
django.views.i18n.javascript_catalog()
view now works correctly if used multiple times with different configurations on the same page. django.utils.timezone.make_aware()
関数がis_dst
引数を取って、DST 中の曖昧な時間を適切に処理できるようになりました。- gettext でサポートされるロケールの異なる文字が使えるようになりました。この機能は、たとえばラテン文字とキリル文字 (例:
be@latin
) のような異なる字体で書かれた言語でよく使われます。 - Added the
django.views.i18n.json_catalog()
view to help build a custom client-side i18n library upon Django translations. It returns a JSON object containing a translations catalog, formatting settings, and a plural rule. get_language_info
テンプレートタグが返すオブジェクトにname_translated
属性が追加されました。また、対応するテンプレートフィルタlanguage_name_translated
も追加します。- プロジェクトのルートディレクトリから
compilemessages
を実行し、makemessages
で作成したアプリのメッセージのすべてを検索できます。 makemessages
now callsxgettext
once per locale directory rather than once per translatable file. This speeds up localization builds.blocktrans
が出力の値をasvar
を使って変数に代入できるようになりました。- コロンビアスペイン語とスコットランド・ゲール語の2つの言語が使用できるようになりました。
管理コマンド¶
- 新しい
sendtestemail
コマンドが追加され、テストメールを送信して、Django 経由のメール送信が正常に動作しているかを簡単にチェックできるようになりました。 sqlmigrate
が生成する SQL コードのリーダビリティを向上するため、マイグレーション操作ごとに生成される SQL コードの前に、マイグレーション操作の説明を記述するようになりました。dumpdata
コマンドの出力の順番が毎回同じ順番で表示されるようになりました。さらに、--output
オプションを指定すると、端末にプログレスバーも表示されるようになりました。createcachetable
コマンドが--dry-run
フラグを取れるようになり、SQL を実行せずに表示だけできるようになりました。- The
startapp
command creates anapps.py
file. Since it doesn't usedefault_app_config
(a discouraged API), you must specify the app config's path, e.g.'polls.apps.PollsConfig'
, inINSTALLED_APPS
for it to be used (instead of just'polls'
). - When using the PostgreSQL backend, the
dbshell
command can connect to the database using the password from your settings file (instead of requiring it to be manually entered). - The
django
package may be run as a script, i.e.python -m django
, which will behave the same asdjango-admin
. - Management commands that have the
--noinput
option now also take--no-input
as an alias for that option.
マイグレーション¶
Initial migrations are now marked with an
initial = True
class attribute which allowsmigrate --fake-initial
to more easily detect initial migrations.Added support for serialization of
functools.partial
andLazyObject
instances.When supplying
None
as a value inMIGRATION_MODULES
, Django will consider the app an app without migrations.When applying migrations, the "Rendering model states" step that's displayed when running migrate with verbosity 2 or higher now computes only the states for the migrations that have already been applied. The model states for migrations being applied are generated on demand, drastically reducing the amount of required memory.
However, this improvement is not available when unapplying migrations and therefore still requires the precomputation and storage of the intermediate migration states.
This improvement also requires that Django no longer supports mixed migration plans. Mixed plans consist of a list of migrations where some are being applied and others are being unapplied. This was never officially supported and never had a public API that supports this behavior.
The
squashmigrations
command now supports specifying the starting migration from which migrations will be squashed.
モデル¶
QuerySet.bulk_create()
now works on proxy models.- Database configuration gained a
TIME_ZONE
option for interacting with databases that store datetimes in local time and don't support time zones whenUSE_TZ
isTrue
. - Added the
RelatedManager.set()
method to the related managers created byForeignKey
,GenericForeignKey
, andManyToManyField
. - The
add()
method on a reverse foreign key now has abulk
parameter to allow executing one query regardless of the number of objects being added rather than one query per object. - Added the
keep_parents
parameter toModel.delete()
to allow deleting only a child's data in a model that uses multi-table inheritance. Model.delete()
andQuerySet.delete()
return the number of objects deleted.- Added a system check to prevent defining both
Meta.ordering
andorder_with_respect_to
on the same model. Date and time
lookups can be chained with other lookups (such asexact
,gt
,lt
, etc.). For example:Entry.objects.filter(pub_date__month__gt=6)
.- Time lookups (hour, minute, second) are now supported by
TimeField
for all database backends. Support for backends other than SQLite was added but undocumented in Django 1.7. - You can specify the
output_field
parameter of theAvg
aggregate in order to aggregate over non-numeric columns, such asDurationField
. - Added the
date
lookup toDateTimeField
to allow querying the field by only the date portion. - Added the
Greatest
andLeast
database functions. - Added the
Now
database function, which returns the current date and time. Transform
is now a subclass of Func() which allowsTransform
s to be used on the right hand side of an expression, just like regularFunc
s. This allows registering some database functions likeLength
,Lower
, andUpper
as transforms.SlugField
now accepts anallow_unicode
argument to allow Unicode characters in slugs.- Added support for referencing annotations in
QuerySet.distinct()
. connection.queries
shows queries with substituted parameters on SQLite.- Query expressions can now be used when
creating new model instances using
save()
,create()
, andbulk_create()
.
Request と Response¶
- Unless
HttpResponse.reason_phrase
is explicitly set, it now is determined by the current value ofHttpResponse.status_code
. Modifying the value ofstatus_code
outside of the constructor will also modify the value ofreason_phrase
. - The debug view now shows details of chained exceptions on Python 3.
- The default 40x error views now accept a second positional parameter, the exception that triggered the view.
- View error handlers now support
TemplateResponse
, commonly used with class-based views. - Exceptions raised by the
render()
method are now passed to theprocess_exception()
method of each middleware. - Request middleware can now set
HttpRequest.urlconf
toNone
to revert any changes made by previous middleware and return to using theROOT_URLCONF
. - The
DISALLOWED_USER_AGENTS
check inCommonMiddleware
now raises aPermissionDenied
exception as opposed to returning anHttpResponseForbidden
so thathandler403
is invoked. - Added
HttpRequest.get_port()
to fetch the originating port of the request. - Added the
json_dumps_params
parameter toJsonResponse
to allow passing keyword arguments to thejson.dumps()
call used to generate the response. - The
BrokenLinkEmailsMiddleware
now ignores 404s when the referer is equal to the requested URL. To circumvent the empty referer check already implemented, some web bots set the referer to the requested URL.
テンプレート¶
- Template tags created with the
simple_tag()
helper can now store results in a template variable by using theas
argument. - Added a
Context.setdefault()
method. - The django.template logger was added and
includes the following messages:
- A
DEBUG
level message for missing context variables. - A
WARNING
level message for uncaught exceptions raised during the rendering of an{% include %}
when debug mode is off (helpful since{% include %}
silences the exception and returns an empty string).
- A
- The
firstof
template tag supports storing the output in a variable using 'as'. Context.update()
can now be used as a context manager.- Django template loaders can now extend templates recursively.
- The debug page template postmortem now include output from each engine that is installed.
- Debug page integration for custom template engines was added.
- The
DjangoTemplates
backend gained the ability to register libraries and builtins explicitly through the templateOPTIONS
. - The
timesince
andtimeuntil
filters were improved to deal with leap years when given large time spans. - The
include
tag now caches parsed templates objects during template rendering, speeding up reuse in places such as for loops.
テスト¶
- Added the
json()
method to test client responses to give access to the response body as JSON. - Added the
force_login()
method to the test client. Use this method to simulate the effect of a user logging into the site while skipping the authentication and verification steps oflogin()
.
URL¶
- Regular expression lookaround assertions are now allowed in URL patterns.
- The application namespace can now be set using an
app_name
attribute on the included module or object. It can also be set by passing a 2-tuple of (<list of patterns>, <application namespace>) as the first argument toinclude()
. - System checks have been added for common URL pattern mistakes.
バリデータ¶
- Added
django.core.validators.int_list_validator()
to generate validators of strings containing integers separated with a custom character. EmailValidator
now limits the length of domain name labels to 63 characters per RFC 1034.- Added
validate_unicode_slug()
to validate slugs that may contain Unicode characters.
Backwards incompatible changes in 1.9¶
警告
In addition to the changes outlined in this section, be sure to review the 1.9 で削除された機能 for the features that have reached the end of their deprecation cycle and therefore been removed. If you haven't updated your code within the deprecation timeline for a given feature, its removal may appear as a backwards incompatible change.
データベースバックエンド API¶
A couple of new tests rely on the ability of the backend to introspect column defaults (returning the result as
Field.default
). You can set thecan_introspect_default
database feature toFalse
if your backend doesn't implement this. You may want to review the implementation on the backends that Django includes for reference (#24245).Registering a global adapter or converter at the level of the DB-API module to handle time zone information of
datetime
values passed as query parameters or returned as query results on databases that don't support time zones is discouraged. It can conflict with other libraries.The recommended way to add a time zone to
datetime
values fetched from the database is to register a converter forDateTimeField
inDatabaseOperations.get_db_converters()
.The
needs_datetime_string_cast
database feature was removed. Database backends that set it must register a converter instead, as explained above.The
DatabaseOperations.value_to_db_<type>()
methods were renamed toadapt_<type>field_value()
to mirror theconvert_<type>field_value()
methods.To use the new
date
lookup, third-party database backends may need to implement theDatabaseOperations.datetime_cast_date_sql()
method.The
DatabaseOperations.time_extract_sql()
method was added. It calls the existingdate_extract_sql()
method. This method is overridden by the SQLite backend to add time lookups (hour, minute, second) toTimeField
, and may be needed by third-party database backends.The
DatabaseOperations.datetime_cast_sql()
method (not to be confused withDatabaseOperations.datetime_cast_date_sql()
mentioned above) has been removed. This method served to format dates on Oracle long before 1.0, but hasn't been overridden by any core backend in years and hasn't been called anywhere in Django's code or tests.In order to support test parallelization, you must implement the
DatabaseCreation._clone_test_db()
method and setDatabaseFeatures.can_clone_databases = True
. You may have to adjustDatabaseCreation.get_test_db_clone_settings()
.
Default settings that were tuples are now lists¶
The default settings in django.conf.global_settings
were a combination of
lists and tuples. All settings that were formerly tuples are now lists.
is_usable
attribute on template loaders is removed¶
以前、Djangoのテンプレートローダーでは is_usable
属性を定義する必要がありました。テンプレート設定でローダーが設定され、この属性が False
であった場合、ローダーは静かに無視されました。実際には、これは setuptools
がインストールされているかを検出するために、egg ローダーによってのみ使用されていました。is_usable
属性は現在削除され、その代わりに、setuptools
がインストールされていない場合、egg ローダーは実行時に失敗します。
Filesystem-based template loaders catch more specific exceptions¶
When using the filesystem.Loader
or app_directories.Loader
template loaders, earlier versions of Django raised a
TemplateDoesNotExist
error if a template source existed
but was unreadable. This could happen under many circumstances, such as if
Django didn't have permissions to open the file, or if the template source was
a directory. Now, Django only silences the exception if the template source
does not exist. All other situations result in the original IOError
being
raised.
HTTP redirects no longer forced to absolute URIs¶
Relative redirects are no longer converted to absolute URIs. RFC 2616
required the Location
header in redirect responses to be an absolute URI,
but it has been superseded by RFC 7231 which allows relative URIs in
Location
, recognizing the actual practice of user agents, almost all of
which support them.
Consequently, the expected URLs passed to assertRedirects
should generally
no longer include the scheme and domain part of the URLs. For example,
self.assertRedirects(response, 'http://testserver/some-url/')
should be
replaced by self.assertRedirects(response, '/some-url/')
(unless the
redirection specifically contained an absolute URL).
In the rare case that you need the old behavior (discovered with an ancient
version of Apache with mod_scgi
that interprets a relative redirect as an
"internal redirect"), you can restore it by writing a custom middleware:
class LocationHeaderFix(object):
def process_response(self, request, response):
if "Location" in response:
response["Location"] = request.build_absolute_uri(response["Location"])
return response
Dropped support for PostgreSQL 9.0¶
Upstream support for PostgreSQL 9.0 ended in September 2015. As a consequence, Django 1.9 sets 9.1 as the minimum PostgreSQL version it officially supports.
Dropped support for Oracle 11.1¶
Upstream support for Oracle 11.1 ended in August 2015. As a consequence, Django 1.9 sets 11.2 as the minimum Oracle version it officially supports.
Template LoaderOrigin
and StringOrigin
are removed¶
In previous versions of Django, when a template engine was initialized with
debug as True
, an instance of django.template.loader.LoaderOrigin
or
django.template.base.StringOrigin
was set as the origin attribute on the
template object. These classes have been combined into
Origin
and is now always set regardless of the
engine debug setting. For a minimal level of backwards compatibility, the old
class names will be kept as aliases to the new Origin
class until
Django 2.0.
Changes to the default logging configuration¶
To make it easier to write custom logging configurations, Django's default
logging configuration no longer defines django.request
and
django.security
loggers. Instead, it defines a single django
logger,
filtered at the INFO
level, with two handlers:
console
: filtered at theINFO
level and only active ifDEBUG=True
.mail_admins
: filtered at theERROR
level and only active ifDEBUG=False
.
If you aren't overriding Django's default logging, you should see minimal
changes in behavior, but you might see some new logging to the runserver
console, for example.
If you are overriding Django's default logging, you should check to see how your configuration merges with the new defaults.
HttpRequest
details in error reporting¶
It was redundant to display the full details of the
HttpRequest
each time it appeared as a stack frame
variable in the HTML version of the debug page and error email. Thus, the HTTP
request will now display the same standard representation as other variables
(repr(request)
). As a result, the
ExceptionReporterFilter.get_request_repr()
method and the undocumented
django.http.build_request_repr()
function were removed.
The contents of the text version of the email were modified to provide a
traceback of the same structure as in the case of AJAX requests. The traceback
details are rendered by the ExceptionReporter.get_traceback_text()
method.
Removal of time zone aware global adapters and converters for datetimes¶
Django no longer registers global adapters and converters for managing time
zone information on datetime
values sent to the database as
query parameters or read from the database in query results. This change
affects projects that meet all the following conditions:
- The
USE_TZ
setting isTrue
. - The database is SQLite, MySQL, Oracle, or a third-party database that
doesn't support time zones. In doubt, you can check the value of
connection.features.supports_timezones
. - The code queries the database outside of the ORM, typically with
cursor.execute(sql, params)
.
If you're passing aware datetime
parameters to such
queries, you should turn them into naive datetimes in UTC:
from django.utils import timezone
param = timezone.make_naive(param, timezone.utc)
If you fail to do so, the conversion will be performed as in earlier versions (with a deprecation warning) up until Django 1.11. Django 2.0 won't perform any conversion, which may result in data corruption.
If you're reading datetime
values from the results, they
will be naive instead of aware. You can compensate as follows:
from django.utils import timezone
value = timezone.make_aware(value, timezone.utc)
You don't need any of this if you're querying the database through the ORM,
even if you're using raw()
queries. The ORM takes care of managing time zone information.
Template tag modules are imported when templates are configured¶
The DjangoTemplates
backend now
performs discovery on installed template tag modules when instantiated. This
update enables libraries to be provided explicitly via the 'libraries'
key of OPTIONS
when defining a
DjangoTemplates
backend. Import
or syntax errors in template tag modules now fail early at instantiation time
rather than when a template with a {% load %}
tag is first
compiled.
django.template.base.add_to_builtins()
is removed¶
Although it was a private API, projects commonly used add_to_builtins()
to
make template tags and filters available without using the
{% load %}
tag. This API has been formalized. Projects should now
define built-in libraries via the 'builtins'
key of OPTIONS
when defining a
DjangoTemplates
backend.
simple_tag
now wraps tag output in conditional_escape
¶
In general, template tags do not autoescape their contents, and this behavior is
documented. For tags like
inclusion_tag
, this is not a problem because
the included template will perform autoescaping. For assignment_tag()
,
the output will be escaped when it is used as a variable in the template.
For the intended use cases of simple_tag
,
however, it is very easy to end up with incorrect HTML and possibly an XSS
exploit. For example:
@register.simple_tag(takes_context=True)
def greeting(context):
return "Hello {0}!".format(context["request"].user.first_name)
In older versions of Django, this will be an XSS issue because
user.first_name
is not escaped.
In Django 1.9, this is fixed: if the template context has autoescape=True
set (the default), then simple_tag
will wrap the output of the tag function
with conditional_escape()
.
To fix your simple_tag
s, it is best to apply the following practices:
- Any code that generates HTML should use either the template system or
format_html()
. - If the output of a
simple_tag
needs escaping, useescape()
orconditional_escape()
. - If you are absolutely certain that you are outputting HTML from a trusted
source (e.g. a CMS field that stores HTML entered by admins), you can mark it
as such using
mark_safe()
.
Tags that follow these rules will be correct and safe whether they are run on Django 1.9+ or earlier.
Paginator.page_range
¶
Paginator.page_range
is
now an iterator instead of a list.
In versions of Django previous to 1.8, Paginator.page_range
returned a
list
in Python 2 and a range
in Python 3. Django 1.8 consistently
returned a list, but an iterator is more efficient.
Existing code that depends on list
specific features, such as indexing,
can be ported by converting the iterator into a list
using list()
.
Implicit QuerySet
__in
lookup removed¶
In earlier versions, queries such as:
Model.objects.filter(related_id=RelatedModel.objects.all())
would implicitly convert to:
Model.objects.filter(related_id__in=RelatedModel.objects.all())
resulting in SQL like "related_id IN (SELECT id FROM ...)"
.
This implicit __in
no longer happens so the "IN" SQL is now "=", and if the
subquery returns multiple results, at least some databases will throw an error.
contrib.admin
browser support¶
The admin no longer supports Internet Explorer 8 and below, as these browsers have reached end-of-life.
CSS and images to support Internet Explorer 6 and 7 have been removed. PNG and GIF icons have been replaced with SVG icons, which are not supported by Internet Explorer 8 and earlier.
The jQuery library embedded in the admin has been upgraded from version 1.11.2 to 2.1.4. jQuery 2.x has the same API as jQuery 1.x, but does not support Internet Explorer 6, 7, or 8, allowing for better performance and a smaller file size. If you need to support IE8 and must also use the latest version of Django, you can override the admin's copy of jQuery with your own by creating a Django application with this structure:
app/static/admin/js/vendor/
jquery.js
jquery.min.js
Django setuptools
5.5.x をインストールするときの SyntaxError
¶
Django 1.9 や 1.9.1 を setuptools
5.5.x でインストールすると、次のように表示されます:
Compiling django/conf/app_template/apps.py ...
File "django/conf/app_template/apps.py", line 4
class {{ camel_case_app_name }}Config(AppConfig):
^
SyntaxError: invalid syntax
Compiling django/conf/app_template/models.py ...
File "django/conf/app_template/models.py", line 1
{{ unicode_literals }}from django.db import models
^
SyntaxError: invalid syntax
これらのエラーを無視しても大丈夫です(Djangoは問題なくインストールされます)が、setuptools
をより新しいバージョンにアップグレードすることでこれらを回避できます。pip を使用している場合、python -m pip install -U pip
を使って pip をアップグレードすると、 setuptools
もアップグレードされます。この問題は、Django 1.9.2 リリースノート で説明されているように、Djangoの後のバージョンで解決されています。
その他¶
- The jQuery static files in
contrib.admin
have been moved into avendor/jquery
subdirectory. - The text displayed for null columns in the admin changelist
list_display
cells has changed from(None)
(or its translated equivalent) to-
(a dash). django.http.responses.REASON_PHRASES
anddjango.core.handlers.wsgi.STATUS_CODE_TEXT
have been removed. Use Python's Standard Library instead:http.client.responses
for Python 3 and httplib.responses for Python 2.ValuesQuerySet
andValuesListQuerySet
have been removed.- The
admin/base.html
template no longer setswindow.__admin_media_prefix__
orwindow.__admin_utc_offset__
. Image references in JavaScript that used that value to construct absolute URLs have been moved to CSS for easier customization. The UTC offset is stored on a data attribute of the<body>
tag. CommaSeparatedIntegerField
validation has been refined to forbid values like','
,',1'
, and'1,,2'
.- Form initialization was moved from the
ProcessFormView.get()
method to the newFormMixin.get_context_data()
method. This may be backwards incompatible if you have overridden theget_context_data()
method without callingsuper()
. - Support for PostGIS 1.5 has been dropped.
- The
django.contrib.sites.models.Site.domain
field was changed to beunique
. - In order to enforce test isolation, database queries are not allowed
by default in
SimpleTestCase
tests anymore. You can disable this behavior by setting theallow_database_queries
class attribute toTrue
on your test class. ResolverMatch.app_name
was changed to contain the full namespace path in the case of nested namespaces. For consistency withResolverMatch.namespace
, the empty value is now an empty string instead ofNone
.- For security hardening, session keys must be at least 8 characters.
- Private function
django.utils.functional.total_ordering()
has been removed. It contained a workaround for afunctools.total_ordering()
bug in Python versions older than 2.7.3. - XML serialization (either through
dumpdata
or the syndication framework) used to output any characters it received. Now if the content to be serialized contains any control characters not allowed in the XML 1.0 standard, the serialization will fail with aValueError
. CharField
now strips input of leading and trailing whitespace by default. This can be disabled by setting the newstrip
argument toFalse
.- Template text that is translated and uses two or more consecutive percent
signs, e.g.
"%%"
, may have a newmsgid
aftermakemessages
is run (most likely the translation will be marked fuzzy). The newmsgid
will be marked"#, python-format"
. - If neither
request.current_app
norContext.current_app
are set, theurl
template tag will now use the namespace of the current request. Setrequest.current_app
toNone
if you don't want to use a namespace hint. - The
SILENCED_SYSTEM_CHECKS
setting now silences messages of all levels. Previously, messages ofERROR
level or higher were printed to the console. - The
FlatPage.enable_comments
field is removed from theFlatPageAdmin
as it's unused by the application. If your project or a third-party app makes use of it, create a custom ModelAdmin to add it back. - The return value of
setup_databases()
and the first argument ofteardown_databases()
changed. They used to be(old_names, mirrors)
tuples. Now they're just the first item,old_names
. - By default
LiveServerTestCase
attempts to find an available port in the 8081-8179 range instead of just trying port 8081. - The system checks for
ModelAdmin
now check instances rather than classes. - The private API to apply mixed migration plans has been dropped for performance reasons. Mixed plans consist of a list of migrations where some are being applied and others are being unapplied.
- The related model object descriptor classes in
django.db.models.fields.related
(private API) are moved from therelated
module torelated_descriptors
and renamed as follows:ReverseSingleRelatedObjectDescriptor
isForwardManyToOneDescriptor
SingleRelatedObjectDescriptor
isReverseOneToOneDescriptor
ForeignRelatedObjectsDescriptor
isReverseManyToOneDescriptor
ManyRelatedObjectsDescriptor
isManyToManyDescriptor
- If you implement a custom
handler404
view, it must return a response with an HTTP 404 status code. UseHttpResponseNotFound
or passstatus=404
to theHttpResponse
. Otherwise,APPEND_SLASH
won't work correctly withDEBUG=False
.
Features deprecated in 1.9¶
assignment_tag()
¶
Django 1.4 added the assignment_tag
helper to ease the creation of
template tags that store results in a template variable. The
simple_tag()
helper has gained this same
ability, making the assignment_tag
obsolete. Tags that use
assignment_tag
should be updated to use simple_tag
.
{% cycle %}
syntax with comma-separated arguments¶
The cycle
tag supports an inferior old syntax from previous Django
versions:
{% cycle row1,row2,row3 %}
Its parsing caused bugs with the current syntax, so support for the old syntax will be removed in Django 1.10 following an accelerated deprecation.
ForeignKey
and OneToOneField
on_delete
argument¶
In order to increase awareness about cascading model deletion, the
on_delete
argument of ForeignKey
and OneToOneField
will be required
in Django 2.0.
Update models and existing migrations to explicitly set the argument. Since the
default is models.CASCADE
, add on_delete=models.CASCADE
to all
ForeignKey
and OneToOneField
s that don't use a different option. You
can also pass it as the second positional argument if you don't care about
compatibility with older versions of Django.
Field.rel
changes¶
Field.rel
and its methods and attributes have changed to match the related
fields API. The Field.rel
attribute is renamed to remote_field
and many
of its methods and attributes are either changed or renamed.
The aim of these changes is to provide a documented API for relation fields.
GeoManager
and GeoQuerySet
custom methods¶
All custom GeoQuerySet
methods (area()
, distance()
, gml()
, ...)
have been replaced by equivalent geographic expressions in annotations (see in
new features). Hence the need to set a custom GeoManager
to GIS-enabled
models is now obsolete. As soon as your code doesn't call any of the deprecated
methods, you can simply remove the objects = GeoManager()
lines from your
models.
Template loader APIs have changed¶
Django template loaders have been updated to allow recursive template
extending. This change necessitated a new template loader API. The old
load_template()
and load_template_sources()
methods are now deprecated.
Details about the new API can be found in the template loader
documentation.
Passing a 3-tuple or an app_name
to include()
¶
The instance namespace part of passing a tuple as an argument to include()
has been replaced by passing the namespace
argument to include()
. For
example:
polls_patterns = [
url(...),
]
urlpatterns = [
url(r"^polls/", include((polls_patterns, "polls", "author-polls"))),
]
は、以下のようになります:
polls_patterns = (
[
url(...),
],
"polls",
) # 'polls' is the app_name
urlpatterns = [
url(r"^polls/", include(polls_patterns, namespace="author-polls")),
]
The app_name
argument to include()
has been replaced by passing a
2-tuple (as above), or passing an object or module with an app_name
attribute (as below). If the app_name
is set in this new way, the
namespace
argument is no longer required. It will default to the value of
app_name
. For example, the URL patterns in the tutorial are changed from:
urlpatterns = [url(r"^polls/", include("polls.urls", namespace="polls")), ...]
to:
urlpatterns = [
url(r"^polls/", include("polls.urls")), # 'namespace="polls"' removed
...,
]
app_name = "polls" # added
urlpatterns = [...]
This change also means that the old way of including an AdminSite
instance
is deprecated. Instead, pass admin.site.urls
directly to
django.conf.urls.url()
:
from django.conf.urls import url
from django.contrib import admin
urlpatterns = [
url(r"^admin/", admin.site.urls),
]
URL application namespace required if setting an instance namespace¶
In the past, an instance namespace without an application namespace would serve the same purpose as the application namespace, but it was impossible to reverse the patterns if there was an application namespace with the same name. Includes that specify an instance namespace require that the included URLconf sets an application namespace.
current_app
parameter to contrib.auth
views¶
All views in django.contrib.auth.views
have the following structure:
def view(request, ..., current_app=None, ...):
...
if current_app is not None:
request.current_app = current_app
return TemplateResponse(request, template_name, context)
As of Django 1.8, current_app
is set on the request
object. For
consistency, these views will require the caller to set current_app
on the
request
instead of passing it in a separate argument.
django.contrib.gis.geoip
¶
The django.contrib.gis.geoip2
module supersedes
django.contrib.gis.geoip
. The new module provides a similar API except that
it doesn't provide the legacy GeoIP-Python API compatibility methods.
その他¶
- The
weak
argument todjango.dispatch.signals.Signal.disconnect()
has been deprecated as it has no effect. - The
check_aggregate_support()
method ofdjango.db.backends.base.BaseDatabaseOperations
has been deprecated and will be removed in Django 2.0. The more generalcheck_expression_support()
should be used instead. django.forms.extras
is deprecated. You can findSelectDateWidget
indjango.forms.widgets
(or simplydjango.forms
) instead.- Private API
django.db.models.fields.add_lazy_relation()
is deprecated. - The
django.contrib.auth.tests.utils.skipIfCustomUser()
decorator is deprecated. With the test discovery changes in Django 1.6, the tests fordjango.contrib
apps are no longer run as part of the user's project. Therefore, the@skipIfCustomUser
decorator is no longer needed to decorate tests indjango.contrib.auth
. - If you customized some error handlers, the view
signatures with only one request parameter are deprecated. The views should
now also accept a second
exception
positional parameter. - The
django.utils.feedgenerator.Atom1Feed.mime_type
anddjango.utils.feedgenerator.RssFeed.mime_type
attributes are deprecated in favor ofcontent_type
. Signer
now issues a warning if an invalid separator is used. This will become an exception in Django 1.10.django.db.models.Field._get_val_from_obj()
is deprecated in favor ofField.value_from_object()
.django.template.loaders.eggs.Loader
is deprecated as distributing applications as eggs is not recommended.- The
callable_obj
keyword argument toSimpleTestCase.assertRaisesMessage()
is deprecated. Pass the callable as a positional argument instead. - The
allow_tags
attribute on methods ofModelAdmin
has been deprecated. Useformat_html()
,format_html_join()
, ormark_safe()
when constructing the method's return value instead. - The
enclosure
keyword argument toSyndicationFeed.add_item()
is deprecated. Use the newenclosures
argument which accepts a list ofEnclosure
objects instead of a single one. - The
django.template.loader.LoaderOrigin
anddjango.template.base.StringOrigin
aliases fordjango.template.base.Origin
are deprecated.
1.9 で削除された機能¶
以下の機能は、非推奨サイクルの終わりに達したため、Django 1.9 で削除されます。詳しくは Features deprecated in 1.7 を見てください。ここには、プロジェクトからこれらの機能を削除する方法についても書かれています。
django.utils.dictconfig
が削除されました。django.utils.importlib
が削除されました。django.utils.tzinfo
が削除されました。django.utils.unittest
が削除されました。syncdb
コマンドが削除されました。django.db.models.signals.pre_syncdb
とdjango.db.models.signals.post_syncdb
が削除されました。- データベースルータ上の
allow_syncdb
へのサポートが削除されました。 - Automatic syncing of apps without migrations is removed. Migrations are
compulsory for all apps unless you pass the
migrate --run-syncdb
option. - The SQL management commands for apps without migrations,
sql
,sqlall
,sqlclear
,sqldropindexes
, andsqlindexes
, are removed. - Support for automatic loading of
initial_data
fixtures and initial SQL data is removed. - All models need to be defined inside an installed application or declare an
explicit
app_label
. Furthermore, it isn't possible to import them before their application is loaded. In particular, it isn't possible to import models inside the root package of an application. - The model and form
IPAddressField
is removed. A stub field remains for compatibility with historical migrations. AppCommand.handle_app()
is no longer supported.RequestSite
andget_current_site()
are no longer importable fromdjango.contrib.sites.models
.- FastCGI support via the
runfcgi
management command is removed. django.utils.datastructures.SortedDict
が削除されました。ModelAdmin.declared_fieldsets
が削除されました。- 後方互換性のために提供されていた
util
が削除されました。django.contrib.admin.util
django.contrib.gis.db.backends.util
django.db.backends.util
django.forms.util
ModelAdmin.get_formsets
が削除されました。- The backward compatible shims introduced to rename the
BaseMemcachedCache._get_memcache_timeout()
method toget_backend_timeout()
is removed. dumpdata
の--natural
および-n
オプションが削除されました。serializers.serialize()
のuse_natural_keys
引数が削除されました。- プライベート API
django.forms.forms.get_declared_fields()
が削除されました。 DateTimeField
でSplitDateTimeWidget
が使用できなくなりました。WSGIRequest.REQUEST
属性が削除されました。django.utils.datastructures.MergeDict
クラスが削除されました。zh-cn
およびzh-tw
言語コードが削除されました。- 内部で使われていた
django.utils.functional.memoize()
が削除されました。 django.core.cache.get_cache
が削除されました。django.db.models.loading
が削除されました。- Passing callable arguments to querysets is no longer possible.
BaseCommand.requires_model_validation
is removed in favor ofrequires_system_checks
. Admin validators is replaced by admin checks.- The
ModelAdmin.validator_class
anddefault_validator_class
attributes are removed. ModelAdmin.validate()
が削除されました。django.db.backends.DatabaseValidation.validate_field
is removed in favor of thecheck_field
method.validate
管理コマンドが削除されました。django.utils.module_loading.import_string
があるため、django.utils.module_loading.import_by_path
が削除されました。future
テンプレートタグライブラリからssi
とurl
テンプレートタグが削除されました。django.utils.text.javascript_quote()
が削除されました。- Database test settings as independent entries in the database settings,
prefixed by
TEST_
, are no longer supported. - The
cache_choices
option toModelChoiceField
andModelMultipleChoiceField
is removed. - The default value of the
RedirectView.permanent
attribute has changed fromTrue
toFalse
. django.contrib.sitemaps.FlatPageSitemap
is removed in favor ofdjango.contrib.flatpages.sitemaps.FlatPageSitemap
.- Private API
django.test.utils.TestTemplateLoader
is removed. - The
django.contrib.contenttypes.generic
module is removed.