/usr/lib/python2.7/dist-packages/pyramid/config/routes.py is in python-pyramid 1.4.5+dfsg-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 | import warnings
from pyramid.interfaces import (
IRequest,
IRouteRequest,
IRoutesMapper,
PHASE2_CONFIG,
)
from pyramid.exceptions import ConfigurationError
from pyramid.registry import predvalseq
from pyramid.request import route_request_iface
from pyramid.urldispatch import RoutesMapper
from pyramid.config.util import (
action_method,
as_sorted_tuple,
)
import pyramid.config.predicates
class RoutesConfiguratorMixin(object):
@action_method
def add_route(self,
name,
pattern=None,
view=None,
view_for=None,
permission=None,
factory=None,
for_=None,
header=None,
xhr=None,
accept=None,
path_info=None,
request_method=None,
request_param=None,
traverse=None,
custom_predicates=(),
view_permission=None,
renderer=None,
view_renderer=None,
view_context=None,
view_attr=None,
use_global_views=False,
path=None,
pregenerator=None,
static=False,
**predicates):
""" Add a :term:`route configuration` to the current
configuration state, as well as possibly a :term:`view
configuration` to be used to specify a :term:`view callable`
that will be invoked when this route matches. The arguments
to this method are divided into *predicate*, *non-predicate*,
and *view-related* types. :term:`Route predicate` arguments
narrow the circumstances in which a route will be match a
request; non-predicate arguments are informational.
Non-Predicate Arguments
name
The name of the route, e.g. ``myroute``. This attribute is
required. It must be unique among all defined routes in a given
application.
factory
A Python object (often a function or a class) or a :term:`dotted
Python name` which refers to the same object that will generate a
:app:`Pyramid` root resource object when this route matches. For
example, ``mypackage.resources.MyFactory``. If this argument is
not specified, a default root factory will be used. See
:ref:`the_resource_tree` for more information about root factories.
traverse
If you would like to cause the :term:`context` to be
something other than the :term:`root` object when this route
matches, you can spell a traversal pattern as the
``traverse`` argument. This traversal pattern will be used
as the traversal path: traversal will begin at the root
object implied by this route (either the global root, or the
object returned by the ``factory`` associated with this
route).
The syntax of the ``traverse`` argument is the same as it is
for ``pattern``. For example, if the ``pattern`` provided to
``add_route`` is ``articles/{article}/edit``, and the
``traverse`` argument provided to ``add_route`` is
``/{article}``, when a request comes in that causes the route
to match in such a way that the ``article`` match value is
'1' (when the request URI is ``/articles/1/edit``), the
traversal path will be generated as ``/1``. This means that
the root object's ``__getitem__`` will be called with the
name ``1`` during the traversal phase. If the ``1`` object
exists, it will become the :term:`context` of the request.
:ref:`traversal_chapter` has more information about
traversal.
If the traversal path contains segment marker names which
are not present in the ``pattern`` argument, a runtime error
will occur. The ``traverse`` pattern should not contain
segment markers that do not exist in the ``pattern``
argument.
A similar combining of routing and traversal is available
when a route is matched which contains a ``*traverse``
remainder marker in its pattern (see
:ref:`using_traverse_in_a_route_pattern`). The ``traverse``
argument to add_route allows you to associate route patterns
with an arbitrary traversal path without using a
``*traverse`` remainder marker; instead you can use other
match information.
Note that the ``traverse`` argument to ``add_route`` is
ignored when attached to a route that has a ``*traverse``
remainder marker in its pattern.
pregenerator
This option should be a callable object that implements the
:class:`pyramid.interfaces.IRoutePregenerator` interface. A
:term:`pregenerator` is a callable called by the
:meth:`pyramid.request.Request.route_url` function to augment or
replace the arguments it is passed when generating a URL for the
route. This is a feature not often used directly by applications,
it is meant to be hooked by frameworks that use :app:`Pyramid` as
a base.
use_global_views
When a request matches this route, and view lookup cannot
find a view which has a ``route_name`` predicate argument
that matches the route, try to fall back to using a view
that otherwise matches the context, request, and view name
(but which does not match the route_name predicate).
static
If ``static`` is ``True``, this route will never match an incoming
request; it will only be useful for URL generation. By default,
``static`` is ``False``. See :ref:`static_route_narr`.
.. note:: New in :app:`Pyramid` 1.1.
Predicate Arguments
pattern
The pattern of the route e.g. ``ideas/{idea}``. This
argument is required. See :ref:`route_pattern_syntax`
for information about the syntax of route patterns. If the
pattern doesn't match the current URL, route matching
continues.
.. note::
For backwards compatibility purposes (as of :app:`Pyramid` 1.0), a
``path`` keyword argument passed to this function will be used to
represent the pattern value if the ``pattern`` argument is
``None``. If both ``path`` and ``pattern`` are passed, ``pattern``
wins.
xhr
This value should be either ``True`` or ``False``. If this
value is specified and is ``True``, the :term:`request` must
possess an ``HTTP_X_REQUESTED_WITH`` (aka
``X-Requested-With``) header for this route to match. This
is useful for detecting AJAX requests issued from jQuery,
Prototype and other Javascript libraries. If this predicate
returns ``False``, route matching continues.
request_method
A string representing an HTTP method name, e.g. ``GET``, ``POST``,
``HEAD``, ``DELETE``, ``PUT`` or a tuple of elements containing
HTTP method names. If this argument is not specified, this route
will match if the request has *any* request method. If this
predicate returns ``False``, route matching continues.
.. note:: The ability to pass a tuple of items as
``request_method`` is new as of Pyramid 1.2. Previous
versions allowed only a string.
path_info
This value represents a regular expression pattern that will
be tested against the ``PATH_INFO`` WSGI environment
variable. If the regex matches, this predicate will return
``True``. If this predicate returns ``False``, route
matching continues.
request_param
This value can be any string. A view declaration with this
argument ensures that the associated route will only match
when the request has a key in the ``request.params``
dictionary (an HTTP ``GET`` or ``POST`` variable) that has a
name which matches the supplied value. If the value
supplied as the argument has a ``=`` sign in it,
e.g. ``request_param="foo=123"``, then the key
(``foo``) must both exist in the ``request.params`` dictionary, and
the value must match the right hand side of the expression (``123``)
for the route to "match" the current request. If this predicate
returns ``False``, route matching continues.
header
This argument represents an HTTP header name or a header
name/value pair. If the argument contains a ``:`` (colon),
it will be considered a name/value pair
(e.g. ``User-Agent:Mozilla/.*`` or ``Host:localhost``). If
the value contains a colon, the value portion should be a
regular expression. If the value does not contain a colon,
the entire value will be considered to be the header name
(e.g. ``If-Modified-Since``). If the value evaluates to a
header name only without a value, the header specified by
the name must be present in the request for this predicate
to be true. If the value evaluates to a header name/value
pair, the header specified by the name must be present in
the request *and* the regular expression specified as the
value must match the header value. Whether or not the value
represents a header name or a header name/value pair, the
case of the header name is not significant. If this
predicate returns ``False``, route matching continues.
accept
This value represents a match query for one or more
mimetypes in the ``Accept`` HTTP request header. If this
value is specified, it must be in one of the following
forms: a mimetype match token in the form ``text/plain``, a
wildcard mimetype match token in the form ``text/*`` or a
match-all wildcard mimetype match token in the form ``*/*``.
If any of the forms matches the ``Accept`` header of the
request, this predicate will be true. If this predicate
returns ``False``, route matching continues.
effective_principals
If specified, this value should be a :term:`principal` identifier or
a sequence of principal identifiers. If the
:func:`pyramid.security.effective_principals` method indicates that
every principal named in the argument list is present in the current
request, this predicate will return True; otherwise it will return
False. For example:
``effective_principals=pyramid.security.Authenticated`` or
``effective_principals=('fred', 'group:admins')``.
.. versionadded:: 1.4a4
custom_predicates
This value should be a sequence of references to custom
predicate callables. Use custom predicates when no set of
predefined predicates does what you need. Custom predicates
can be combined with predefined predicates as necessary.
Each custom predicate callable should accept two arguments:
``info`` and ``request`` and should return either ``True``
or ``False`` after doing arbitrary evaluation of the info
and/or the request. If all custom and non-custom predicate
callables return ``True`` the associated route will be
considered viable for a given request. If any predicate
callable returns ``False``, route matching continues. Note
that the value ``info`` passed to a custom route predicate
is a dictionary containing matching information; see
:ref:`custom_route_predicates` for more information about
``info``.
predicates
Pass a key/value pair here to use a third-party predicate
registered via
:meth:`pyramid.config.Configurator.add_view_predicate`. More than
one key/value pair can be used at the same time. See
:ref:`view_and_route_predicates` for more information about
third-party predicates. This argument is new as of Pyramid 1.4.
View-Related Arguments
.. warning::
The arguments described below have been deprecated as of
:app:`Pyramid` 1.1. *Do not use these for new development; they
should only be used to support older code bases which depend upon
them.* Use a separate call to
:meth:`pyramid.config.Configurator.add_view` to associate a view
with a route using the ``route_name`` argument.
view
.. warning:: Deprecated as of :app:`Pyramid` 1.1.
A Python object or :term:`dotted Python name` to the same
object that will be used as a view callable when this route
matches. e.g. ``mypackage.views.my_view``.
view_context
.. warning:: Deprecated as of :app:`Pyramid` 1.1.
A class or an :term:`interface` or :term:`dotted Python
name` to the same object which the :term:`context` of the
view should match for the view named by the route to be
used. This argument is only useful if the ``view``
attribute is used. If this attribute is not specified, the
default (``None``) will be used.
If the ``view`` argument is not provided, this argument has
no effect.
This attribute can also be spelled as ``for_`` or ``view_for``.
view_permission
.. warning:: Deprecated as of :app:`Pyramid` 1.1.
The permission name required to invoke the view associated
with this route. e.g. ``edit``. (see
:ref:`using_security_with_urldispatch` for more information
about permissions).
If the ``view`` attribute is not provided, this argument has
no effect.
This argument can also be spelled as ``permission``.
view_renderer
.. warning:: Deprecated as of :app:`Pyramid` 1.1.
This is either a single string term (e.g. ``json``) or a
string implying a path or :term:`asset specification`
(e.g. ``templates/views.pt``). If the renderer value is a
single term (does not contain a dot ``.``), the specified
term will be used to look up a renderer implementation, and
that renderer implementation will be used to construct a
response from the view return value. If the renderer term
contains a dot (``.``), the specified term will be treated
as a path, and the filename extension of the last element in
the path will be used to look up the renderer
implementation, which will be passed the full path. The
renderer implementation will be used to construct a response
from the view return value. See
:ref:`views_which_use_a_renderer` for more information.
If the ``view`` argument is not provided, this argument has
no effect.
This argument can also be spelled as ``renderer``.
view_attr
.. warning:: Deprecated as of :app:`Pyramid` 1.1.
The view machinery defaults to using the ``__call__`` method
of the view callable (or the function itself, if the view
callable is a function) to obtain a response dictionary.
The ``attr`` value allows you to vary the method attribute
used to obtain the response. For example, if your view was
a class, and the class has a method named ``index`` and you
wanted to use this method instead of the class' ``__call__``
method to return the response, you'd say ``attr="index"`` in
the view configuration for the view. This is
most useful when the view definition is a class.
If the ``view`` argument is not provided, this argument has no
effect.
"""
# these are route predicates; if they do not match, the next route
# in the routelist will be tried
if request_method is not None:
request_method = as_sorted_tuple(request_method)
factory = self.maybe_dotted(factory)
if pattern is None:
pattern = path
if pattern is None:
raise ConfigurationError('"pattern" argument may not be None')
if self.route_prefix:
pattern = self.route_prefix.rstrip('/') + '/' + pattern.lstrip('/')
mapper = self.get_routes_mapper()
introspectables = []
intr = self.introspectable('routes',
name,
'%s (pattern: %r)' % (name, pattern),
'route')
intr['name'] = name
intr['pattern'] = pattern
intr['factory'] = factory
intr['xhr'] = xhr
intr['request_methods'] = request_method
intr['path_info'] = path_info
intr['request_param'] = request_param
intr['header'] = header
intr['accept'] = accept
intr['traverse'] = traverse
intr['custom_predicates'] = custom_predicates
intr['pregenerator'] = pregenerator
intr['static'] = static
intr['use_global_views'] = use_global_views
introspectables.append(intr)
if factory:
factory_intr = self.introspectable('root factories',
name,
self.object_description(factory),
'root factory')
factory_intr['factory'] = factory
factory_intr['route_name'] = name
factory_intr.relate('routes', name)
introspectables.append(factory_intr)
def register_route_request_iface():
request_iface = self.registry.queryUtility(IRouteRequest, name=name)
if request_iface is None:
if use_global_views:
bases = (IRequest,)
else:
bases = ()
request_iface = route_request_iface(name, bases)
self.registry.registerUtility(
request_iface, IRouteRequest, name=name)
def register_connect():
pvals = predicates.copy()
pvals.update(
dict(
xhr=xhr,
request_method=request_method,
path_info=path_info,
request_param=request_param,
header=header,
accept=accept,
traverse=traverse,
custom=predvalseq(custom_predicates),
)
)
predlist = self.get_predlist('route')
_, preds, _ = predlist.make(self, **pvals)
route = mapper.connect(
name, pattern, factory, predicates=preds,
pregenerator=pregenerator, static=static
)
intr['object'] = route
return route
# We have to connect routes in the order they were provided;
# we can't use a phase to do that, because when the actions are
# sorted, actions in the same phase lose relative ordering
self.action(('route-connect', name), register_connect)
# But IRouteRequest interfaces must be registered before we begin to
# process view registrations (in phase 3)
self.action(('route', name), register_route_request_iface,
order=PHASE2_CONFIG, introspectables=introspectables)
# deprecated adding views from add_route; must come after
# route registration for purposes of autocommit ordering
if any([view, view_context, view_permission, view_renderer,
view_for, for_, permission, renderer, view_attr]):
self._add_view_from_route(
route_name=name,
view=view,
permission=view_permission or permission,
context=view_context or view_for or for_,
renderer=view_renderer or renderer,
attr=view_attr,
)
@action_method
def add_route_predicate(self, name, factory, weighs_more_than=None,
weighs_less_than=None):
""" Adds a route predicate factory. The view predicate can later be
named as a keyword argument to
:meth:`pyramid.config.Configurator.add_route`.
``name`` should be the name of the predicate. It must be a valid
Python identifier (it will be used as a keyword argument to
``add_view``).
``factory`` should be a :term:`predicate factory`.
See :ref:`view_and_route_predicates` for more information.
.. note::
This method is new as of Pyramid 1.4.
"""
self._add_predicate(
'route',
name,
factory,
weighs_more_than=weighs_more_than,
weighs_less_than=weighs_less_than
)
def add_default_route_predicates(self):
p = pyramid.config.predicates
for (name, factory) in (
('xhr', p.XHRPredicate),
('request_method', p.RequestMethodPredicate),
('path_info', p.PathInfoPredicate),
('request_param', p.RequestParamPredicate),
('header', p.HeaderPredicate),
('accept', p.AcceptPredicate),
('effective_principals', p.EffectivePrincipalsPredicate),
('custom', p.CustomPredicate),
('traverse', p.TraversePredicate),
):
self.add_route_predicate(name, factory)
def get_routes_mapper(self):
""" Return the :term:`routes mapper` object associated with
this configurator's :term:`registry`."""
mapper = self.registry.queryUtility(IRoutesMapper)
if mapper is None:
mapper = RoutesMapper()
self.registry.registerUtility(mapper, IRoutesMapper)
return mapper
def _add_view_from_route(self,
route_name,
view,
context,
permission,
renderer,
attr,
):
if view:
self.add_view(
permission=permission,
context=context,
view=view,
name='',
route_name=route_name,
renderer=renderer,
attr=attr,
)
else:
# prevent mistakes due to misunderstanding of how hybrid calls to
# add_route and add_view interact
if attr:
raise ConfigurationError(
'view_attr argument not permitted without view '
'argument')
if context:
raise ConfigurationError(
'view_context argument not permitted without view '
'argument')
if permission:
raise ConfigurationError(
'view_permission argument not permitted without view '
'argument')
if renderer:
raise ConfigurationError(
'view_renderer argument not permitted without '
'view argument')
warnings.warn(
'Passing view-related arguments to add_route() is deprecated as of '
'Pyramid 1.1. Use add_view() to associate a view with a route '
'instead. See "Deprecations" in "What\'s New in Pyramid 1.1" '
'within the general Pyramid documentation for further details.',
DeprecationWarning,
4)
|