django.utils)¶このドキュメントは、django.utils のすべての安定したモジュールを対象としています。django.utils 内のほとんどのモジュールは内部使用を目的としていることから、 内部リリース非推奨ポリシー に従い、以下に記載する内容のみが 安定版として提供され、また後方互換性を維持しています。
django.utils.cache¶このモジュールには、HTTPキャッシュの制御を補助するための関数が含まれています。これは、レスポンスの Vary ヘッダーを管理することによって行います。レスポンスオブジェクトのヘッダーを直接パッチするための関数や、そのヘッダーパッチを行うためのデコレータも含まれています。
Vary ヘッダーについての詳細は、 RFC 9110 Section 12.5.5 を参照してください。
基本的に、 Vary HTTPヘッダーは、キャッシュがキャッシュキーを構築する際に考慮すべきヘッダーを定義します。同一パスのリクエストであっても、 Vary で指定されたヘッダーの内容が異なる場合は、誤ったコンテンツの配信を防ぐために異なるキャッシュキーを取得する必要があります。
たとえば、国際化のためのミドルウェア は、Accept-language ヘッダーによってキャッシュを区別するようにしています。
この関数は、キーワード引数を Cache-Control ヘッダーに追加することで、ヘッダーをパッチします。変換する内容は以下の通りです。
すべてのキーワードパラメータ名を小文字に変換し、アンダースコアをハイフンに変換する
パラメータの値が True （実質的な真の値ではなく、正確に True ）である場合、ヘッダーにはパラメータ名のみを追加する
すべての他のパラメータは、その値に str() を適用した後に追加する
レスポンスのCache-Controlヘッダーから max-age を整数として返します（見つからなかった場合や整数でなかった場合は None を返します）。
与えられた HttpResponse オブジェクトに以下のような便利なヘッダーを追加します。
Expires
Cache-Control
それぞれのヘッダーは、未設定の場合にのみ追加されます。
cache_timeout は秒単位で指定します。デフォルトでは、 CACHE_MIDDLEWARE_SECONDS の値が使用されます。
Expires ヘッダーを現在の日付/時刻で設定します。
Cache-Control: max-age=0, no-cache, no-store, must-revalidate, private ヘッダーをレスポンスに追加し、ページがキャッシュされないように設定します。
それぞれのヘッダーは、未設定の場合にのみ追加されます。
与えられた HttpResponse オブジェクトに、 Vary ヘッダーを追加（または更新）します。 newheaders は、Vary に含まれるべきヘッダー名のリストです。ヘッダーにアスタリスクが含まれている場合、 RFC 9110 Section 12.5.5 に従い Vary ヘッダーは単一のアスタリスク '*' で構成されます。それ以外の場合、Vary の既存のヘッダーは削除されません。
リクエストのパスに基づいたキャッシュキーを返します。グローバルパスレジストリから考慮すべきヘッダーのリストを取得してそれを使用してキャッシュキーを構築するため、リクエストフェーズで使用できます。
ヘッダーリストが保存されていない場合、ページを再構築する必要があるので、この関数は None を返します。
レスポンスオブジェクトから、特定のリクエストパスに対してどのヘッダーを考慮する必要があるかを学習します。それらのヘッダーはグローバルパスレジストリに格納されるため、後からそのパスにアクセスした際には、レスポンスオブジェクト自体を構築することなく、どのヘッダーを考慮する必要があるかがわかります。ヘッダーはレスポンスの Vary ヘッダーで指定されますが、レスポンスの生成は防ぎたいでしょう。
キャッシュキー生成に使用するヘッダーのリストは、ページ自体と同じキャッシュ内に保存されています。キャッシュがあるデータを破棄する場合、Varyヘッダーとキャッシュキー生成に使用するヘッダーのリストを取得するために、レスポンスを構築する必要があります。
django.utils.dateparse¶このモジュールで定義された関数は、以下の特性を共有しています：
ISO 8601 日付/時刻形式の文字列（またはそれに近い代替形式）を受け付け、Python の datetime モジュールにある対応するクラスからオブジェクトを返します。
入力が適切にフォーマットされているが、有効な日付や時刻ではない場合、 ValueError を発生させます。
それが全く適切にフォーマットされていない場合、 None を返します。
入力ではピコ秒単位まで受け付けますが、Pythonがサポートしているマイクロ秒単位に切り捨てられます。
文字列を解析し、datetime.date を返します。
文字列を解析し、datetime.time を返します。
UTC オフセットはサポートされていません; もし value がそれを記述している場合、結果は None です。
文字列を解析し、datetime.datetime を返します。
UTC オフセットに対応しています。もし value がそれを記述している場合、結果の tzinfo 属性は datetime.timezone インスタンスになります。
文字列を解析し、 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¶関数デコレータをメソッドデコレータに変換します。これは、メソッドまたはクラスをデコレートするのに使用できます。後者の場合、 name はデコレートされるメソッドの名前であり、必須です。
decorator は関数のリストまたはタプルでも構いません。それらは逆順でラップされるため、呼び出しの順序は関数がリスト/タプル内に登場する順序となります。
使用方法の例については、 クラスベースビューのデコレート を参照してください。
ミドルウェアクラスが与えられた場合、ビューデコレータを返します。これにより、ミドルウェアの機能をビューごとに使用できます。ミドルウェアは、パラメータを渡さずに作成されます。
これは、Django 1.9以前の古いスタイルと互換性のあるミドルウェアを想定しています（process_request(), process_exception(), process_response() のようなメソッドを持っている）。
decorator_from_middleware と似ていますが、middleware_class に渡す引数を受け入れる関数を返します。例えば、cache_page() デコレータは CacheMiddleware からこのように作成されます：
cache_page = decorator_from_middleware_with_args(CacheMiddleware)
@cache_page(3600)
def my_view(request):
pass
ミドルウェアを 同期専用 としてマークします。(これはDjangoのデフォルトですが、将来的にデフォルトが変更された場合に備えて、あらかじめ設定しておくことを可能にします。)
ミドルウェアを 非同期専用 としてマークします。WSGIリクエストパスから呼び出されたとき、Djangoはそれを非同期イベントループでラップします。
ミドルウェアを 同期および非同期互換 としてマークすることで、リクエストの変換を避けることができます。このデコレータを使用するためには、現在のリクエストタイプの検出を実装する必要があります。詳細については、非同期ミドルウェアのドキュメント を参照してください。
django.utils.encoding¶任意のオブジェクト s を表す str オブジェクトを返します。バイトストリングは encoding コーデックを使用して処理します。
strings_only が True の場合、(いくつかの) 非文字列型オブジェクトを変換しないでください。
オブジェクトインスタンスが保護された型であるかどうかを判断します。
force_str(strings_only=True) に渡された際に、保護された型のオブジェクトはそのまま保持されます。
smart_str() に似ていますが、遅延インスタンスは遅延オブジェクトとして保持されるのではなく、文字列に変換されます。
strings_only が True の場合、(いくつかの) 非文字列型オブジェクトを変換しないでください。
任意のオブジェクト s を、 encoding で指定された方法でエンコードされたバイト文字列バージョンを返します。
strings_only が True の場合、(いくつかの) 非文字列型オブジェクトを変換しないでください。
smart_bytes に似ていますが、遅延インスタンスは遅延オブジェクトとして保持されるのではなく、バイト文字列に解決されます。
strings_only が True の場合、(いくつかの) 非文字列型オブジェクトを変換しないでください。
国際化リソース識別子 (IRI) の一部を、URL に含めるのに適した URI の一部に変換します。
これは、入力が任意のバイトストリームではなく文字列であると仮定しているため、若干単純化された、セクション3.1の RFC 3987 Section 3.1 のアルゴリズムです。
IRI (文字列または UTF-8 バイト) を取得し、エンコードされた結果を含む文字列を返します。
統一リソース識別子（URI）を国際化リソース識別子（IRI）に変換します。
これは RFC 3987 Section 3.2 のセクション3.2からのアルゴリズムです。
ASCII バイトで表される URI を受け取り、エンコードされた結果を含む文字列を返します。
ファイルシステムのパスを、URLに含めるのに適したURI部分に変換します。パスは、UTF-8バイト、文字列、または 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 文字列を返します。
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 を使用します。
For definitions of the different versions of RSS, see The myth of RSS compatibility.
Stylesheet¶RSS スタイルシートを表します。
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(). Use mimetype=None if you don't
want your stylesheet to have a MIME type specified.
スタイルシートの media 属性として使用される任意の文字列。デフォルトは "screen" です。 スタイルシートに media 属性を持たせたくない場合は、 media=None と指定してください。
Enclosure¶RssFeed¶Rss201rev2Feed¶RssUserland091Feed¶Atom1Feed¶django.utils.functional¶@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
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 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
Similar to @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.
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(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をエスケープするためのいくつかの追加の低レベルユーティリティを提供します。
与えられたテキストに対して、HTMLで使うためにアンパサンド、引用符、および山括弧をエンコードします。入力は最初に文字列に強制され、出力には mark_safe() が適用されます。
これは 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() を値に対して呼び出すためです。
format_html() のラッパーで、同じフォーマット文字列を使用してフォーマットする必要がある引数のグループと、sep を使用して結合する一般的なケースのためのものです。sep も conditional_escape() を通して渡されます。
args_generator は、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),
)
args_generator においてマッピングのサポートが追加されました。
すべての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 のシリアライズ を参照してください。
文字列から <> で囲まれた、HTML タグのように見えるものをすべて除去しようとします。
生成される文字列が HTML セーフであることについては、 絶対に 保証されません。したがって、たとえば escape() でエスケープするなどの処理を行わずに、 strip_tags 呼び出しの結果を決してセーフと扱ってはいけません。
例:
strip_tags(value)
value が "<b>Joel</b> <button>is</button> a <span>slug</span>" の場合、戻り値は "Joel is a slug" になります。
より堅牢なソリューションを探している場合は、サードパーティ製のHTMLサニタイジングツールの使用を検討してください。
クラス上の __html__() メソッドは、HTMLエスケープが必要ないクラスの出力を非Djangoテンプレートが検出するのに役立ちます。
このデコレータは、装飾されたクラスに __str__() を mark_safe() でラッピングし、 __html__() メソッドを定義します。 __str__() メソッドが HTML エスケープを必要としないテキストを確かに返すことを保証してください。
django.utils.http¶Python の urllib.parse.urlencode() 関数のバージョンで、MultiValueDict や非文字列値に対して操作を行うことができます。
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 。
django.utils.module_loading¶Python モジュールを扱うための関数です。
ドットで区切られたモジュールパスをインポートし、パスの最後の名前で指定された属性・クラスを返します。インポートが失敗した場合は 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 エンジンによって解釈されるべきでない文字（例えば '<' ）を適切なエンティティに変換済みであることを意味します。
文字列を (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_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/ のようになります。
下記によって文字列をURLスラグに変換します:
allow_unicode が False （デフォルト）の場合、ASCII に変換します。
小文字に変換します。
英数字、アンダースコア、ハイフン、空白以外の文字を削除します。
空白や繰り返されるダッシュを単一のダッシュに置き換えます。
先頭と末尾の空白、ダッシュ、アンダースコアを削除します。
例:
>>> slugify(" Joel is a slug ")
'joel-is-a-slug'
Unicode 文字を許可したい場合は、allow_unicode=True を渡します。例えば：
>>> slugify("你好 World", allow_unicode=True)
'你好-world'
django.utils.timezone¶UTCからの固定オフセットを持つタイムゾーンを表す tzinfo インスタンスを返します。
offset は datetime.timedelta または整数の分数です。UTCより東のタイムゾーンには正の値を、西には負の値を使用してください。
デフォルトのタイムゾーン を表す tzinfo インスタンスを返します。
デフォルトタイムゾーンとカレントタイムゾーン の名前を返します。
カレントタイムゾーンを表す tzinfo インスタンスを返します。 カレントタイムゾーン を参照してください。
カレントタイムゾーン の名前を返します。
カレントタイムゾーンを 設定します 。 timezone 引数は、 tzinfo のサブクラスのインスタンスまたはタイムゾーン名でなければなりません。
カレントタイムゾーン を未設定にします。
This is a Python context manager that sets the current time zone on entry with activate(), and restores
the previously active time zone on exit. If the timezone argument is
None, the current time zone is unset
on entry with deactivate() instead.
override は関数デコレータとしても使用できます。
aware な datetime を、デフォルトでは カレントタイムゾーン へと変換します。
value が省略された場合, デフォルトは now() になります。
この関数は naive な日時には機能しません。代わりに make_aware() を使用してください。
localtime() を使用して、指定された datetime を異なるタイムゾーンの date() に変換し、デフォルトでは カレントタイムゾーン を使用します。
value が省略された場合, デフォルトは now() になります。
この関数は naive な日時には機能しません。
value が "aware" であれば True を、"naive" であれば False を返します。この関数は value が datetime であると仮定します。
value が naive である場合は True を aware である場合は False を返します。この関数は value が datetime であると仮定します。
value が naive な datetime であるとき、timezone 内での同じ時点を表す aware な datetime を返します。timezone が None に設定されている場合、デフォルトで カレントタイムゾーン になります。
timezone で指定されたタイムゾーンにおいて、aware な datetime である value と同じ時点を表す naive な datetime を返します。 timezone が None に設定されている場合、デフォルトで カレントタイムゾーン に設定されます。
django.utils.translation¶以下の使い方の完全な説明は、翻訳ドキュメント を参照してください。
上述の lazy ではないものと同じですが、遅延処理を使用します。
遅延翻訳のドキュメント を参照してください。
翻訳用に文字列をマークしますが、この段階では翻訳しません。(外部で使われる可能性があるため) ベースの言語のままにする必要があるグローバル変数に文字列を保持するために使えます。そして、後の時点で翻訳します。
singular と plural を翻訳し、number と context に基づいて適切な文字列を返します。
上述の lazy ではないものと同じですが、遅延処理を使用します。
遅延翻訳のドキュメント を参照してください。
アクティブな翻訳オブジェクトを NullTranslations() のインスタンスにします。何らかの理由で遅延された翻訳を元の文字列で表示したいときに役立ちます。
指定された言語の翻訳オブジェクトを取得するために django.utils.translation.activate() を使用し、現在のスレッドの翻訳オブジェクトとしてそれを有効化し、終了時に以前のアクティブな言語を再有効化する Python のコンテキストマネージャです。オプションで、 deactivate 引数が True である場合に限り、終了時に一時的な翻訳を無効化するために django.utils.translation.deactivate() を使用できます。言語引数として None を渡すと、コンテキスト内で NullTranslations() インスタンスが有効化されます。
override は関数デコレータとしても使用できます。
与えられた言語コード (たとえば 'fr' や 'pt_BR') に対するグローバル言語ファイルが存在するかどうかをチェックします。ユーザーが提供する言語が有効かどうかを決めるために使われます。
Returns the currently selected language code. Returns None if
translations are temporarily deactivated (by deactivate_all() or
when None is passed to override()).
リクエストを分析して、ユーザがシステムにどの言語を表示させたいかを明らかにします。settings.LANGUAGES にリストアップされている言語のみが考慮されます。ユーザが主言語の他に副言語をリクエストする場合は、主言語が送信されます。
check_path が True の場合、関数はまず、パスが LANGUAGES 設定にリストアップされた言語コードで始まるかどうか、リクエストされた URL をチェックします。
もし lang_code が LANGUAGES 設定内に存在していれば lang_code を返し、もっと一般的なバリアントを選択する可能性があります。例えば、lang_code が 'es-ar' で、'es-ar' は LANGUAGES 内にはないが 'es' は存在する場合、'es' が返されます。
lang_code には最大500文字までの長さ制限があります。 lang_code がこの制限を超え、strict が True の場合、または汎用バリアントが存在せず、strict が False の場合、 LookupError が発生します。
strict が False (デフォルト) の場合、言語コードもその一般的なバリアントも見つからないときに、国別のバリアントが返されることがあります。たとえば、LANGUAGES に 'es-co' のみが含まれている場合、その国別バリアントは lang_code が 'es' や 'es-ar' のような場合に返されます。これらのマッチは strict=True の場合には返されません。
何も見つからない場合、LookupError を発生させます。
12月 03, 2025