Маршрутизация 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 (Optional[int]) – максимальная длина строки.
• length (Optional[int]) – точная длина строки.

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

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

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

Параметры:

• map (Map) – карта Map.
• args (Any) –
• kwargs (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 (Optional[int]) – минимальное значение.
• max (Optional[int]) – максимальное значение.
• 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 (Optional[float]) – минимальное значение.
• max (Optional[float]) – максимальное значение.
• signed (bool) – разрешить значения со знаком (отрицательные).

Изменения

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

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

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

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

Изменения

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

Параметры:

• map (Map) – карта Map.
• args (Any) –
• kwargs (Any) –

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

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

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

Параметры:

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

Изменения

Изменено в версии 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 является обязательным, так как HTTP RFC требует абсолютных 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 (str) –
• script_name (Optional[str]) –
• subdomain (Optional[str]) –
• url_scheme (str) –
• default_method (str) –
• path_info (Optional[str]) –
• query_args (Optional[Union[Mapping[str, Any], str]]) –

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

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 (Union[WSGIEnvironment, Request]) – WSGI-окружение.
• server_name (Optional[str]) – необязательное имя сервера (см. выше).
• subdomain (Optional[str]) – необязательно текущий поддомен (см. выше).

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

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 (str) – конечная точка для проверки.
• arguments (str) – эта функция принимает один или несколько аргументов как позиционные аргументы. Каждый из них проверяется.

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

bool

iter_rules(endpoint=None)

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

Параметры:

endpoint (Optional[str]) – если предоставлено, возвращаются только правила для этой конечной точки.

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

итератор

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

Iterator[Rule]

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 (str) –
• script_name (str) –
• subdomain (Optional[str]) –
• url_scheme (str) –
• path_info (str) –
• default_method (str) –
• query_args (Optional[Union[Mapping[str, Any], str]]) –

allowed_methods(path_info=None)

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

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

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

Параметры:

path_info (Optional[str]) –

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

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, кодируются в URL с помощью набора символов, определенного в экземпляре карты.

Дополнительные значения преобразуются в строки и добавляются к 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 (Optional[Mapping[str, Any]]) – значения для построения URL. Необработанные значения добавляются к URL в качестве параметров запроса.
• method (Optional[str]) – HTTP-метод для правила, если для одной и той же конечной точки указаны разные URL для различных методов.
• force_external (bool) – принудительно формировать полные канонические внешние URL-адреса. Если схема URL не указана, это сгенерирует URL с относительным протоколом.
• append_unknown (bool) – неизвестные параметры добавляются к сгенерированному URL в качестве аргументов строки запроса. Отключите это, если вы хотите, чтобы генератор игнорировал эти значения.
• url_scheme (Optional[str]) – Схема для использования вместо связанной 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 (Callable[[str, Mapping[str, Any]], WSGIApplication]) – функция, которая вызывается с конечной точкой в качестве первого аргумента и словарем значений во втором. Должна передать управление фактической функции представления с этой информацией. (см. выше)
• path_info (Optional[str]) – информация о пути для сопоставления. Переопределяет информацию о пути, указанную при связывании.
• method (Optional[str]) – HTTP-метод, используемый для сопоставления. Переопределяет метод, указанный при связывании.
• catch_http_exceptions (bool) – установить в True для перехвата любых исключений Werkzeug HTTPException.

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

WSGIApplication

get_host(domain_part)

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

Параметры:

domain_part (Optional[str]) –

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

str

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

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

Параметры:

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

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

str

match(path_info: Optional[str] = None, method: Optional[str] = None, return_rule: te.Literal[False] = False, query_args: Optional[Union[Mapping[str, Any], str]] = None, websocket: Optional[bool] = None) → Tuple[str, Mapping[str, Any]]

match(path_info:Optional[str]=None, method:Optional[str]=None, return_rule:te.Literal[True]=True, query_args:Optional[Union[Mapping[str,Any],str]]=None, websocket:Optional[bool]=None) → Tuple[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 (Optional[str]) – информация о пути для сопоставления. Переопределяет информацию о пути, указанную при связывании.
• method (Optional[str]) – 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-правила, заканчивающиеся слешем, являются URL-адресами ветвей, а другие — листьями. Если включён strict_slashes (что является значением по умолчанию), все URL-адреса ветвей, которые совпадают без заключительного слеша, будут перенаправлены на тот же 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 (Optional[Mapping[str, Any]]) –
• subdomain (Optional[str]) –
• methods (Optional[Iterable[str]]) –
• build_only (bool) –
• endpoint (Optional[str]) –
• strict_slashes (Optional[bool]) –
• merge_slashes (Optional[bool]) –
• redirect_to (Optional[Union[str, Callable[[...], str]]]) –
• alias (bool) –
• host (Optional[str]) –
• websocket (bool) –

empty()

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

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

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

Rule

Сопоставители

class werkzeug.routing.StateMachineMatcher(merge_slashes)

Параметры:

merge_slashes (bool) –

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

class werkzeug.routing.RuleFactory

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

get_rules(map)

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

Параметры:

map (Map) –

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

Iterable[Rule]

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 (str) –
• rules (Iterable[RuleFactory]) –

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 (str) –
• rules (Iterable[RuleFactory]) –

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 (str) –
• rules (Iterable[RuleFactory]) –

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

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 (Iterable[Rule]) –

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

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