Служебные функции 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]))

Вместо args также можно передать kwargs. Например:

>>> 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 текущего потока.

Именованный аргумент query задаёт параметры, добавляемые к возвращаемому URL. Он может принимать экземпляр QueryDict (например, request.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'

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

 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)

Она полезна, когда необходимо выполнить обратное преобразование URL до загрузки URLconf проекта. Вот несколько распространённых случаев, когда нужна эта функция:

• передача преобразованного URL в качестве атрибута url обобщённого представления на основе класса.
• передача преобразованного URL декоратору (например, аргумента login_url декоратора django.contrib.auth.decorators.permission_required()).
• передача преобразованного URL в качестве значения по умолчанию для параметра в сигнатуре функции.

resolve()

Функцию resolve() можно использовать для разрешения путей URL в соответствующие функции представлений. Она имеет следующую сигнатуру:

resolve(path, urlconf=None) [исходный код]

path — это путь URL, который нужно разрешить. Как и в случае с reverse(), беспокоиться о параметре urlconf не нужно. Функция возвращает объект ResolverMatch, позволяющий получить различные метаданные о разрешённом URL.

Если 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 также можно присвоить тройке:

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. В этом случае необходимо определить базовый URL проекта Django на веб-сервере (обычно об этом заботится reverse()). Для этого можно вызвать get_script_prefix(), которая вернёт часть URL проекта Django, соответствующую префиксу скрипта. Если проект Django находится в корне веб-сервера, это всегда "/".