Диспетчер URL¶

Overview¶

Чтобы разработать 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. Это должна быть sequence (последовательность( экземпляров django.urls.path() и/или django.urls.re_path().
3. Django проходит по каждому шаблону URL по порядку и останавливается на первом, который соответствует запрошенному URL.
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 - соответствует любой строке заголовка, состоящей из букв или цифр ASCII, а также символов дефиса и подчеркивания. Например, build-your-1st-django-site.
• uuid - соответствует форматированному UUID. Чтобы предотвратить сопоставление нескольких URL-адресов с одной и той же страницей, необходимо использовать дефисы, а буквы должны быть строчными. Например, 075194d3-6885-417e-a8a8-6c931e272f00. Возвращает экземпляр UUID.
• path - соответствует любой непустой строке, включая разделитель пути, '/'. Это позволяет вам сопоставлять полный путь URL, а не просто сегмент пути URL, как в случае с str.

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

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

Конвертер - это класс, который включает в себя следующее:

• Атрибут класса regex в виде строки.
• Метод to_python(self, value), который обрабатывает преобразование согласованной строки в тип, который должен быть передан в функцию. Он должен вызвать ValueError, если он не может преобразовать данное значение. ValueError интерпретируется как несоответствие, и, как следствие, пользователю отправляется ответ 404.
• Метод to_url(self, value), который обрабатывает преобразование типа Python в строку, которая будет использоваться в 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-(\d+)/)?$', blog_articles),                  # bad
    re_path(r'^comments/(?:page-(?P<page_number>\d+)/)?$', 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 и view:

# 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.

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

Каждое регулярное выражение в urlpatterns компилируется при первом обращении к нему. Это делает систему невероятно быстрой.

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

urlpatterns должен быть sequence (последовательностью) экземпляров 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.

Включение других URLconfs¶

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

Например, вот выдержка из URLconf для самого сайта Django. Он включает ряд других URLconfs:

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().

Это можно использовать для удаления избыточности из URLconfs, где один префикс шаблона используется многократно. Например, рассмотрим этот 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),
]

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

У URLconfs есть ловушка, которая позволяет передавать дополнительные аргументы функциям просмотра в виде словаря 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() соответствует количеству аргументов и именам ключевым аргументов.

Пространства имен 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)),
]