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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Это стандартный валидатор.

Пример:

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

Параметры:

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

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

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

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

Параметры:

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

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

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

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

Параметры:

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

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

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

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

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

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

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

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

Параметры:

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

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

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

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

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

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

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

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

Параметры:

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

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

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

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

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

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

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

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

Параметры:

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

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

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

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

Параметры:

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

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

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

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

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

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

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

converters

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

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'>}

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

lock_class()

Тип блокировки, используемой при обновлении.

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

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

is_endpoint_expecting(endpoint, *arguments)

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

Параметры:

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

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

bool

iter_rules(endpoint=None)

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

Параметры:

endpoint (Any | None) – если указано, возвращаются только правила для этой конечной точки.

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

итератор

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

Iterator[Rule]

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 отсутствует, функция поддомена недоступна.

Changelog

Изменено в версии 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 (str | None)
• subdomain (str | None)
• url_scheme (str)
• default_method (str)
• path_info (str | None)
• query_args (Mapping[str, Any] | str | None)

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

MapAdapter

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

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

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

Если переданный объект environ имеет атрибут environ, используется значение этого атрибута. Это позволяет передавать объекты запроса. Дополнительно PATH_INFO добавлен в качестве значения по умолчанию для MapAdapter, чтобы не нужно было передавать path info в метод match.

Changelog

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

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

Изменено в версии 0.8: Эта функция больше не будет вызывать ValueError, когда было передано неожиданное имя сервера.

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

Параметры:

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

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

MapAdapter

update()

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

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

None

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

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

Параметры:

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

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

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

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

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

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

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

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

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

Параметры:

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

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

WSGIApplication

match(path_info: str | None = None, method: str | None = None, return_rule: Literal[False] = False, query_args: Mapping[str, Any] | str | None = None, websocket: bool | None = None) → tuple[Any, Mapping[str, Any]]

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

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

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

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

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

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

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

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

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

Параметры:

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

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

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

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

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

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

test(path_info=None, method=None)

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

Параметры:

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

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

bool

allowed_methods(path_info=None)

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

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

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

Параметры:

path_info (str | None)

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

Iterable[str]

get_host(domain_part)

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

Параметры:

domain_part (str | None)

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

str

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

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

Параметры:

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

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

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

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

str

Изменения

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

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

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 (t.Mapping[str, t.Any] | None)
• subdomain (str | None)
• methods (t.Iterable[str] | None)
• build_only (bool)
• endpoint (t.Any | None)
• strict_slashes (bool | None)
• merge_slashes (bool | None)
• redirect_to (str | t.Callable[..., str] | None)
• alias (bool)
• host (str | None)
• websocket (bool)

empty()

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

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

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

Правило

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

class werkzeug.routing.StateMachineMatcher(merge_slashes)

Параметры:

merge_slashes (bool)

Фабрики правил

class werkzeug.routing.RuleFactory

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

get_rules(map)

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

Параметры:

map (Map)

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

t.Iterable[Правило]

class werkzeug.routing.Subdomain(subdomain, rules)

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

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

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

Параметры:

• subdomain (строка)
• rules (t.Iterable[Фабрика правил])

class werkzeug.routing.Submount(path, rules)

Подобно Subdomain , но добавляет префикс к правилу URL заданной строкой:

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

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

Параметры:

• path (строка)
• rules (t.Iterable[Фабрика правил])

class werkzeug.routing.EndpointPrefix(prefix, rules)

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

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

Параметры:

• prefix (строка)
• rules (t.Iterable[Фабрика правил])

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

class werkzeug.routing.RuleTemplate(rules)

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

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

from werkzeug.routing import Map, Rule, RuleTemplate

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

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

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

Параметры:

rules (t.Iterable[Правило])

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

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

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

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

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

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

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

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

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

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

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

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

from werkzeug.routing import Map, Rule

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

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

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

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

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

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

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

Веб-сокеты

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

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

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

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

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

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

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

/resource/<id>

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

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

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

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