Django ユーティリティ (django.utils)

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

django.utils.cache

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

Vary ヘッダーについての詳細は、 RFC 9110 Section 12.5.5 を参照してください。

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

たとえば、国際化のためのミドルウェア は、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 の値が使用されます。

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 に従い 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 モジュールにある対応するクラスからオブジェクトを返します。

• 入力が適切にフォーマットされているが、有効な日付や時刻ではない場合、 ValueError を発生させます。

• それが全く適切にフォーマットされていない場合、 None を返します。

• 入力ではピコ秒単位まで受け付けますが、Pythonがサポートしているマイクロ秒単位に切り捨てられます。

parse_date(value)[ソース]

文字列を解析し、datetime.date を返します。

parse_time(value)[ソース]

文字列を解析し、datetime.time を返します。

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

parse_datetime(value)[ソース]

文字列を解析し、datetime.datetime を返します。

UTC オフセットに対応しています。もし value がそれを記述している場合、結果の tzinfo 属性は datetime.timezone インスタンスになります。

parse_duration(value)[ソース]

文字列を解析し、 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) であることを期待します。

django.utils.decorators

method_decorator(decorator, name='')[ソース]

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

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

使用方法の例については、 クラスベースビューのデコレート を参照してください。

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() デコレータは CacheMiddleware からこのように作成されます：

cache_page = decorator_from_middleware_with_args(CacheMiddleware)


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

sync_only_middleware(middleware)[ソース]

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

async_only_middleware(middleware)[ソース]

ミドルウェアを 非同期専用 としてマークします。WSGIリクエストパスから呼び出されたとき、Djangoはそれを非同期イベントループでラップします。

sync_and_async_middleware(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 のアルゴリズムです。

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

uri_to_iri(uri)[ソース]

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

これは RFC 3987 Section 3.2 のセクション3.2からのアルゴリズムです。

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

filepath_to_uri(path)[ソース]

ファイルシステムのパスを、URLに含めるのに適したURI部分に変換します。パスは、UTF-8バイト、文字列、または Path のいずれかであると想定されます。

このメソッドは、通常URIの特別な文字として認識される特定の文字をエンコードします。このメソッドは、URI内で有効な文字であるため、「'」文字をエンコードしないことに注意してください。詳細については、 encodeURIComponent() JavaScript関数をご覧ください。

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

escape_uri_path(path)[ソース]

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

django.utils.feedgenerator

使用例：

>>> 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 を使用します。

異なるバージョンのRSSの定義については、こちらを参照してください: https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004/02/04/incompatible-rss

get_tag_uri(url, date)[ソース]

TagURI を作成します。

参考: https://web.archive.org/web/20110514113830/http://diveintomark.org/archives/2004/05/28/howto-atom-id

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, **kwargs)[ソース]

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

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

すべてのパラメータは文字列でなければなりませんが、 categories のみ文字列のシーケンスであるべきです。

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() から呼び出されます。

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

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():
    ...

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

{% 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
del person.friends  # or delattr(person, "friends")

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

descriptor protocol の挙動の都合で、アクセスされていない cached_property に対して del （または delattr ）を使用すると 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)[ソース]

@classmethod と同様に、 @classproperty デコレータは単一の cls 引数をもつメソッドの結果をクラスから直接アクセスできるプロパティに変換します。

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() デコレータを使用します)。

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

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 のユーティリティを使用します。このモジュールは、HTMLをエスケープするためのいくつかの追加の低レベルユーティリティを提供します。

escape(text)[ソース]

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

conditional_escape(text)[ソース]

escape() に似ていますが、事前にエスケープされた文字列には作用しないため、二重にエスケープすることはありません。

format_html(format_string, *args, **kwargs)[ソース]

これは str.format() に似ていますが、HTML フラグメントを組み立てるのに適しています。最初の引数 format_string はエスケープされませんが、その他の引数とキーワード引数はすべて conditional_escape() を通してから str.format() に渡されます。最終的に、出力には 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() を適用する必要がなく、1つを忘れた場合にバグや XSS 脆弱性が発生するリスクがないという利点があります。

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

バージョン 5.0 で非推奨: format_html() を引数やキーワード引数なしで呼び出すサポートは非推奨となりました。

format_html_join(sep, format_string, args_generator)[ソース]

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

args_generator は、format_html() に渡される args のシーケンスを返すイテレータであるべきです。例えば：

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

json_script(value, element_id=None, encoder=None)[ソース]

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

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

encoder のデフォルトは django.core.serializers.json.DjangoJSONEncoder で、このエンコーダーがデータのシリアライズに使用されます。このシリアライザについての詳細は、JSON のシリアライズ を参照してください。

strip_tags(value)[ソース]

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

結果の文字列がHTMLセーフであることについては、何の保証もありません。したがって、例えば escape() でエスケープするなどして最初に行わない限り、strip_tag 呼び出しの結果を安全とマークすることは絶対に行わないでください。

例:

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() でラッピングし、 __html__() メソッドを定義します。 __str__() メソッドが HTML エスケープを必要としないテキストを確かに返すことを保証してください。

django.utils.http

urlencode(query, doseq=False)[ソース]

Python の urllib.parse.urlencode() 関数のバージョンで、MultiValueDict や非文字列値に対して操作を行うことができます。

http_date(epoch_seconds=None)[ソース]

RFC 1123 Section 5.2.14 にて指定されている通り、HTTP RFC 9110 Section 5.6.7 の日付フォーマットに合わせて時間をフォーマットします。

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

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

content_disposition_header(as_attachment, filename)[ソース]

RFC 6266 に指定された 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() を使用するべきです。

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

>>> 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() のバージョンです。最初の引数は、フォーマットされる文字列です。例えば：

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. 先頭と末尾の空白、ダッシュ、アンダースコアを削除します。

例:

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

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

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

django.utils.timezone

get_fixed_timezone(offset)[ソース]

UTCからの固定オフセットを持つタイムゾーンを表す tzinfo インスタンスを返します。

offset は datetime.timedelta または整数の分数です。UTCより東のタイムゾーンには正の値を、西には負の値を使用してください。

get_default_timezone()[ソース]

デフォルトのタイムゾーン を表す tzinfo インスタンスを返します。

get_default_timezone_name()[ソース]

デフォルトタイムゾーンとカレントタイムゾーン の名前を返します。

get_current_timezone()[ソース]

カレントタイムゾーンを表す tzinfo インスタンスを返します。 カレントタイムゾーン を参照してください。

get_current_timezone_name()[ソース]

カレントタイムゾーン の名前を返します。

activate(timezone)[ソース]

カレントタイムゾーンを 設定します 。 timezone 引数は、 tzinfo のサブクラスのインスタンスまたはタイムゾーン名でなければなりません。

deactivate()[ソース]

カレントタイムゾーン を未設定にします。

override(timezone)[ソース]

これは、エントリ時に activate() を使用して カレントタイムゾーン を設定し、終了時に以前にアクティブだったタイムゾーンを復元する Python のコンテキストマネージャーです。もし timezone 引数が None である場合、エントリ時に deactivate() を使用して カレントタイムゾーン が解除されます。

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

localtime(value=None, timezone=None)[ソース]

aware な datetime を、デフォルトでは カレントタイムゾーン へと変換します。

value が省略された場合, デフォルトは now() になります。

この関数は naive な日時には機能しません。代わりに make_aware() を使用してください。

localdate(value=None, timezone=None)[ソース]

localtime() を使用して、指定された datetime を異なるタイムゾーンの date() に変換し、デフォルトでは カレントタイムゾーン を使用します。

value が省略された場合, デフォルトは now() になります。

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

now()[ソース]

現在の時刻を表す datetime を返します。返される内容は USE_TZ の値によって異なります。

• USE_TZ が False の場合、システムのローカルタイムゾーンで現在の時刻を表す、関連するタイムゾーンのない naive な日時（タイムゾーンの関連がない日時）になります。

• USE_TZ が True の場合、 UTC の現在時刻を表す aware な日時になります。 now() は常に TIME_ZONE の値に関係なく UTC の時刻を返すことに注意してください。カレントタイムゾーンの時刻を取得するには localtime() を使用します。

is_aware(value)[ソース]

value が "aware" であれば True を、"naive" であれば False を返します。この関数は value が datetime であると仮定します。

is_naive(value)[ソース]

value が naive である場合は True を aware である場合は False を返します。この関数は value が datetime であると仮定します。

make_aware(value, timezone=None)[ソース]

value が naive な datetime であるとき、timezone 内での同じ時点を表す aware な datetime を返します。timezone が None に設定されている場合、デフォルトで カレントタイムゾーン になります。

make_naive(value, timezone=None)[ソース]

timezone で指定されたタイムゾーンにおいて、aware な datetime である value と同じ時点を表す naive な datetime を返します。 timezone が None に設定されている場合、デフォルトで カレントタイムゾーン に設定されます。

django.utils.translation

以下の使い方の完全な説明は、翻訳ドキュメント を参照してください。

gettext(message)[ソース]

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

pgettext(context, message)[ソース]

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

詳しくは 文脈マーカー を参照してください。

gettext_lazy(message)

pgettext_lazy(context, message)

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

遅延翻訳のドキュメント を参照してください。

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 ではないものと同じですが、遅延処理を使用します。

遅延翻訳のドキュメント を参照してください。

activate(language)[ソース]

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

deactivate()[ソース]

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

deactivate_all()[ソース]

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

override(language, deactivate=False)[ソース]

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

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

check_for_language(lang_code)[ソース]

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

get_language()[ソース]

現在選択中の言語コードを返します。翻訳が (deactivate_all() や None が override() に渡されることによって) 一時的に無効化されている場合は None を返します。

get_language_bidi()[ソース]

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

• False = 左から右へのレイアウト

• True = 右から左へのレイアウト

get_language_from_request(request, check_path=False)[ソース]

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

check_path が True の場合、関数はまず、パスが LANGUAGES 設定にリストアップされた言語コードで始まるかどうか、リクエストされた URL をチェックします。

get_supported_language_variant(lang_code, strict=False)[ソース]

もし lang_code が LANGUAGES 設定内に存在していれば lang_code を返し、もっと一般的なバリアントを選択する可能性があります。例えば、lang_code が 'es-ar' で、'es-ar' は LANGUAGES 内にはないが 'es' は存在する場合、'es' が返されます。

lang_code has a maximum accepted length of 500 characters. A LookupError is raised if lang_code exceeds this limit and strict is True, or if there is no generic variant and strict is False.

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

何も見つからない場合、LookupError を発生させます。

Changed in Django 4.2.15:

In older versions, lang_code values over 500 characters were processed without raising a LookupError.

to_locale(language)[ソース]

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

templatize(src)[ソース]

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