Маршрутизация 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}']

Итак, что это делает? Во-первых, мы создаём новый 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]) – максимальная длина строки.
• length (Необязательно[int]) – точная длина строки.

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

None

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

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

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

Параметры

• map (Map) – Map.
• args (Любое) –
• kwargs (Любое) –

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

None

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

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

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

Параметры

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

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

None

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

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

None

Изменения

В версии 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]) – минимальное значение.
• max (Необязательно[float]) – максимальное значение.
• signed (bool) – разрешить знакомые (отрицательные) значения.

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

None

Изменения

В версии 0.15: Параметр signed.

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

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

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

Изменения

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

Параметры

• map (Map) – Map.
• args (Любое) –
• kwargs (Любое) –

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

None

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

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 (Необязательно[Итерируемый[werkzeug.routing.RuleFactory]]) – последовательность правил URL для этой карты.
• default_subdomain (строка) – значение домена по умолчанию для правил без указанного домена.
• charset (строка) – кодировка URL. По умолчанию "utf-8"
• strict_slashes (логическое значение) – если правило заканчивается слешем, а соответствующий URL — нет, перенаправить на URL с конечным слешем.
• merge_slashes (логическое значение) – объединять последовательные слеши при сопоставлении или построении URL-адресов. Сопоставления будут перенаправлять на нормализованный URL-адрес. Слеши в переменных частях не объединяются.
• redirect_defaults (логическое значение) – перенаправлять на правило по умолчанию, если оно не было посещено таким образом. Это помогает создавать уникальные URL.
• converters (Необязательно[Отображение[строка, Тип[werkzeug.routing.BaseConverter]]]) – словарь преобразователей, добавляющий дополнительные преобразователи в список преобразователей. Если вы переопределяете преобразователь, это переопределит исходный.
• sort_parameters (логическое значение) – если установлено в True, параметры URL сортируются. См. url_encode для получения более подробной информации.
• sort_key (Необязательно[Вызываемая функция[[Любой], Любой]]) – функция сортировки для url_encode.
• encoding_errors (строка) – метод обработки ошибок при декодировании
• host_matching (логическое значение) – если установлено в True, это включает функцию проверки хоста и отключает функцию проверки домена. Если включено, параметр host в правилах используется вместо subdomain.

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

None

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

Изменено в версии 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 (werkzeug.routing.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, оно будет использовать значение 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 (Необязательно[строка]) –
• subdomain (Необязательно[строка]) –
• url_scheme (строка) –
• default_method (строка) –
• path_info (Необязательно[строка]) –
• query_args (Необязательно[Объединение[Отображение[строка, Любой], строка]]) –

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

werkzeug.routing.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: ранее этот метод принимал параметр bogus calculate_subdomain, который не оказывал никакого влияния. Он был удалён из-за этого.

Параметры

• environ (WSGIEnvironment) – среда WSGI.
• server_name (Необязательно[str]) – необязательное имя сервера (см. выше).
• subdomain (Необязательно[str]) – необязательно, текущий домен второго уровня (см. выше).

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

MapAdapter

default_converters = {'any': <class 'werkzeug.routing.AnyConverter'>, 'default': <class 'werkzeug.routing.UnicodeConverter'>, 'float': <class 'werkzeug.routing.FloatConverter'>, 'int': <class 'werkzeug.routing.IntegerConverter'>, 'path': <class 'werkzeug.routing.PathConverter'>, 'string': <class 'werkzeug.routing.UnicodeConverter'>, 'uuid': <class 'werkzeug.routing.UUIDConverter'>}

Словарь конвертеров по умолчанию.

is_endpoint_expecting(endpoint, *arguments)

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

Параметры

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

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

bool

iter_rules(endpoint=None)

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

Параметры

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

Возвращает

итератор

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

Iterator[werkzeug.routing.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 (werkzeug.routing.Map) –
• server_name (строка) –
• script_name (строка) –
• subdomain (Необязательно[строка]) –
• url_scheme (строка) –
• path_info (строка) –
• default_method (строка) –
• query_args (Необязательно[Union[Mapping[строка, любой тип], строка]]) –

allowed_methods(path_info=None)

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

Изменения

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

Параметры

path_info (Необязательно[строка]) –

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

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

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

WSGIApplication

get_host(domain_part)

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

Параметры

domain_part (Необязательно[строка]) –

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

строка

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=None, method=None, return_rule=False, query_args=None, websocket=None)

Использование простое: вы просто передаёте методу 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 (Optional[str]) – информация о пути для сопоставления. Переопределяет информацию о пути, указанную при привязке.
• method (Optional[str]) – HTTP-метод, используемый для сопоставления. Переопределяет метод, указанный при привязке.
• return_rule (bool) – возвращает правило, которое соответствует, а не только конечную точку (по умолчанию False).
• query_args (Optional[Union[Mapping[str, Any], str]]) – необязательные аргументы запроса, используемые для автоматических перенаправлений в виде строки или словаря. В настоящее время невозможно использовать аргументы запроса для сопоставления URL.
• websocket (Optional[bool]) – Сопоставить WebSocket, а не запросы HTTP. Запрос WebSocket имеет ws или wss url_scheme. Это переопределяет это обнаружение.

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

Tuple[Union[str, werkzeug.routing.Rule], Mapping[str, Any]]

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

Новое в версии 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, заканчивающиеся слешем, являются правилами ветвления, остальные — листьями. Если включено 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-запросам.

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

Введено в версии 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) –

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

None

empty()

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

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

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

werkzeug.routing.Rule

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

class werkzeug.routing.RuleFactory

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

get_rules(map)

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

Параметры

map (werkzeug.routing.Map) –

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

Iterable[werkzeug.routing.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[Правило]) –

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

None

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[Правило]) –

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

None

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[Правило]) –

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

None

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

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[Правило]) –

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

None

Пользовательские конвертеры

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

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

Он может реализовать метод 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"