---
title: "Django ユーティリティ (django.utils)"
version: 6.1
locale: ja
source: https://docs.djangoproject.com/ja/6.1/ref/utils/
canonical: https://djangodocs.dev/ja/6.1/ref/utils/
---
# Django ユーティリティ (`django.utils`)

このドキュメントは、`django.utils` のすべての安定したモジュールを対象としています。`django.utils` 内のほとんどのモジュールは内部使用を目的としていることから、 [内部リリース非推奨ポリシー](/ja/6.1/internals/release-process/#internal-release-deprecation-policy) に従い、以下に記載する内容のみが 安定版として提供され、また後方互換性を維持しています。

## `django.utils.cache`

このモジュールには、HTTPキャッシュの制御を補助するための関数が含まれています。これは、レスポンスの `Vary` ヘッダーを管理することによって行います。レスポンスオブジェクトのヘッダーを直接パッチするための関数や、そのヘッダーパッチを行うためのデコレータも含まれています。

`Vary` ヘッダーについての詳細は、 [**RFC 9110 Section 12.5.5**](https://datatracker.ietf.org/doc/html/rfc9110.html#section-12.5.5) を参照してください。

基本的に、 `Vary` HTTPヘッダーは、キャッシュがキャッシュキーを構築する際に考慮すべきヘッダーを定義します。同一パスのリクエストであっても、 `Vary` で指定されたヘッダーの内容が異なる場合は、誤ったコンテンツの配信を防ぐために異なるキャッシュキーを取得する必要があります。

たとえば、[国際化のためのミドルウェア](/ja/6.1/topics/i18n/) は、`Accept-language` ヘッダーによってキャッシュを区別するようにしています。

#### `patch_cache_control(response, **kwargs)`

この関数は、キーワード引数を `Cache-Control` ヘッダーに追加することで、ヘッダーをパッチします。変換する内容は以下の通りです。

- すべてのキーワードパラメータ名を小文字に変換し、アンダースコアをハイフンに変換する
- パラメータの値が `True` （実質的な真の値ではなく、正確に `True` ）である場合、ヘッダーにはパラメータ名のみを追加する
- すべての他のパラメータは、その値に `str()` を適用した後に追加する

#### `get_max_age(response)`

レスポンスのCache-Controlヘッダーから max-age を整数として返します（見つからなかった場合や整数でなかった場合は `None` を返します）。

#### `patch_response_headers(response, cache_timeout=None)`

与えられた `HttpResponse` オブジェクトに以下のような便利なヘッダーを追加します。

- `Expires`
- `Cache-Control`

それぞれのヘッダーは、未設定の場合にのみ追加されます。

`cache_timeout` は秒単位で指定します。デフォルトでは、 [`CACHE_MIDDLEWARE_SECONDS`](/ja/6.1/ref/settings/#std-setting-CACHE_MIDDLEWARE_SECONDS) の値が使用されます。

#### `add_never_cache_headers(response)`

`Expires` ヘッダーを現在の日付/時刻で設定します。

`Cache-Control: max-age=0, no-cache, no-store, must-revalidate, private` ヘッダーをレスポンスに追加し、ページがキャッシュされないように設定します。

それぞれのヘッダーは、未設定の場合にのみ追加されます。

#### `patch_vary_headers(response, newheaders)`

与えられた `HttpResponse` オブジェクトに、 `Vary` ヘッダーを追加（または更新）します。 `newheaders` は、`Vary` に含まれるべきヘッダー名のリストです。ヘッダーにアスタリスクが含まれている場合、 [**RFC 9110 Section 12.5.5**](https://datatracker.ietf.org/doc/html/rfc9110.html#section-12.5.5) に従い  `Vary` ヘッダーは単一のアスタリスク `'*'` で構成されます。それ以外の場合、`Vary` の既存のヘッダーは削除されません。

#### `get_cache_key(request, key_prefix=None, method='GET', cache=None)`

リクエストのパスに基づいたキャッシュキーを返します。グローバルパスレジストリから考慮すべきヘッダーのリストを取得してそれを使用してキャッシュキーを構築するため、リクエストフェーズで使用できます。

ヘッダーリストが保存されていない場合、ページを再構築する必要があるので、この関数は `None` を返します。

#### `learn_cache_key(request, response, cache_timeout=None, key_prefix=None, cache=None)`

レスポンスオブジェクトから、特定のリクエストパスに対してどのヘッダーを考慮する必要があるかを学習します。それらのヘッダーはグローバルパスレジストリに格納されるため、後からそのパスにアクセスした際には、レスポンスオブジェクト自体を構築することなく、どのヘッダーを考慮する必要があるかがわかります。ヘッダーはレスポンスの `Vary` ヘッダーで指定されますが、レスポンスの生成は防ぎたいでしょう。

キャッシュキー生成に使用するヘッダーのリストは、ページ自体と同じキャッシュ内に保存されています。キャッシュがあるデータを破棄する場合、Varyヘッダーとキャッシュキー生成に使用するヘッダーのリストを取得するために、レスポンスを構築する必要があります。

## `django.utils.dateparse`

このモジュールで定義された関数は、以下の特性を共有しています：

- ISO 8601 日付/時刻形式の文字列（またはそれに近い代替形式）を受け付け、Python の [`datetime`](https://docs.python.org/3/library/datetime.html#module-datetime) モジュールにある対応するクラスからオブジェクトを返します。
- 入力が適切にフォーマットされているが、有効な日付や時刻ではない場合、 [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) を発生させます。
- それが全く適切にフォーマットされていない場合、 `None` を返します。
- 入力ではピコ秒単位まで受け付けますが、Pythonがサポートしているマイクロ秒単位に切り捨てられます。

#### `parse_date(value)`

文字列を解析し、[`datetime.date`](https://docs.python.org/3/library/datetime.html#datetime.date) を返します。

#### `parse_time(value)`

文字列を解析し、[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time) を返します。

UTC オフセットはサポートされていません; もし `value` がそれを記述している場合、結果は `None` です。

#### `parse_datetime(value)`

文字列を解析し、[`datetime.datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) を返します。

UTC オフセットに対応しています。もし `value` がそれを記述している場合、結果の `tzinfo` 属性は [`datetime.timezone`](https://docs.python.org/3/library/datetime.html#datetime.timezone) インスタンスになります。

#### `parse_duration(value)`

文字列を解析し、 [`datetime.timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta) を返します。

データは、 `"DD HH:MM:SS.uuuuuu"` 、 `"DD HH:MM:SS,uuuuuu"` の形式、または ISO 8601 で指定された形式 (例えば、`P4DT1H15M20S` は `4 1:15:20` に相当) や PostgreSQL の日時間隔形式 (例えば、`3 days 04:05:06`) であることを期待します。

> **Years and months not supported**
>
> ISO 8601 years (`Y`) and months (`M`) are unsupported as they
> cannot be represented by [`timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta).

> **Changed in Django 6.1**
>
> ISO 8601 duration parsing now supports weeks (`PnW`).

## `django.utils.decorators`

#### `method_decorator(decorator, name='')`

関数デコレータをメソッドデコレータに変換します。これは、メソッドまたはクラスをデコレートするのに使用できます。後者の場合、 `name` はデコレートされるメソッドの名前であり、必須です。

`decorator` は関数のリストまたはタプルでも構いません。それらは逆順でラップされるため、呼び出しの順序は関数がリスト/タプル内に登場する順序となります。

使用方法の例については、 [クラスベースビューのデコレート](/ja/6.1/topics/class-based-views/intro/#id1) を参照してください。

#### `decorator_from_middleware(middleware_class)`

ミドルウェアクラスが与えられた場合、ビューデコレータを返します。これにより、ミドルウェアの機能をビューごとに使用できます。ミドルウェアは、パラメータを渡さずに作成されます。

これは、Django 1.9以前の古いスタイルと互換性のあるミドルウェアを想定しています（`process_request()`, `process_exception()`, `process_response()` のようなメソッドを持っている）。

#### `decorator_from_middleware_with_args(middleware_class)`

`decorator_from_middleware` と似ていますが、`middleware_class` に渡す引数を受け入れる関数を返します。例えば、[`cache_page()`](/ja/6.1/topics/cache/#django.views.decorators.cache.cache_page) デコレータは `CacheMiddleware` からこのように作成されます：

```
cache_page = decorator_from_middleware_with_args(CacheMiddleware)

@cache_page(3600)
def my_view(request):
    pass
```

#### `sync_only_middleware(middleware)`

ミドルウェアを [同期専用](/ja/6.1/topics/http/middleware/#async-middleware) としてマークします。(これはDjangoのデフォルトですが、将来的にデフォルトが変更された場合に備えて、あらかじめ設定しておくことを可能にします。)

#### `async_only_middleware(middleware)`

ミドルウェアを [非同期専用](/ja/6.1/topics/http/middleware/#async-middleware) としてマークします。WSGIリクエストパスから呼び出されたとき、Djangoはそれを非同期イベントループでラップします。

#### `sync_and_async_middleware(middleware)`

ミドルウェアを [同期および非同期互換](/ja/6.1/topics/http/middleware/#async-middleware) としてマークすることで、リクエストの変換を避けることができます。このデコレータを使用するためには、現在のリクエストタイプの検出を実装する必要があります。詳細については、[非同期ミドルウェアのドキュメント](/ja/6.1/topics/http/middleware/#async-middleware) を参照してください。

## `django.utils.encoding`

#### `smart_str(s, encoding='utf-8', strings_only=False, errors='strict')`

任意のオブジェクト `s` を表す `str` オブジェクトを返します。バイトストリングは `encoding` コーデックを使用して処理します。

`strings_only` が `True` の場合、(いくつかの) 非文字列型オブジェクトを変換しないでください。

#### `is_protected_type(obj)`

オブジェクトインスタンスが保護された型であるかどうかを判断します。

`force_str(strings_only=True)` に渡された際に、保護された型のオブジェクトはそのまま保持されます。

#### `force_str(s, encoding='utf-8', strings_only=False, errors='strict')`

`smart_str()` に似ていますが、遅延インスタンスは遅延オブジェクトとして保持されるのではなく、文字列に変換されます。

`strings_only` が `True` の場合、(いくつかの) 非文字列型オブジェクトを変換しないでください。

#### `smart_bytes(s, encoding='utf-8', strings_only=False, errors='strict')`

任意のオブジェクト `s` を、 `encoding` で指定された方法でエンコードされたバイト文字列バージョンを返します。

`strings_only` が `True` の場合、(いくつかの) 非文字列型オブジェクトを変換しないでください。

#### `force_bytes(s, encoding='utf-8', strings_only=False, errors='strict')`

`smart_bytes` に似ていますが、遅延インスタンスは遅延オブジェクトとして保持されるのではなく、バイト文字列に解決されます。

`strings_only` が `True` の場合、(いくつかの) 非文字列型オブジェクトを変換しないでください。

#### `iri_to_uri(iri)`

国際化リソース識別子 (IRI) の一部を、URL に含めるのに適した URI の一部に変換します。

これは、入力が任意のバイトストリームではなく文字列であると仮定しているため、若干単純化された、セクション3.1の [**RFC 3987 Section 3.1**](https://datatracker.ietf.org/doc/html/rfc3987.html#section-3.1) のアルゴリズムです。

IRI (文字列または UTF-8 バイト) を取得し、エンコードされた結果を含む文字列を返します。

#### `uri_to_iri(uri)`

統一リソース識別子（URI）を国際化リソース識別子（IRI）に変換します。

これは [**RFC 3987 Section 3.2**](https://datatracker.ietf.org/doc/html/rfc3987.html#section-3.2) のセクション3.2からのアルゴリズムです。

ASCII バイトで表される URI を受け取り、エンコードされた結果を含む文字列を返します。

#### `filepath_to_uri(path)`

ファイルシステムのパスを、URLに含めるのに適したURI部分に変換します。パスは、UTF-8バイト、文字列、または [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) のいずれかであると想定されます。

This method will encode certain characters that would normally be
recognized as special characters for URIs. Note that this method does not
encode the ' character, as it is a valid character within URIs. See
`encodeURIComponent()` JavaScript function for more details.

エンコードされた結果を含む ASCII 文字列を返します。

#### `escape_uri_path(path)`

URI (Uniform Resource Identifier) のパス部分から安全でない文字をエスケープします。

## `django.utils.feedgenerator`

使用例：

```pycon
>>> from django.utils import feedgenerator
>>> feed = feedgenerator.Rss201rev2Feed(
...     title="Poynter E-Media Tidbits",
...     link="https://www.poynter.org/tag/e-media-tidbits/",
...     description="A group blog by the sharpest minds in online media/journalism/publishing.",
...     language="en",
... )
>>> feed.add_item(
...     title="Hello",
...     link="https://www.holovaty.com/test/",
...     description="Testing.",
... )
>>> with open("test.rss", "w") as fp:
...     feed.write(fp, "utf-8")
...
```

ジェネレータの選択を簡略化するには、現在は `Rss201rev2Feed` である `feedgenerator.DefaultFeed` を使用します。

For definitions of the different versions of RSS, see [The myth of RSS
compatibility](https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004/02/04/incompatible-rss).

#### `get_tag_uri(url, date)`

TagURI を作成します。

See [How to make a good ID in Atom](https://web.archive.org/web/20110514113830/http://diveintomark.org/archives/2004/05/28/howto-atom-id).

### `Stylesheet`

#### `class Stylesheet(url, mimetype='', media='screen')`

RSS スタイルシートを表します。

#### `url`

必須の引数です。スタイルシートが配置される URL を意味します。

#### `mimetype`

An optional string containing the MIME type of the stylesheet. If not
specified, Django will attempt to guess it by using Python's
[`mimetypes.guess_type()`](https://docs.python.org/3/library/mimetypes.html#mimetypes.guess_type). Use `mimetype=None` if you don't
want your stylesheet to have a MIME type specified.

#### `media`

スタイルシートの `media` 属性として使用される任意の文字列。デフォルトは `"screen"` です。 スタイルシートに `media` 属性を持たせたくない場合は、 `media=None` と指定してください。

### `SyndicationFeed`

#### `class SyndicationFeed`

すべての配信 (syndication) フィードの基底クラスです。サブクラスでは `write()` を提供すべきです。

#### `__init__(title, link, description, language=None, author_email=None, author_name=None, author_link=None, subtitle=None, categories=None, feed_url=None, feed_copyright=None, feed_guid=None, ttl=None, stylesheets=None, **kwargs)`

与えられたメタデータの辞書でフィードを初期化します。これはフィード全体に適用されます。

`__init__` に渡した追加のキーワード引数は、`self.feed` に格納されます。

以下の2つを除き、パラメータは文字列を指定してください。

- `categories` は文字列のシーケンスであるべきです。
- `stylesheets` には、文字列または [`Stylesheet`](#django.utils.feedgenerator.Stylesheet) インスタンスのいずれかのシーケンスを指定する必要があります。

#### `add_item(title, link, description, author_email=None, author_name=None, author_link=None, pubdate=None, comments=None, unique_id=None, categories=(), item_copyright=None, ttl=None, updateddate=None, enclosures=None, **kwargs)`

フィードにアイテムを追加します。すべての引数は文字列であることが前提ですが、 `pubdate` と `updateddate` は `datetime.datetime` オブジェクトであり、 `enclosures` は `Enclosure` インスタンスのリストです。

#### `num_items()`

#### `root_attributes()`

ルート (つまり、feed/channel) 要素に配置する追加の属性を返します。 `write()` から呼び出されます。

#### `add_root_elements(handler)`

ルート(つまり、feed/channel)要素に要素を追加します。`write()` から呼び出されます。

#### `add_stylesheets(self, handler)`

ドキュメントにスタイルシート情報を追加します。 `write()` から呼び出されます。

#### `item_attributes(item)`

各アイテム(つまり item/entry 要素)に配置するための追加属性を返します。

#### `add_item_elements(handler, item)`

各アイテム（すなわち、item/entry）要素に要素を追加します。

#### `write(outfile, encoding)`

指定されたエンコーディングでフィードを `outfile` に出力します。これはファイルライクオブジェクトです。サブクラスではこれをオーバーライドするべきです。

#### `writeString(encoding)`

指定されたエンコーディングでフィードを文字列として返します。

#### `latest_post_date()`

フィード内のすべてのアイテムの中で最新の `pubdate` または `updateddate` を返します。これらの属性を持つアイテムがない場合は、現在のUTC日付/時間を返します。

### `Enclosure`

#### `class Enclosure`

RSSエンクロージャを表します

### `RssFeed`

#### `class RssFeed(SyndicationFeed)`

### `Rss201rev2Feed`

#### `class Rss201rev2Feed(RssFeed)`

仕様: <https://cyber.harvard.edu/rss/rss.html>

### `RssUserland091Feed`

#### `class RssUserland091Feed(RssFeed)`

仕様: <http://backend.userland.com/rss091>

### `Atom1Feed`

#### `class Atom1Feed(SyndicationFeed)`

仕様: [**RFC 4287**](https://datatracker.ietf.org/doc/html/rfc4287.html)

## `django.utils.functional`

#### `class cached_property(func)`

`@cached_property` デコレータは、単一の `self` 引数を持つメソッドの結果をプロパティとしてキャッシュします。キャッシュされた結果はインスタンスが存在する限り永続しますので、インスタンスが渡され、その後関数が呼び出された場合、キャッシュされた結果が返されます。

典型的なケースを考えてみましょう。ビューがモデルのメソッドを呼び出して計算を行った後に、テンプレートが再度メソッドを呼び出してモデルインスタンスをコンテキストに配置することがあるでしょう。

```
# the model
class Person(models.Model):
    def friends(self):
        # expensive computation
        ...
        return friends

# in the view:
if person.friends():
    ...
```

テンプレートは次のように記述します。

```html+django
{% for friend in person.friends %}
```

この場合、 `friends()` が2回呼び出されます。ビューとテンプレートのインスタンス `person` は同一なので、 `friends()` メソッドに `@cached_property` をつけることで、呼び出しの重複を回避できます。

```
from django.utils.functional import cached_property

class Person(models.Model):
    @cached_property
    def friends(self): ...
```

なお、メソッドがプロパティになったため、Pythonのコードからのアクセスが変わっていることに注意してください。

```
# in the view:
if person.friends:
    ...
```

キャッシュされた値は、インスタンスの通常の属性のように扱うことができます。

```
# clear it, requiring re-computation next time it's called
person.__dict__.pop("friends", None)

# set a value manually, that will persist on the instance until cleared
person.friends = ["Huckleberry Finn", "Tom Sawyer"]
```

Because of the way the [descriptor protocol](https://docs.python.org/3/reference/datamodel.html#descriptor-invocation) works, using `del` (or `delattr`) on a
`cached_property` that hasn't been accessed raises `AttributeError`.

`@cached_property` はパフォーマンスの利点をもたらすだけでなく、属性の値がインスタンスが有効なうちに予期せず変更されないことも保証します。これは、 `datetime.now()` に基づいて計算されるメソッドや、同一のインスタンスのメソッドを呼び出している間に他のプロセスによって変更がデータベースに保存された場合などに発生する可能性があります。

また、メソッドのキャッシュされたプロパティを作成することもできます。たとえば、高コストな `get_friends()` メソッドを持っており、キャッシュされた値を取得せずに呼び出すことを許可したい場合、次のように記述できます。

```
friends = cached_property(get_friends)
```

`person.get_friends()` を呼び出すたびに `friends` は再計算されますが、キャッシュされたプロパティの値は、上記の説明に従って削除するまで永続します。

```
x = person.friends  # calls first time
y = person.get_friends()  # calls again
z = person.friends  # does not call
x is z  # is True
```

#### `class classproperty(method=None)`

Similar to [`@classmethod`](https://docs.python.org/3/library/functions.html#classmethod), the `@classproperty`
decorator converts the result of a method with a single `cls` argument
into a property that can be accessed directly from the class.

#### `keep_lazy(func, *resultclasses)`

Djangoでは、文字列を最初の引数として受け取り、その文字列に何らかの処理を行う多くのユーティリティ関数を（特に `django.utils` において）提供しています。これらの関数は、テンプレートフィルタや他のコード内で直接使用されます。

独自の類似機能を書いて、翻訳を扱う際に、最初の引数が遅延評価の翻訳オブジェクトだった場合に何をすべきかという問題に直面します。この機能がビューの外部で使用される可能性があるため(その場合、現在のスレッドのロケール設定が正しくない可能性があります)、すぐに文字列に変換したくないでしょう。

このような場合には、`django.utils.functional.keep_lazy()` デコレータを使用してください。これは、関数が引数の1つとして遅延評価される翻訳を持つ場合に、関数の評価を文字列に変換する必要があるまで遅らせるように変更します。

例:

```
from django.utils.functional import keep_lazy, keep_lazy_text

def fancy_utility_function(s, *args, **kwargs):
    # Do some conversion on string 's'
    ...

fancy_utility_function = keep_lazy(str)(fancy_utility_function)

# Or more succinctly:
@keep_lazy(str)
def fancy_utility_function(s, *args, **kwargs): ...
```

`keep_lazy()` デコレータは、オリジナルの関数が返すことができる型を指定するための追加引数 (`*args`) を受け取ります。一般的な使用例は、テキストを返す関数を持つ場合です。これには、`str` 型を `keep_lazy` に渡すことができます(または、次のセクションで説明されている [`keep_lazy_text()`](#django.utils.functional.keep_lazy_text) デコレータを使用します)。

このデコレータを使用すると、入力が適切な文字列であると仮定して関数を書き、最後に遅延翻訳オブジェクトのサポートを追加できます。

#### `keep_lazy_text(func)`

`keep_lazy(str)(func)` のショートカットです。

テキストを返す関数があり、引数の評価を遅延させつつ、遅延引数を取ることができるようにしたい場合は、このデコレータを使用できます：

```
from django.utils.functional import keep_lazy, keep_lazy_text

# Our previous example was:
@keep_lazy(str)
def fancy_utility_function(s, *args, **kwargs): ...

# Which can be rewritten as:
@keep_lazy_text
def fancy_utility_function(s, *args, **kwargs): ...
```

## `django.utils.html`

通常、Djangoの自動エスケープ機構を利用するために、Djangoのテンプレートを使用してHTMLを構築するべきです。適切な場合には、 [`django.utils.safestring`](#module-django.utils.safestring) のユーティリティを使用します。このモジュールは、HTMLをエスケープするためのいくつかの追加の低レベルユーティリティを提供します。

#### `escape(text)`

与えられたテキストに対して、HTMLで使うためにアンパサンド、引用符、および山括弧をエンコードします。入力は最初に文字列に強制され、出力には [`mark_safe()`](#django.utils.safestring.mark_safe) が適用されます。

#### `conditional_escape(text)`

Similar to `escape()`, except that it doesn't operate on pre-escaped
strings, so it will not double escape.

#### `format_html(format_string, *args, **kwargs)`

これは [`str.format()`](https://docs.python.org/3/library/stdtypes.html#str.format) に似ていますが、HTML フラグメントを組み立てるのに適しています。最初の引数 `format_string` はエスケープされませんが、その他の引数とキーワード引数はすべて [`conditional_escape()`](#django.utils.html.conditional_escape) を通してから `str.format()` に渡されます。最終的に、出力には [`mark_safe()`](#django.utils.safestring.mark_safe) が適用されます。

小さなHTML断片を構築する場合、この関数は文字列補間の `%` や `str.format()` を直接利用するよりも望まれます。なぜなら、この関数はテンプレートシステムと同様に、全ての引数にエスケープ処理を適用するからです。

そのため、以下のように書く代わりに：

```
mark_safe(
    "%s <b>%s</b> %s"
    % (
        some_html,
        escape(some_text),
        escape(some_other_text),
    )
)
```

次のものを使用すべきです:

```
format_html(
    "{} <b>{}</b> {}",
    mark_safe(some_html),
    some_text,
    some_other_text,
)
```

これは、各引数に対して [`escape()`](#django.utils.html.escape) を適用する必要がなく、1つを忘れた場合にバグや XSS 脆弱性が発生するリスクがないという利点があります。

この関数は `str.format()` を使用して補間を行いますが、 `str.format()` が提供する一部の書式設定オプション（例えば数値の書式設定など）は機能しないことに注意してください。なぜなら、すべての引数が [`conditional_escape()`](#django.utils.html.conditional_escape) を介して渡され、これが最終的に [`force_str()`](#django.utils.encoding.force_str) を値に対して呼び出すためです。

#### `format_html_join(sep, format_string, args_generator)`

[`format_html()`](#django.utils.html.format_html) のラッパーで、同じフォーマット文字列を使用してフォーマットする必要がある引数のグループと、`sep` を使用して結合する一般的なケースのためのものです。`sep` も [`conditional_escape()`](#django.utils.html.conditional_escape) を通して渡されます。

`args_generator` は、[`format_html()`](#django.utils.html.format_html) に渡す引数を生成するイテレータである必要があります。生成する値は、位置引数のシーケンスか、キーワード引数のマッピングのいずれかです。

例えば、タプルは位置引数として使用されます。

```
format_html_join(
    "\n",
    "<li>{} {}</li>",
    ((u.first_name, u.last_name) for u in users),
)
```

辞書はキーワード引数として使用されます。

```
format_html_join(
    "\n",
    '<li data-id="{id}">{id} {title}</li>',
    ({"id": b.id, "title": b.title} for b in books),
)
```

#### `json_script(value, element_id=None, encoder=None)`

すべてのHTML/XML特殊文字をそのユニコードエスケープでエスケープするため、値はJavaScriptでの使用に安全です。エスケープされたJSONを `<script>` タグでラップします。 `element_id` パラメータが `None` でない場合、`<script>` タグに渡されたidが与えられます。例えば：

```pycon
>>> json_script({"hello": "world"}, element_id="hello-data")
'<script id="hello-data" type="application/json">{"hello": "world"}</script>'
```

`encoder` のデフォルトは [`django.core.serializers.json.DjangoJSONEncoder`](/ja/6.1/topics/serialization/#django.core.serializers.json.DjangoJSONEncoder) で、このエンコーダーがデータのシリアライズに使用されます。このシリアライザについての詳細は、[JSON のシリアライズ](/ja/6.1/topics/serialization/#serialization-formats-json) を参照してください。

#### `strip_tags(value)`

文字列から `<>` で囲まれた、HTML タグのように見えるものをすべて除去しようとします。

生成される文字列が HTML セーフであることについては、 **絶対に** 保証されません。したがって、たとえば [`escape()`](#django.utils.html.escape) でエスケープするなどの処理を行わずに、 `strip_tags` 呼び出しの結果を決してセーフと扱ってはいけません。

例:

```
strip_tags(value)
```

`value` が `"<b>Joel</b> <button>is</button> a <span>slug</span>"` の場合、戻り値は `"Joel is a slug"` になります。

より堅牢なソリューションを探している場合は、サードパーティ製のHTMLサニタイジングツールの使用を検討してください。

#### `html_safe()`

クラス上の `__html__()` メソッドは、HTMLエスケープが必要ないクラスの出力を非Djangoテンプレートが検出するのに役立ちます。

このデコレータは、装飾されたクラスに `__str__()` を [`mark_safe()`](#django.utils.safestring.mark_safe) でラッピングし、 `__html__()` メソッドを定義します。 `__str__()` メソッドが HTML エスケープを必要としないテキストを確かに返すことを保証してください。

## `django.utils.http`

#### `urlencode(query, doseq=False)`

Python の [`urllib.parse.urlencode()`](https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urlencode) 関数のバージョンで、`MultiValueDict` や非文字列値に対して操作を行うことができます。

#### `http_date(epoch_seconds=None)`

[**RFC 1123 Section 5.2.14**](https://datatracker.ietf.org/doc/html/rfc1123.html#section-5.2.14) にて指定されている通り、HTTP [**RFC 9110 Section 5.6.7**](https://datatracker.ietf.org/doc/html/rfc9110.html#section-5.6.7) の日付フォーマットに合わせて時間をフォーマットします。

UTC(協定世界時)でのエポックからの秒数で表された浮動小数点数を受け入れます。例えば、 `time.time()` によって出力されるものです。`None` に設定された場合、デフォルトでは現在時刻になります。

次の形式で文字列を出力します: `Wdy, DD Mon YYYY HH:MM:SS GMT` 。

#### `content_disposition_header(as_attachment, filename)`

[**RFC 6266**](https://datatracker.ietf.org/doc/html/rfc6266.html) に指定された `filename` から `Content-Disposition` HTTPヘッダー値を構築します。 `as_attachment` が `False` でかつ `filename` が `None` の場合は `None` を返し、それ以外の場合は `Content-Disposition` HTTPヘッダーに適した文字列を返します。

#### `base36_to_int(s)`

base36 文字列を整数に変換します。

#### `int_to_base36(i)`

正の整数を base36 文字列に変換します。

#### `urlsafe_base64_encode(s)`

URLで使用するためにバイト文字列を base64 文字列にエンコードし、末尾の等号を削除します。

#### `urlsafe_base64_decode(s)`

base64エンコードされた文字列をデコードし、削除されたかもしれない末尾の等号を追加します。

## `django.utils.module_loading`

Python モジュールを扱うための関数です。

#### `import_string(dotted_path)`

ドットで区切られたモジュールパスをインポートし、パスの最後の名前で指定された属性・クラスを返します。インポートが失敗した場合は `ImportError` を発生させます。例えば：

```
from django.utils.module_loading import import_string

ValidationError = import_string("django.core.exceptions.ValidationError")
```

これは以下と同じです:

```
from django.core.exceptions import ValidationError
```

## `django.utils.safestring`

HTML でさらにエスケープする必要なく安全に表示できる「安全な文字列（safe strings）」を扱うための関数とクラス。何かを「安全な文字列」としてマークするということは、文字列の生成者が HTML エンジンによって解釈されるべきでない文字（例えば '\<' ）を適切なエンティティに変換済みであることを意味します。

#### `class SafeString`

HTML出力の目的で「安全」として明示的にマークされた（これ以上のエスケープが必要ない） `str` のサブクラスです。

#### `mark_safe(s)`

文字列を (HTML) 出力目的で安全であると明示的にマークします。返されたオブジェクトは、文字列が適切な場所であればどこでも使用できます。

単一の文字列に対して複数回呼び出すことができます。

デコレータとしても使用できます。

HTMLの断片を組み立てる際には、通常、 [`django.utils.html.format_html()`](#django.utils.html.format_html) を使用するべきです。

マークされた文字列を安全としても、変更されると再び安全でなくなります。例えば：

```pycon
>>> mystr = "<b>Hello World</b>   "
>>> mystr = mark_safe(mystr)
>>> type(mystr)
<class 'django.utils.safestring.SafeString'>

>>> mystr = mystr.strip()  # removing whitespace
>>> type(mystr)
<type 'str'>
```

## `django.utils.text`

#### `format_lazy(format_string, *args, **kwargs)`

`format_string`、`args`、または `kwargs` に遅延オブジェクトが含まれている場合の [`str.format()`](https://docs.python.org/3/library/stdtypes.html#str.format) のバージョンです。最初の引数は、フォーマットされる文字列です。例えば：

```
from django.utils.text import format_lazy
from django.utils.translation import pgettext_lazy

urlpatterns = [
    path(
        format_lazy("{person}/<int:pk>/", person=pgettext_lazy("URL", "person")),
        PersonDetailView.as_view(),
    ),
]
```

この例では、翻訳機がURLの一部を翻訳できます。"person" を "persona" に翻訳した場合、正規表現は `persona/(?P<pk>\d+)/$` に一致します。例えば、`persona/5/` のようになります。

#### `slugify(value, allow_unicode=False)`

下記によって文字列をURLスラグに変換します:

1. `allow_unicode` が `False` （デフォルト）の場合、ASCII に変換します。
2. 小文字に変換します。
3. 英数字、アンダースコア、ハイフン、空白以外の文字を削除します。
4. 空白や繰り返されるダッシュを単一のダッシュに置き換えます。
5. 先頭と末尾の空白、ダッシュ、アンダースコアを削除します。

例:

```pycon
>>> slugify(" Joel is a slug ")
'joel-is-a-slug'
```

Unicode 文字を許可したい場合は、`allow_unicode=True` を渡します。例えば：

```pycon
>>> slugify("你好 World", allow_unicode=True)
'你好-world'
```

## `django.utils.timezone`

#### `get_fixed_timezone(offset)`

UTCからの固定オフセットを持つタイムゾーンを表す [`tzinfo`](https://docs.python.org/3/library/datetime.html#datetime.tzinfo) インスタンスを返します。

`offset` は [`datetime.timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta) または整数の分数です。UTCより東のタイムゾーンには正の値を、西には負の値を使用してください。

#### `get_default_timezone()`

[デフォルトのタイムゾーン](/ja/6.1/topics/i18n/timezones/#default-current-time-zone) を表す [`tzinfo`](https://docs.python.org/3/library/datetime.html#datetime.tzinfo) インスタンスを返します。

#### `get_default_timezone_name()`

[デフォルトタイムゾーンとカレントタイムゾーン](/ja/6.1/topics/i18n/timezones/#default-current-time-zone) の名前を返します。

#### `get_current_timezone()`

カレントタイムゾーンを表す [`tzinfo`](https://docs.python.org/3/library/datetime.html#datetime.tzinfo) インスタンスを返します。 [カレントタイムゾーン](/ja/6.1/topics/i18n/timezones/#default-current-time-zone) を参照してください。

#### `get_current_timezone_name()`

[カレントタイムゾーン](/ja/6.1/topics/i18n/timezones/#default-current-time-zone) の名前を返します。

#### `activate(timezone)`

カレントタイムゾーンを [設定します](/ja/6.1/topics/i18n/timezones/#default-current-time-zone) 。 `timezone` 引数は、 [`tzinfo`](https://docs.python.org/3/library/datetime.html#datetime.tzinfo) のサブクラスのインスタンスまたはタイムゾーン名でなければなりません。

#### `deactivate()`

[カレントタイムゾーン](/ja/6.1/topics/i18n/timezones/#default-current-time-zone) を未設定にします。

#### `override(timezone)`

This is a Python context manager that sets the [current time zone](/ja/6.1/topics/i18n/timezones/#default-current-time-zone) on entry with [`activate()`](#django.utils.timezone.activate), and restores
the previously active time zone on exit. If the `timezone` argument is
`None`, the [current time zone](/ja/6.1/topics/i18n/timezones/#default-current-time-zone) is unset
on entry with [`deactivate()`](#django.utils.timezone.deactivate) instead.

`override` は関数デコレータとしても使用できます。

#### `localtime(value=None, timezone=None)`

aware な [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) を、デフォルトでは [カレントタイムゾーン](/ja/6.1/topics/i18n/timezones/#default-current-time-zone) へと変換します。

`value` が省略された場合, デフォルトは [`now()`](#django.utils.timezone.now) になります。

この関数は naive な日時には機能しません。代わりに [`make_aware()`](#django.utils.timezone.make_aware) を使用してください。

#### `localdate(value=None, timezone=None)`

[`localtime()`](#django.utils.timezone.localtime) を使用して、指定された [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) を異なるタイムゾーンの [`date()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.date) に変換し、デフォルトでは [カレントタイムゾーン](/ja/6.1/topics/i18n/timezones/#default-current-time-zone) を使用します。

`value` が省略された場合, デフォルトは [`now()`](#django.utils.timezone.now) になります。

この関数は naive な日時には機能しません。

#### `now()`

現在の時刻を表す [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) を返します。返される内容は [`USE_TZ`](/ja/6.1/ref/settings/#std-setting-USE_TZ) の値によって異なります。

- [`USE_TZ`](/ja/6.1/ref/settings/#std-setting-USE_TZ) が `False` の場合、システムのローカルタイムゾーンで現在の時刻を表す、関連するタイムゾーンのない [naive](/ja/6.1/topics/i18n/timezones/#naive-vs-aware-datetimes) な日時（タイムゾーンの関連がない日時）になります。
- [`USE_TZ`](/ja/6.1/ref/settings/#std-setting-USE_TZ) が `True` の場合、 UTC の現在時刻を表す [aware](/ja/6.1/topics/i18n/timezones/#naive-vs-aware-datetimes) な日時になります。 [`now()`](#django.utils.timezone.now) は常に [`TIME_ZONE`](/ja/6.1/ref/settings/#std-setting-TIME_ZONE) の値に関係なく UTC の時刻を返すことに注意してください。カレントタイムゾーンの時刻を取得するには [`localtime()`](#django.utils.timezone.localtime) を使用します。

#### `is_aware(value)`

`value` が "aware" であれば `True` を、"naive" であれば `False` を返します。この関数は `value` が [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) であると仮定します。

#### `is_naive(value)`

`value` が naive である場合は `True` を aware である場合は `False` を返します。この関数は `value` が [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) であると仮定します。

#### `make_aware(value, timezone=None)`

`value` が naive な [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) であるとき、`timezone` 内での同じ時点を表す aware な [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) を返します。`timezone` が `None` に設定されている場合、デフォルトで [カレントタイムゾーン](/ja/6.1/topics/i18n/timezones/#default-current-time-zone) になります。

#### `make_naive(value, timezone=None)`

`timezone` で指定されたタイムゾーンにおいて、aware な [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) である `value` と同じ時点を表す naive な [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) を返します。 `timezone` が `None` に設定されている場合、デフォルトで [カレントタイムゾーン](/ja/6.1/topics/i18n/timezones/#default-current-time-zone) に設定されます。

## `django.utils.translation`

以下の使い方の完全な説明は、[翻訳ドキュメント](/ja/6.1/topics/i18n/translation/) を参照してください。

#### `gettext(message)`

`message` を翻訳し、文字列として返します。

#### `pgettext(context, message)`

`context` を考慮して `message` を翻訳し、文字列として返します。

詳しくは [文脈マーカー](/ja/6.1/topics/i18n/translation/#contextual-markers) を参照してください。

#### `gettext_lazy(message)`

#### `pgettext_lazy(context, message)`

上述の lazy ではないものと同じですが、遅延処理を使用します。

[遅延翻訳のドキュメント](/ja/6.1/topics/i18n/translation/#lazy-translations) を参照してください。

#### `gettext_noop(message)`

翻訳用に文字列をマークしますが、この段階では翻訳しません。(外部で使われる可能性があるため) ベースの言語のままにする必要があるグローバル変数に文字列を保持するために使えます。そして、後の時点で翻訳します。

#### `ngettext(singular, plural, number)`

`number` に基づいて、`singular` と `plural` を翻訳し、適切な文字列を返します。

#### `npgettext(context, singular, plural, number)`

`singular` と `plural` を翻訳し、`number` と `context` に基づいて適切な文字列を返します。

#### `ngettext_lazy(singular, plural, number)`

#### `npgettext_lazy(context, singular, plural, number)`

上述の lazy ではないものと同じですが、遅延処理を使用します。

[遅延翻訳のドキュメント](/ja/6.1/topics/i18n/translation/#lazy-translations) を参照してください。

#### `activate(language)`

渡された language に対して翻訳オブジェクトを取り出し、現在のスレッドに対してカレント翻訳オブジェクトとして有効化します。

#### `deactivate()`

カレント翻訳オブジェクトを無効化し、さらなる \_ 呼び出しが再びデフォルトの翻訳オブジェクトに対して解決するようにします。

#### `deactivate_all()`

アクティブな翻訳オブジェクトを `NullTranslations()` のインスタンスにします。何らかの理由で遅延された翻訳を元の文字列で表示したいときに役立ちます。

#### `override(language, deactivate=False)`

指定された言語の翻訳オブジェクトを取得するために [`django.utils.translation.activate()`](#django.utils.translation.activate) を使用し、現在のスレッドの翻訳オブジェクトとしてそれを有効化し、終了時に以前のアクティブな言語を再有効化する Python のコンテキストマネージャです。オプションで、 `deactivate` 引数が `True` である場合に限り、終了時に一時的な翻訳を無効化するために [`django.utils.translation.deactivate()`](#django.utils.translation.deactivate) を使用できます。言語引数として `None` を渡すと、コンテキスト内で `NullTranslations()` インスタンスが有効化されます。

`override` は関数デコレータとしても使用できます。

#### `check_for_language(lang_code)`

与えられた言語コード (たとえば 'fr' や 'pt\_BR') に対するグローバル言語ファイルが存在するかどうかをチェックします。ユーザーが提供する言語が有効かどうかを決めるために使われます。

`lang_code` has a maximum accepted length of 500 characters. `False`
is returned if it exceeds this limit, before any language-file lookup.

#### `get_language()`

Returns the currently selected language code. Returns `None` if
translations are temporarily deactivated (by [`deactivate_all()`](#django.utils.translation.deactivate_all) or
when `None` is passed to [`override()`](#django.utils.translation.override)).

#### `get_language_bidi()`

選択中の言語の BiDi レイアウトを返します:

- `False` = 左から右へのレイアウト
- `True` = 右から左へのレイアウト

#### `get_language_from_request(request, check_path=False)`

リクエストを分析して、ユーザがシステムにどの言語を表示させたいかを明らかにします。settings.LANGUAGES にリストアップされている言語のみが考慮されます。ユーザが主言語の他に副言語をリクエストする場合は、主言語が送信されます。

`check_path` が `True` の場合、関数はまず、パスが [`LANGUAGES`](/ja/6.1/ref/settings/#std-setting-LANGUAGES) 設定にリストアップされた言語コードで始まるかどうか、リクエストされた URL をチェックします。

#### `get_supported_language_variant(lang_code, strict=False)`

もし `lang_code` が [`LANGUAGES`](/ja/6.1/ref/settings/#std-setting-LANGUAGES) 設定内に存在していれば `lang_code` を返し、もっと一般的なバリアントを選択する可能性があります。例えば、`lang_code` が `'es-ar'` で、`'es-ar'` は [`LANGUAGES`](/ja/6.1/ref/settings/#std-setting-LANGUAGES) 内にはないが `'es'` は存在する場合、`'es'` が返されます。

`lang_code` には最大500文字までの長さ制限があります。 `lang_code` がこの制限を超え、`strict` が `True` の場合、または汎用バリアントが存在せず、`strict` が `False` の場合、 [`LookupError`](https://docs.python.org/3/library/exceptions.html#LookupError) が発生します。

`strict` が `False` (デフォルト) の場合、言語コードもその一般的なバリアントも見つからないときに、国別のバリアントが返されることがあります。たとえば、[`LANGUAGES`](/ja/6.1/ref/settings/#std-setting-LANGUAGES) に `'es-co'` のみが含まれている場合、その国別バリアントは `lang_code` が `'es'` や `'es-ar'` のような場合に返されます。これらのマッチは `strict=True` の場合には返されません。

何も見つからない場合、[`LookupError`](https://docs.python.org/3/library/exceptions.html#LookupError) を発生させます。

#### `to_locale(language)`

言語の名前 (en-us) をロケール名 (en\_US) に変換します。

#### `templatize(src)`

Django テンプレートを `xgettext` によって理解されるものに変更します。Django 翻訳タグを標準的な `gettext` 関数の文に変換することによって行われます。