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

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

Вот простой пример, который может быть определением 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='', strict_slashes=True, merge_slashes=True, redirect_defaults=True, converters=None, sort_parameters=False, sort_key=None, host_matching=False)

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

Параметры:

• rules (t.Iterable[RuleFactory] | None) – последовательность правил URL для этой карты.
• default_subdomain (строка) – По умолчанию домен для правил без определенного домена.
• 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.
• host_matching (логическое значение) – если установлено значение True, это включит функцию соответствия хосту и отключит функцию соответствия поддоменам. При включении параметр host правил используется вместо параметра subdomain.

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

Изменения

Изменено в версии 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-адрес.

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

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, чтобы вам не приходилось передавать информацию о пути в метод сопоставления.

Changelog

Изменено в версии 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) – если указано, возвращаются только правила для этой конечной точки.

Возвращаемое значение:

итератор

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

Итератор[Rule]

lock_class()

Тип блокировки для использования при обновлении.

Changelog

Новое в версии 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 (str) –
• script_name (str) –
• subdomain (str | None) –
• url_scheme (str) –
• path_info (str) –
• default_method (str) –
• query_args (t.Mapping[str, t.Any] | str | None) –

allowed_methods(path_info=None)

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

Изменения

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

Параметры:

path_info (str | None) –

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

Iterable[str]

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, будут закодированы в соответствии с набором символов, определённым в экземпляре объекта 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 (str) – конечная точка URL для построения.
• values (Mapping[str, Any] | None) – значения для построения URL. Необработанные значения добавляются в URL в качестве параметров запроса.
• method (str | None) – HTTP-метод для правила, если для одной и той же конечной точки имеются разные URL для разных методов.
• force_external (bool) – принудительно использовать полные канонические внешние URL. Если схема URL не указана, это создаст URL с протоколом-относительным URL.
• append_unknown (bool) – неизвестные параметры добавляются к сгенерированному URL в качестве параметра строки запроса. Отключите это, если вы хотите, чтобы билдер игнорировал их.
• url_scheme (str | None) – Схема, используемая вместо привязанного url_scheme.

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

str

Изменения

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

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

WSGIApplication

get_host(domain_part)

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

Параметры:

domain_part (str | None) –

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

str

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(path_info: str | None = None, method: str | None = None, return_rule: Literal[False] = False, query_args: Mapping[str, Any] | str | None = None, websocket: bool | None = None) → tuple[str, Mapping[str, Any]]

match(path_info:str|None=None, method:str|None=None, return_rule:Literal[True]=True, query_args:Mapping[str,Any]|str|None=None, websocket:bool|None=None) → tuple[werkzeug.routing.rules.Rule,Mapping[str,Any]]

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

• получение исключения NotFound, указывающего, что ни один URL не соответствует. Исключение NotFound также является WSGI-приложением, которое можно вызвать для получения страницы по умолчанию с ошибкой «страница не найдена» (оно совпадает с объектом 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-запросам.

Changelog

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

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

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

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

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

Parameters:

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

Return type:

Rule

Matchers

class werkzeug.routing.StateMachineMatcher(merge_slashes)

Parameters:

merge_slashes (bool) –

Правила-фабрики

class werkzeug.routing.RuleFactory

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

get_rules(map)

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

Параметры:

map (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".

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

Начиная с 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)

Веб-сокеты

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

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

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

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

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

Сопоставление по состоянию машины

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

/resource/<id>

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

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

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

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