# Django 5.2.9 ドキュメント

# Django 5.2 リリースノート

2025年4月2日

Django 5.2 へようこそ！

このリリースノートでは、 バージョン 5.2 の新機能 と、Django 5.1 以前からアップグレードする際に注意すべき、 後方互換性のない変更 について説明します。また、 一部の機能を非推奨 としました。

既存のプロジェクトをアップデートするときは、 Django の新しいバージョンへの更新 ガイドに従ってください。

Django 5.2 は 長期サポートリリース として設計されています。リリースから最低3年間はセキュリティアップデートを受けます。以前の LTS である Django 4.2 に対するサポートは2026年4月に終了します。

## Python バージョン間の互換性

Django 5.2 supports Python 3.10, 3.11, 3.12, 3.13, and 3.14 (as of 5.2.8). We highly recommend and only officially support the latest release of each series.

## Django 5.2 の新機能

### `shell` における自動モデルインポート

`shell` 管理コマンドは、インストール済みのすべてのアプリからモデルを自動的にインポートするようになりました。 `--verbosity` フラグを 2 以上に設定すると、インポートされたオブジェクトの詳細をさらに表示できます。

/ 

    $ python -Wall manage.py shell --verbosity=2
    6 objects imported automatically, including:

      from django.contrib.admin.models import LogEntry
      from django.contrib.auth.models import Group, Permission, User
      from django.contrib.contenttypes.models import ContentType
      from django.contrib.sessions.models import Session

    ...\> py -Wall manage.py shell --verbosity=2
    6 objects imported automatically, including:

      from django.contrib.admin.models import LogEntry
      from django.contrib.auth.models import Group, Permission, User
      from django.contrib.contenttypes.models import ContentType
      from django.contrib.sessions.models import Session

この挙動は、自動インポートを追加または削除するように カスタマイズすることができます 。

### 複合主キー

新たに追加された `django.db.models.CompositePrimaryKey` により、複数のフィールドからなる主キーをテーブルに作成することができるようになりました。

複合主キーを使うには、モデルを定義する際に `pk` 属性を `CompositePrimaryKey` で設定します。

    from django.db import models

    class Release(models.Model):
        pk = models.CompositePrimaryKey("version", "name")
        version = models.IntegerField()
        name = models.CharField(max_length=20)

詳細は 複合主キー を参照してください。

### `BoundField` のオーバーライドの簡素化

Prior to version 5.2, overriding `Field.get_bound_field()` was the only option to use a custom `BoundField`. Django now supports specifying the following attributes to customize form rendering:

- プロジェクト層で `BaseRenderer.bound_field_class`

- フォーム層で `Form.bound_field_class`

- フィールド層で `Field.bound_field_class`

例えば、 `Form` クラスの `BoundField` をカスタマイズするには、下記のように実装します。

    from django import forms

    class CustomBoundField(forms.BoundField):

        custom_class = "custom"

        def css_classes(self, extra_classes=None):
            result = super().css_classes(extra_classes)
            if self.custom_class not in result:
                result += f" {self.custom_class}"
            return result.strip()

    class CustomForm(forms.Form):
        bound_field_class = CustomBoundField

        name = forms.CharField(
            label="Your Name",
            max_length=100,
            required=False,
            widget=forms.TextInput(attrs={"class": "name-input-class"}),
        )
        email = forms.EmailField(label="Your Email")

`CustomForm` インスタンスをレンダリングする際、下記の HTML が含まれます。

    <div class="custom">
      <label for="id_name">Your Name:</label>
      <input type="text" name="name" class="name-input-class" maxlength="100" id="id_name">
    </div>

    <div class="custom">
      <label for="id_email">Your Email:</label>
      <input type="email" name="email" maxlength="320" required="" id="id_email">
    </div>

この機能の更なる詳細は BoundField のカスタマイズ を参照してください。

### マイナーな機能

#### `django.contrib.admin`

- `admin/base.html` テンプレートに新たなブロックとして extrabody <extrabody>`が追加されました。これにより、 ``</body>` タグの直前にカスタムコードを追加できるようになりました。

- `URLField` の値がリンクとしてレンダリングされるようになりました。

#### `django.contrib.admindocs`

- docstring 内のコンポーネントへのリンクは、 `:role:`リンクテキスト <link>`` という形式を用いることで、カスタムのリンクテキストをサポートするようになりました。詳細は ドキュメンテーション・ヘルパー を参照してください。

- モデルページ は、対応する閲覧または変更権限を持つユーザーのみに制限されるようになりました。

#### `django.contrib.auth`

- PBKDF2 パスワードハッシュに対するデフォルトのイテレーション回数が 870,000 から 1,000,000 に増加しました。

- `a` を先頭に持つ下記の非同期メソッドが新たに追加されました。

  - `UserManager.acreate_user()`

  - `UserManager.acreate_superuser()`

  - `BaseUserManager.aget_by_natural_key()`

  - `User.aget_user_permissions()`

  - `User.aget_all_permissions()`

  - `User.aget_group_permissions()`

  - `User.ahas_perm()`

  - `User.ahas_perms()`

  - `User.ahas_module_perms()`

  - `ModelBackend.aauthenticate()`

  - `ModelBackend.aget_user_permissions()`

  - `ModelBackend.aget_group_permissions()`

  - `ModelBackend.aget_all_permissions()`

  - `ModelBackend.ahas_perm()`

  - `ModelBackend.ahas_module_perms()`

  - `RemoteUserBackend.aauthenticate()`

  - `RemoteUserBackend.aconfigure_user()`

- 認証バックエンドは非同期実装を提供できるようになり、非同期の認証関数（例： `aauthenticate()` ）を呼び出す際にそれらが使用され、コンテキストスイッチが減って性能が向上します。詳細は 非同期インターフェースを追加する を参照してください。

- パスワードバリデータクラス に新たに `get_error_message()` 関数が追加されました。この関数をサブクラスでオーバーライドすることで、エラーメッセージをカスタマイズできるようになりました。

#### `django.contrib.gis`

- GDAL は、新たに追加された `OGRGeometry.has_curve` プロパティ、 `OGRGeometry.get_linear_geometry()` および `OGRGeometry.get_curve_geometry()` メソッドにより、曲線ジオメトリ `CurvePolygon` 、`CompoundCurve` 、`CircularString` 、`MultiSurface` 、 `MultiCurve` をサポートするようになりました。

- `coveredby` と `covers` ルックアップが MySQLをサポートするようになりました。

#### `django.contrib.syndication`

- すべての `SyndicationFeed` クラスが `stylesheets` 属性をサポートするようになりました。指定すると、与えられたリスト内の各スタイルシートごとに、文書の先頭へ `<? xml-stylesheet ?>` の処理命令が追加されます。詳しくは フィードのスタイルシート を参照してください。

#### データベースバックエンド

- MySQL の接続において、非推奨の文字セット `utf8mb3` のエイリアスである `utf8` ではなく、デフォルトで `utf8mb4` 文字セットを使用するようになりました。

- オラクルのバックエンドにおいて コネクションプール がサポートされました。これは、データベース設定の `OPTIONS` パートにおいて `"pool"` を設定することで使用できます。

#### デコレータ

- `method_decorator()` が非同期ビューメソッドをサポートするようになりました。

#### E メール

- `EmailMessage.attachments` と `EmailMultiAlternatives.attachments` のタプル要素は、通常のタプルではなく名前付きタプルになりました。

- `EmailMultiAlternatives.alternatives` は通常のタプルではなく名前付きタプルになりました。

- `body_contains()` メソッドが新たに追加されました。このメソッドは、メールの `body` および添付されたすべての `text/*` MIME タイプの代替コンテンツに指定したテキストが含まれているかどうかを示すブール値を返します。

#### エラー報告

- `SafeExceptionReporterFilter.hidden_settings` 属性は、値の名前に `AUTH` が含まれる場合にその値を機密情報として扱うようになりました。

#### フォーム

- `ColorInput` が新たに追加されました。このフォームウィジェットは `<input type="color" ...>` でレンダリングされ、 `rrggbb` 16進数フォーマットで色を入力できます。一部のブラウザでは視覚的なカラー選択インターフェースをこの入力タイプでサポートしています。

- `SearchInput` が新たに追加されました。このフォームウィジェットは `<input type="search" ...>` でレンダリングされ、検索文字列を入力できます。

- `TelInput` が新たに追加されました。このフォームウィジェットは `<input type="tel" ...>` でレンダリングされ、電話番号を入力できます。

- `ErrorList` に `field_id` 引数が追加され、エラーテンプレートの HTML に `id` 属性を追加できるようになりました。詳細は `ErrorList.field_id` を参照してください。

- `BoundField` に `aria_describedby` プロパティが追加され、テンプレート内でこの HTML 属性を簡単に使えるようになりました。

- スクリーンリーダー利用者のアクセシビリティを改善するため、フォームフィールドとそのエラーメッセージの関連付けに `aria-describedby` が使用されるようになりました。詳細は フォームエラーの表示方法 を参照してください。

- `Script` が新たに追加されました。このアセットオブジェクトはフォームメディア内の JavaScript にカスタム HTML 属性を追加するために利用できます。詳細は オブジェクトとしてのパス を参照してください。

#### 管理コマンド

- `runserver` を実行すると、本番環境には不向きであることを示す警告が新たに表示されるようになりました。この警告は `DJANGO_RUNSERVER_HIDE_WARNING` 環境変数を `"true"` に設定することで非表示にできます。

- `makemigrations` および `migrate` コマンドに新たに `Command.autodetector` 属性が追加されました。この属性をサブクラスでオーバーライドすることで、カスタムの自動検出クラスを使用することができるようになります。

- `BaseCommand.get_check_kwargs()` メソッドが新たに追加されました。このメソッドをカスタムコマンドでオーバーライドすることで、データベース依存のチェックを有効化するなど、システムチェックの実行を制御できるようになります。

#### マイグレーション

- `AlterConstraint` が新たに no-op 操作として追加され、データベースの制約を削除・再作成しなくても制約を変更できるようになりました。

#### モデル

- `QuerySet.values()` と `QuerySet.values_list()` の使用時に生成される `SELECT` 句は、参照される式の指定順と一致するようになりました。従来は直感に反する一連の規則に基づいて順序が決定されていたため、 `QuerySet.union()` などのメソッドによるクエリ結合の結果が予測しにくいものとなっていました。

- `GeneratedField` を使用するモデル制約のバリデーションが新たにサポートされるようになりました。

- `Expression.set_returning` が新たに追加されました。この属性は式が集合を返す関数を含むことを指定し、サブクエリの評価を強制します。これは多くの Postgres における集合を返す関数で必要となります。

- SQLite において、無制限の `VARCHAR` 列がサポートされたため `CharField.max_length` が必須でなくなりました。

- PostgreSQL 17以降において、 `QuerySet.explain()` が `memory` と `serialize` オプションをサポートされるようになりました。

- データベース関数に `JSONArray` が新たに追加されました。この関数はフィールド名または式のリストを引数に取り、これらの値を含む JSON 配列を返します。

- `Expression.allows_composite_expressions` が新たに追加されました。この属性は複合式を許容するかどうかを指定し、例えば 複合主キー をサポートする際に使用されます。

#### Request と Response

- `HttpResponse.content` の文字列表現を提供する `HttpResponse.text` プロパティが追加されました。

- `HttpRequest.get_preferred_type()` が追加されました。この関数はクライアントが受け入れる優先メディアタイプを参照するために使用できます。

- `HttpResponseRedirect` と `HttpResponsePermanentRedirect` に `preserve_request` 引数が追加されました。この引数はそれぞれのクラスで HTTP ステータスコード 302/307 、 301/308 を使用するかどうかを決定します。

- `redirect()` に `preserve_request` 引数が追加されました。これにより、特定のステータスコードを用いたリダイレクト時に、ユーザーエージェントに対して HTTP メソッドと本文の再利用を指示できるようになりました。

#### シリアライズ (シリアル化)

- 各シリアライゼーション形式は、関数ではなく `Deserializer` クラスを定義するようになりました。これは、custom serialization format を定義する際の拡張性を高めるためです。

#### テンプレート

- `simple_block_tag()` デコレータが新たに追加されました。これにより、テンプレートの一部を受け取って使用できる単純なブロックタグの作成が可能となりました。

#### テスト

- Django のカスタムアサーションに由来するスタックフレームが非表示になりました。これにより、テスト失敗の出力が読みやすくなり、 `test --pdb` で失敗したテストメソッドに直接入れるようになります。

- `fixtures` と serialized_rollback=True で有効化されたマイグレーションから読み込まれたデータが `TransactionTestCase.setUpClass()` において利用可能になりました。

#### URL

- `reverse()` と `reverse_lazy()` に `query` および `fragment` キーワード引数を受け付けるようになりました。これにより、生成される URL にそれぞれクエリ文字列および／またはフラグメント識別子を追加できるようになりました。

#### ユーティリティ

- `SafeString` now returns `NotImplemented` in `__add__` for non-string right-hand side values. This aligns with the `str` addition behavior and allows `__radd__` to be used if available.

- `format_html_join()` は、マッピングのイテラブルを受け取り、その内容をキーワード引数として `format_html()` に渡せるようになりました。

## 5.2 における後方互換性のない変更

### データベースバックエンド API

このセクションでは、サードパーティのデータベースバックエンドで必要になる可能性のある変更について説明します。

- `Model._is_pk_set()` メソッドが新たに追加され、モデルインスタンスの主キーが定義されているかどうかをチェックできるようになりました。

- `BaseDatabaseOperations.adapt_decimalfield_value()` は no-op 操作となり、単に与えられた値を返すようになりました。

### `django.contrib.gis`

- PostGIS 3.0 に対するサポートが削除されました。

- GDAL 3.0 に対するサポートが削除されました。

### PostgreSQL 13 に対するサポートの削除

PostgreSQL 13 へのアップストリームサポートは2025年11月に終了します。 Django 5.2 では PostgreSQL 14 以降をサポートします。

### MySQL 接続における文字セットの既定値の変更

MySQL の接続は、非推奨の文字セット `utf8mb3` のエイリアスである `utf8` ではなく、デフォルトで `utf8mb4` 文字セットを使用するようになりました。レガシーなデータベースで必要な場合は、`DATABASES` 設定の `OPTIONS` で `utf8mb3` を指定できます。

### その他

- `EmailMultiAlternatives.alternatives` の追加は `attach_alternative()` メソッドでのみサポートされます。

- `gettext` の最小サポートバージョンが 0.15 から 0.19 に変更されました。

- `HttpRequest.accepted_types` はリクエストの `Accept` ヘッダーに基づき、クライアントの設定によってソートされるようになりました。

- 属性 `UniqueConstraint.violation_error_code` と `UniqueConstraint.violation_error_message` は指定されれば常に使用されるように変更されました。従来は `UniqueConstraint.fields` が指定され `UniqueConstraint.condition` が指定されない場合に無視されていました。

- コンテクストプロセッサである `debug()` はデフォルトのプロジェクトテンプレートには含まれなくなりました。

- 下記のメソッドは テンプレートコンテキストをレンダリングする 際の副作用を防ぐために、`alters_data=True` が設定されるようになりました。

  - `UserManager.create_user()`

  - `UserManager.acreate_user()`

  - `UserManager.create_superuser()`

  - `UserManager.acreate_superuser()`

  - `QuerySet.create()`

  - `QuerySet.acreate()`

  - `QuerySet.bulk_create()`

  - `QuerySet.abulk_create()`

  - `QuerySet.get_or_create()`

  - `QuerySet.aget_or_create()`

  - `QuerySet.update_or_create()`

  - `QuerySet.aupdate_or_create()`

- `oracledb` の最小サポートバージョンが 1.3.2 から 2.3.0 に変更されました。

- 1つの引数のみを許容するビルトインの集合関数 (`Avg`, `Count`, `Max`, `Min`, `StdDev`, `Sum`, and `Variance`) は引数の数が不適切な場合に `TypeError` を呼び出すようになりました。

## 5.2 で非推奨となった機能

### その他

- `django.contrib.staticfiles.finders.find()` 関数の `all` 引数は非推奨となりました。代わりに `find_all` 引数を使用してください。

- `django.contrib.auth.login()` および `django.contrib.auth.alogin()` において `user` が `None` であるとき、 `request.user` や `request.auser()` にフォールバックする挙動は非推奨となりました。

- PostgreSQL 特有の集合を返す関数 `django.contrib.postgres.aggregates.ArrayAgg` 、 `django.contrib.postgres.aggregates.JSONBAgg` 、 `django.contrib.postgres.aggregates.StringAgg``の ``ordering` キーワード引数は非推奨となりました。代わりに `order_by` 引数を使用してください。

- `aprocess_request()` をオーバーライドせずに `process_request()` をオーバーライドする `RemoteUserMiddleware` のサブクラスのサポートが非推奨となりました。