Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/werkzeug/routing/__init__.py: 100%

1"""When it comes to combining multiple controller or view functions 

2(however you want to call them) you need a dispatcher. A simple way 

3would be applying regular expression tests on the ``PATH_INFO`` and 

4calling registered callback functions that return the value then. 

5 

6This module implements a much more powerful system than simple regular 

7expression matching because it can also convert values in the URLs and 

8build URLs. 

9 

10Here a simple example that creates a URL map for an application with 

11two subdomains (www and kb) and some URL rules: 

12 

13.. code-block:: python 

14 

15 m = Map([ 

16 # Static URLs 

17 Rule('/', endpoint='static/index'), 

18 Rule('/about', endpoint='static/about'), 

19 Rule('/help', endpoint='static/help'), 

20 # Knowledge Base 

21 Subdomain('kb', [ 

22 Rule('/', endpoint='kb/index'), 

23 Rule('/browse/', endpoint='kb/browse'), 

24 Rule('/browse/<int:id>/', endpoint='kb/browse'), 

25 Rule('/browse/<int:id>/<int:page>', endpoint='kb/browse') 

26 ]) 

27 ], default_subdomain='www') 

28 

29If the application doesn't use subdomains it's perfectly fine to not set 

30the default subdomain and not use the `Subdomain` rule factory. The 

31endpoint in the rules can be anything, for example import paths or 

32unique identifiers. The WSGI application can use those endpoints to get the 

33handler for that URL. It doesn't have to be a string at all but it's 

34recommended. 

35 

36Now it's possible to create a URL adapter for one of the subdomains and 

37build URLs: 

38 

39.. code-block:: python 

40 

41 c = m.bind('example.com') 

42 

43 c.build("kb/browse", dict(id=42)) 

44 'http://kb.example.com/browse/42/' 

45 

46 c.build("kb/browse", dict()) 

47 'http://kb.example.com/browse/' 

48 

49 c.build("kb/browse", dict(id=42, page=3)) 

50 'http://kb.example.com/browse/42/3' 

51 

52 c.build("static/about") 

53 '/about' 

54 

55 c.build("static/index", force_external=True) 

56 'http://www.example.com/' 

57 

58 c = m.bind('example.com', subdomain='kb') 

59 

60 c.build("static/about") 

61 'http://www.example.com/about' 

62 

63The first argument to bind is the server name *without* the subdomain. 

64Per default it will assume that the script is mounted on the root, but 

65often that's not the case so you can provide the real mount point as 

66second argument: 

67 

68.. code-block:: python 

69 

70 c = m.bind('example.com', '/applications/example') 

71 

72The third argument can be the subdomain, if not given the default 

73subdomain is used. For more details about binding have a look at the 

74documentation of the `MapAdapter`. 

75 

76And here is how you can match URLs: 

77 

78.. code-block:: python 

79 

80 c = m.bind('example.com') 

81 

82 c.match("/") 

83 ('static/index', {}) 

84 

85 c.match("/about") 

86 ('static/about', {}) 

87 

88 c = m.bind('example.com', '/', 'kb') 

89 

90 c.match("/") 

91 ('kb/index', {}) 

92 

93 c.match("/browse/42/23") 

94 ('kb/browse', {'id': 42, 'page': 23}) 

95 

96If matching fails you get a ``NotFound`` exception, if the rule thinks 

97it's a good idea to redirect (for example because the URL was defined 

98to have a slash at the end but the request was missing that slash) it 

99will raise a ``RequestRedirect`` exception. Both are subclasses of 

100``HTTPException`` so you can use those errors as responses in the 

101application. 

102 

103If matching succeeded but the URL rule was incompatible to the given 

104method (for example there were only rules for ``GET`` and ``HEAD`` but 

105routing tried to match a ``POST`` request) a ``MethodNotAllowed`` 

106exception is raised. 

107""" 

108 

109from .converters import AnyConverter as AnyConverter 

110from .converters import BaseConverter as BaseConverter 

111from .converters import FloatConverter as FloatConverter 

112from .converters import IntegerConverter as IntegerConverter 

113from .converters import PathConverter as PathConverter 

114from .converters import UnicodeConverter as UnicodeConverter 

115from .converters import UUIDConverter as UUIDConverter 

116from .converters import ValidationError as ValidationError 

117from .exceptions import BuildError as BuildError 

118from .exceptions import NoMatch as NoMatch 

119from .exceptions import RequestAliasRedirect as RequestAliasRedirect 

120from .exceptions import RequestPath as RequestPath 

121from .exceptions import RequestRedirect as RequestRedirect 

122from .exceptions import RoutingException as RoutingException 

123from .exceptions import WebsocketMismatch as WebsocketMismatch 

124from .map import Map as Map 

125from .map import MapAdapter as MapAdapter 

126from .matcher import StateMachineMatcher as StateMachineMatcher 

127from .rules import EndpointPrefix as EndpointPrefix 

128from .rules import parse_converter_args as parse_converter_args 

129from .rules import Rule as Rule 

130from .rules import RuleFactory as RuleFactory 

131from .rules import RuleTemplate as RuleTemplate 

132from .rules import RuleTemplateFactory as RuleTemplateFactory 

133from .rules import Subdomain as Subdomain 

134from .rules import Submount as Submount