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)[source]

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 参数是 URLconf 模块，其中包含用于反查的 URL 模式。默认情况下，使用的是当前线程的根 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.

Note

reverse() 返回的字符串已经被 urlquoted。例如：

>>> 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 属性。

• 为装饰器提供一个反查的 URL（例如 django.contrib.auth.decorators.permission_required() 装饰器的 login_url 参数）。

• 提供一个反查的 URL 作为函数签名中参数的默认值。

Changed in Django 5.2:

The query and fragment arguments were added.

resolve()

resolve() 函数可用于解析到相应视图函数的 URL 路径。该函数的签名如下：

resolve(path, urlconf=None)[source]

path 是你要解析的 URL 路径。与 reverse() 一样，你不需要担心 urlconf 参数。该函数返回一个 ResolverMatch 对象，允许你访问关于解析 URL 的各种元数据。

如果 URL 没有解析，函数会引发一个 Resolver404 异常（Http404 的一个子类）。

class ResolverMatch[source]

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 模式的应用程序命名空间。

app_names

匹配 URL 模式的完整应用程序命名空间中的单个命名空间组件列表。例如，如果 app_name 是 'foo:bar'，那么 app_names 将是 ['foo', 'bar']。

namespace

匹配 URL 模式的实例命名空间。

namespaces

匹配 URL 模式的完整实例命名空间中的单个命名空间组件列表，即，如果命名空间是 foo:bar，那么命名空间将是 ['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 对象也可以解包为以下三个：

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()[source]

通常，你应该始终使用 reverse() 来定义应用程序中的 URL。然而，如果你的应用程序自己构建了 URL 层次结构的一部分，偶尔可能需要生成 URL。在这种情况下，你需要能够找到 Django 项目在其 Web 服务器内的基本 URL（通常，reverse() 会为你处理这个）。在这种情况下，你可以调用 get_script_prefix()，它将返回你的 Django 项目的 URL 的脚本前缀部分。如果你的 Django 项目位于其 Web 服务器的根目录，这将始终是 "/"。

Warning

此函数 不能 在请求-响应周期之外使用，因为它依赖于在该周期期间初始化的值。