Диспетчер URL

Обзор

Чтобы спроектировать URL для приложения, создайте модуль Python, который неофициально называют URLconf (конфигурация URL). Этот модуль представляет собой обычный код Python и задаёт соответствие между выражениями путей URL и функциями Python (вашими представлениями).

Это соответствие может быть сколь угодно коротким или длинным. Оно может ссылаться на другие соответствия. А поскольку это обычный код Python, его можно создавать динамически.

Django также позволяет переводить URL в соответствии с активным языком. Подробнее см. в документации по интернационализации.

Как Django обрабатывает запрос

Когда пользователь запрашивает страницу на сайте, работающем на Django, система выполняет следующие действия, чтобы определить, какой код Python запустить:

1. Django определяет корневой модуль URLconf, который нужно использовать. Обычно это значение настройки ROOT_URLCONF, но если у входящего объекта HttpRequest есть атрибут urlconf (установленный промежуточным ПО), вместо настройки ROOT_URLCONF будет использовано его значение.
2. Django загружает этот модуль Python и ищет переменную urlpatterns. Это должна быть последовательность экземпляров django.urls.path() и/или django.urls.re_path().
3. Django по порядку проверяет каждый шаблон URL и останавливается на первом совпавшем с запрошенным URL, сопоставляя его с path_info.

4. Когда один из шаблонов URL совпадает, Django импортирует и вызывает соответствующее представление — функцию Python (или представление на основе класса). Представлению передаются следующие аргументы:

   • Экземпляр HttpRequest.
   • Если совпавший шаблон URL не содержит именованных групп, совпадения из регулярного выражения передаются как позиционные аргументы.
   • Именованные аргументы состоят из всех предоставленных именованных частей, совпавших с выражением пути, переопределённых аргументами, указанными в необязательном аргументе kwargs для django.urls.path() или django.urls.re_path().
5. Если ни один шаблон URL не совпал или на любом этапе этого процесса возникло исключение, Django вызывает соответствующее представление для обработки ошибки. См. раздел Обработка ошибок ниже.

Пример

Пример URLconf:

from django.urls import path

from . import views

urlpatterns = [
    path("articles/2003/", views.special_case_2003),
    path("articles/<int:year>/", views.year_archive),
    path("articles/<int:year>/<int:month>/", views.month_archive),
    path("articles/<int:year>/<int:month>/<slug:slug>/", views.article_detail),
]

Примечания:

• Чтобы захватить значение из URL, используйте угловые скобки.
• При захвате значений можно указать тип конвертера. Например, используйте <int:name> для захвата целочисленного параметра. Если конвертер не указан, совпадением будет любая строка, не содержащая символ /.
• Добавлять начальный слеш не нужно, поскольку он есть в каждом URL. Например, это articles, а не /articles.

Примеры запросов:

• Запрос к /articles/2005/03/ совпадёт с третьим элементом списка. Django вызовет функцию views.month_archive(request, year=2005, month=3).
• /articles/2003/ совпадёт с первым шаблоном в списке, а не со вторым, поскольку шаблоны проверяются по порядку и первый же пройдёт проверку. При желании можно использовать порядок шаблонов, чтобы добавлять особые случаи вроде этого. Здесь Django вызовет функцию views.special_case_2003(request)
• /articles/2003 не совпадёт ни с одним из этих шаблонов, поскольку каждый из них требует, чтобы URL заканчивался слешем.
• /articles/2003/03/building-a-django-site/ совпадёт с последним шаблоном. Django вызовет функцию views.article_detail(request, year=2003, month=3, slug="building-a-django-site").

Конвертеры путей

По умолчанию доступны следующие конвертеры путей:

• str — совпадает с любой непустой строкой, за исключением разделителя пути '/'. Это значение по умолчанию, если конвертер не указан в выражении.
• int — совпадает с нулём или любым положительным целым числом. Возвращает int.
• slug — совпадает со строкой slug, состоящей из букв ASCII или цифр, а также дефиса и символа подчёркивания. Например, building-your-1st-django-site.
• uuid — совпадает с UUID в заданном формате. Чтобы несколько URL не указывали на одну и ту же страницу, дефисы должны присутствовать, а буквы должны быть строчными. Например, 075194d3-6885-417e-a8a8-6c931e272f00. Возвращает экземпляр UUID.
• path — совпадает с любой непустой строкой, включая разделитель пути '/'. Это позволяет сопоставлять полный путь URL, а не его сегмент, как в случае с str.

Регистрация пользовательских конвертеров путей

Для более сложных требований к сопоставлению можно определить собственные конвертеры путей.

Конвертер — это класс, который содержит следующее:

• Строковый атрибут класса regex.
• Метод to_python(self, value), который преобразует совпавшую строку в тип, передаваемый функции представления. Если указанное значение преобразовать нельзя, метод должен вызывать ValueError. Исключение ValueError трактуется как отсутствие совпадения, и в результате пользователю отправляется ответ 404, если не совпадёт другой шаблон URL.
• Метод to_url(self, value), который преобразует тип Python в строку для использования в URL. Если указанное значение преобразовать нельзя, метод должен вызывать ValueError. Исключение ValueError трактуется как отсутствие совпадения, и в результате reverse() вызовет NoReverseMatch, если не совпадёт другой шаблон URL.

Например:

class FourDigitYearConverter:
    regex = "[0-9]{4}"

    def to_python(self, value):
        return int(value)

    def to_url(self, value):
        return "%04d" % value

Зарегистрируйте классы пользовательских конвертеров в URLconf с помощью register_converter():

from django.urls import path, register_converter

from . import converters, views

register_converter(converters.FourDigitYearConverter, "yyyy")

urlpatterns = [
    path("articles/2003/", views.special_case_2003),
    path("articles/<yyyy:year>/", views.year_archive),
    ...,
]

Использование регулярных выражений

Если синтаксиса путей и конвертеров недостаточно для определения шаблонов URL, можно также использовать регулярные выражения. Для этого используйте re_path() вместо path().

В регулярных выражениях Python синтаксис именованных групп регулярного выражения имеет вид (?P<name>pattern), где name — имя группы, а pattern — шаблон для поиска совпадений.

Вот приведённый ранее пример URLconf, переписанный с использованием регулярных выражений:

from django.urls import path, re_path

from . import views

urlpatterns = [
    path("articles/2003/", views.special_case_2003),
    re_path(r"^articles/(?P<year>[0-9]{4})/$", views.year_archive),
    re_path(r"^articles/(?P<year>[0-9]{4})/(?P<month>[0-9]{2})/$", views.month_archive),
    re_path(
        r"^articles/(?P<year>[0-9]{4})/(?P<month>[0-9]{2})/(?P<slug>[\w-]+)/$",
        views.article_detail,
    ),
]

Это примерно то же самое, что и предыдущий пример, за исключением следующего:

• URL, которые будут совпадать, ограничены несколько сильнее. Например, год 10000 больше не будет совпадать, поскольку целочисленные значения года ограничены ровно четырьмя цифрами.
• Каждый захваченный аргумент передаётся представлению как строка, независимо от того, какой тип совпадения выполняет регулярное выражение.

При переходе с path() на re_path() или наоборот особенно важно учитывать, что тип аргументов представления может измениться, поэтому, возможно, потребуется адаптировать представления.

from django.urls import re_path

urlpatterns = [
    re_path(r"^blog/(page-([0-9]+)/)?$", blog_articles),  # bad
    re_path(r"^comments/(?:page-(?P<page_number>[0-9]+)/)?$", comments),  # good
]

По чему выполняется поиск в URLconf

URLconf выполняет поиск по запрошенному URL как по обычной строке Python. В неё не входят параметры GET или POST и имя домена.

Например, при запросе к https://www.example.com/myapp/ URLconf будет искать myapp/.

При запросе к https://www.example.com/myapp/?page=3 URLconf будет искать myapp/.

URLconf не проверяет метод запроса. Другими словами, все методы запроса — POST, GET, HEAD и т. д. — для одного и того же URL будут направлены в одну и ту же функцию.

Задание значений по умолчанию для аргументов представлений

Удобный приём — задать значения по умолчанию для аргументов представлений. Вот пример URLconf и представления:

# URLconf
from django.urls import path

from . import views

urlpatterns = [
    path("blog/", views.page),
    path("blog/page<int:num>/", views.page),
]


# View (in blog/views.py)
def page(request, num=1):
    # Output the appropriate page of blog entries, according to num.
    ...

В приведённом выше примере оба шаблона URL указывают на одно и то же представление — views.page, — но первый шаблон не захватывает ничего из URL. Если совпадёт первый шаблон, функция page() использует значение аргумента num по умолчанию — 1. Если совпадёт второй шаблон, page() использует захваченное значение num.

Производительность

Django обрабатывает регулярные выражения в списке urlpatterns, который компилируется при первом обращении к нему. При последующих запросах используется кэшированная конфигурация через преобразователь URL.

Синтаксис переменной urlpatterns

urlpatterns должна быть последовательностью экземпляров path() и/или re_path().

Обработка ошибок

Если Django не может найти совпадение для запрошенного URL или возникает исключение, Django вызывает представление для обработки ошибки.

Представления для этих случаев задаются четырьмя переменными. Их значений по умолчанию достаточно для большинства проектов, но при необходимости их можно изменить.

Подробную информацию см. в документации по настройке представлений для обработки ошибок.

Эти значения можно задать в корневом URLconf. Установка этих переменных в любом другом URLconf не даст эффекта.

Значения должны быть вызываемыми объектами или строками, содержащими полный путь импорта Python к представлению, которое следует вызвать для обработки соответствующей ошибки.

Переменные:

• handler400 — см. django.conf.urls.handler400.
• handler403 — см. django.conf.urls.handler403.
• handler404 — см. django.conf.urls.handler404.
• handler500 — см. django.conf.urls.handler500.

Подключение других URLconf

В любой момент ваш urlpatterns может «подключать» другие модули URLconf. По сути, это позволяет разместить набор URL ниже других URL.

Например, вот фрагмент URLconf самого сайта Django. Он подключает несколько других URLconf:

from django.urls import include, path

urlpatterns = [
    # ... snip ...
    path("community/", include("aggregator.urls")),
    path("contact/", include("contact.urls")),
    # ... snip ...
]

Когда Django встречает include(), он отсекает ту часть URL, которая совпала до этого момента, и передаёт оставшуюся строку подключённому URLconf для дальнейшей обработки.

Также можно подключить дополнительные шаблоны URL, используя список экземпляров path(). Например, рассмотрим этот URLconf:

from django.urls import include, path

from apps.main import views as main_views
from credit import views as credit_views

extra_patterns = [
    path("reports/", credit_views.report),
    path("reports/<int:id>/", credit_views.report),
    path("charge/", credit_views.charge),
]

urlpatterns = [
    path("", main_views.homepage),
    path("help/", include("apps.help.urls")),
    path("credit/", include(extra_patterns)),
]

В этом примере URL /credit/reports/ будет обработан представлением Django credit_views.report().

Этот способ позволяет избежать повторений в URLconf, где один и тот же префикс шаблона используется несколько раз. Например, рассмотрим этот URLconf:

from django.urls import path
from . import views

urlpatterns = [
    path("<page_slug>-<page_id>/history/", views.history),
    path("<page_slug>-<page_id>/edit/", views.edit),
    path("<page_slug>-<page_id>/discuss/", views.discuss),
    path("<page_slug>-<page_id>/permissions/", views.permissions),
]

Его можно улучшить, указав общий префикс пути только один раз и сгруппировав отличающиеся суффиксы:

from django.urls import include, path
from . import views

urlpatterns = [
    path(
        "<page_slug>-<page_id>/",
        include(
            [
                path("history/", views.history),
                path("edit/", views.edit),
                path("discuss/", views.discuss),
                path("permissions/", views.permissions),
            ]
        ),
    ),
]

# In settings/urls/main.py
from django.urls import include, path

urlpatterns = [
    path("<username>/blog/", include("foo.urls.blog")),
]

# In foo/urls/blog.py
from django.urls import path
from . import views

urlpatterns = [
    path("", views.blog.index),
    path("archive/", views.blog.archive),
]

Передача дополнительных параметров функциям представлений

В URLconf предусмотрен механизм, позволяющий передавать функциям представлений дополнительные аргументы в виде словаря Python.

Функция path() принимает необязательный третий аргумент — словарь дополнительных именованных аргументов, которые следует передать функции представления.

Например:

from django.urls import path
from . import views

urlpatterns = [
    path("blog/<int:year>/", views.year_archive, {"foo": "bar"}),
]

В этом примере при запросе к /blog/2005/ Django вызовет views.year_archive(request, year=2005, foo='bar').

Этот приём используется в фреймворке синдикации для передачи метаданных и параметров представлениям.

# main.py
from django.urls import include, path

urlpatterns = [
    path("blog/", include("inner"), {"blog_id": 3}),
]

# inner.py
from django.urls import path
from mysite import views

urlpatterns = [
    path("archive/", views.archive),
    path("about/", views.about),
]

# main.py
from django.urls import include, path
from mysite import views

urlpatterns = [
    path("blog/", include("inner")),
]

# inner.py
from django.urls import path

urlpatterns = [
    path("archive/", views.archive, {"blog_id": 3}),
    path("about/", views.about, {"blog_id": 3}),
]

Обратное разрешение URL

При работе над проектом Django часто требуется получить URL в окончательном виде — либо для включения в сгенерированное содержимое (URL представлений и ресурсов, URL, показываемые пользователю, и т. д.), либо для управления навигацией на стороне сервера (перенаправления и т. д.).

Настоятельно рекомендуется избегать жёстко заданных URL (это трудоёмкий, плохо масштабируемый и подверженный ошибкам подход). Не менее опасно создавать специальные механизмы генерации URL, параллельные описанию в URLconf: со временем это может привести к созданию устаревших URL.

Иными словами, нужен механизм, следующий принципу DRY. Помимо прочих преимуществ, он позволил бы изменять схему URL, не просматривая весь исходный код проекта в поисках устаревших URL.

Основная информация, доступная для получения URL, — идентификатор (например, имя) представления, отвечающего за его обработку. Другие данные, необходимые для поиска нужного URL, — типы (позиционные или именованные) и значения аргументов представления.

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

• Получив URL, запрошенный пользователем или браузером, он вызывает нужное представление Django и передаёт ему необходимые аргументы со значениями, извлечёнными из URL.
• Получив идентификатор соответствующего представления Django и значения аргументов, которые ему были бы переданы, он возвращает связанный с ними URL.

Первый вариант использования мы обсуждали в предыдущих разделах. Второй называется обратным разрешением URL, обратным сопоставлением URL, обратным поиском URL или просто обратным разрешением URL.

Django предоставляет инструменты для обратного разрешения URL на разных уровнях, где требуются URL:

• В шаблонах: с помощью шаблонного тега url.
• В коде Python: с помощью функции reverse().
• В коде более высокого уровня, связанном с обработкой URL экземпляров моделей Django: с помощью метода get_absolute_url().

from django.urls import path

from . import views

urlpatterns = [
    # ...
    path("articles/<int:year>/", views.year_archive, name="news-year-archive"),
    # ...
]

<a href="{% url 'news-year-archive' 2012 %}">2012 Archive</a>
{# Or with the year in a template context variable: #}
<ul>
{% for yearvar in year_list %}
<li><a href="{% url 'news-year-archive' yearvar %}">{{ yearvar }} Archive</a></li>
{% endfor %}
</ul>

from django.http import HttpResponseRedirect
from django.urls import reverse


def redirect_to_year(request):
    # ...
    year = 2006
    # ...
    return HttpResponseRedirect(reverse("news-year-archive", args=(year,)))

Именование шаблонов URL

Для обратного разрешения URL необходимо использовать именованные шаблоны URL, как в примерах выше. В строке, используемой в качестве имени URL, можно указывать любые символы. Она не обязана соответствовать правилам именования Python.

При именовании шаблонов URL выбирайте имена, которые вряд ли совпадут с именами, выбранными в других приложениях. Если вы назовёте шаблон URL comment, а другое приложение сделает то же самое, URL, найденный функцией reverse(), будет зависеть от того, какой шаблон окажется последним в списке urlpatterns вашего проекта.

Если добавить к имени URL префикс, возможно, образованный от имени приложения (например, myapp-comment вместо comment), вероятность конфликта уменьшится.

Можно намеренно выбрать то же имя URL, что и у другого приложения, если требуется переопределить представление. Например, часто переопределяют LoginView. Некоторые части Django и большинство сторонних приложений предполагают, что у этого представления есть шаблон URL с именем login. Если у вашего пользовательского представления входа в систему URL будет называться login, функция reverse() найдёт ваше пользовательское представление, если оно находится в urlpatterns после подключения django.contrib.auth.urls (если этот модуль вообще подключён).

Одно и то же имя можно использовать для нескольких шаблонов URL, если они отличаются аргументами. Помимо имени URL, функция reverse() учитывает количество аргументов и имена именованных аргументов. Конвертеры путей также могут вызвать ValueError, чтобы указать на отсутствие совпадения. Подробнее см. в разделе Регистрация пользовательских конвертеров путей.

Пространства имён URL

from django.urls import include, path

urlpatterns = [
    path("author-polls/", include("polls.urls", namespace="author-polls")),
    path("publisher-polls/", include("polls.urls", namespace="publisher-polls")),
]

from django.urls import path

from . import views

app_name = "polls"
urlpatterns = [
    path("", views.IndexView.as_view(), name="index"),
    path("<int:pk>/", views.DetailView.as_view(), name="detail"),
    ...,
]

from django.urls import path

from . import views

app_name = "polls"
urlpatterns = [
    path("", views.IndexView.as_view(), name="index"),
    path("<int:pk>/", views.DetailView.as_view(), name="detail"),
    ...,
]

from django.urls import include, path

urlpatterns = [
    path("polls/", include("polls.urls")),
]

(<list of path()/re_path() instances>, <application namespace>)

from django.urls import include, path

from . import views

polls_patterns = (
    [
        path("", views.IndexView.as_view(), name="index"),
        path("<int:pk>/", views.DetailView.as_view(), name="detail"),
    ],
    "polls",
)

urlpatterns = [
    path("polls/", include(polls_patterns)),
]