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

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

Werkzeug предоставляет гораздо более мощную систему, аналогичную Routes. Все объекты, упомянутые на этой странице, необходимо импортировать из werkzeug.routing, а не из werkzeug!

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

Вот простой пример, который может быть определением 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 ['Rule points to %r with arguments %r' % (endpoint, args)]

Итак, что это делает? Прежде всего, мы создаем новую 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. minlength – минимальная длина строки. Должна быть больше или равна 1. maxlength – максимальная длина строки. length – точная длина строки.

class werkzeug.routing.PathConverter(map)

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

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

Параметры:	map – Map.

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

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

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

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

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. fixed_digits – количество фиксированных цифр в URL. Если вы установите его, например, в 4, правило будет соответствовать только тому случаю, когда URL выглядит как /0001/. По умолчанию длина переменная. min – минимальное значение. max – максимальное значение. signed – разрешить знакомые (отрицательные) значения.

Изменения

Добавлено в версии 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. min – минимальное значение. max – максимальное значение. signed – разрешить знакомые (отрицательные) значения.

Изменения

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

class werkzeug.routing.UUIDConverter(map)

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

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

Изменения

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

Параметры:	map – Map.

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

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)

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

Параметры:

rules – последовательность правил URL для этой карты. default_subdomain – Поддомен по умолчанию для правил без определённого поддомена. charset – кодировка URL. По умолчанию "utf-8" strict_slashes – Если правило заканчивается слешем, а URL не заканчивается слешем, перенаправить на URL с конечным слешем. merge_slashes – Объединять последовательные слеши при сопоставлении или построении URL. Сопоставления будут перенаправлять на нормализованный URL. Слеши в переменных частях не объединяются. redirect_defaults – Перенаправлять на правило по умолчанию, если оно не было посещено таким образом. Это помогает создавать уникальные URL. converters – Словарь конвертеров, добавляющий дополнительные конвертеры в список конвертеров. Если вы переопределяете один конвертер, он перекроет исходный. sort_parameters – Если установлено True, параметры URL сортируются. Смотрите url_encode для получения дополнительной информации. sort_key – Функция сортировки для url_encode. encoding_errors – Метод обработки ошибок при декодировании host_matching – Если установлено True, это включает функцию сопоставления хоста и отключает функцию поддомена. При включении используется параметр host к правилам вместо subdomain.

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

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

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

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

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

converters

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

add(rulefactory)

Добавить новое правило или фабрику в карту и связать её. Требуется, чтобы правило не было связано с другой картой.

Параметры:	rulefactory – объект Rule или RuleFactory

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.

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

subdomain по умолчанию будет default_subdomain для этой карты, если не определён. Если default_subdomain не задан, вы не можете использовать функцию поддомена.

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

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

Изменено в версии 0.15: path_info по умолчанию '/' если None.

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

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

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

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

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

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

Изменено в версии 0.8: Этот метод больше не будет генерировать ValueError при передаче неожиданного имени сервера.

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

Параметры:	environ – WSGI среда. server_name – необязательное имя сервера (см. выше). subdomain – необязательно, текущий поддомен (см. выше).

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

iter_rules(endpoint=None)

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

Параметры:	endpoint – если задано, возвращаются только правила для этой конечной точки.
Возвращает:	итератор

lock_class()

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

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

update()

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

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 на основе информации во время выполнения.

allowed_methods(path_info=None)

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

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

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

build(endpoint, values=None, method=None, force_external=False, append_unknown=True)

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

Дополнительные значения преобразуются в unicode и добавляются в 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, если для одной и той же конечной точки определены разные методы.

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

Новая версия с 0.6: был добавлен параметр append_unknown.

Параметры:

endpoint – конечная точка URL. values – значения для построения URL. Необработанные значения добавляются в URL в качестве параметров запроса. method – HTTP-метод для правила, если для одной и той же конечной точки существуют разные URL для разных методов. force_external – принудительно использовать полные канонические внешние URL. Если схема URL не указана, это сгенерирует URL-адрес с относительной схемой протокола. append_unknown – неизвестные параметры добавляются в сгенерированный URL в качестве аргумента строки запроса. Отключите это, если вы хотите, чтобы билдер игнорировал их.

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

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

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

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

get_host(domain_part)

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

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

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

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 – информация о пути, используемая для сопоставления. Переопределяет информацию о пути, указанную при привязке. 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 – информация о пути, используемая для сопоставления. Переопределяет информацию о пути, указанную при привязке. method – HTTP-метод, используемый для сопоставления. Переопределяет метод, указанный при привязке.

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 '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-запросам.

New in version 1.0: Added websocket.

New in version 1.0: Added merge_slashes.

Changelog

New in version 0.7: Added alias и host.

Changed in version 0.6.1: HEAD добавлен в methods если GET присутствует.

empty()

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

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

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

class werkzeug.routing.RuleFactory

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

get_rules(map)

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

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

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>.

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')
    ])])
])

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

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')])

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

Настраиваемые преобразователи

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