# Django 5.2.8 ドキュメント

# Django 5.1 リリースノート

2024年8月7日

Django 5.1 へようこそ！

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

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

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

Django 5.1 は、Python 3.10、3.11、3.12、および 3.13（5.1.3 時点）をサポートしています。 最新のリリース を使用することを強く推奨しており、公式にサポートするのも各シリーズの最新リリースのみです。

## Django 5.1 の新機能

### `{% querystring %}` テンプレートタグ

Django 5.1 では、`{% querystring %}` テンプレートタグが導入されました。これにより、URL 内のクエリパラメータの変更が簡略化され、既存のクエリパラメータを維持しつつ、特定の部分を追加または変更してリンクを生成するのが簡単になります。

たとえば、テンプレート内でページネーションやクエリ文字列を操作するのは面倒な場合があります。ページネーションされたビュー内で、次のページに移動するための URL を動的に生成する次のようなテンプレートフラグメントについて考えてみてください。

    {# Linebreaks added for readability, this should be one, long line. #}
    <a href="?{% for key, values in request.GET.iterlists %}
      {% if key != "page" %}
        {% for value in values %}
          {{ key }}={{ value }}&amp;
        {% endfor %}
      {% endif %}
    {% endfor %}page={{ page.next_page_number }}">Next page</a>

これを新しいテンプレートタグを使用するように切り替えると、上記は次のように魔法のように簡略化されます。

    <a href="{% querystring page=page.next_page_number %}">Next page</a>

### PostgreSQL の接続プール

Django 5.1 では、PostgreSQL の 接続プール のサポートも導入されました。新しい接続の確立には比較的長い時間がかかる場合があるため、接続をオープンにしたままにしておくことで、レイテンシを削減できます。

psycopg で接続プールを使用するには、次のように `OPTIONS` 内の `"pool"` オプションに、`ConnectionPool` に渡されるディクショナリを設定するか、`True` にすることで `ConnectionPool` のデフォルトを使用します。

    DATABASES = {
        "default": {
            "ENGINE": "django.db.backends.postgresql",
            # ...
            "OPTIONS": {
                "pool": {
                    "min_size": 2,
                    "max_size": 4,
                    "timeout": 10,
                }
            },
        },
    }

### デフォルトで認証を要求するミドルウェア

新しい `LoginRequiredMiddleware` は、すべての未認証リクエストをログインページにリダイレクトします。新しい `login_not_required()` デコレータを使用すると、ビューで未認証リクエストを許可できるようになります。

`LoginRequiredMiddleware` は、`login_required()` デコレータによって設定された `login_url` と `redirect_field_name` の値を尊重しますが、`LoginRequiredMixin` による `login_url` または `redirect_field_name` の設定はサポートされていません。

これを有効にするには、`"django.contrib.auth.middleware.LoginRequiredMiddleware"` を `MIDDLEWARE` 設定に追加します。

### マイナーな機能

#### `django.contrib.admin`

- `ModelAdmin.list_display` において、関連モデルのフィールドをリスト表示するために `__` 演算子によるルックアップができるようになりました。

#### `django.contrib.auth`

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

- OWASP の推奨に従い、`ScryptPasswordHasher` の `parallelism` が 1 から 5 に増加しました。

- 新しい `AdminUserCreationForm` と、既存の `AdminPasswordChangeForm` は、フォームの保存時に使用不可のパスワードを設定することでパスワードベースの認証を無効化できるようになりました。この機能は、管理画面のユーザー作成ページやパスワード変更ページで利用可能です。

- `login_required()`、`permission_required()`、`user_passes_test()` デコレータが、非同期ビュー関数のラッピングをサポートするようになりました。

- `ReadOnlyPasswordHashWidget` に、ユーザーパスワードのリセットボタンが含まれるようになりました。このボタンは、以前に `ReadOnlyPasswordHashField` のヘルプテキストに埋め込まれていたリンクを置き換えます。これにより、`UserChangeForm` の全体的なアクセシビリティが向上します。

#### `django.contrib.gis`

- SpatiaLite 5.1 以降で `BoundingCircle` をサポートするようになりました。

- MySQL 8.0.24 以降で `Collect` をサポートするようになりました。

- `GeoIP2` が、`ipaddress.IPv4Address` または `ipaddress.IPv6Address` オブジェクトを使用してクエリできるようになりました。

- `GeoIP2.country()` が `continent_code`、`continent_name`、`is_in_european_union` の値を公開するようになりました。

- `GeoIP2.city()` は、`accuracy_radius` と `region_name` の値を新たに公開するようになりました。さらに、`dma_code` と `region` の値は、それぞれ `metro_code` と `region_code` として公開されるようになりましたが、後方互換性のために従来のキーも引き続き使用可能です。

- `Area` は、`ha` 単位（ヘクタール）をサポートするようになりました。

- 新しい `OGRGeometry.is_3d` 属性により、ジオメトリが `Z` 座標次元を持っているかどうかを確認できるようになりました。

- 新しい `OGRGeometry.set_3d()` メソッドにより、`Z` 座標次元の追加および削除が可能になりました。

- `OGRGeometry`、`Point`、`LineString`、`Polygon`、および `GeometryCollection` とそのサブクラスは、新しい `OGRGeometry.is_measured` 属性、`m` プロパティ、および `OGRGeometry.set_measured()` メソッドを通じて測定ジオメトリ（Measured Geometries）をサポートするようになりました。

- `OGRGeometry.centroid` が、サポートされるすべてのジオメトリタイプで利用可能になりました。

- `FromWKB()` および `FromWKT()` 関数が、オプションの `srid` 引数をサポートするようになりました（ただし、Oracle では無視されます）。

#### `django.contrib.postgres`

- `BTreeIndex` が新たに `deduplicate_items` パラメータをサポートするようになりました。

#### `django.contrib.sessions`

- `django.contrib.sessions.backends.cached_db.SessionStore` は、キャッシュにセッション情報を保存する際に例外を処理するようになりました。新たに追加された セッションロガー を通じて、適切なエラーメッセージとそのトレースバックをログに記録します。

- `django.contrib.sessions.backends.base.SessionBase` およびすべての組み込みセッションエンジンが非同期APIを提供するようになりました。新しい非同期メソッドはすべて `a` を接頭辞に持つ名前で提供され、例えば `aget()`、`akeys()`、`acycle_key()` などがあります。

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

- `"init_command"` オプションが SQLite の `OPTIONS` でサポートされるようになり、接続時に設定する PRAGMA オプション を指定できるようになりました。

- `"transaction_mode"` オプションが SQLite の `OPTIONS` でサポートされるようになり、トランザクションの動作 を指定できるようになりました。

- `"pool"` オプションが PostgreSQL の `OPTIONS` でサポートされるようになり、接続プール を利用できるようになりました。

#### エラー報告

- アクセシビリティ向上のため、技術的な404および500エラーページに、ヘッダー、フッター、メインコンテンツ領域に対応するHTMLランドマーク要素が使用されるようになりました。

#### ファイルストレージ

- `FileSystemStorage` の `allow_overwrite` パラメータにより、既存のファイルを上書きして新しいファイルを保存できるようになりました。

#### フォーム

- アクセシビリティを向上させ、スクリーンリーダーがフィールドセットとそのヘルプテキストを関連付けられるようにするため、フォームのフィールドセットに `aria-describedby` HTML属性が追加されました。

#### 管理コマンド

- `makemigrations` コマンドが、各オペレーションの `オペレーション・カテゴリ` を強調表示するために意味のある記号を表示するようになりました。

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

- 新しい `Operation.category` 属性により、`makemigrations` がオペレーションに対して意味のある記号を表示するために使用する `オペレーション・カテゴリ` を指定できるようになりました。

#### モデル

- `QuerySet.explain()` が PostgreSQL 16以降で `generic_plan` オプションをサポートするようになりました。

- `RowRange` は、`start` 引数に正の整数、`end` 引数に負の整数を受け入れるようになりました。

- 新しい `exclusion` 引数が `RowRange` と `ValueRange` に追加され、ウィンドウフレームから行、グループ、および同順位（タイ）を除外できるようになりました。

- `QuerySet.order_by()` が、アノテーションのトランスフォーム、たとえば `JSONObject` のキーや `ArrayAgg` のインデックスなどによる並び替えをサポートするようになりました。

- `F()` 式と `OuterRef()` 式が、`CharField`、`EmailField`、`SlugField`、`URLField`、`TextField`、あるいは `ArrayField` を出力する場合、スライス が可能になりました。

- `Model.refresh_from_db()` と `Model.arefresh_from_db()` に新しく追加された `from_queryset` 引数を使用すれば、モデルの値を再読み込みするためのクエリセットをカスタマイズできます。これにより、再読み込み前に行をロックしたり、リレーション先のオブジェクトを取得したりすることが可能になります。

- 新しい `Expression.constraint_validation_compatible` 属性を使用すると、制約の検証時にその式を無視するよう指定することができます。

#### テンプレート

- カスタムタグは、`Parser` オブジェクトに追加のデータを設定できるようになりました。このデータは `Template` インスタンス上で利用可能になります。このようなデータは、テンプレートローダーや他のテンプレートクライアントで使用できます。

- テンプレートエンジン は、チェックフレームワークに既に登録されている `check()` メソッドを実装するようになりました。

#### テスト

- `assertContains()`、`assertNotContains()`、および `assertInHTML()` は、アサーションエラーメッセージにヘイスタック（haystacks）を追加するようになりました。

- `RequestFactory`、`AsyncRequestFactory`、`Client`、および `AsyncClient` クラスは、新たに `query_params` パラメータをサポートしました。このパラメータは、クエリ文字列のキーと値を含む辞書を受け付けます。これにより、任意のHTTPメソッドに対してクエリ文字列を簡単に設定できるようになりました。

      self.client.post("/items/1", query_params={"action": "delete"})
      await self.async_client.post("/items/1", query_params={"action": "delete"})

- 新しい `SimpleTestCase.assertNotInHTML()` アサーションにより、指定されたHTMLヘイスタック内に特定のHTMLフラグメントが含まれていないことをテストできるようになりました。

- テストの独立性を確保するため、`SimpleTestCase` 内でスレッド内のデータベース接続が許可されなくなりました。

#### バリデータ

- 新しい `DomainNameValidator` は、国際化ドメイン名を含むドメイン名を検証します。また、新しい `validate_domain_name()` 関数は、`DomainNameValidator` のインスタンスを返します。

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

### `django.contrib.gis`

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

- PROJ < 6 のサポートが削除されました。

- GDAL 2.4 のサポートが削除されました。

- `GeoIP2` は、ディレクトリパスが指定された場合に、これまでのように都市データベースと国データベースの両方を開くことはなくなりました。代わりに、都市データベースが利用可能であればそちらを優先します。国データベースは都市データベースのサブセットであり、通常は両方を使用する必要はありません。同じディレクトリ内で国データベースを使用する必要がある場合は、コンストラクタに国データベースのパスを明示的に渡してください。

### MariaDB 10.4 のサポートを終了しました

MariaDB 10.4のアップストリームサポートは2024年6月に終了します。Django 5.1はMariaDB 10.5以降をサポートします。

### PostgreSQL 12 のサポートを終了しました

PostgreSQL 12 のアップストリーム サポートは 2024 年 11 月に終了します。Django 5.1 は PostgreSQL 13 以降をサポートします。

### その他

- アクセシビリティを向上させるために、admin サイトの changelist フィルタを `<div>` タグではなく `<nav>` タグでレンダリングするようになりました。

- アクセシビリティを向上させるために、admin サイトの footer を `<div>` タグではなく `<footer>` タグでレンダリングするようになり、さらに `<div id="main">` 要素の下に移動しました。

- アクセシビリティを向上させるため、名前付きのフィールドセットで `collapse` クラスを使用する `ModelAdmin.fieldsets` および `InlineModelAdmin.fieldsets` に関連付けられた展開可能なウィジェットが、 `<details>` および `<summary>` 要素を含むようになりました。

- JavaScript ファイル `collapse.js` は、Django admin サイトでは不要になったので削除されました。

- `SimpleTestCase.assertURLEqual()` と `assertInHTML()` は `": "` を `msg_prefix` に追加します。これにより、他のアサーションの振る舞いと一致するようになります。

- `django.utils.text.Truncator` used by `truncatechars_html` and `truncatewords_html` template filters now uses `html.parser.HTMLParser` subclasses. This results in a more robust and faster operation, but there may be small differences in the output.

- ドキュメント化されていなかった `django.urls.converters.get_converter()` 関数が削除されました。

- SQLite の最小サポートバージョンが 3.27.0 から 3.31.0 に引き上げられました。

- `name` なしでファイルを保存した場合に、`FileField` が `FieldError` を発生させるようになりました。

- 画像をストレージに保存した後に `ImageField.update_dimension_fields(force=True)` が呼び出されなくなりました。ストレージバックエンドが画像をリサイズする場合、`width_field` と `height_field` が実際の画像の幅と高さと一致しなくなります。

- `asgiref` の最小サポートバージョンが 3.7.0 から 3.8.1 に引き上げられました。

- To improve performance, the `delete_selected` admin action now uses `QuerySet.bulk_create()` when creating multiple `LogEntry` objects. As a result, `pre_save` and `post_save` signals for `LogEntry` are not sent when multiple objects are deleted via this admin action.

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

### その他

- `ModelAdmin.log_deletion()` メソッドと `LogEntryManager.log_action()` メソッドは非推奨になりました。サブクラスは代わりに `ModelAdmin.log_deletions()` と `LogEntryManager.log_actions()` を実装する必要があります。

- 文書化されていない `django.utils.itercompat.is_iterable()` 関数と `django.utils.itercompat` モジュールが非推奨になりました。代わりに `isinstance(..., collections.abc.Iterable)` を使用してください。

- `django.contrib.gis.geoip2.GeoIP2.coords()` メソッドは非推奨になりました。代わりに `django.contrib.gis.geoip2.GeoIP2.lon_lat()` を使用してください。

- `django.contrib.gis.geoip2.GeoIP2.open()` メソッドは非推奨になりました。代わりに `GeoIP2` コンストラクタを使用してください。

- `Model.save()` および `Model.asave()` への位置引数の引き渡しは非推奨となり、キーワードのみの引数が推奨されるようになりました。

- 設定 `django.contrib.gis.gdal.OGRGeometry.coord_dim` は非推奨になりました。代わりに `set_3d()` を使用してください。

- `django.urls.register_converter()` による既存のコンバータのオーバーライドは非推奨になりました。

- `CheckConstraint` の `check` キーワード引数は非推奨となり、代わりに `condition` が推奨されるようになりました。

- 文書化されていない `FileSystemStorage` の `OS_OPEN_FLAGS` プロパティは非推奨となりました。ストレージ内のファイルを上書きできるようにするには、新しい `allow_overwrite` オプションを `True` に設定してください。

- `FieldCacheMixin` の `get_cache_name()` メソッドは非推奨となり、代わりに `cache_name` キャッシュプロパティが推奨されるようになりました。

## 5.1 で削除された機能

以下の機能は、非推奨サイクルの終わりに達したため、Django 5.1 で削除されます。

これらの変更の詳細、およびこれらの機能の使用を取り除く方法については、4.2 で非推奨となった機能 を参照してください。

- `BaseUserManager.make_random_password()` メソッドは削除されました。

- モデルの `Meta.index_together` オプションは削除されました。

- `length_is` テンプレートフィルタは削除されました。

- `django.contrib.auth.hashers.SHA1PasswordHasher`、`django.contrib.auth.hashers.UnsaltedSHA1PasswordHasher`、`django.contrib.auth.hashers.UnsaltedMD5PasswordHasher` は削除されました。

- モデルの `django.contrib.postgres.fields.CICharField` 、 `django.contrib.postgres.fields.CIEmailField` 、`django.contrib.postgres.fields.CITextField` は、履歴マイグレーションにおけるサポートを除いて、削除されました。

- `django.contrib.postgres.fields.CIText` ミックスインは削除されました。

- `BaseGeometryWidget` の `map_width` と `map_height` 属性は削除されました。

- `SimpleTestCase.assertFormsetError()` メソッドは削除されました。

- `TransactionTestCase.assertQuerysetEqual()` メソッドは削除されました。

- `JSONField` と関連するルックアップや式に対して、エンコードされた JSON 文字列リテラルを渡すことはサポートされなくなりました。

- `Signer` および `TimestampSigner` への位置引数の受け渡しのサポートが削除されました。

- `DEFAULT_FILE_STORAGE` と `STATICFILES_STORAGE` の設定は削除されました。

- `django.core.files.storage.get_storage_class()` 関数は削除されました。