# Django 5.2.9 ドキュメント

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

警告

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