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

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

None

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

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

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

Параметры

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

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

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 (Optional[int]) – минимальное значение.
• max (Optional[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 (Optional[float]) – минимальное значение.
• max (Optional[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 (Any) –
• kwargs (Any) –

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

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 является обязательным, поскольку спецификация 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 (Необязательный[строка]) –
• 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, чтобы вам не приходилось передавать информацию о пути в метод сопоставления.

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

Изменено в версии 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.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 (Optional[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 (Optional[строка]) –
• url_scheme (строка) –
• path_info (строка) –
• default_method (строка) –
• query_args (Optional[Union[Mapping[строка, любой], строка]]) –

allowed_methods(path_info=None)

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

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

Новая функция в версии 0.7.

Параметры

path_info (Optional[строка]) –

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

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

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

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

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

Изменено в версии 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 (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) –

Return type

None

empty()

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

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

Return type

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[werkzeug.routing.RuleFactory]) –

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

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[werkzeug.routing.RuleFactory]) –

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

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[werkzeug.routing.RuleFactory]) –

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

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

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

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", {})

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

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

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