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

reverse()

The reverse() function can be used to return an absolute path reference for a given view and optional parameters, similar to the url tag:

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

viewname can be a URL pattern name or the callable view object used in the URLconf. For example, given the following 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 が使用されます。

The query keyword argument specifies parameters to be added to the returned URL. It can accept an instance of QueryDict (such as request.GET) or any value compatible with urllib.parse.urlencode(). The encoded query string is appended to the resolved URL, prefixed by a ?.

The fragment keyword argument specifies a fragment identifier to be appended to the returned URL (that is, after the path and query string, preceded by a #).

例:

>>> 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:

The query and fragment arguments were added.

注釈

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

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

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

Reversing class-based views by view object

The view object can also be the result of calling as_view() if the same view object is used in the URLConf. Following the original example, the view object could be defined as:

news/views.py

 from django.views import View


 class ArchiveView(View): ...


 archive = ArchiveView.as_view()

However, remember that namespaced views cannot be reversed by view object.

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:

The query and fragment arguments were added.

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サーバーのルートにある場合、これは常に "/" です。

警告

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