werkzeug.routing.rules.Rule

class documentation

class Rule(RuleFactory): (source)

A Rule represents one URL pattern. There are some options for `Rule` that change the way it behaves and are passed to the `Rule` constructor. Note that besides the rule-string all arguments *must* be keyword arguments in order to not break the application on Werkzeug upgrades. `string` Rule strings basically are just normal URL paths with placeholders in the format ``<converter(arguments):name>`` where the converter and the arguments are optional. If no converter is defined the `default` converter is used which means `string` in the normal configuration. URL rules that end with a slash are branch URLs, others are leaves. If you have `strict_slashes` enabled (which is the default), all branch URLs that are matched without a trailing slash will trigger a redirect to the same URL with the missing slash appended. The converters are defined on the `Map`. `endpoint` The endpoint for this rule. This can be anything. A reference to a function, a string, a number etc. The preferred way is using a string because the endpoint is used for URL generation. `defaults` An optional dict with defaults for other rules with the same endpoint. This is a bit tricky but useful if you want to have unique URLs:: url_map = Map([ Rule('/all/', defaults={'page': 1}, endpoint='all_entries'), Rule('/all/page/<int:page>', endpoint='all_entries') ]) If a user now visits ``http://example.com/all/page/1`` they will be redirected to ``http://example.com/all/``. If `redirect_defaults` is disabled on the `Map` instance this will only affect the URL generation. `subdomain` The subdomain rule string for this rule. If not specified the rule only matches for the `default_subdomain` of the map. If the map is not bound to a subdomain this feature is disabled. Can be useful if you want to have user profiles on different subdomains and all subdomains are forwarded to your application:: url_map = Map([ Rule('/', subdomain='<username>', endpoint='user/homepage'), Rule('/stats', subdomain='<username>', endpoint='user/stats') ]) `methods` A sequence of http methods this rule applies to. If not specified, all methods are allowed. For example this can be useful if you want different endpoints for `POST` and `GET`. If methods are defined and the path matches but the method matched against is not in this list or in the list of another rule for that path the error raised is of the type `MethodNotAllowed` rather than `NotFound`. If `GET` is present in the list of methods and `HEAD` is not, `HEAD` is added automatically. `strict_slashes` Override the `Map` setting for `strict_slashes` only for this rule. If not specified the `Map` setting is used. `merge_slashes` Override :attr:`Map.merge_slashes` for this rule. `build_only` Set this to True and the rule will never match but will create a URL that can be build. This is useful if you have resources on a subdomain or folder that are not handled by the WSGI application (like static data) `redirect_to` If given this must be either a string or callable. In case of a callable it's called with the url adapter that triggered the match and the values of the URL as keyword arguments and has to return the target for the redirect, otherwise it has to be a string with placeholders in rule syntax:: 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) ]) When the rule is matched the routing system will raise a `RequestRedirect` exception with the target for the redirect. Keep in mind that the URL will be joined against the URL root of the script so don't use a leading slash on the target URL unless you really mean root of that domain. `alias` If enabled this rule serves as an alias for another rule with the same endpoint and arguments. `host` If provided and the URL map has host matching enabled this can be used to provide a match rule for the whole host. This also means that the subdomain feature is disabled. `websocket` If ``True``, this rule is only matches for WebSocket (``ws://``, ``wss://``) requests. By default, rules will only match for HTTP requests. .. versionchanged:: 2.1 Percent-encoded newlines (``%0a``), which are decoded by WSGI servers, are considered when routing instead of terminating the match early. .. versionadded:: 1.0 Added ``websocket``. .. versionadded:: 1.0 Added ``merge_slashes``. .. versionadded:: 0.7 Added ``alias`` and ``host``. .. versionchanged:: 0.6.1 ``HEAD`` is added to ``methods`` if ``GET`` is present.

Method	`__eq__`	Undocumented
Method	`__init__`	Undocumented
Method	`__repr__`	Undocumented
Method	`__str__`	Undocumented
Method	`bind`	Bind the url to a map and create a regular expression based on the information from the rule itself and the defaults from the map.
Method	`build`	Assembles the relative url for that rule and the subdomain. If building doesn't work for some reasons `None` is returned.
Method	`build_compare_key`	The build compare key for sorting.
Method	`compile`	Compiles the regular expression and stores it.
Method	`empty`	Return an unbound copy of this rule.
Method	`get_converter`	Looks up the converter for the given parameter.
Method	`get_empty_kwargs`	Provides kwargs for instantiating empty copy with empty()
Method	`get_rules`	Subclasses of `RuleFactory` have to override this method and return an iterable of rules.
Method	`provides_defaults_for`	Check if this rule has defaults for a given rule.
Method	`refresh`	Rebinds and refreshes the URL. Call this if you modified the rule in place.
Method	`suitable_for`	Check if the dict of values has enough data for url generation.
Class Variable	`__hash__`	Undocumented
Instance Variable	`alias`	Undocumented
Instance Variable	`arguments`	Undocumented
Instance Variable	`build_only`	Undocumented
Instance Variable	`defaults`	Undocumented
Instance Variable	`endpoint`	Undocumented
Instance Variable	`host`	Undocumented
Instance Variable	`is_branch`	Undocumented
Instance Variable	`is_leaf`	Undocumented
Instance Variable	`map`	Undocumented
Instance Variable	`merge_slashes`	Undocumented
Instance Variable	`methods`	Undocumented
Instance Variable	`redirect_to`	Undocumented
Instance Variable	`rule`	Undocumented
Instance Variable	`strict_slashes`	Undocumented
Instance Variable	`subdomain`	Undocumented
Instance Variable	`websocket`	Undocumented
Static Method	`_get_func_code`	Undocumented
Method	`_compile_builder`	Undocumented
Method	`_encode_query_vars`	Undocumented
Method	`_parse_rule`	Undocumented
Instance Variable	`_build`	Undocumented
Instance Variable	`_build_unknown`	Undocumented
Instance Variable	`_converters`	Undocumented
Instance Variable	`_parts`	Undocumented
Instance Variable	`_trace`	Undocumented

def __eq__(self, other: object) -> bool: (source) ¶

Undocumented

def __init__(self, string: str, defaults: t.Optional[t.Mapping[str, t.Any]] = None, subdomain: t.Optional[str] = None, methods: t.Optional[t.Iterable[str]] = None, build_only: bool = False, endpoint: t.Optional[str] = None, strict_slashes: t.Optional[bool] = None, merge_slashes: t.Optional[bool] = None, redirect_to: t.Optional[t.Union[str, t.Callable[..., str]]] = None, alias: bool = False, host: t.Optional[str] = None, websocket: bool = False): (source) ¶

Undocumented

def __repr__(self) -> str: (source) ¶

Undocumented

def __str__(self) -> str: (source) ¶

Undocumented

def bind(self, map: Map, rebind: bool = False): (source) ¶

Bind the url to a map and create a regular expression based on the information from the rule itself and the defaults from the map. :internal:

def build(self, values: t.Mapping[str, t.Any], append_unknown: bool = True) -> t.Optional[t.Tuple[str, str]]: (source) ¶

Assembles the relative url for that rule and the subdomain. If building doesn't work for some reasons `None` is returned. :internal:

def build_compare_key(self) -> t.Tuple[int, int, int]: (source) ¶

The build compare key for sorting. :internal:

def compile(self): (source) ¶

Compiles the regular expression and stores it.

def empty(self) -> Rule: (source) ¶

Return an unbound copy of this rule. This can be useful if want to reuse an already bound URL for another map. See ``get_empty_kwargs`` to override what keyword arguments are provided to the new copy.

def get_converter(self, variable_name: str, converter_name: str, args: t.Tuple, kwargs: t.Mapping[str, t.Any]) -> BaseConverter: (source) ¶

Looks up the converter for the given parameter. .. versionadded:: 0.9

def get_empty_kwargs(self) -> t.Mapping[str, t.Any]: (source) ¶

Provides kwargs for instantiating empty copy with empty() Use this method to provide custom keyword arguments to the subclass of ``Rule`` when calling ``some_rule.empty()``. Helpful when the subclass has custom keyword arguments that are needed at instantiation. Must return a ``dict`` that will be provided as kwargs to the new instance of ``Rule``, following the initial ``self.rule`` value which is always provided as the first, required positional argument.