1# -*- coding: utf-8 -*- 2""" 3 webapp2_extras.routes 4 ===================== 5 6 Extra route classes for webapp2. 7 8 :copyright: 2011 by tipfy.org. 9 :license: Apache Sotware License, see LICENSE for details. 10""" 11import re 12import urllib 13 14from webob import exc 15 16import webapp2 17 18 19class MultiRoute(object): 20 """Base class for routes with nested routes.""" 21 22 routes = None 23 children = None 24 match_children = None 25 build_children = None 26 27 def __init__(self, routes): 28 self.routes = routes 29 30 def get_children(self): 31 if self.children is None: 32 self.children = [] 33 for route in self.routes: 34 for r in route.get_routes(): 35 self.children.append(r) 36 37 for rv in self.children: 38 yield rv 39 40 def get_match_children(self): 41 if self.match_children is None: 42 self.match_children = [] 43 for route in self.get_children(): 44 for r in route.get_match_routes(): 45 self.match_children.append(r) 46 47 for rv in self.match_children: 48 yield rv 49 50 def get_build_children(self): 51 if self.build_children is None: 52 self.build_children = {} 53 for route in self.get_children(): 54 for n, r in route.get_build_routes(): 55 self.build_children[n] = r 56 57 for rv in self.build_children.iteritems(): 58 yield rv 59 60 get_routes = get_children 61 get_match_routes = get_match_children 62 get_build_routes = get_build_children 63 64 65class DomainRoute(MultiRoute): 66 """A route used to restrict route matches to a given domain or subdomain. 67 68 For example, to restrict routes to a subdomain of the appspot domain:: 69 70 app = WSGIApplication([ 71 DomainRoute('<subdomain>.app-id.appspot.com', [ 72 Route('/foo', 'FooHandler', 'subdomain-thing'), 73 ]), 74 Route('/bar', 'BarHandler', 'normal-thing'), 75 ]) 76 77 The template follows the same syntax used by :class:`webapp2.Route` and 78 must define named groups if any value must be added to the match results. 79 In the example above, an extra `subdomain` keyword is passed to the 80 handler, but if the regex didn't define any named groups, nothing would 81 be added. 82 """ 83 84 def __init__(self, template, routes): 85 """Initializes a URL route. 86 87 :param template: 88 A route template to match against ``environ['SERVER_NAME']``. 89 See a syntax description in :meth:`webapp2.Route.__init__`. 90 :param routes: 91 A list of :class:`webapp2.Route` instances. 92 """ 93 super(DomainRoute, self).__init__(routes) 94 self.template = template 95 96 def get_match_routes(self): 97 # This route will do pre-matching before matching the nested routes! 98 yield self 99 100 def match(self, request): 101 # Use SERVER_NAME to ignore port number that comes with request.host? 102 # host_match = self.regex.match(request.host.split(':', 1)[0]) 103 host_match = self.regex.match(request.environ['SERVER_NAME']) 104 105 if host_match: 106 args, kwargs = webapp2._get_route_variables(host_match) 107 return _match_routes(self.get_match_children, request, None, 108 kwargs) 109 110 @webapp2.cached_property 111 def regex(self): 112 regex, reverse_template, args_count, kwargs_count, variables = \ 113 webapp2._parse_route_template(self.template, 114 default_sufix='[^\.]+') 115 return regex 116 117 118class NamePrefixRoute(MultiRoute): 119 """The idea of this route is to set a base name for other routes:: 120 121 app = WSGIApplication([ 122 NamePrefixRoute('user-', [ 123 Route('/users/<user:\w+>/', UserOverviewHandler, 'overview'), 124 Route('/users/<user:\w+>/profile', UserProfileHandler, 125 'profile'), 126 Route('/users/<user:\w+>/projects', UserProjectsHandler, 127 'projects'), 128 ]), 129 ]) 130 131 The example above is the same as setting the following routes, just more 132 convenient as you can reuse the name prefix:: 133 134 app = WSGIApplication([ 135 Route('/users/<user:\w+>/', UserOverviewHandler, 'user-overview'), 136 Route('/users/<user:\w+>/profile', UserProfileHandler, 137 'user-profile'), 138 Route('/users/<user:\w+>/projects', UserProjectsHandler, 139 'user-projects'), 140 ]) 141 """ 142 143 _attr = 'name' 144 145 def __init__(self, prefix, routes): 146 """Initializes a URL route. 147 148 :param prefix: 149 The prefix to be prepended. 150 :param routes: 151 A list of :class:`webapp2.Route` instances. 152 """ 153 super(NamePrefixRoute, self).__init__(routes) 154 self.prefix = prefix 155 # Prepend a prefix to a route attribute. 156 for route in self.get_routes(): 157 setattr(route, self._attr, prefix + getattr(route, self._attr)) 158 159 160class HandlerPrefixRoute(NamePrefixRoute): 161 """Same as :class:`NamePrefixRoute`, but prefixes the route handler.""" 162 163 _attr = 'handler' 164 165 166class PathPrefixRoute(NamePrefixRoute): 167 """Same as :class:`NamePrefixRoute`, but prefixes the route path. 168 169 For example, imagine we have these routes:: 170 171 app = WSGIApplication([ 172 Route('/users/<user:\w+>/', UserOverviewHandler, 173 'user-overview'), 174 Route('/users/<user:\w+>/profile', UserProfileHandler, 175 'user-profile'), 176 Route('/users/<user:\w+>/projects', UserProjectsHandler, 177 'user-projects'), 178 ]) 179 180 We could refactor them to reuse the common path prefix:: 181 182 app = WSGIApplication([ 183 PathPrefixRoute('/users/<user:\w+>', [ 184 Route('/', UserOverviewHandler, 'user-overview'), 185 Route('/profile', UserProfileHandler, 'user-profile'), 186 Route('/projects', UserProjectsHandler, 'user-projects'), 187 ]), 188 ]) 189 190 This is not only convenient, but also performs better: the nested routes 191 will only be tested if the path prefix matches. 192 """ 193 194 _attr = 'template' 195 196 def __init__(self, prefix, routes): 197 """Initializes a URL route. 198 199 :param prefix: 200 The prefix to be prepended. It must start with a slash but not 201 end with a slash. 202 :param routes: 203 A list of :class:`webapp2.Route` instances. 204 """ 205 assert prefix.startswith('/') and not prefix.endswith('/'), \ 206 'Path prefixes must start with a slash but not end with a slash.' 207 super(PathPrefixRoute, self).__init__(prefix, routes) 208 209 def get_match_routes(self): 210 # This route will do pre-matching before matching the nested routes! 211 yield self 212 213 def match(self, request): 214 if not self.regex.match(urllib.unquote(request.path)): 215 return None 216 217 return _match_routes(self.get_match_children, request) 218 219 @webapp2.cached_property 220 def regex(self): 221 regex, reverse_template, args_count, kwargs_count, variables = \ 222 webapp2._parse_route_template(self.prefix + '<:/.*>') 223 return regex 224 225 226class RedirectRoute(webapp2.Route): 227 """A convenience route class for easy redirects. 228 229 It adds redirect_to, redirect_to_name and strict_slash options to 230 :class:`webapp2.Route`. 231 """ 232 233 def __init__(self, template, handler=None, name=None, defaults=None, 234 build_only=False, handler_method=None, methods=None, 235 schemes=None, redirect_to=None, redirect_to_name=None, 236 strict_slash=False): 237 """Initializes a URL route. Extra arguments compared to 238 :meth:`webapp2.Route.__init__`: 239 240 :param redirect_to: 241 A URL string or a callable that returns a URL. If set, this route 242 is used to redirect to it. The callable is called passing 243 ``(handler, *args, **kwargs)`` as arguments. This is a 244 convenience to use :class:`RedirectHandler`. These two are 245 equivalent:: 246 247 route = Route('/foo', handler=webapp2.RedirectHandler, 248 defaults={'_uri': '/bar'}) 249 route = Route('/foo', redirect_to='/bar') 250 251 :param redirect_to_name: 252 Same as `redirect_to`, but the value is the name of a route to 253 redirect to. In the example below, accessing '/hello-again' will 254 redirect to the route named 'hello':: 255 256 route = Route('/hello', handler=HelloHandler, name='hello') 257 route = Route('/hello-again', redirect_to_name='hello') 258 259 :param strict_slash: 260 If True, redirects access to the same URL with different trailing 261 slash to the strict path defined in the route. For example, take 262 these routes:: 263 264 route = Route('/foo', FooHandler, strict_slash=True) 265 route = Route('/bar/', BarHandler, strict_slash=True) 266 267 Because **strict_slash** is True, this is what will happen: 268 269 - Access to ``/foo`` will execute ``FooHandler`` normally. 270 - Access to ``/bar/`` will execute ``BarHandler`` normally. 271 - Access to ``/foo/`` will redirect to ``/foo``. 272 - Access to ``/bar`` will redirect to ``/bar/``. 273 """ 274 super(RedirectRoute, self).__init__( 275 template, handler=handler, name=name, defaults=defaults, 276 build_only=build_only, handler_method=handler_method, 277 methods=methods, schemes=schemes) 278 279 if strict_slash and not name: 280 raise ValueError('Routes with strict_slash must have a name.') 281 282 self.strict_slash = strict_slash 283 self.redirect_to_name = redirect_to_name 284 285 if redirect_to is not None: 286 assert redirect_to_name is None 287 self.handler = webapp2.RedirectHandler 288 self.defaults['_uri'] = redirect_to 289 290 def get_match_routes(self): 291 """Generator to get all routes that can be matched from a route. 292 293 :yields: 294 This route or all nested routes that can be matched. 295 """ 296 if self.redirect_to_name: 297 main_route = self._get_redirect_route(name=self.redirect_to_name) 298 else: 299 main_route = self 300 301 if not self.build_only: 302 if self.strict_slash is True: 303 if self.template.endswith('/'): 304 template = self.template[:-1] 305 else: 306 template = self.template + '/' 307 308 yield main_route 309 yield self._get_redirect_route(template=template) 310 else: 311 yield main_route 312 313 def _get_redirect_route(self, template=None, name=None): 314 template = template or self.template 315 name = name or self.name 316 defaults = self.defaults.copy() 317 defaults.update({ 318 '_uri': self._redirect, 319 '_name': name, 320 }) 321 new_route = webapp2.Route(template, webapp2.RedirectHandler, 322 defaults=defaults) 323 return new_route 324 325 def _redirect(self, handler, *args, **kwargs): 326 # Get from request because args is empty if named routes are set? 327 # args, kwargs = (handler.request.route_args, 328 # handler.request.route_kwargs) 329 kwargs.pop('_uri', None) 330 kwargs.pop('_code', None) 331 return handler.uri_for(kwargs.pop('_name'), *args, **kwargs) 332 333 334def _match_routes(iter_func, request, extra_args=None, extra_kwargs=None): 335 """Tries to match a route given an iterator.""" 336 method_not_allowed = False 337 for route in iter_func(): 338 try: 339 match = route.match(request) 340 if match: 341 route, args, kwargs = match 342 if extra_args: 343 args += extra_args 344 345 if extra_kwargs: 346 kwargs.update(extra_kwargs) 347 348 return route, args, kwargs 349 except exc.HTTPMethodNotAllowed: 350 method_not_allowed = True 351 352 if method_not_allowed: 353 raise exc.HTTPMethodNotAllowed() 354