Маршрутизация URL

При объединении нескольких функций контроллера или представления (как угодно их назвать) требуется диспетчер. Простым способом будет применение тестов на основе регулярных выражений к PATH_INFO и вызов зарегистрированных функций обратного вызова, возвращающих значение.

Werkzeug предоставляет гораздо более мощную систему, аналогичную Routes. Все объекты, упомянутые на этой странице, необходимо импортировать из werkzeug.routing, а не из werkzeug!

Быстрый старт

Вот простой пример, который может быть определением URL для блога:

from werkzeug.routing import Map, Rule, NotFound, RequestRedirect

url_map = Map([
    Rule('/', endpoint='blog/index'),
    Rule('/<int:year>/', endpoint='blog/archive'),
    Rule('/<int:year>/<int:month>/', endpoint='blog/archive'),
    Rule('/<int:year>/<int:month>/<int:day>/', endpoint='blog/archive'),
    Rule('/<int:year>/<int:month>/<int:day>/<slug>',
         endpoint='blog/show_post'),
    Rule('/about', endpoint='blog/about_me'),
    Rule('/feeds/', endpoint='blog/feeds'),
    Rule('/feeds/<feed_name>.rss', endpoint='blog/show_feed')
])

def application(environ, start_response):
    urls = url_map.bind_to_environ(environ)
    try:
        endpoint, args = urls.match()
    except HTTPException, e:
        return e(environ, start_response)
    start_response('200 OK', [('Content-Type', 'text/plain')])
    return [f'Rule points to {endpoint!r} with arguments {args!r}'.encode()]

Итак, что это делает? Во-первых, мы создаём новый Map, который хранит множество правил URL. Затем мы передаём ему список объектов Rule.

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

Формат правил URL прост, но подробно объяснён ниже.

Внутри WSGI-приложения мы привязываем url_map к текущему запросу, что вернёт новый MapAdapter. Этот адаптер url_map можно затем использовать для сопоставления или построения доменных имён для текущего запроса.

Метод MapAdapter.match() может вернуть кортеж в формате (endpoint, args) или вызвать одно из трёх исключений NotFound, MethodNotAllowed или RequestRedirect. Более подробную информацию об этих исключениях можно найти в документации метода MapAdapter.match().

Формат правила

Строки правил — это пути URL с плейсхолдерами для переменных частей в формате <converter(arguments):name>. converter и arguments (в скобках) необязательны. Если преобразователь не указан, используется преобразователь default (по умолчанию string). Доступные преобразователи обсуждаются ниже.

Правила, заканчивающиеся слешем, являются «ветвями», другие — «листьями». Если strict_slashes включено (по умолчанию), посещение URL-адреса ветви без заключительного слэша перенаправит на URL-адрес с добавленным слешем.

Многие HTTP-серверы объединяют последовательные слеши в один при получении запросов. Если merge_slashes включено (по умолчанию), правила будут объединять слеши в непеременных частях при сопоставлении и построении. Посещение URL-адреса с последовательными слешами перенаправит на URL-адрес со слитыми слешами. Если вы хотите отключить merge_slashes для Rule или Map, вам также необходимо соответствующим образом настроить свой веб-сервер.

Встроенные преобразователи

Встроенные преобразователи для распространённых типов URL-переменных. Доступные преобразователи можно переопределить или расширить через Map.converters.

class werkzeug.routing.UnicodeConverter(map, minlength=1, maxlength=None, length=None)

Этот преобразователь — по умолчанию, принимает любые строки, но только один сегмент пути. Таким образом, строка не может содержать слеш.

Это значение по умолчанию для валидатора.

Пример:

Rule('/pages/<page>'),
Rule('/<string(length=2):lang_code>')

Параметры:

map (Map) – Map.
minlength (int) – минимальная длина строки. Должна быть больше или равна 1.
maxlength (int | None) – максимальная длина строки.
length (int | None) – точная длина строки.

class werkzeug.routing.PathConverter(map, *args, **kwargs)

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

Rule('/<path:wikipage>')
Rule('/<path:wikipage>/edit')

Параметры:

map (Map) – Map.
args (t.Any) –
kwargs (t.Any) –

class werkzeug.routing.AnyConverter(map, *items)

Соответствует одному из указанных элементов. Элементы могут быть идентификаторами Python или строками:

Rule('/<any(about, help, imprint, class, "foo,bar"):page_name>')

Параметры:

map (Map) – Map.
items (str) – эта функция принимает возможные элементы в качестве позиционных аргументов.

Изменения

Изменено в версии 2.2: Значение валидируется при построении URL.

class werkzeug.routing.IntegerConverter(map, fixed_digits=0, min=None, max=None, signed=False)

Этот преобразователь принимает только целые значения:

Rule("/page/<int:page>")

По умолчанию он принимает только неотрицательные значения. Параметр signed включит возможность использования отрицательных значений.

Rule("/page/<int(signed=True):page>")

Параметры:

map (Map) – Map.
fixed_digits (int) – количество фиксированных цифр в URL. Если вы установите это значение в 4, например, правило будет соответствовать только URL-адресу /0001/. По умолчанию — переменная длина.
min (int | None) – минимальное значение.
max (int | None) – максимальное значение.
signed (bool) – разрешить значения со знаком (отрицательные).

Изменения

Добавлена в версии 0.15: Параметр signed.

class werkzeug.routing.FloatConverter(map, min=None, max=None, signed=False)

Этот преобразователь принимает только значения с плавающей точкой:

Rule("/probability/<float:probability>")

По умолчанию он принимает только положительные значения. Параметр signed включит возможность использования отрицательных значений.

Rule("/offset/<float(signed=True):offset>")

Параметры:

map (Map) – Map.
min (float | None) – минимальное значение.
max (float | None) – максимальное значение.
signed (bool) – разрешить значения со знаком (отрицательные).

Изменения

Добавлена в версии 0.15: Параметр signed.

class werkzeug.routing.UUIDConverter(map, *args, **kwargs)

Этот преобразователь принимает только строки UUID:

Rule('/object/<uuid:identifier>')

Изменения

Добавлена в версии 0.10.

Параметры:

map (Map) – Map.
args (t.Any) –
kwargs (t.Any) –

Карты, правила и адаптеры

class werkzeug.routing.Map(rules=None, default_subdomain='', charset=None, strict_slashes=True, merge_slashes=True, redirect_defaults=True, converters=None, sort_parameters=False, sort_key=None, encoding_errors=None, host_matching=False)

Класс карты хранит все правила URL и некоторые параметры конфигурации. Некоторые значения конфигурации хранятся только в экземпляре Map, так как они влияют на все правила, другие являются просто значениями по умолчанию и могут быть переопределены для каждого правила. Обратите внимание, что вы должны указать все аргументы, кроме rules, в качестве именованных аргументов!

Параметры:

rules (t.Iterable[RuleFactory] | None) – последовательность правил URL для этой карты.
default_subdomain (строка) – По умолчанию домен для правил без указанного домена.
charset (строка | None) – кодировка символов URL. По умолчанию "utf-8"
strict_slashes (булево значение) – Если правило заканчивается слешем, а сопоставленный URL нет, перенаправить на URL с заключительным слешем.
merge_slashes (булево значение) – Объединять последовательные слеши при сопоставлении или построении URL. Сопоставления будут перенаправлять на нормализованный URL. Слеши в переменных частях не объединяются.
redirect_defaults (булево значение) – Перенаправлять на правило по умолчанию, если оно не было посещено таким образом. Это помогает создавать уникальные URL.
converters (t.Mapping[строка, тип[BaseConverter]] | None) – Словарь преобразователей, добавляющий дополнительные преобразователи в список преобразователей. Если вы переопределите преобразователь, это переопределит исходный.
sort_parameters (булево значение) – Если установлено в True, параметры URL сортируются. См. url_encode для получения дополнительной информации.
sort_key (t.Callable[[t.Any], t.Any] | None) – Функция ключа сортировки для url_encode.
encoding_errors (строка | None) – метод обработки ошибок при декодировании
host_matching (булево значение) – Если установлено в True, это включает функцию соответствия хосту и отключает функцию соответствия по домену. Если включено, параметр host к правилам используется вместо subdomain.

Изменено в версии 2.3: Параметры charset и encoding_errors устарели и будут удалены в Werkzeug 3.0.

Журнал изменений

Изменено в версии 1.0: Если url_scheme равно ws или wss, будут сопоставляться только правила WebSocket.

Изменено в версии 1.0: Добавлен параметр merge_slashes.

Изменено в версии 0.7: Добавлены параметры encoding_errors и host_matching.

Изменено в версии 0.5: Добавлены параметры sort_parameters и sort_key.

converters: Словарь преобразователей. Его можно изменить после создания класса, но это повлияет только на правила, добавленные после изменения. Если правила определены со списком, переданным в класс, вместо него необходимо использовать параметр converters конструктора.

add(rulefactory)

Добавить новое правило или фабрику в карту и привязать ее. Требуется, чтобы правило не было привязано к другой карте.

Параметры:: rulefactory (RuleFactory) – Rule или RuleFactory
Тип возвращаемого значения:: None

bind(server_name, script_name=None, subdomain=None, url_scheme='http', default_method='GET', path_info=None, query_args=None)

Возвращает новую MapAdapter с указанными деталями в вызове. Обратите внимание, что script_name будет по умолчанию '/' если не указано иначе или None. Параметр server_name является обязательным, так как RFC HTTP требует абсолютных URL для перенаправлений, и поэтому все исключения перенаправлений, генерируемые Werkzeug, будут содержать полный канонический URL.

Если в match() не передан путь path_info, будет использован путь по умолчанию, переданный в bind. Хотя это не имеет смысла для ручных вызовов bind, это полезно, если вы привязываете карту к среде WSGI, которая уже содержит путь path_info.

subdomain будет по умолчанию default_subdomain для этой карты, если не определено. Если нет default_subdomain, вы не можете использовать функцию соответствия по домену.

Журнал изменений

Изменено в версии 1.0: Если url_scheme равно ws или wss, будут сопоставляться только правила WebSocket.

Изменено в версии 0.15: path_info по умолчанию '/', если None.

Изменено в версии 0.8: query_args может быть строкой.

Изменено в версии 0.7: Добавлен query_args.

Параметры:

server_name (строка) –
script_name (строка | None) –
subdomain (строка | None) –
url_scheme (строка) –
default_method (строка) –
path_info (строка | None) –
query_args (отображение[строка, любой тип] | строка | None) –

Тип возвращаемого значения:

MapAdapter

bind_to_environ(environ, server_name=None, subdomain=None)

Подобно bind(), но вы можете передать ему среду WSGI, и он извлечёт информацию из этого словаря. Обратите внимание, что из-за ограничений протокола невозможно получить текущий поддомен и реальный server_name из среды. Если вы не предоставите их, Werkzeug будет использовать SERVER_NAME и SERVER_PORT (или HTTP_HOST если предоставлено) как используемые server_name с отключённой функцией поддомена.

Если subdomain None, но при этом предоставлены среда и имя сервера, он автоматически рассчитает текущий поддомен. Например: server_name 'example.com', и SERVER_NAME в wsgi environ 'staging.dev.example.com', вычисленный поддомен будет 'staging.dev'.

Если у переданного объекта environ есть атрибут environ, используется значение этого атрибута. Это позволяет передавать объекты запросов. Кроме того, PATH_INFO добавлен в качестве значения по умолчанию для MapAdapter, чтобы вам не приходилось передавать информацию о пути в метод match.

Изменения

Изменено в версии 1.0.0: Если переданное имя сервера указывает порт 443, оно будет соответствовать, если входящая схема — https без порта.

Изменено в версии 1.0.0: Выводится предупреждение, если переданное имя сервера не соответствует входящему имени сервера WSGI.

Изменено в версии 0.8: Это больше не будет генерировать ValueError при передаче неожиданного имени сервера.

Изменено в версии 0.5: ранее этот метод принимал недействительный calculate_subdomain параметр, который не имел никакого эффекта. Он был удален из-за этого.

Параметры:

environ (WSGIEnvironment | Request) – среда WSGI.
server_name (строка | None) – необязательное имя сервера (см. выше).
subdomain (строка | None) – необязательно текущий поддомен (см. выше).

Тип возвращаемого значения:

MapAdapter

default_converters = {'any': <class 'werkzeug.routing.converters.AnyConverter'>, 'default': <class 'werkzeug.routing.converters.UnicodeConverter'>, 'float': <class 'werkzeug.routing.converters.FloatConverter'>, 'int': <class 'werkzeug.routing.converters.IntegerConverter'>, 'path': <class 'werkzeug.routing.converters.PathConverter'>, 'string': <class 'werkzeug.routing.converters.UnicodeConverter'>, 'uuid': <class 'werkzeug.routing.converters.UUIDConverter'>}: Словарь преобразующих функций по умолчанию.

is_endpoint_expecting(endpoint, *arguments)

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

Параметры:

endpoint (строка) – конечная точка для проверки.
arguments (строка) – эта функция принимает один или несколько аргументов как позиционные аргументы. Каждый из них проверяется.

Тип возвращаемого значения:

bool

iter_rules(endpoint=None)

Проходит по всем правилам или правилам конечной точки.

Параметры:: endpoint (строка | None) – если указано, возвращаются только правила для этой конечной точки.
Возвращает:: итератор
Тип возвращаемого значения:: Итератор[Правило]

lock_class(): Тип блокировки, который следует использовать при обновлении.

Изменения

Добавлен в версии 1.0.

update()

Вызывается перед сопоставлением и построением, чтобы сохранить скомпилированные правила в правильном порядке после изменений.

Тип возвращаемого значения:: None

class werkzeug.routing.MapAdapter(map, server_name, script_name, subdomain, url_scheme, path_info, default_method, query_args=None)

Возвращается методом Map.bind() или Map.bind_to_environ() и отвечает за сопоставление и построение URL на основе информации в реальном времени.

Параметры:

map (Map) –
server_name (строка) –
script_name (строка) –
subdomain (строка | None) –
url_scheme (строка) –
path_info (строка) –
default_method (строка) –
query_args (t.Mapping[строка, t.Any] | строка | None) –

allowed_methods(path_info=None)

Возвращает допустимые методы, соответствующие заданному пути.

Изменения

Новая в версии 0.7.

Параметры:: path_info (строка | None) –
Тип возвращаемого значения:: Iterable[строка]

build(endpoint, values=None, method=None, force_external=False, append_unknown=True, url_scheme=None)

Построение URL происходит в обратном порядке. Вместо match вы вызываете build и передаете ему конечную точку и словарь аргументов для замены.

Функция build также принимает аргумент, называемый force_external, который, если вы установите его в значение True, заставит URL быть внешним. По умолчанию внешние URL-адреса (включающие имя сервера) будут использоваться только в том случае, если целевой URL-адрес находится на другом домене.

>>> m = Map([
...     Rule('/', endpoint='index'),
...     Rule('/downloads/', endpoint='downloads/index'),
...     Rule('/downloads/<int:id>', endpoint='downloads/show')
... ])
>>> urls = m.bind("example.com", "/")
>>> urls.build("index", {})
'/'
>>> urls.build("downloads/show", {'id': 42})
'/downloads/42'
>>> urls.build("downloads/show", {'id': 42}, force_external=True)
'http://example.com/downloads/42'

Так как URL-адреса не могут содержать данные, не являющиеся ASCII, вы всегда получите байты. Символы, не являющиеся ASCII, кодируются по правилам URL с кодировкой символов, определенной в экземпляре map.

Дополнительные значения преобразуются в строки и добавляются к URL-адресу в виде параметров запроса:

>>> urls.build("index", {'q': 'My Searchstring'})
'/?q=My+Searchstring'

При обработке этих дополнительных значений списки дополнительно интерпретируются как несколько значений (как в werkzeug.datastructures.MultiDict):

>>> urls.build("index", {'q': ['a', 'b', 'c']})
'/?q=a&q=b&q=c'

Передача MultiDict также добавит несколько значений:

>>> urls.build("index", MultiDict((('p', 'z'), ('q', 'a'), ('q', 'b'))))
'/?p=z&q=a&q=b'

Если правило не существует при построении BuildError, генерируется исключение.

Метод build принимает аргумент, называемый method, который позволяет указать метод, для которого должен быть построен URL, если для одной и той же конечной точки указаны разные методы.

Параметры:

endpoint (строка) – конечная точка URL-адреса.
values (Словарь[строка, любой] | None) – значения для построения URL-адреса. Необработанные значения добавляются в URL-адрес в виде параметров запроса.
method (строка | None) – HTTP-метод для правила, если для одной и той же конечной точки указаны разные URL-адреса для разных методов.
force_external (булево) – принудительно создавать полные канонические внешние URL-адреса. Если схема URL не указана, это сгенерирует URL-адрес с относительной схемой протокола.
append_unknown (булево) – неизвестные параметры добавляются к сгенерированному URL-адресу в качестве параметра строки запроса. Отключите эту опцию, если вы хотите, чтобы генератор игнорировал эти параметры.
url_scheme (строка | None) – Схема, используемая вместо привязанной url_scheme.

Тип возвращаемого значения:

строка

Изменения

Изменено в версии 2.0: Добавлен параметр url_scheme.

Новая в версии 0.6: Добавлен параметр append_unknown.

dispatch(view_func, path_info=None, method=None, catch_http_exceptions=False)

Выполняет весь процесс диспетчеризации. view_func вызывается с конечной точкой и словарем со значениями для представления. Он должен найти функцию представления, вызвать ее и вернуть объект ответа или WSGI-приложение. HTTP-исключения по умолчанию не обрабатываются, чтобы приложения могли отображать более информативные сообщения об ошибках, просто перехватывая их вручную. Если вы хотите использовать стандартные сообщения об ошибках, вы можете передать catch_http_exceptions=True, и оно будет перехватывать HTTP-исключения.

Вот небольшой пример использования диспетчеризации:

from werkzeug.wrappers import Request, Response
from werkzeug.wsgi import responder
from werkzeug.routing import Map, Rule

def on_index(request):
    return Response('Hello from the index')

url_map = Map([Rule('/', endpoint='index')])
views = {'index': on_index}

@responder
def application(environ, start_response):
    request = Request(environ)
    urls = url_map.bind_to_environ(environ)
    return urls.dispatch(lambda e, v: views[e](request, **v),
                         catch_http_exceptions=True)

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

Параметры:

view_func (t.Callable[[строка, t.Mapping[строка, t.Any]], WSGIApplication]) – функция, которая вызывается с конечной точкой в качестве первого аргумента и словарем значений как второго. Должна перенаправить на фактическую функцию представления с этой информацией. (см. выше)
path_info (строка | None) – информация о пути, используемая для сопоставления. Переопределяет информацию о пути, указанную при привязке.
method (строка | None) – HTTP-метод, используемый для сопоставления. Переопределяет метод, указанный при привязке.
catch_http_exceptions (булево) – установите в True для перехвата любых исключений werkzeug HTTPException.

Тип возвращаемого значения:

WSGIApplication

get_host(domain_part)

Определяет полное имя хоста для заданной части домена. Часть домена — это поддомен в случае, если сопоставление хоста отключено, или полное имя хоста.

Параметры:: domain_part (строка | None) –
Тип возвращаемого значения:: строка

make_alias_redirect_url(path, endpoint, values, method, query_args)

Внутренне используется для создания URL перенаправления псевдонима.

Параметры:

path (str) –
endpoint (str) –
values (Mapping[str, Any]) –
method (str) –
query_args (Mapping[str, Any] | str) –

Тип возвращаемого значения:

str

Использование простое: вы передаете методу match текущий путь, а также метод (по умолчанию GET). После этого могут произойти следующие события:

получение исключения NotFound, указывающего, что ни один URL не совпадает. Исключение NotFound также является WSGI-приложением, которое вы можете вызвать для получения стандартной страницы ошибки 404 (оно оказывается тем же объектом, что и werkzeug.exceptions.NotFound)
получение исключения MethodNotAllowed, указывающего, что для этого URL есть соответствие, но не для текущего метода запроса. Это полезно для RESTful-приложений.
получение исключения RequestRedirect с атрибутом new_url. Это исключение используется для уведомления вас о запросе Werkzeug от вашего WSGI-приложения. Это, например, происходит, если вы запрашиваете /foo, хотя правильный URL /foo/ Вы можете использовать экземпляр RequestRedirect как объект-ответ, аналогично всем другим подклассам HTTPException.
получение исключения WebsocketMismatch, если единственное соответствие — правило WebSocket, но привязка — HTTP-запрос, или если соответствие — правило HTTP, но привязка — WebSocket-запрос.
получение кортежа в виде (endpoint, arguments), если есть соответствие (если return_rule не равно True, в этом случае вы получите кортеж в виде (rule, arguments))

Если информация о пути не передается методу match, используется значение по умолчанию для карты (по умолчанию это корневой URL, если он не определен явно).

Все создаваемые исключения являются подклассами HTTPException, поэтому они могут использоваться как WSGI-ответы. Все они будут отображать общие страницы ошибок или перенаправлений.

Вот небольшой пример сопоставления:

>>> m = Map([
...     Rule('/', endpoint='index'),
...     Rule('/downloads/', endpoint='downloads/index'),
...     Rule('/downloads/<int:id>', endpoint='downloads/show')
... ])
>>> urls = m.bind("example.com", "/")
>>> urls.match("/", "GET")
('index', {})
>>> urls.match("/downloads/42")
('downloads/show', {'id': 42})

И вот что происходит при перенаправлении и отсутствии URL:

>>> urls.match("/downloads")
Traceback (most recent call last):
  ...
RequestRedirect: http://example.com/downloads/
>>> urls.match("/missing")
Traceback (most recent call last):
  ...
NotFound: 404 Not Found

Параметры:

path_info – информация о пути для сопоставления. Заменяет информацию о пути, указанную при привязке.
method – HTTP-метод для сопоставления. Заменяет метод, указанный при привязке.
return_rule – возвращает правило, которое совпало, а не только конечную точку (по умолчанию False).
query_args – необязательные параметры запроса, которые используются для автоматических перенаправлений в виде строки или словаря. В настоящее время невозможно использовать параметры запроса для сопоставления URL.
websocket – Сопоставление WebSocket вместо HTTP-запросов. WebSocket-запрос имеет ws или wss url_scheme. Это переопределяет это определение.

Журнал изменений

Введено в версии 1.0: Добавлен websocket.

Изменено в версии 0.8: query_args может быть строкой.

Введено в версии 0.7: Добавлен query_args.

Введено в версии 0.6: Добавлен return_rule.

test(path_info=None, method=None)

Проверка, будет ли соответствовать правило. Работает как match, но возвращает True, если URL совпадает, или False, если его нет.

Параметры:

path_info (str | None) – информация о пути для сопоставления. Заменяет информацию о пути, указанную при привязке.
method (str | None) – HTTP-метод для сопоставления. Заменяет метод, указанный при привязке.

Тип возвращаемого значения:

bool

class werkzeug.routing.Rule(string, defaults=None, subdomain=None, methods=None, build_only=False, endpoint=None, strict_slashes=None, merge_slashes=None, redirect_to=None, alias=False, host=None, websocket=False)

Правило представляет один шаблон URL. Существуют некоторые параметры Rule, которые изменяют его поведение и передаются в конструктор Rule. Обратите внимание, что помимо строки правила все аргументы должны быть именованными аргументами, чтобы не сломать приложение при обновлении Werkzeug.

string

Строки правил, по сути, являются обычными URL-путями с плейсхолдерами в формате <converter(arguments):name>, где преобразователь и аргументы являются необязательными. Если преобразователь не определён, используется преобразователь default, что означает string в стандартной конфигурации.

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

Преобразователи определены в Map.

endpoint

Конечная точка для этого правила. Это может быть что угодно. Ссылка на функцию, строка, число и т. д. Предпочтительный способ — использовать строку, так как конечная точка используется для генерации URL.

defaults

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

url_map = Map([
    Rule('/all/', defaults={'page': 1}, endpoint='all_entries'),
    Rule('/all/page/<int:page>', endpoint='all_entries')
])

Если пользователь теперь посетит http://example.com/all/page/1, он будет перенаправлен на http://example.com/all/. Если redirect_defaults отключена в экземпляре Map, это будет влиять только на генерацию URL.

subdomain

Строка правила для поддомена для этого правила. Если не указано, правило соответствует только default_subdomain карты. Если карта не привязана к поддомену, эта функция отключена.

Может быть полезно, если вы хотите иметь пользовательские профили на разных поддоменах, и все поддомены перенаправляются в ваше приложение:

url_map = Map([
    Rule('/', subdomain='<username>', endpoint='user/homepage'),
    Rule('/stats', subdomain='<username>', endpoint='user/stats')
])

methods

Последовательность HTTP-методов, к которым относится это правило. Если не указано, разрешены все методы. Например, это может быть полезно, если вы хотите разные конечные точки для POST и GET. Если методы определены и путь соответствует, но метод, на который обращаются, не указан в этом списке или в списке другого правила для этого пути, возникает ошибка типа MethodNotAllowed вместо NotFound. Если GET присутствует в списке методов, а HEAD — нет, HEAD добавляется автоматически.

strict_slashes

Переопределяет параметр Map для strict_slashes только для этого правила. Если не указано, используется параметр Map.

merge_slashes

Переопределяет Map.merge_slashes для этого правила.

build_only

Установите это значение в True, и правило никогда не будет соответствовать, но будет создан URL, который можно построить. Это полезно, если у вас есть ресурсы на поддомене или в папке, которые не обрабатываются приложением WSGI (например, статические данные).

redirect_to

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

def foo_with_slug(adapter, id):
    # ask the database for the slug for the old id.  this of
    # course has nothing to do with werkzeug.
    return f'foo/{Foo.get_slug_for_id(id)}'

url_map = Map([
    Rule('/foo/<slug>', endpoint='foo'),
    Rule('/some/old/url/<slug>', redirect_to='foo/<slug>'),
    Rule('/other/old/url/<int:id>', redirect_to=foo_with_slug)
])

При соответствии правилу система маршрутизации поднимет исключение RequestRedirect с целевым объектом для перенаправления.

Помните, что URL будет соединён с корнем URL скрипта, поэтому не используйте ведущий слеш в целевом URL, если вы не имеете в виду корень этого домена.

alias

Если включено, это правило служит псевдонимом для другого правила с той же конечной точкой и аргументами.

host

Если указано и карта URL имеет включенное соответствие по хосту, это можно использовать для предоставления правила соответствия для всего хоста. Это также означает, что функция поддомена отключена.

websocket

Если True, это правило соответствует только запросам WebSocket (ws://, wss://). По умолчанию правила будут соответствовать только HTTP-запросам.

Журнал изменений

Изменено в версии 2.1: Кодированные по проценту новые строки (%0a), которые декодируются серверами WSGI, учитываются при маршрутизации вместо преждевременного прекращения соответствия.

Добавлен в версии 1.0: Добавлен websocket.

Добавлен в версии 1.0: Добавлен merge_slashes.

Добавлен в версии 0.7: Добавлены alias и host.

Изменено в версии 0.6.1: HEAD добавляется к methods если GET присутствует.

Параметры:

string (str) –
defaults (t.Mapping[str, t.Any] | None) –
subdomain (str | None) –
methods (t.Iterable[str] | None) –
build_only (bool) –
endpoint (str | None) –
strict_slashes (bool | None) –
merge_slashes (bool | None) –
redirect_to (str | t.Callable[..., str] | None) –
alias (bool) –
host (str | None) –
websocket (bool) –

empty()

Возвращает не связанную копию этого правила.

Это может быть полезно, если вы хотите повторно использовать уже привязанный URL для другой карты. См. get_empty_kwargs для переопределения именованных аргументов, предоставляемых новой копии.

Тип возвращаемого значения:: Rule

Matchers

class werkzeug.routing.StateMachineMatcher(merge_slashes)

Параметры:: merge_slashes (bool) –

Производители правил

class werkzeug.routing.RuleFactory

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

get_rules(map)

Подклассы RuleFactory должны переопределить этот метод и вернуть итерируемый объект правил.

Параметры:: map (Карта) –
Тип возвращаемого значения:: t.Iterable[Правило]

class werkzeug.routing.Subdomain(subdomain, rules)

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

url_map = Map([
    Rule('/', endpoint='#select_language'),
    Subdomain('<string(length=2):lang_code>', [
        Rule('/', endpoint='index'),
        Rule('/about', endpoint='about'),
        Rule('/help', endpoint='help')
    ])
])

Теперь все правила, кроме конечной точки '#select_language', будут прослушивать поддомены длиной в две буквы, которые содержат код языка для текущего запроса.

Параметры:

subdomain (строка) –
rules (t.Iterable[Производитель правил]) –

class werkzeug.routing.Submount(path, rules)

Как и Subdomain, но добавляет заданную строку в начало правила URL:

url_map = Map([
    Rule('/', endpoint='index'),
    Submount('/blog', [
        Rule('/', endpoint='blog/index'),
        Rule('/entry/<entry_slug>', endpoint='blog/show')
    ])
])

Теперь правило 'blog/show' соответствует /blog/entry/<entry_slug>.

Параметры:

path (строка) –
rules (t.Iterable[Производитель правил]) –

class werkzeug.routing.EndpointPrefix(prefix, rules)

Добавляет префикс к всем конечным точкам (которые должны быть строками для этой фабрики). Это может быть полезно для подприложений:

url_map = Map([
    Rule('/', endpoint='index'),
    EndpointPrefix('blog/', [Submount('/blog', [
        Rule('/', endpoint='index'),
        Rule('/entry/<entry_slug>', endpoint='show')
    ])])
])

Параметры:

prefix (строка) –
rules (t.Iterable[Производитель правил]) –

Шаблоны правил

class werkzeug.routing.RuleTemplate(rules)

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

Вот небольшой пример такого шаблона правила:

from werkzeug.routing import Map, Rule, RuleTemplate

resource = RuleTemplate([
    Rule('/$name/', endpoint='$name.list'),
    Rule('/$name/<int:id>', endpoint='$name.show')
])

url_map = Map([resource(name='user'), resource(name='page')])

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

Параметры:: rules (t.Iterable[Правило]) –

Пользовательские преобразователи

Вы можете добавить пользовательские преобразователи, которые добавляют поведение, не предоставляемое встроенными преобразователями. Чтобы создать пользовательский преобразователь, унаследуйте от BaseConverter, а затем передайте новый класс параметру Map converters параметра или добавьте его в url_map.converters.

Преобразователь должен иметь атрибут regex с регулярным выражением для сопоставления. Если преобразователь может принимать аргументы в правиле URL, он должен принимать их в методе __init__. Вся строка регулярного выражения будет соответствовать в качестве группы и использоваться в качестве значения для преобразования.

Если пользовательский преобразователь может сопоставлять обратную косую черту, /, у него должен быть атрибут part_isolating, установленный в значение False. Это обеспечит правильное сопоставление правил, использующих пользовательский преобразователь.

Он может реализовать метод to_python для преобразования сопоставленной строки в другой объект. Это также может выполнить дополнительную проверку, которая не была возможна с атрибутом regex, и в этом случае должно вызвать исключение werkzeug.routing.ValidationError. Вызов любых других ошибок приведет к ошибке 500.

Он может реализовать метод to_url для преобразования объекта Python в строку при построении URL. Любая ошибка, вызванная здесь, будет преобразована в werkzeug.routing.BuildError и в конечном итоге вызовет ошибку 500.

В этом примере реализован преобразователь BooleanConverter, который будет соответствовать строкам "yes", "no" и "maybe", возвращая случайное значение для "maybe".

from random import randrange
from werkzeug.routing import BaseConverter, ValidationError

class BooleanConverter(BaseConverter):
    regex = r"(?:yes|no|maybe)"

    def __init__(self, url_map, maybe=False):
        super().__init__(url_map)
        self.maybe = maybe

    def to_python(self, value):
        if value == "maybe":
            if self.maybe:
                return not randrange(2)
            raise ValidationError
        return value == 'yes'

    def to_url(self, value):
        return "yes" if value else "no"

from werkzeug.routing import Map, Rule

url_map = Map([
    Rule("/vote/<bool:werkzeug_rocks>", endpoint="vote"),
    Rule("/guess/<bool(maybe=True):foo>", endpoint="guess")
], converters={'bool': BooleanConverter})

Если вы хотите изменить значение по умолчанию преобразователя, назначьте другой преобразователь ключу "default".

Сопоставление по хосту

Изменения

Введено в версии 0.7.

Начиная с Werkzeug 0.7, также возможно выполнять сопоставление по полному имени хоста, а не только по поддомену. Для включения этой функции необходимо передать host_matching=True конструктору Map и указать аргумент host для всех маршрутов:

url_map = Map([
    Rule('/', endpoint='www_index', host='www.example.com'),
    Rule('/', endpoint='help_index', host='help.example.com')
], host_matching=True)

Конечно, переменные части также возможны в разделе хоста:

url_map = Map([
    Rule('/', endpoint='www_index', host='www.example.com'),
    Rule('/', endpoint='user_index', host='<user>.example.com')
], host_matching=True)

Веб-сокеты

Изменения

Введено в версии 1.0.

Если Rule создан с websocket=True, он будет соответствовать только в том случае, если Map привязан к запросу с методом url_scheme ws или wss.

Примечание

Werkzeug не имеет дальнейшей поддержки WebSocket за пределами маршрутизации. Эта функция в основном полезна для проектов ASGI.

url_map = Map([
    Rule("/ws", endpoint="comm", websocket=True),
])
adapter = map.bind("example.org", "/ws", url_scheme="ws")
assert adapter.match() == ("comm", {})

Если единственным соответствием является правило WebSocket, а привязка — HTTP (или единственным соответствием является HTTP, а привязка — WebSocket), возникает исключение WebsocketMismatch (производное от BadRequest).

Поскольку URL-адреса WebSocket имеют другой протокол, правила всегда создаются со схемой и хостом, force_external=True подразумевается.

url = adapter.build("comm")
assert url == "ws://example.org/ws"

Сопоставление с помощью конечного автомата

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

/resource/<id>

Во-первых, это правило разлагается на две RulePart. Первая — это статическая часть со значением resource, вторая — динамическая и требует соответствия регулярному выражению resource.

Затем создаётся конечный автомат с начальным состоянием, которое представляет первую / правила. У этого начального состояния есть одно статическое переключение на следующее состояние, которое представляет вторую / правила. У этого второго состояния есть одно динамическое переключение на конечное состояние, которое включает само правило.

Для сопоставления пути сопоставитель начинает с начального состояния и следует переходам, которые работают. Очевидно, что пробный путь /resource/2 имеет части "", resource и 2, которые соответствуют переходам, и поэтому правило будет соответствовать. В то время как /other/2 не будет соответствовать, так как нет перехода для части other от начального состояния.

Единственное отклонение от этого правила — если RulePart не является изолирующим по частям, то есть он будет соответствовать /. В этом случае RulePart считается конечным и представляет собой переход, который должен включать все последующие части пробного пути.