If the registry argument is not None, it must
be an instance of the pyramid.registry.Registry class
representing the registry to configure. If registry is None, the
configurator will create a pyramid.registry.Registry instance
itself; it will also perform some default configuration that would not
otherwise be done. After its construction, the configurator may be used
to add further configuration to the registry.

Warning

If registry is assigned the above-mentioned class
instance, all other constructor arguments are ignored,
with the exception of package.

If the package argument is passed, it must be a reference to a Python
package (e.g. sys.modules['thepackage']) or a dotted
Python name to the same. This value is used as a basis to convert
relative paths passed to various configuration methods, such as methods
which accept a renderer argument, into absolute paths. If None
is passed (the default), the package is assumed to be the Python package
in which the caller of the Configurator constructor lives.

If the root_package is passed, it will propagate through the
configuration hierarchy as a way for included packages to locate
resources relative to the package in which the main Configurator was
created. If None is passed (the default), the root_package will
be derived from the package argument. The package attribute is
always pointing at the package being included when using include(),
whereas the root_package does not change.

If the root_factory argument is passed, it should be an object
representing the default root factory for your application or a
dotted Python name to the same. If it is None, a default
root factory will be used.

A ConfigurationError will be raised when an
authorization policy is supplied without also supplying an
authentication policy (authorization requires authentication).

If renderers is None (the default), a default set of
renderer factories is used. Else, it should be a list of
tuples representing a set of renderer factories which should be
configured into this application, and each tuple representing a set of
positional values that should be passed to
pyramid.config.Configurator.add_renderer().

If debug_logger is not passed, a default debug logger that logs to a
logger will be used (the logger name will be the package name of the
caller of this configurator). If it is passed, it should be an
instance of the logging.Logger (PEP 282) standard library class
or a Python logger name. The debug logger is used by Pyramid
itself to log warnings and authorization debugging information.

If default_permission is passed, it should be a
permission string to be used as the default permission for
all view configuration registrations performed against this
Configurator. An example of a permission string:'view'.
Adding a default permission makes it unnecessary to protect each
view configuration with an explicit permission, unless your
application policy requires some exception for a particular view.
By default, default_permission is None, meaning that view
configurations which do not explicitly declare a permission will
always be executable by entirely anonymous users (any
authorization policy in effect is ignored).

If session_factory is passed, it should be an object which
implements the session factory interface. If a nondefault
value is passed, the session_factory will be used to create a
session object when request.session is accessed. Note that
the same outcome can be achieved by calling
pyramid.config.Configurator.set_session_factory(). By
default, this argument is None, indicating that no session
factory will be configured (and thus accessing request.session
will throw an error) unless set_session_factory is called later
during configuration.

If autocommit is True, every method called on the configurator
will cause an immediate action, and no configuration conflict detection
will be used. If autocommit is False, most methods of the
configurator will defer their action until
pyramid.config.Configurator.commit() is called. When
pyramid.config.Configurator.commit() is called, the actions implied
by the called methods will be checked for configuration conflicts unless
autocommit is True. If a conflict is detected, a
ConfigurationConflictError will be raised. Calling
pyramid.config.Configurator.make_wsgi_app() always implies a final
commit.

If default_view_mapper is passed, it will be used as the default
view mapper factory for view configurations that don't otherwise
specify one (see pyramid.interfaces.IViewMapperFactory). If
default_view_mapper is not passed, a superdefault view mapper will be
used.

If exceptionresponse_view is passed, it must be a view
callable or None. If it is a view callable, it will be used as an
exception view callable when an exception response is raised. If
exceptionresponse_view is None, no exception response view will
be registered, and all raised exception responses will be bubbled up to
Pyramid's caller. By
default, the pyramid.httpexceptions.default_exceptionresponse_view
function is used as the exceptionresponse_view.

If introspection is passed, it must be a boolean value. If it's
True, introspection values during actions will be kept for use
for tools like the debug toolbar. If it's False, introspection
values provided by registrations will be ignored. By default, it is
True.

New in version 1.1: The exceptionresponse_view argument.

New in version 1.2: The route_prefix argument.

New in version 1.3: The introspection argument.

New in version 1.6: The root_package argument.
The response_factory argument.

Commit any pending configuration actions. If a configuration
conflict is detected in the pending configuration actions, this method
will raise a ConfigurationConflictError; within the traceback
of this error will be information about the source of the conflict,
usually including file names and line numbers of the cause of the
configuration conflicts.

Indicate that application or test configuration has begun.
This pushes a dictionary containing the application
registry implied by registry attribute of this
configurator and the request implied by the
request argument onto the thread local stack
consulted by various pyramid.threadlocal API
functions.

Include a configuration callable, to support imperative
application extensibility.

Warning

In versions of Pyramid prior to 1.2, this
function accepted *callables, but this has been changed
to support only a single callable.

A configuration callable should be a callable that accepts a single
argument named config, which will be an instance of a
Configurator. However, be warned that it will not be the same
configurator instance on which you call this method. The
code which runs as a result of calling the callable should invoke
methods on the configurator passed to it which add configuration
state. The return value of a callable will be ignored.

Values allowed to be presented via the callable argument to
this method: any callable Python object or any dotted Python
name which resolves to a callable Python object. It may also be a
Python module, in which case, the module will be searched for
a callable named includeme, which will be treated as the
configuration callable.

For example, if the includeme function below lives in a module
named myapp.myconfig:

Included configuration statements will be overridden by local
configuration statements if an included callable causes a
configuration conflict by registering something with the same
configuration parameters.

If the route_prefix is supplied, it must be a string. Any calls
to pyramid.config.Configurator.add_route() within the included
callable will have their pattern prefixed with the value of
route_prefix. This can be used to help mount a set of routes at a
different location than the included callable's author intended, while
still maintaining the same route names. For example:

The package argument should be a Python package or module
object (or a dotted Python name which refers to such a
package or module). If package is None, the package of the
caller is used.

The categories argument, if provided, should be the
Venusian 'scan categories' to use during scanning. Providing
this argument is not often necessary; specifying scan categories is
an extremely advanced usage. By default, categories is None
which will execute all Venusian decorator callbacks including
Pyramid-related decorators such as
pyramid.view.view_config. See the Venusian
documentation for more information about limiting a scan by using an
explicit set of categories.

The onerror argument, if provided, should be a Venusian
onerror callback function. The onerror function is passed to
venusian.Scanner.scan() to influence error behavior when an
exception is raised during the scanning process. See the
Venusian documentation for more information about onerror
callbacks.

The ignore argument, if provided, should be a Venusian ignore
value. Providing an ignore argument allows the scan to ignore
particular modules, packages, or global objects during a scan.
ignore can be a string or a callable, or a list containing
strings or callables. The simplest usage of ignore is to provide
a module or package by providing a full path to its dotted name. For
example: config.scan(ignore='my.module.subpackage') would ignore
the my.module.subpackage package during a scan, which would
prevent the subpackage and any of its submodules from being imported
and scanned. See the Venusian documentation for more
information about the ignore argument.

To perform a scan, Pyramid creates a Venusian Scanner object.
The kw argument represents a set of keyword arguments to pass to
the Venusian Scanner object's constructor. See the
venusian documentation (its Scanner class) for more
information about the constructor. By default, the only keyword
arguments passed to the Scanner constructor are {'config':self}
where self is this configurator object. This services the
requirement of all built-in Pyramid decorators, but extension systems
may require additional arguments. Providing this argument is not
often necessary; it's an advanced usage.

Add a route configuration to the current
configuration state, as well as possibly a view
configuration to be used to specify a 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. 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 dotted
Python name which refers to the same object that will generate a
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
The Resource Tree for more information about root factories.

traverse

If you would like to cause the context to be
something other than the 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 context of the request.
Traversal 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
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.

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

New in version 1.1.

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, or if the Accept header isn't set at all in the request,
this will match the current route. If this does not match the
Accept header of the request, route matching continues.

Predicate Arguments

pattern

The pattern of the route e.g. ideas/{idea}. This
argument is required. See 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 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 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.

Changed in version 1.2: The ability to pass a tuple of items as request_method.
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.

effective_principals

If specified, this value should be a principal identifier or
a sequence of principal identifiers. If the
pyramid.request.Request.effective_principals property
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').

New in version 1.4a4.

custom_predicates

Deprecated since version 1.5: 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
Custom Route Predicates for more information about
info.

The name argument is a string representing an
application-relative local URL prefix. It may alternately be a full
URL.

The path argument is the path on disk where the static files
reside. This can be an absolute path, a package-relative path, or a
asset specification.

The cache_max_age keyword argument is input to set the
Expires and Cache-Control headers for static assets served.
Note that this argument has no effect when the name is a url
prefix. By default, this argument is None, meaning that no
particular Expires or Cache-Control headers are set in the response.

The permission keyword argument is used to specify the
permission required by a user to execute the static view. By
default, it is the string
pyramid.security.NO_PERMISSION_REQUIRED, a special sentinel
which indicates that, even if a default permission exists for
the current application, the static view should be renderered to
completely anonymous users. This default value is permissive
because, in most web apps, static assets seldom need protection from
viewing. If permission is specified, the security checking will
be performed against the default root factory ACL.

Any other keyword arguments sent to add_static_view are passed on
to pyramid.config.Configurator.add_route() (e.g. factory,
perhaps to define a custom factory with a custom ACL for this static
view).

The name argument to add_static_view is usually a simple URL
prefix (e.g. 'images'). When this is the case, the
pyramid.request.Request.static_url() API will generate a URL
which points to a Pyramid view, which will serve up a set of assets
that live in the package itself. For example:

When add_static_view is called with a name argument that
represents a URL prefix, as it is above, subsequent calls to
pyramid.request.Request.static_url() with paths that start with
the path argument passed to add_static_view will generate a
URL something like http://<PyramidappURL>/images/logo.png,
which will cause the logo.png file in the images subdirectory
of the mypackage package to be served.

add_static_view can alternately be used with a name argument
which is a URL, causing static assets to be served from an external
webserver. This happens when the name argument is a fully
qualified URL (e.g. starts with http:// or similar). In this
mode, the name is used as the prefix of the full URL when
generating a URL using pyramid.request.Request.static_url().
Furthermore, if a protocol-relative URL (e.g. //example.com/images)
is used as the name argument, the generated URL will use the
protocol of the request (http or https, respectively).

For example, if add_static_view is called like so:

add_static_view('http://example.com/images','mypackage:images/')

Subsequently, the URLs generated by
pyramid.request.Request.static_url() for that static view will
be prefixed with http://example.com/images (the external webserver
listening on example.com must be itself configured to respond
properly to such a request.):

Add a view configuration to the current
configuration state. Arguments to add_view are broken
down below into predicate arguments and non-predicate
arguments. Predicate arguments narrow the circumstances in
which the view callable will be invoked when a request is
presented to Pyramid; non-predicate arguments are
informational.

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

renderer

This is either a single string term (e.g. json) or a
string implying a path or asset specification
(e.g. templates/views.pt) naming a renderer
implementation. If the renderer value does not contain
a dot ., the specified string 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 value 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.

When the renderer is a path, although a path is usually just
a simple relative pathname (e.g. templates/foo.pt,
implying that a template named "foo.pt" is in the
"templates" directory relative to the directory of the
current package of the Configurator), a path can be
absolute, starting with a slash on UNIX or a drive letter
prefix on Windows. The path can alternately be a
asset specification in the form
some.dotted.package_name:relative/path, making it
possible to address template assets which live in a
separate package.

The renderer attribute is optional. If it is not
defined, the "null" renderer is assumed (no rendering is
performed and the value is passed back to the upstream
Pyramid machinery unmodified).

http_cache

New in version 1.1.

When you supply an http_cache value to a view configuration,
the Expires and Cache-Control headers of a response
generated by the associated view callable are modified. The value
for http_cache may be one of the following:

A nonzero integer. If it's a nonzero integer, it's treated as a
number of seconds. This number of seconds will be used to
compute the Expires header and the Cache-Control:max-age parameter of responses to requests which call this view.
For example: http_cache=3600 instructs the requesting browser
to 'cache this response for an hour, please'.

A datetime.timedelta instance. If it's a
datetime.timedelta instance, it will be converted into a
number of seconds, and that number of seconds will be used to
compute the Expires header and the Cache-Control:max-age parameter of responses to requests which call this view.
For example: http_cache=datetime.timedelta(days=1) instructs
the requesting browser to 'cache this response for a day, please'.

Zero (0). If the value is zero, the Cache-Control and
Expires headers present in all responses from this view will
be composed such that client browser cache (and any intermediate
caches) are instructed to never cache the response.

A two-tuple. If it's a two tuple (e.g. http_cache=(1,{'public':True})), the first value in the tuple may be a
nonzero integer or a datetime.timedelta instance; in either
case this value will be used as the number of seconds to cache
the response. The second value in the tuple must be a
dictionary. The values present in the dictionary will be used as
input to the Cache-Control response header. For example:
http_cache=(3600,{'public':True}) means 'cache for an hour,
and add public to the Cache-Control header of the response'.
All keys and values supported by the
webob.cachecontrol.CacheControl interface may be added to the
dictionary. Supplying {'public':True} is equivalent to
calling response.cache_control.public=True.

Providing a non-tuple value as http_cache is equivalent to
calling response.cache_expires(value) within your view's body.

Providing a two-tuple value as http_cache is equivalent to
calling response.cache_expires(value[0],**value[1]) within your
view's body.

If you wish to avoid influencing, the Expires header, and
instead wish to only influence Cache-Control headers, pass a
tuple as http_cache with the first element of None, e.g.:
(None,{'public':True}).

If you wish to prevent a view that uses http_cache in its
configuration from having its caching response headers changed by
this machinery, set response.cache_control.prevent_auto=True
before returning the response from the view. This effectively
disables any HTTP caching done by http_cache for that response.

require_csrf

New in version 1.7.

A boolean option or None. Default: None.

If this option is set to True then CSRF checks will be enabled
for requests to this view. The required token or header default to
csrf_token and X-CSRF-Token, respectively.

CSRF checks only affect "unsafe" methods as defined by RFC2616. By
default, these methods are anything except
GET, HEAD, OPTIONS, and TRACE.

The view name of a different view
configuration which will receive the response body of this
view as the request.wrapped_body attribute of its own
request, and the response returned by this
view as the request.wrapped_response attribute of its
own request. Using a wrapper makes it possible to "chain"
views together to form a composite response. The response
of the outermost wrapper view will be returned to the user.
The wrapper view will be found as any view is found: see
View Configuration. The "best" wrapper view will be found
based on the lookup ordering: "under the hood" this wrapper
view is looked up via
pyramid.view.render_view_to_response(context,request,'wrapper_viewname'). The context and request of a wrapper
view is the same context and request of the inner view. If
this attribute is unspecified, no view wrapping is done.

decorator

A dotted Python name to function (or the function itself,
or an iterable of the aforementioned) which will be used to
decorate the registered view callable. The decorator
function(s) will be called with the view callable as a single
argument. The view callable it is passed will accept
(context,request). The decorator(s) must return a
replacement view callable which also accepts (context,request).

If decorator is an iterable, the callables will be combined and
used in the order provided as a decorator.
For example:

Except with the existing benefits of decorator= (having a common
decorator syntax for all view calling conventions and not having to
think about preserving function attributes such as __name__ and
__module__ within decorator logic).

An important distinction is that each decorator will receive a
response object implementing pyramid.interfaces.IResponse
instead of the raw value returned from the view callable. All
decorators in the chain must return a response object or raise an
exception:

A Python object or dotted Python name which refers to a
view mapper, or None. By default it is None, which
indicates that the view should use the default view mapper. This
plug-point is useful for Pyramid extension developers, but it's not
very useful for 'civilians' who are just developing stock Pyramid
applications. Pay no attention to the man behind the curtain.

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, or if the Accept header isn't set at all in the request,
this will match the current view. If this does not match the
Accept header of the request, view matching continues.

An object or a dotted Python name referring to an
interface or class object that the context must be
an instance of, or the interface that the
context must provide in order for this view to be
found and called. This predicate is true when the
context is an instance of the represented class or
if the context provides the represented interface;
it is otherwise false. This argument may also be provided
to add_view as for_ (an older, still-supported
spelling).

This value should be an interface that the
request must provide in order for this view to be
found and called. This value exists only for backwards
compatibility purposes.

request_method

This value can be either a string (such as "GET", "POST",
"PUT", "DELETE", "HEAD" or "OPTIONS") representing
an HTTP REQUEST_METHOD, or a tuple containing one or more of
these strings. A view declaration with this argument ensures that
the view will only be called when the method attribute of the
request (aka the REQUEST_METHOD of the WSGI environment) matches
a supplied value. Note that use of GET also implies that the
view will respond to HEAD as of Pyramid 1.4.

Changed in version 1.2: The ability to pass a tuple of items as request_method.
Previous versions allowed only a string.

request_param

This value can be any string or any sequence of strings. A view
declaration with this argument ensures that the view will only be
called 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 is a string)
or values (if the value is a tuple). If any value
supplied 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 view to "match" the current request.

match_param

New in version 1.2.

This value can be a string of the format "key=value" or a tuple
containing one or more of these strings.

A view declaration with this argument ensures that the view will
only be called when the request has key/value pairs in its
matchdict that equal those supplied in the predicate.
e.g. match_param="action=edit" would require the action
parameter in the matchdict match the right hand side of
the expression (edit) for the view to "match" the current
request.

If the match_param is a tuple, every key/value pair must match
for the predicate to pass.

containment

This value should be a Python class or interface (or a
dotted Python name) that an object in the
lineage of the context must provide in order for this view
to be found and called. The nodes in your object graph must be
"location-aware" to use this feature. See
Location-Aware Resources for more information about
location-awareness.

xhr

This value should be either True or False. If this
value is specified and is True, the request
must possess an HTTP_X_REQUESTED_WITH (aka
X-Requested-With) header that has the value
XMLHttpRequest for this view to be found and called.
This is useful for detecting AJAX requests issued from
jQuery, Prototype and other Javascript libraries.

header

This value represents an HTTP header name or a header
name/value pair. If the value contains a : (colon), it
will be considered a name/value pair
(e.g. User-Agent:Mozilla/.* or Host:localhost). 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.

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

If specified, this value should be one of None, True,
False, or a string representing the 'check name'. If the value
is True or a string, CSRF checking will be performed. If the
value is False or None, CSRF checking will not be performed.

If the value provided is a string, that string will be used as the
'check name'. If the value provided is True, csrf_token will
be used as the check name.

If CSRF checking is performed, the checked value will be the value
of request.params[check_name]. This value will be compared
against the value of request.session.get_csrf_token(), and the
check will pass if these two values are the same. If the check
passes, the associated view will be permitted to execute. If the
check fails, the associated view will not be permitted to execute.

Note that using this feature requires a session factory to
have been configured.

New in version 1.4a2.

physical_path

If specified, this value should be a string or a tuple representing
the physical path of the context found via traversal for this
predicate to match as true. For example: physical_path='/' or
physical_path='/a/b/c' or physical_path=('','a','b','c').
This is not a path prefix match or a regex, it's a whole-path match.
It's useful when you want to always potentially show a view when some
object is traversed to, but you can't be sure about what kind of
object it will be, so you can't use the context predicate. The
individual path elements inbetween slash characters or in tuple
elements should be the Unicode representation of the name of the
resource and should not be encoded in any way.

New in version 1.4a3.

effective_principals

If specified, this value should be a principal identifier or
a sequence of principal identifiers. If the
pyramid.request.Request.effective_principals property
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').

New in version 1.4a4.

custom_predicates

Deprecated since version 1.5: This value should be a sequence of references to custom
predicate callables. Use custom predicates when no set of
predefined predicates do what you need. Custom predicates
can be combined with predefined predicates as necessary.
Each custom predicate callable should accept two arguments:
context and request and should return either
True or False after doing arbitrary evaluation of
the context and/or the request. The predicates argument
to this method and the ability to register third-party view
predicates via
pyramid.config.Configurator.add_view_predicate()
obsoletes this argument, but it is kept around for backwards
compatibility.

Add a default Not Found View to the current configuration state.
The view will be called when Pyramid or application code raises an
pyramid.httpexceptions.HTTPNotFound exception (e.g. when a
view cannot be found for the request). The simplest example is:

If view argument is not provided, the view callable defaults to
default_exceptionresponse_view().

All arguments except append_slash have the same meaning as
pyramid.config.Configurator.add_view() and each predicate
argument restricts the set of circumstances under which this notfound
view will be invoked. Unlike
pyramid.config.Configurator.add_view(), this method will raise
an exception if passed name, permission, context,
for_, or http_cache keyword arguments. These argument values
make no sense in the context of a Not Found View.

If append_slash is True, when this Not Found View is invoked,
and the current path info does not end in a slash, the notfound logic
will attempt to find a route that matches the request's path
info suffixed with a slash. If such a route exists, Pyramid will
issue a redirect to the URL implied by the route; if it does not,
Pyramid will return the result of the view callable provided as
view, as normal.

If the argument provided as append_slash is not a boolean but
instead implements IResponse, the
append_slash logic will behave as if append_slash=True was passed,
but the provided class will be used as the response class instead of
the default HTTPFound response class
when a redirect is performed. For example:

The above means that a redirect to a slash-appended route will be
attempted, but instead of HTTPFound
being used, HTTPMovedPermanentlywillbeused for the redirect response if a slash-appended route is found.

Changed in version 1.6: The append_slash argument was modified to allow any object that
implements the IResponse interface to specify the response class
used when a redirect is performed.

Add a forbidden view to the current configuration state. The
view will be called when Pyramid or application code raises a
pyramid.httpexceptions.HTTPForbidden exception and the set of
circumstances implied by the predicates provided are matched. The
simplest example is:

If view argument is not provided, the view callable defaults to
default_exceptionresponse_view().

All arguments have the same meaning as
pyramid.config.Configurator.add_view() and each predicate
argument restricts the set of circumstances under which this forbidden
view will be invoked. Unlike
pyramid.config.Configurator.add_view(), this method will raise
an exception if passed name, permission, context,
for_, or http_cache keyword arguments. These argument values
make no sense in the context of a forbidden view.

Add an event subscriber for the event stream
implied by the supplied iface interface.

The subscriber argument represents a callable object (or a
dotted Python name which identifies a callable); it will be
called with a single object event whenever Pyramid emits
an event associated with the iface, which may be an
interface or a class or a dotted Python name to a
global object representing an interface or a class.

Using the default iface value, None will cause the subscriber
to be registered for all event types. See Using Events for
more information about events and subscribers.

Override the Pyramidauthentication policy in the
current configuration. The policy argument must be an instance
of an authentication policy or a dotted Python name
that points at an instance of an authentication policy.

Override the Pyramidauthorization policy in the
current configuration. The policy argument must be an instance
of an authorization policy or a dotted Python name that points
at an instance of an authorization policy.

require_csrf controls whether CSRF checks will be automatically
enabled on each view in the application. This value is used as the
fallback when require_csrf is left at the default of None on
pyramid.config.Configurator.add_view().

token is the name of the CSRF token used in the body of the
request, accessed via request.POST[token]. Default: csrf_token.

header is the name of the header containing the CSRF token,
accessed via request.headers[header]. Default: X-CSRF-Token.

If token or header are set to None they will not be used
for checking CSRF tokens.

safe_methods is an iterable of HTTP methods which are expected to
not contain side-effects as defined by RFC2616. Safe methods will
never be automatically checked for CSRF tokens.
Default: ('GET','HEAD','OPTIONS',TRACE').

Set the default permission to be used by all subsequent
view configuration registrations. permission
should be a permission string to be used as the
default permission. An example of a permission
string:'view'. Adding a default permission makes it
unnecessary to protect each view configuration with an
explicit permission, unless your application policy requires
some exception for a particular view.

If a default permission is not set, views represented by
view configuration registrations which do not explicitly
declare a permission will be executable by entirely anonymous
users (any authorization policy is ignored).

Later calls to this method override will conflict with earlier calls;
there can be only one default permission active at a time within an
application.

Warning

If a default permission is in effect, view configurations meant to
create a truly anonymously accessible view (even exception
view views) must use the value of the permission importable as
pyramid.security.NO_PERMISSION_REQUIRED. When this string
is used as the permission for a view configuration, the default
permission is ignored, and the view is registered, making it
available to all callers regardless of their credentials.

A configurator directive which registers a free-standing
permission without associating it with a view callable. This can be
used so that the permission shows up in the introspectable data under
the permissions category (permissions mentioned via add_view
already end up in there). For example:

When adding a method to the request, callable may be any
function that receives the request object as the first
parameter. If name is None then it will be computed
from the name of the callable.

When adding a property to the request, callable can either
be a callable that accepts the request as its single positional
parameter, or it can be a property descriptor. If name is
None, the name of the property will be computed from the
name of the callable.

If the callable is a property descriptor a ValueError
will be raised if name is None or reify is True.

Add one or more translation directory paths to the
current configuration state. The specs argument is a
sequence that may contain absolute directory paths
(e.g. /usr/share/locale) or asset specification
names naming a directory path (e.g. some.package:locale)
or a combination of the two.

Later calls to add_translation_dir insert directories into the
beginning of the list of translation directories created by earlier
calls. This means that the same translation found in a directory
added later in the configuration process will be found before one
added earlier in the configuration process. However, if multiple
specs are provided in a single call to add_translation_dirs, the
directories will be inserted into the beginning of the directory list
in the order they're provided in the *specs list argument (items
earlier in the list trump ones later in the list).

Return a deployment settings object for the current
application. A deployment settings object is a dictionary-like
object that contains key/value pairs based on the dictionary passed
as the settings argument to the
pyramid.config.Configurator constructor.

When you add a traverser as described in
Changing the Traverser, it's convenient to continue to use the
pyramid.request.Request.resource_url() API. However, since the
way traversal is done may have been modified, the URLs that
resource_url generates by default may be incorrect when resources
are returned by a custom traverser.

If you've added a traverser, you can change how
resource_url() generates a URL for a
specific type of resource by calling this method.

The adapter argument represents a class that implements the
IResourceURL interface. The class
constructor should accept two arguments in its constructor (the
resource and the request) and the resulting instance should provide
the attributes detailed in that interface (virtual_path and
physical_path, in particular).

The resource_iface argument represents a class or interface that
the resource should possess for this url adapter to be used when
pyramid.request.Request.resource_url() looks up a resource url
adapter. If resource_iface is not passed, or it is passed as
None, the url adapter will be used for every type of resource.

When an object of type (or interface) type_or_iface is
returned from a view callable, Pyramid will use the adapter
adapter to convert it into an object which implements the
pyramid.interfaces.IResponse interface. If adapter is
None, an object returned of type (or interface) type_or_iface
will itself be used as a response object.

The superdefault traversal algorithm that Pyramid uses
is explained in The Traversal Algorithm. Though it is rarely
necessary, this default algorithm can be swapped out selectively for
a different traversal pattern via configuration. The section
entitled Changing the Traverser details how to create a
traverser class.

For example, to override the superdefault traverser used by Pyramid,
you might do something like this:

This would cause the Pyramid superdefault traverser to never be used;
instead all traversal would be done using your MyCustomTraverser
class, no matter which object was returned by the root
factory of this application. Note that we passed no arguments to
the iface keyword parameter. The default value of iface,
None represents that the registered traverser should be used when
no other more specific traverser is available for the object returned
by the root factory.

However, more than one traversal algorithm can be active at the same
time. The traverser used can depend on the result of the root
factory. For instance, if your root factory returns more than one
type of object conditionally, you could claim that an alternate
traverser adapter should be used against one particular class or
interface returned by that root factory. When the root factory
returned an object that implemented that class or interface, a custom
traverser would be used. Otherwise, the default traverser would be
used. The iface argument represents the class of the object that
the root factory might return or an interface that the object
might implement.

To use a particular traverser only when the root factory returns a
particular class:

config.add_traverser(MyCustomTraverser,MyRootClass)

When more than one traverser is active, the "most specific" traverser
will be used (the one that matches the class or interface of the
value returned by the root factory most closely).

Add a 'tween factory'. A tween (a contraction of 'between')
is a bit of code that sits between the Pyramid router's main request
handling function and the upstream WSGI component that uses
Pyramid as its 'app'. Tweens are a feature that may be used
by Pyramid framework extensions, to provide, for example,
Pyramid-specific view timing support, bookkeeping code that examines
exceptions before they are returned to the upstream WSGI application,
or a variety of other features. Tweens behave a bit like
WSGI 'middleware' but they have the benefit of running in a
context in which they have access to the Pyramid application
registry as well as the Pyramid rendering machinery.

Note

You can view the tween ordering configured into a given
Pyramid application by using the ptweens
command. See Displaying "Tweens".

The tween_factory argument must be a dotted Python name
to a global object representing the tween factory.

The under and over arguments allow the caller of
add_tween to provide a hint about where in the tween chain this
tween factory should be placed when an implicit tween chain is used.
These hints are only used when an explicit tween chain is not used
(when the pyramid.tweens configuration value is not set).
Allowable values for under or over (or both) are:

None (the default).

A dotted Python name to a tween factory: a string
representing the dotted name of a tween factory added in a call to
add_tween in the same configuration session.

An iterable of any combination of the above. This allows the user
to specify fallbacks if the desired tween is not included, as well
as compatibility with multiple other tweens.

under means 'closer to the main Pyramid application than',
over means 'closer to the request ingress than'.

For example, calling add_tween('myapp.tfactory',over=pyramid.tweens.MAIN) will attempt to place the tween factory
represented by the dotted name myapp.tfactory directly 'above'
(in ptweens order) the main Pyramid request handler.
Likewise, calling add_tween('myapp.tfactory',over=pyramid.tweens.MAIN,under='mypkg.someothertween') will
attempt to place this tween factory 'above' the main handler but
'below' (a fictional) 'mypkg.someothertween' tween factory.

If all options for under (or over) cannot be found in the
current configuration, it is an error. If some options are specified
purely for compatibilty with other tweens, just add a fallback of
MAIN or INGRESS. For example, under=('mypkg.someothertween','mypkg.someothertween2',INGRESS). This constraint will require
the tween to be located under both the 'mypkg.someothertween' tween,
the 'mypkg.someothertween2' tween, and INGRESS. If any of these is
not in the current configuration, this constraint will only organize
itself based on the tweens that are present.

Specifying neither over nor under is equivalent to specifying
under=INGRESS.

Implicit tween ordering is obviously only best-effort. Pyramid will
attempt to present an implicit order of tweens as best it can, but
the only surefire way to get any particular ordering is to use an
explicit tween order. A user may always override the implicit tween
ordering by using an explicit pyramid.tweens configuration value
setting.

under, and over arguments are ignored when an explicit tween
chain is specified using the pyramid.tweens configuration value.

Adds a subscriber predicate factory. The associated subscriber
predicate can later be named as a keyword argument to
pyramid.config.Configurator.add_subscriber() in the
**predicates anonymous keyword argument dictionary.

name should be the name of the predicate. It must be a valid
Python identifier (it will be used as a **predicates keyword
argument to add_subscriber()).

name should be the name of the view deriver. There are no
restrictions on the name of a view deriver. If left unspecified, the
name will be constructed from the name of the deriver.

The under and over options can be used to control the ordering
of view derivers by providing hints about where in the view pipeline
the deriver is used. Each option may be a string or a list of strings.
At least one view deriver in each, the over and under directions, must
exist to fully satisfy the constraints.

under means closer to the user-defined view callable,
and over means closer to view pipeline ingress.

The default value for over is rendered_view and under is
decorated_view. This places the deriver somewhere between the two
in the view pipeline. If the deriver should be placed elsewhere in the
pipeline, such as above decorated_view, then you MUST also specify
under to something earlier in the order, or a
CyclicDependencyError will be raised when trying to sort the
derivers.

The object passed as factory should be an object (or a
dotted Python name which refers to an object) which
will be used by the Pyramid router to create all
request objects. This factory object must have the same
methods and attributes as the
pyramid.request.Request class (particularly
__call__, and blank).

This method is typically only used by Pyramid
framework extension authors, not by Pyramid application
developers.

The discriminator uniquely identifies the action. It must be
given, but it can be None, to indicate that the action never
conflicts. It must be a hashable value.

The callable is a callable object which performs the task
associated with the action when the action is executed. It is
optional.

args and kw are tuple and dict objects respectively, which
are passed to callable when this action is executed. Both are
optional.

order is a grouping mechanism; an action with a lower order will
be executed before an action with a higher order (has no effect when
autocommit is True).

introspectables is a sequence of introspectable objects
(or the empty sequence if no introspectable objects are associated
with this action). If this configurator's introspection
attribute is False, these introspectables will be ignored.

extra provides a facility for inserting extra keys and values
into an action dictionary.

This method is typically only used by Pyramid
framework extension authors, not by Pyramid application
developers.

Framework extenders can add directive methods to a configurator by
instructing their users to call config.add_directive('somename','some.callable'). This will make some.callable accessible as
config.somename. some.callable should be a function which
accepts config as a first argument, and arbitrary positional and
keyword arguments following. It should use config.action as
necessary to perform actions. Directive methods can then be invoked
like 'built-in' directives such as add_view, add_route, etc.

The action_wrap argument should be True for directives which
perform config.action with potentially conflicting
discriminators. action_wrap will cause the directive to be
wrapped in a decorator which provides more accurate conflict
cause information.

add_directive does not participate in conflict detection, and
later calls to add_directive will override earlier calls.

This method is typically only used by Pyramid framework
extension authors, not by Pyramid application developers.

This is API is useful to framework extenders who create
pluggable systems which need to register 'proxy' view
callables for functions, instances, or classes which meet the
requirements of being a Pyramid view callable. For
example, a some_other_framework function in another
framework may want to allow a user to supply a view callable,
but he may want to wrap the view callable in his own before
registering the wrapper as a Pyramid view callable.
Because a Pyramid view callable can be any of a
number of valid objects, the framework extender will not know
how to call the user-supplied object. Running it through
derive_view normalizes it to a callable which accepts two
arguments: context and request.

This API returns a callable which accepts the arguments
context,request and which returns the result of calling
the provided view object.

The attr keyword argument is most useful when the view
object is a class. It names the method that should be used as
the callable. If attr is not provided, the attribute
effectively defaults to __call__. See
Defining a View Callable as a Class for more information.

The renderer keyword argument should be a renderer
name. If supplied, it will cause the returned callable to use
a renderer to convert the user-supplied view result to
a response object. If a renderer argument is not
supplied, the user-supplied view must itself return a
response object.

Resolve the potentially relative asset
specification string passed as relative_spec into an
absolute asset specification string and return the string.
Use the package of this configurator as the package to
which the asset specification will be considered relative
when generating an absolute asset specification. If the
provided relative_spec argument is already absolute, or if
the relative_spec is not a string, it is simply returned.

Resolve the dotted Python namedotted to a
global Python object. If dotted is not a string, return
it without attempting to do any name resolution. If
dotted is a relative dotted name (e.g. .foo.bar,
consider it relative to the package argument supplied to
this Configurator's constructor.

When you pass a non-Noneregistry argument to the
Configurator constructor, no initial setup is performed
against the registry. This is because the registry you pass in may
have already been initialized for use under Pyramid via a
different configurator. However, in some circumstances (such as when
you want to use a global registry instead of a registry created as a
result of the Configurator constructor), or when you want to reset
the initial setup of a registry, you do want to explicitly
initialize the registry associated with a Configurator for use under
Pyramid. Use setup_registry to do this initialization.

setup_registry configures settings, a root factory, security
policies, renderers, a debug logger, a locale negotiator, and various
other settings using the configurator's current registry, as per the
descriptions in the Configurator constructor.

Unit/integration testing helper: register a renderer at
path (usually a relative filename ala templates/foo.pt
or an asset specification) and return the renderer object.
If the renderer argument is None, a 'dummy' renderer will
be used. This function is useful when testing code that calls
the pyramid.renderers.render() function or
pyramid.renderers.render_to_response() function or
any other render_* or get_* API of the
pyramid.renderers module.

Note that calling this method for with a path argument
representing a renderer factory type (e.g. for foo.pt
usually implies the chameleon_zpt renderer factory)
clobbers any existing renderer factory registered for that
type.

Note

This method is also available under the alias
testing_add_template (an older name for it).

Unit/integration testing helper: Registers a
subscriber which listens for events of the type
event_iface. This method returns a list object which is
appended to by the subscriber whenever an event is captured.

When an event is dispatched that matches the value implied by
the event_iface argument, that event will be appended to
the list. You can then compare the values in the list to
expected event notifications. This method is useful when
testing code that wants to call
pyramid.registry.Registry.notify(),
or zope.component.event.dispatch().

The default value of event_iface (None) implies a
subscriber registered for any kind of event.

The pyramid.traversal.find_resource() API is called with
a path as one of its arguments. If the dictionary you
register when calling this method contains that path as a
string key (e.g. /foo/bar or foo/bar), the
corresponding value will be returned to find_resource (and
thus to your code) when
pyramid.traversal.find_resource() is called with an
equivalent path string or tuple.

remember_result, if provided, should be the result returned by
the remember method of the faux authentication policy. If it is
not provided (or it is provided, and is None), the default value
[] (the empty list) will be returned by remember.

forget_result, if provided, should be the result returned by
the forget method of the faux authentication policy. If it is
not provided (or it is provided, and is None), the default value
[] (the empty list) will be returned by forget.

The set of registries that have been created for Pyramid
applications, one for each call to
pyramid.config.Configurator.make_wsgi_app() in the current
process. The object itself supports iteration and has a last property
containing the last registry loaded.

The registries contained in this object are stored as weakrefs, thus they
will only exist for the lifetime of the actual applications for which they
are being used.