Обзор¶

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

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

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

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

При запросе к странице вашего Django-сайта, используется такой алгоритм для определения какой код выполнить:

1. Django определяет какой корневой модуль URLconf использовать. Обычно, это значение настройки ROOT_URLCONF, но, если объект запроса HttpRequest содержит атрибут urlconf (установленный request middleware), его значение будет использоваться вместо ROOT_URLCONF.

2. Django загружает модуль конфигурации URL и ищет переменную urlpatterns. Это должен быть список экземпляров django.conf.urls.url().

3. Django перебирает каждый URL-шаблон по порядку, и останавливается при первом совпадении с запрошенным URL-ом.

4. Если одно из регулярных выражений соответствует URL-у, Django импортирует и вызывает соответствующее представление, которое является просто функцией Python(или представление-класс). При вызове передаются следующие аргументы:

   • Объект HttpRequest.

   • Если в результате применения регулярного выражения получили именованные совпадения, они будут переданы как позиционные аргументы.

   • Именованные аргументы создаются из именованных совпадений. Они могут быть перезаписаны значениями из аргумента kwargs, переданного в django.conf.urls.url().

     Changed in Django 3.0:

     In older versions, the keyword arguments with None values are made up also for not provided named parts.

5. Если ни одно регулярное выражение не соответствует, или возникла ошибка на любом из этапов, Django вызывает соответствующий обработчик ошибок. Смотрите Error handling ниже.

Примеры¶

Вот пример простого 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, '2005', '03').

• /articles/2003/ соответствует первому выражению, не второму, потому что шаблоны проверяются по порядку и берется первый найденный. Не стесняйтесь использовать порядок для обработки различных ситуаций, таких как эта. В данном примере Django вызовет функцию views.special_case_2003(request).

• /articles/2003 не соответствует ни одному регулярному выражению, потому что каждое ожидает, что URL оканчивается на косую черту.

• /articles/2003/03/03/ соответствует последнему выражению. Django вызовет функцию views.article_detail(request, '2003', '03', '03').

Преобразователи пути¶

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

• str — соответствует любой непустой строке, за исключением разделителя пути '/'. Это значение по умолчанию, если преобразователь не включен в выражение.

• int — соответствует нулю или любому положительному целому числу. Возвращает int.

• slug — соответствует любой короткой строке, состоящей из букв или цифр ASCII, а также символов дефиса и подчеркивания. Например, создайте свой первый сайт на Django.

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

  Changed in Django 3.1:

  Support for raising ValueError to indicate no match was added.

Например:

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

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

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

Зарегистрируйте пользовательские классы конвертеров в вашей конфигурации URL, используя 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 – шаблон.

Вот пример конфигурации URL, переписанный с использованием именованных групп:

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 больше не будет соответствовать, поскольку целые числа года ограничены длиной ровно четыре цифры.

• Каждый найденный аргумент передается в представление как строка, независимо от того, какое «совпадение» определено в регулярном выражении. Например, URLconf содержит такую строку:

При переключении с использования 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 при поиске нужного шаблона URL¶

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

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

При запросе к https://www.example.com/myapp/?page=3 – 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 из URL, которое найдет регулярное выражение.

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

Each regular expression in a urlpatterns is compiled the first time it’s accessed. This makes the system blazingly fast.

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

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

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

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

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

Подробности в разделе о переопределении обработчика ошибок.

Эти значения должны быть определены в главном URLconf.

Значение это функции, или полный путь для импорта, которая будет вызвана, если не был найден подходящий URL-шаблон.

Есть следующие переменные:

• handler400 – Смотрите django.conf.urls.handler400.

• handler403 – Смотрите django.conf.urls.handler403.

• handler404 – Смотрите django.conf.urls.handler404.

• handler500 – Смотрите django.conf.urls.handler500.

Комбинирование URLconfs¶

В любой момент, ваш urlpatterns может «включать» другие модули URLconf.

Вот пример URLconf для сайта Django. Он включает множество других конфигураций URL:

from django.urls import include, path

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

Заметим, что регулярные выражения не содержат $ (определитель конца строки), но содержит косую черту в конце. Каждый раз, когда Django встречает include() (django.conf.urls.include()), из URL обрезается уже совпавшая часть, остальное передается во включенный URLconf для дальнейшей обработки.

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

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/ обработан представлением credit_views.report().

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

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),
]

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

Конфигурация URL-ов позволяет определить дополнительные аргументы для функции представления, используя словарь Python.

Функция django.conf.urls.url() может принимать третий необязательный элемент. Этот элемент является словарем, который определяет дополнительные именованные аргументы для функции представления.

Например:

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

Такой подход используется в syndication framework для передачи параметров и дополнительных данных в представление.

# 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-а по URL-шаблону¶

Обычной задачей является получение URL-а по его определению для отображения пользователю или для редиректа.

Очень важно не «хардкодить» URL-ы (трудоемкая и плохо поддерживаемая стратегия). Также не следует создавать «костыли» для генерации URL-ов, которые не следуют задокументированному дизайну URLconf.

В общем необходимо придерживаться принципа DRY. Немаловажно иметь возможность менять URL-ы в одном месте, а не выполнять поиск и замену по всему проекту.

Для получения URL-а нам необходим его идентификатор, то есть название URL-шаблона, и позиционные и именованные аргументы.

В Django для работы с URL-ами используется так называемый «URL mapper». Ему передается URLconf, и теперь его можно использовать в два направления:

• Получая запрошенный URL находит необходимое представление и предоставляет все необходимые аргументы полученные из URL-а.

• Получая идентификатор представления и передаваемые ему аргументы, возвращает URL.

Первое это то, что мы уже рассмотрели в предыдущем разделе. Второе называется URL reversing, в общем получение URL-а по его названию.

Django предоставляет инструменты для получения URL-ов в различных компонентах фреймворка:

• В шаблонах: Использование шаблонного тега url.

• В Python коде: Использование функции django.core.urlresolvers.reverse().

• На более высоком уровне для привязки URL-ов к моделям - метод 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.

Добавление префикса к названию URL-шаблона, возможного состоящего из названия приложения, уменьшит шанс конфликта. Мы советуем использовать myapp-comment вместо comment.

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

Вы также можете использовать одно и то же имя для нескольких шаблонов URL-адресов, если они различаются своими аргументами. Помимо имени URL, reverse() соответствует количеству аргументов и именам аргументов ключевого слова. Преобразователи путей также могут выдавать ValueError, чтобы указать на отсутствие совпадения, подробности см. в разделе «registering-custom-path-converters».

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