pyramid.config

class Configurator(registry=None, package=None, settings=None, root_factory=None, security_policy=None, authentication_policy=None, authorization_policy=None, renderers=None, debug_logger=None, locale_negotiator=None, request_factory=None, response_factory=None, default_permission=None, session_factory=None, default_view_mapper=None, autocommit=False, exceptionresponse_view=<function default_exceptionresponse_view>, route_prefix=None, introspection=True, root_package=None)

A Configurator is used to configure a Pyramid application registry.

The Configurator lifecycle can be managed by using a context manager to automatically handle calling pyramid.config.Configurator.begin() and pyramid.config.Configurator.end() as well as pyramid.config.Configurator.commit().

with Configurator(settings=settings) as config:
    config.add_route('home', '/')
    app = config.make_wsgi_app()

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 settings argument is passed, it should be a Python dictionary representing the deployment settings for this application. These are later retrievable using the pyramid.registry.Registry.settings attribute (aka request.registry.settings).

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.

If security_policy is passed, it should be an instance of a security policy or a dotted Python name to the same.

If authentication_policy is passed, it should be an instance of an authentication policy or a dotted Python name to the same.

If authorization_policy is passed, it should be an instance of an authorization policy or a dotted Python name to the same.

Note

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 locale_negotiator is passed, it should be a locale negotiator implementation or a dotted Python name to same. See Using a Custom Locale Negotiator.

If request_factory is passed, it should be a request factory implementation or a dotted Python name to the same. See Changing the Request Factory. By default it is None, which means use the default request factory.

If response_factory is passed, it should be a response factory implementation or a dotted Python name to the same. See Changing the Response Factory. By default it is None, which means use the default response factory.

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

See also

See also Setting a Default Permission.

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 route_prefix is passed, all routes added with pyramid.config.Configurator.add_route() will have the specified path prepended to their pattern.

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.

New in version 1.9: The ability to use the configurator as a context manager with the with-statement to make threadlocal configuration available for further configuration with an implicit commit.

Controlling Configuration State

commit()

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.

Warning

You should think very carefully before manually invoking commit(). Especially not as part of any reusable configuration methods. Normally it should only be done by an application author at the end of configuration in order to override certain aspects of an addon.

begin(request=<object object>)

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.

If request is not specified and the registry owned by the configurator is already pushed as the current threadlocal registry then this method will keep the current threadlocal request unchanged.

Changed in version 1.8: The current threadlocal request is propagated if the current threadlocal registry remains unchanged.

end()

Indicate that application or test configuration has ended. This pops the last value pushed onto the thread local stack (usually by the begin method) and returns that value.

include(callable, route_prefix=None)

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:

# myapp.myconfig module

def my_view(request):
    from pyramid.response import Response
    return Response('OK')

def includeme(config):
    config.add_view(my_view)

You might cause it to be included within your Pyramid application like so:

from pyramid.config import Configurator

def main(global_config, **settings):
    config = Configurator()
    config.include('myapp.myconfig.includeme')

Because the function is named includeme, the function name can also be omitted from the dotted name reference:

from pyramid.config import Configurator

def main(global_config, **settings):
    config = Configurator()
    config.include('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 and will have a similar effect to using pyramid.config.Configurator.route_prefix_context(). 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:

from pyramid.config import Configurator

def included(config):
    config.add_route('show_users', '/show')

def main(global_config, **settings):
    config = Configurator()
    config.include(included, route_prefix='/users')

In the above configuration, the show_users route will have an effective route pattern of /users/show, instead of /show because the route_prefix argument will be prepended to the pattern.

New in version 1.2: The route_prefix parameter.

Changed in version 1.9: The included function is wrapped with a call to pyramid.config.Configurator.begin() and pyramid.config.Configurator.end() while it is executed.

make_wsgi_app()

Commits any pending configuration statements, sends a pyramid.events.ApplicationCreated event to all listeners, adds this configuration's registry to pyramid.config.global_registries, and returns a Pyramid WSGI application representing the committed configuration state.

route_prefix_context(route_prefix)

Return this configurator with a route prefix temporarily set.

When the context exits, the route_prefix is reset to the original.

route_prefix is a string suitable to be used as a route prefix, or None.

Example Usage:

config = Configurator()
with config.route_prefix_context('foo'):
    config.add_route('bar', '/bar')

New in version 1.10.

scan(package=None, categories=('pyramid',), onerror=None, ignore=None, **kw)

Scan a Python package and any of its subpackages for objects marked with configuration decoration such as pyramid.view.view_config. Any decorated object found will influence the current configuration state.

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 ['pyramid'] which will execute only Pyramid-related Venusian decorator callbacks such as from pyramid.view.view_config. See the Venusian documentation for more information about limiting a scan by using an explicit set of categories. Pass None to pick up all Venusian decorators.

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.

New in version 1.1: The **kw argument.

New in version 1.3: The ignore argument.

Changed in version 2.0: The categories argument now defaults to ['pyramid'] instead of None to control which decorator callbacks are executed.

Adding Routes and Views

add_route(name, pattern=None, factory=None, for_=None, header=None, xhr=None, accept=None, path_info=None, request_method=None, request_param=None, traverse=None, custom_predicates=(), use_global_views=False, path=None, pregenerator=None, static=False, inherit_slash=None, **predicates)

Add a route configuration to the current configuration state. Arguments to add_route are divided into predicate and non-predicate types. Route predicate arguments narrow the circumstances in which a route will 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.

pregenerator

This option should be a callable object that implements the pyramid.interfaces.IRoutePregenerator interface. A pregenerator is a callable called by the 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 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 Static Routes.

New in version 1.1.

inherit_slash

This argument can only be used when the pattern is an empty string (''). By default, the composed route pattern will always include a trailing slash, but this argument provides a way to opt-out if both, you (the developer invoking add_route) and the integrator (the developer setting the route prefix), agree that the pattern should not contain a trailing slash. For example:

with config.route_prefix_context('/users'):
    config.add_route('users', '', inherit_slash=True)

In this example, the resulting route pattern will be /users. Alternatively, if the route prefix were /users/, then the resulting route pattern would be /users/.

New in version 2.0.

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 or an iterable of strings. 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 both the key (foo) must 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 can be a string or an iterable of strings for HTTP headers. The matching is determined as follow:

• If a string does not contain a : (colon), it will be considered to be the header name (example If-Modified-Since). In this case, the header specified by the name must be present in the request for this string to match. Case is not significant.

• If a string contains a colon, it will be considered a name/value pair (for example User-Agent:Mozilla/.* or Host:localhost), where the value part is a regular expression. The header specified by the name must be present in the request and the regular expression specified as the value part must match the value of the request header. Case is not significant for the header name, but it is for the value.

All strings must be matched for this predicate to return True. If this predicate returns False, route matching continues.

accept

A media type that will be matched against the Accept HTTP request header. If this value is specified, it may be a specific media type such as text/html, or a list of the same. If the media type is acceptable by the Accept header of the request, or if the Accept header isn't set at all in the request, this predicate will match. If this does not match the Accept header of the request, route matching continues.

If accept is not specified, the HTTP_ACCEPT HTTP header is not taken into consideration when deciding whether or not to select the route.

Unlike the accept argument to pyramid.config.Configurator.add_view(), this value is strictly a predicate and supports pyramid.config.not_().

Changed in version 1.10: Specifying a media range is deprecated due to changes in WebOb and ambiguities that occur when trying to match ranges against ranges in the Accept header. Support will be removed in Pyramid 2.0. Use a list of specific media types to match more than one type.

Changed in version 2.0: Removed support for media ranges.

is_authenticated

This value, if specified, must be either True or False. If it is specified and True, only a request from an authenticated user, as determined by the security policy in use, will satisfy the predicate. If it is specified and False, only a request from a user who is not authenticated will satisfy the predicate.

New in version 2.0.

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.authorization.Authenticated or effective_principals=('fred', 'group:admins').

New in version 1.4a4.

Deprecated since version 2.0: Use is_authenticated or a custom predicate.

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.

**predicates

Pass extra keyword parameters to use custom predicates registered via pyramid.config.Configurator.add_route_predicate(). More than one custom predicate can be used at the same time. See View and Route Predicates for more information about custom predicates.

New in version 1.4.

add_static_view(name, path, cache_max_age=3600, permission=NO_PERMISSION_REQUIRED)

Add a view used to render static assets such as images and CSS files.

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 content_encodings keyword argument is a list of alternative file encodings supported in the Accept-Encoding HTTP Header. Alternative files are found using file extensions defined in mimetypes.encodings_map. An encoded asset will be returned with the Content-Encoding header set to the selected encoding. If the asset contains alternative encodings then the Accept-Encoding value will be added to the response's Vary header. By default, the list is empty and no alternatives will be supported.

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

Usage

The add_static_view function is typically used in conjunction with the pyramid.request.Request.static_url() method. add_static_view adds a view which renders a static asset when some URL is visited; pyramid.request.Request.static_url() generates a URL to that asset.

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:

add_static_view('images', 'mypackage:images/')

Code that registers such a view can generate URLs to the view via pyramid.request.Request.static_url():

request.static_url('mypackage:images/logo.png')

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://<Pyramid app URL>/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.):

static_url('mypackage:images/logo.png', request)

See Serving Static Assets for more information.

Changed in version 2.0: Added the content_encodings argument.

add_view(view=None, name='', for_=None, permission=None, request_type=None, route_name=None, request_method=None, request_param=None, containment=None, attr=None, renderer=None, wrapper=None, xhr=None, accept=None, header=None, path_info=None, custom_predicates=(), context=None, decorator=None, mapper=None, http_cache=None, match_param=None, require_csrf=None, exception_only=False, **view_options)

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.

Non-Predicate Arguments

view

A view callable or a dotted Python name which refers to a view callable. This argument is required unless a renderer argument also exists. If a renderer argument is passed, and a view argument is not provided, the view callable defaults to a callable that returns an empty dictionary (see Writing View Callables Which Use a Renderer).

permission

A permission that the user must possess in order to invoke the view callable. See Configuring View Security for more information about view security and permissions. This is often a string like view or edit.

If permission is omitted, a default permission may be used for this view registration if one was named as the pyramid.config.Configurator constructor's default_permission argument, or if pyramid.config.Configurator.set_default_permission() was used prior to this view registration. Pass the value pyramid.security.NO_PERMISSION_REQUIRED as the permission argument to explicitly indicate that the view should always be executable by entirely anonymous users, regardless of the default permission, bypassing any authorization policy that may be in effect.

attr

This knob is most useful when the view definition is a class.

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.

Note that if the view itself returns a response (see View Callable Responses), the specified renderer implementation is never called.

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 defaults here may be overridden by pyramid.config.Configurator.set_default_csrf_options().

This feature requires a configured session factory.

If this option is set to False then CSRF checks will be disabled regardless of the default require_csrf setting passed to set_default_csrf_options.

See Checking CSRF Tokens Automatically for more information.

wrapper

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:

@view_config(...,
    decorator=(decorator2,
               decorator1))
def myview(request):
    ....

Is similar to doing:

@view_config(...)
@decorator2
@decorator1
def myview(request):
    ...

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:

def log_timer(wrapped):
    def wrapper(context, request):
        start = time.time()
        response = wrapped(context, request)
        duration = time.time() - start
        response.headers['X-View-Time'] = '%.3f' % (duration,)
        log.info('view took %.3f seconds', duration)
        return response
    return wrapper

Changed in version 1.4a4: Passing an iterable.

mapper

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

A media type that will be matched against the Accept HTTP request header. If this value is specified, it must be a specific media type such as text/html or text/html;level=1. If the media type is acceptable by the Accept header of the request, or if the Accept header isn't set at all in the request, this predicate will match. If this does not match the Accept header of the request, view matching continues.

If accept is not specified, the HTTP_ACCEPT HTTP header is not taken into consideration when deciding whether or not to invoke the associated view callable.

The accept argument is technically not a predicate and does not support wrapping with pyramid.config.not_().

See Accept Header Content Negotiation for more information.

Changed in version 1.10: Specifying a media range is deprecated and will be removed in Pyramid 2.0. Use explicit media types to avoid any ambiguities in content negotiation.

Changed in version 2.0: Removed support for media ranges.

exception_only

New in version 1.8.

When this value is True, the context argument must be a subclass of Exception. This flag indicates that only an exception view should be created, and that this view should not match if the traversal context matches the context argument. If the context is a subclass of Exception and this value is False (the default), then a view will be registered to match the traversal context as well.

Predicate Arguments

name

The view name. Read Traversal to understand the concept of a view name.

context

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). If the view should only match when handling exceptions, then set the exception_only to True.

route_name

This value must match the name of a route configuration declaration (see URL Dispatch) that must match before this view will be called.

request_type

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 argument can be a string or an iterable of strings for HTTP headers. The matching is determined as follow:

• If a string does not contain a : (colon), it will be considered to be a header name (example If-Modified-Since). In this case, the header specified by the name must be present in the request for this string to match. Case is not significant.

• If a string contains a colon, it will be considered a name/value pair (for example User-Agent:Mozilla/.* or Host:localhost), where the value part is a regular expression. The header specified by the name must be present in the request and the regular expression specified as the value part must match the value of the request header. Case is not significant for the header name, but it is for the value.

All strings must be matched for this predicate to return True. If this predicate returns False, view matching continues.

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.

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

is_authenticated

This value, if specified, must be either True or False. If it is specified and True, only a request from an authenticated user, as determined by the security policy in use, will satisfy the predicate. If it is specified and False, only a request from a user who is not authenticated will satisfy the predicate.

New in version 2.0.

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.authorization.Authenticated or effective_principals=('fred', 'group:admins').

New in version 1.4a4.

Deprecated since version 2.0: Use is_authenticated or a custom predicate.

custom_predicates

Deprecated since version 1.5: This value should be a sequence of references to custom predicate callables. 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 ability to register custom view predicates via pyramid.config.Configurator.add_view_predicate() obsoletes this argument, but it is kept around for backwards compatibility.

**view_options

Pass extra keyword parameters to use custom predicates or set a value for a view deriver. See pyramid.config.Configurator.add_view_predicate() and pyramid.config.Configurator.add_view_deriver(). See View and Route Predicates for more information about custom predicates and View Derivers for information about view derivers.

Changed in version 2.0: Removed support for the check_csrf predicate.

add_notfound_view(view=None, attr=None, renderer=None, wrapper=None, route_name=None, request_type=None, request_method=None, request_param=None, containment=None, xhr=None, accept=None, header=None, path_info=None, custom_predicates=(), decorator=None, mapper=None, match_param=None, append_slash=False, **view_options)

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:

def notfound(request):
    return Response('Not Found', status='404 Not Found')

config.add_notfound_view(notfound)

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, require_csrf, context, for_, or exception_only 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 HTTPTemporaryRedirect response class when a redirect is performed. For example:

from pyramid.httpexceptions import HTTPMovedPermanently
config.add_notfound_view(append_slash=HTTPMovedPermanently)

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

HTTPTemporaryRedirect class is used as default response, which is equivalent to HTTPFound with addition of redirecting with the same HTTP method (useful when doing POST requests).

New in version 1.3.

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.

Changed in version 1.8: The view is created using exception_only=True.

add_forbidden_view(view=None, attr=None, renderer=None, wrapper=None, route_name=None, request_type=None, request_method=None, request_param=None, containment=None, xhr=None, accept=None, header=None, path_info=None, custom_predicates=(), decorator=None, mapper=None, match_param=None, **view_options)

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:

def forbidden(request):
    return Response('Forbidden', status='403 Forbidden')

config.add_forbidden_view(forbidden)

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, require_csrf, context, for_, or exception_only keyword arguments. These argument values make no sense in the context of a forbidden exception view.

New in version 1.3.

Changed in version 1.8: The view is created using exception_only=True.

add_exception_view(view=None, context=None, **view_options)

Add an exception view for the specified exception to the current configuration state. The view will be called when Pyramid or application code raises the given exception.

This method accepts almost all of the same arguments as pyramid.config.Configurator.add_view() except for name, permission, for_, require_csrf, and exception_only.

By default, this method will set context=Exception, thus registering for most default Python exceptions. Any subclass of Exception may be specified.

New in version 1.8.

Adding an Event Subscriber

add_subscriber(subscriber, iface=None, **predicates)

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.

Any number of predicate keyword arguments may be passed in **predicates. Each predicate named will narrow the set of circumstances in which the subscriber will be invoked. Each named predicate must have been registered via pyramid.config.Configurator.add_subscriber_predicate() before it can be used. See Subscriber Predicates for more information.

New in version 1.4: The **predicates argument.

Using Security

set_security_policy(policy)

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

Note

Using the security_policy argument to the pyramid.config.Configurator constructor can be used to achieve the same purpose.

set_authentication_policy(policy)

Deprecated since version 2.0: Authentication policies have been replaced by security policies. See Upgrading Authentication/Authorization for more information.

Override the Pyramid authentication 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.

Note

Using the authentication_policy argument to the pyramid.config.Configurator constructor can be used to achieve the same purpose.

set_authorization_policy(policy)

Deprecated since version 2.0: Authentication policies have been replaced by security policies. See Upgrading Authentication/Authorization for more information.

Override the Pyramid authorization 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.

Note

Using the authorization_policy argument to the pyramid.config.Configurator constructor can be used to achieve the same purpose.

set_default_csrf_options(require_csrf=True, token='csrf_token', header='X-CSRF-Token', safe_methods=('GET', 'HEAD', 'OPTIONS', 'TRACE'), check_origin=True, allow_no_origin=False, callback=None)

Set the default CSRF options used by subsequent view registrations.

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

check_origin is a boolean. If False, the Origin and Referer headers will not be validated as part of automated CSRF checks.

allow_no_origin is a boolean. If True, a request lacking both an Origin and Referer header will pass the CSRF check. This option has no effect if check_origin is False.

If callback is set, it must be a callable accepting (request) and returning True if the request should be checked for a valid CSRF token. This callback allows an application to support alternate authentication methods that do not rely on cookies which are not subject to CSRF attacks. For example, if a request is authenticated using the Authorization header instead of a cookie, this may return False for that request so that clients do not need to send the X-CSRF-Token header. The callback is only tested for non-safe methods as defined by safe_methods.

New in version 1.7.

Changed in version 1.8: Added the callback option.

Changed in version 2.0: Added the allow_no_origin and check_origin options.

set_csrf_storage_policy(policy)

Set the CSRF storage policy used by subsequent view registrations.

policy is a class that implements the pyramid.interfaces.ICSRFStoragePolicy() interface and defines how to generate and persist CSRF tokens.

set_default_permission(permission)

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.

See also

See also Setting a Default Permission.

Note

Using the default_permission argument to the pyramid.config.Configurator constructor can be used to achieve the same purpose.

add_permission(permission_name)

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:

config = Configurator()
config.add_permission('view')

Extending the Request Object

add_request_method(callable=None, name=None, property=False, reify=False)

Add a property or method to the request object.

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 callable is a property descriptor, it has to be an instance of a class which is a subclass of property. 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.

See pyramid.request.Request.set_property() for more details on property vs reify. When reify is True, the value of property is assumed to also be True.

In all cases, callable may also be a dotted Python name which refers to either a callable or a property descriptor.

If callable is None then the method is only used to assist in conflict detection between different addons requesting the same attribute on the request object.

This is the recommended method for extending the request object and should be used in favor of providing a custom request factory via pyramid.config.Configurator.set_request_factory().

New in version 1.4.

Using I18N

add_translation_dirs(*specs, **kw)

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.

Example:

config.add_translation_dirs('/usr/share/locale',
                            'some.package:locale')

The translation directories are defined as a list in which translations defined later have precedence over translations defined earlier.

By default, consecutive calls to add_translation_dirs will add directories to the start of the list. This means later calls to add_translation_dirs will have their translations trumped by earlier calls. If you explicitly need this call to trump an earlier call then you may set override to True.

If multiple specs are provided in a single call to add_translation_dirs, the directories will be inserted in the order they're provided (earlier items are trumped by later items).

Changed in version 1.8: The override parameter was added to allow a later call to add_translation_dirs to override an earlier call, inserting folders at the beginning of the translation directory list.

set_locale_negotiator(negotiator)

Set the locale negotiator for this application. The locale negotiator is a callable which accepts a request object and which returns a locale name. The negotiator argument should be the locale negotiator implementation or a dotted Python name which refers to such an implementation.

Later calls to this method override earlier calls; there can be only one locale negotiator active at a time within an application. See Activating Translation for more information.

Note

Using the locale_negotiator argument to the pyramid.config.Configurator constructor can be used to achieve the same purpose.

Overriding Assets

override_asset(to_override, override_with)

Add a Pyramid asset override to the current configuration state.

to_override is an asset specification to the asset being overridden.

override_with is an asset specification to the asset that is performing the override. This may also be an absolute path.

See Static Assets for more information about asset overrides.

Getting and Adding Settings

add_settings(settings=None, **kw)

Augment the deployment settings with one or more key/value pairs.

You may pass a dictionary:

config.add_settings({'external_uri':'http://example.com'})

Or a set of key/value pairs:

config.add_settings(external_uri='http://example.com')

This function is useful when you need to test code that accesses the pyramid.registry.Registry.settings API (or the pyramid.config.Configurator.get_settings() API) and which uses values from that API.

get_settings()

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.

Note

the pyramid.registry.Registry.settings API performs the same duty.

Hooking Pyramid Behavior

add_accept_view_order(value, weighs_more_than=None, weighs_less_than=None)

Specify an ordering preference for the accept view option used during view lookup.

By default, if two views have different accept options and a request specifies Accept: */* or omits the header entirely then it is random which view will be selected. This method provides a way to specify a server-side, relative ordering between accept media types.

value should be a media type as specified by RFC 7231#section-5.3.2. For example, text/plain;charset=utf8, application/json or text/html.

weighs_more_than and weighs_less_than control the ordering of media types. Each value may be a string or a list of strings. If all options for weighs_more_than (or weighs_less_than) cannot be found, it is an error.

Earlier calls to add_accept_view_order are given higher priority over later calls, assuming similar constraints but standard conflict resolution mechanisms can be used to override constraints.

See Accept Header Content Negotiation for more information.

New in version 1.10.

add_renderer(name, factory)

Add a Pyramid renderer factory to the current configuration state.

The name argument is the renderer name. Use None to represent the default renderer (a renderer which will be used for all views unless they name another renderer specifically).

The factory argument is Python reference to an implementation of a renderer factory or a dotted Python name to same.

add_resource_url_adapter(adapter, resource_iface=None)

New in version 1.3.

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.

See Changing How pyramid.request.Request.resource_url() Generates a URL for more information.

add_response_adapter(adapter, type_or_iface)

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.

adapter and type_or_interface may be Python objects or strings representing dotted names to importable Python global objects.

See Changing How Pyramid Treats View Responses for more information.

add_traverser(adapter, iface=None)

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:

from myapp.traversal import MyCustomTraverser
config.add_traverser(MyCustomTraverser)

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

Note that either adapter or iface can be a dotted Python name or a Python object.

See Changing the Traverser for more information.

add_tween(tween_factory, under=None, over=None)

New in version 1.2.

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

• One of the constants pyramid.tweens.MAIN, pyramid.tweens.INGRESS, or pyramid.tweens.EXCVIEW.

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

For more information, see Registering Tweens.

add_route_predicate(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 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_route).

factory should be a predicate factory or dotted Python name which refers to a predicate factory.

See View and Route Predicates for more information.

New in version 1.4.

add_subscriber_predicate(name, factory, weighs_more_than=None, weighs_less_than=None)

New in version 1.4.

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

factory should be a predicate factory or dotted Python name which refers to a predicate factory.

See Subscriber Predicates for more information.

add_view_predicate(name, factory, weighs_more_than=None, weighs_less_than=None)

New in version 1.4.

Adds a view predicate factory. The associated view predicate can later be named as a keyword argument to pyramid.config.Configurator.add_view() in the predicates anonyous keyword argument dictionary.

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 by others).

factory should be a predicate factory or dotted Python name which refers to a predicate factory.

See View and Route Predicates for more information.

add_view_deriver(deriver, name=None, under=None, over=None)

New in version 1.7.

Add a view deriver to the view pipeline. View derivers are a feature used by extension authors to wrap views in custom code controllable by view-specific options.

deriver should be a callable conforming to the pyramid.interfaces.IViewDeriver interface.

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.

See View Derivers for more information.

set_execution_policy(policy)

Override the Pyramid execution policy in the current configuration. The policy argument must be an instance of an pyramid.interfaces.IExecutionPolicy or a dotted Python name that points at an instance of an execution policy.

set_request_factory(factory)

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

See pyramid.config.Configurator.add_request_method() for a less intrusive way to extend the request objects with custom methods and properties.

Note

Using the request_factory argument to the pyramid.config.Configurator constructor can be used to achieve the same purpose.

set_root_factory(factory)

Add a root factory to the current configuration state. If the factory argument is None a default root factory will be registered.

Note

Using the root_factory argument to the pyramid.config.Configurator constructor can be used to achieve the same purpose.

set_session_factory(factory)

Configure the application with a session factory. If this method is called, the factory argument must be a session factory callable or a dotted Python name to that factory.

Note

Using the session_factory argument to the pyramid.config.Configurator constructor can be used to achieve the same purpose.

set_view_mapper(mapper)

Setting a view mapper makes it possible to make use of view callable objects which implement different call signatures than the ones supported by Pyramid as described in its narrative documentation.

The mapper argument should be an object implementing pyramid.interfaces.IViewMapperFactory or a dotted Python name to such an object. The provided mapper will become the default view mapper to be used by all subsequent view configuration registrations.

See also

See also Using a View Mapper.

Note

Using the default_view_mapper argument to the pyramid.config.Configurator constructor can be used to achieve the same purpose.

Extension Author APIs

action(discriminator, callable=None, args=(), kw=None, order=0, introspectables=(), **extra)

Register an action which will be executed when pyramid.config.Configurator.commit() is called (or executed immediately if autocommit is True).

Warning

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.

add_directive(name, directive, action_wrap=True)

Add a directive method to the configurator.

Warning

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.

with_package(package)

Return a new Configurator instance with the same registry as this configurator. package may be an actual Python package object or a dotted Python name representing a package.

derive_view(view, attr=None, renderer=None)

Create a view callable using the function, instance, or class (or dotted Python name referring to the same) provided as view object.

Warning

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.

For example:

def some_other_framework(user_supplied_view):
    config = Configurator(reg)
    proxy_view = config.derive_view(user_supplied_view)
    def my_wrapper(context, request):
        do_something_that_mutates(request)
        return proxy_view(context, request)
    config.add_view(my_wrapper)

The view object provided should be one of the following:

• A function or another non-class callable object that accepts a request as a single positional argument and which returns a response object.

• A function or other non-class callable object that accepts two positional arguments, context, request and which returns a response object.

• A class which accepts a single positional argument in its constructor named request, and which has a __call__ method that accepts no arguments that returns a response object.

• A class which accepts two positional arguments named context, request, and which has a __call__ method that accepts no arguments that returns a response object.

• A dotted Python name which refers to any of the kinds of objects above.

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.

Utility Methods

absolute_asset_spec(relative_spec)

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.

maybe_dotted(dotted)

Resolve the dotted Python name dotted 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.

ZCA-Related APIs

hook_zca()

Call zope.component.getSiteManager.sethook() with the argument pyramid.threadlocal.get_current_registry, causing the Zope Component Architecture 'global' APIs such as zope.component.getSiteManager(), zope.component.getAdapter() and others to use the Pyramid application registry rather than the Zope 'global' registry.

unhook_zca()

Call zope.component.getSiteManager.reset() to undo the action of pyramid.config.Configurator.hook_zca().

setup_registry(settings=None, root_factory=None, security_policy=None, authentication_policy=None, authorization_policy=None, renderers=None, debug_logger=None, locale_negotiator=None, request_factory=None, response_factory=None, default_permission=None, session_factory=None, default_view_mapper=None, exceptionresponse_view=<function default_exceptionresponse_view>)

When you pass a non-None registry 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.

Testing Helper APIs

testing_add_renderer(path, renderer=None)

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

testing_add_subscriber(event_iface=None)

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.

testing_resources(resources)

Unit/integration testing helper: registers a dictionary of resource objects that can be resolved via the pyramid.traversal.find_resource() API.

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.

testing_securitypolicy(userid=None, identity=None, permissive=True, remember_result=None, forget_result=None)

Unit/integration testing helper. Registers a faux security policy.

This function is most useful when testing code that uses the security APIs, such as pyramid.request.Request.identity(), pyramid.request.Request.authenticated_userid, or pyramid.request.Request.has_permission(),

The behavior of the registered security policy depends on the arguments passed to this method.

Parameters:

• userid (str) -- If provided, the policy's authenticated_userid method will return this value. As a result, pyramid.request.Request.authenticated_userid will have this value as well.

• identity (object) -- If provided, the policy's identity method will return this value. As a result, pyramid.request.Request.identity` will have this value.

• permissive (bool) -- If true, the policy will allow access to any user for any permission. If false, the policy will deny all access.

• remember_result (list) -- If provided, the policy's remember method will return this value. Otherwise, remember will return an empty list.

• forget_result (list) -- If provided, the policy's forget method will return this value. Otherwise, forget will return an empty list.

New in version 1.4: The remember_result argument.

New in version 1.4: The forget_result argument.

Changed in version 2.0: Removed groupids argument and add identity argument.

Attributes

introspectable

A shortcut attribute which points to the pyramid.registry.Introspectable class (used during directives to provide introspection to actions).

New in version 1.3.

introspector

The introspector related to this configuration. It is an instance implementing the pyramid.interfaces.IIntrospector interface.

New in version 1.3.

registry

The application registry which holds the configuration associated with this configurator.

global_registries

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.

class not_(value)

You can invert the meaning of any predicate value by wrapping it in a call to pyramid.config.not_.

from pyramid.config import not_

config.add_view(
    'mypackage.views.my_view',
    route_name='ok',
    request_method=not_('POST')
    )

The above example will ensure that the view is called if the request method is not POST, at least if no other view is more specific.

This technique of wrapping a predicate value in not_ can be used anywhere predicate values are accepted:

• pyramid.config.Configurator.add_view()

• pyramid.config.Configurator.add_route()

• pyramid.config.Configurator.add_subscriber()

• pyramid.view.view_config()

• pyramid.events.subscriber()

New in version 1.5.

PHASE0_CONFIG

PHASE1_CONFIG

PHASE2_CONFIG

PHASE3_CONFIG