django.urls ユーティリティ関数

reverse()

reverse() 関数は指定したビューと任意のパラメータに対して、url タグと同様に、絶対パス参照を返すために使用します。

reverse(viewname, urlconf=None, args=None, kwargs=None, current_app=None, *, query=None, fragment=None)[ソース]

viewname には URL パターン名 またはURLconf で使用される呼び出し可能なビューオブジェクトを指定できます。たとえば、下記の url が与えられている場合を考えます。

from news import views

path("archive/", views.archive, name="news-archive")

URL を逆引きするために、以下の方法を使用できます：

# using the named URL
reverse("news-archive")

# passing a callable object
# (This is discouraged because you can't reverse namespaced views this way.)
from news import views

reverse(views.archive)

URLが引数を受け入れる場合は、 args にそれらを渡すことができます。例えば：

from django.urls import reverse


def myview(request):
    return HttpResponseRedirect(reverse("arch-summary", args=[1945]))

kwargs を args の代わりに渡すこともできます。例えば：

>>> reverse("admin:app_list", kwargs={"app_label": "auth"})
'/admin/auth/'

args と kwargs を同時に reverse() に渡すことはできません。

一致するものが見つからない場合、reverse() は NoReverseMatch 例外を発生させます。

reverse() 関数は、URLの正規表現パターンの多くを逆引きできますが、すべてを逆引きできるわけではありません。現時点での主な制限は、パターンに垂直バー (“|”) 文字を使用して選択肢を含めることができないということです。そのようなパターンを使用して受信URLに対してマッチングし、それらをビューに送ることは問題なく行えますが、そのようなパターンを逆引きすることはできません。

current_app 引数は、現在実行中のビューが属しているアプリケーションを指示するヒントをリゾルバに提供することを可能にします。この current_app 引数は、特定のアプリケーションインスタンス上のURLに対してアプリケーションの名前空間を解決するためのヒントとして使用されます。これは、 名前空間化された URL の解決順序 に従っています。

urlconf 引数は、リバースに使用する URL パターンを含む URLconf モジュールです。デフォルトでは、現在のスレッドのルート URLconf が使用されます。

query キーワード引数は、返される URL に追加するパラメータを指定します。これは GET` など）のインスタンス、または urllib.parse.urlencode() と互換性のある任意の値を受け付けます。エンコードされたクエリ文字列は先頭に ? を付加して、解決された URL に追加されます。

fragment キーワード引数は、返される URL に付加するフラグメント識別子を指定します（つまり、パスとクエリ文字列の後ろに、先頭に # を付けて追加されます）。

例:

>>> from django.urls import reverse
>>> reverse("admin:index", query={"q": "biscuits", "page": 2}, fragment="results")
'/admin/?q=biscuits&page=2#results'
>>> reverse("admin:index", query=[("color", "blue"), ("color", 1), ("none", None)])
'/admin/?color=blue&color=1&none=None'
>>> reverse("admin:index", query={"has empty spaces": "also has empty spaces!"})
'/admin/?has+empty+spaces=also+has+empty+spaces%21'
>>> reverse("admin:index", fragment="no encoding is done")
'/admin/#no encoding is done'
Changed in Django 5.2:

query と fragment 引数が追加されました。

注釈

reverse() によって返される文字列は、すでに URL エンコードされています 。例えば：

>>> reverse("cities", args=["Orléans"])
'.../Orl%C3%A9ans/'

reverse() の出力に対してさらにエンコーディング（例えば urllib.parse.quote() など）を適用すると、望ましくない結果が生じることがあります。

クラスベースのビューをビューオブジェクトで逆引きする

URLconf で同じビューオブジェクトが使用されている場合、ビューオブジェクトは as_view() を呼び出した結果でもかまいません。元の例に従うと、ビューオブジェクトは次のように定義できます。

news/views.py
 from django.views import View


 class ArchiveView(View): ...


 archive = ArchiveView.as_view()

ただし、名前空間付きのビューはビューオブジェクトによる逆引きができないことに注意してください。

reverse_lazy()

reverse() の遅延評価バージョンです。

reverse_lazy(viewname, urlconf=None, args=None, kwargs=None, current_app=None, *, query=None, fragment=None)

プロジェクトの URLConf がロードされる前に、URL 反転を使用する必要がある場合に役立ちます。この関数が必要となる一般的なケースには以下のようなものがあります：

  • クラスベースのジェネリックビューの url 属性に逆引きURLを提供する場合。

  • デコレータ（たとえば django.contrib.auth.decorators.permission_required() デコレータの login_url 引数など）への URL の逆引きを提供する場合。

  • 関数のシグネチャでパラメータのデフォルト値として逆引きURLを提供する場合。

Changed in Django 5.2:

query と fragment 引数が追加されました。

resolve()

resolve() 関数は、URL パスを対応するビュー関数に解決するために使用できます。次のシグネチャを持っています:

resolve(path, urlconf=None)[ソース]

path は解決したい URL パスです。 reverse() と同じように、 urlconf パラメータについて心配する必要はありません。この関数は、解決された URL に関するさまざまなメタデータにアクセスを許可する ResolverMatch オブジェクトを返します。

URL が解決しない場合、その関数は Resolver404 例外を発生させます（ Http404 のサブクラスです）。

class ResolverMatch[ソース]
func

URL を提供するために使用されるビュー関数

args

URL からパースされた、ビュー関数に渡される引数。

kwargs

ビュー関数に渡されるであろうすべてのキーワード引数、すなわち captured_kwargs と extra_kwargs です。

captured_kwargs

URL から解析された、ビュー関数に渡されるキーワード引数がキャプチャされます。

extra_kwargs

ビュー関数に渡される追加のキーワード引数。

url_name

URL に一致する URL パターンの名前。

route

一致するURLパターンのルート。

例えば、path('users/<id>/', ...) がマッチするパターンである場合、 route には 'users/<id>/' が含まれます。

tried

URL が一致するか利用可能なパターンが尽きる前に試みられた URL パターンのリストです。

app_name

URLに一致するURLパターンのアプリケーション名前空間です。

app_names

URL にマッチする URL パターンの完全なアプリケーション名前空間内の個別の名前空間コンポーネントのリストです。例えば、もし app_name が 'foo:bar' である場合、app_names は ['foo', 'bar'] になります。

namespace

対応するURLのURLパターンのインスタンス名前空間。

namespaces

URL がマッチする URL パターンの完全なインスタンス名前空間内の個々の名前空間コンポーネントのリストです。つまり、名前空間が foo:bar である場合、namespaces は ['foo', 'bar'] になります。

view_name

URL にマッチするビューの名前で、名前空間が存在する場合はその名前空間を含みます。

その後、 ResolverMatch オブジェクトを調査して、URL に一致する URL パターンに関する情報を提供できます。

# Resolve a URL
match = resolve("/some/path/")
# Print the URL pattern that matches the URL
print(match.url_name)

ResolverMatch オブジェクトは、3値タプルに代入することもできます:

func, args, kwargs = resolve("/some/path/")

resolve() の可能な使用例の一つは、リダイレクトする前にビューが Http404 エラーを発生させるかどうかをテストすることです。

from urllib.parse import urlsplit
from django.urls import resolve
from django.http import Http404, HttpResponseRedirect


def myview(request):
    next = request.META.get("HTTP_REFERER", None) or "/"
    response = HttpResponseRedirect(next)

    # modify the request and response as required, e.g. change locale
    # and set corresponding locale cookie

    view, args, kwargs = resolve(urlsplit(next).path)
    kwargs["request"] = request
    try:
        view(*args, **kwargs)
    except Http404:
        return HttpResponseRedirect("/")
    return response

get_script_prefix()

get_script_prefix()[ソース]

通常、アプリケーション内でURLを定義する際には、常に reverse() を使用すべきです。しかし、アプリケーションがURL階層の一部を自身で構築する場合、時々URLを生成する必要があります。その場合、DjangoプロジェクトのベースURLをそのWebサーバー内で見つける必要があります（通常、 reverse() がこれを処理します）。そのような場合、 get_script_prefix() を呼び出すことができます。これは、DjangoプロジェクトのURLのスクリプトプレフィックス部分を返します。あなたのDjangoプロジェクトがWebサーバーのルートにある場合、これは常に "/" です。

警告

この関数は、リクエスト・レスポンスサイクル中に初期化された値に依存しているため、そのサイクルの外部では 使用できません 。

« previous | up | next »