pyramid.config

class Configurator(registry=None, package=None, settings=None, root_factory=None, authentication_policy=None, authorization_policy=None, renderers=None, debug_logger=None, locale_negotiator=None, request_factory=None, renderer_globals_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)

A Configurator is used to configure a Pyramid application registry.

The Configurator accepts a number of arguments: registry, package, settings, root_factory, authentication_policy, authorization_policy, renderers, debug_logger, locale_negotiator, request_factory, renderer_globals_factory, default_permission, session_factory, default_view_mapper, autocommit, exceptionresponse_view and route_prefix.

If the registry argument is passed as a non-None value, 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 a registry is passed to the Configurator constructor, all other constructor arguments except package are ignored.

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 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 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 passed, it should be a list of tuples representing a set of renderer factories which should be configured into this application (each tuple representing a set of positional values that should be passed to pyramid.config.Configurator.add_renderer()). If it is not passed, a default set of renderer factories is used.

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 リクエストファクトリの変更. By default it is None, which means use the default request factory.

If renderer_globals_factory is passed, it should be a renderer globals factory implementation or a dotted Python name to the same. See レンダラーグローバルの追加 (非推奨). By default, it is None, which means use no renderer globals factory.

Warning

as of Pyramid 1.1, renderer_globals_factory is deprecated. Instead, use a BeforeRender event subscriber as per Before Render イベントの使用.

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 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 a 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. This argument is new in Pyramid 1.1.

If route_prefix is passed, all routes added with pyramid.config.Configurator.add_route() will have the specified path prepended to their pattern. This parameter is new in Pyramid 1.2.

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. This parameter is new as of Pyramid 1.3.

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.

begin(request=None)

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 on to the thread local stack consulted by various pyramid.threadlocal API functions.

end()

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

include(callable, route_prefix=None)

Include a configuration callables, 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 (be warned that it will not be the same configurator instance on which you call this method, however). The code which runs as the 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 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. 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.

The route_prefix parameter is new as of Pyramid 1.2.

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.

scan(package=None, categories=None, 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 None which will execute all Venusian decorator callbacks including Pyramid-related decorators such as pyramid.view.view_config. See the Venusian documentation for more information about limiting a scan by using an explicit set of categories.

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

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

Note

the ignore argument is new in Pyramid 1.3.

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.

Note

the **kw argument is new in Pyramid 1.1

Adding Routes and Views

add_route(name, pattern=None, view=None, view_for=None, permission=None, factory=None, for_=None, header=None, xhr=None, accept=None, path_info=None, request_method=None, request_param=None, traverse=None, custom_predicates=(), view_permission=None, renderer=None, view_renderer=None, view_context=None, view_attr=None, use_global_views=False, path=None, pregenerator=None, static=False, **predicates)

Add a route configuration to the current configuration state, as well as possibly a view configuration to be used to specify a view callable that will be invoked when this route matches. The arguments to this method are divided into predicate, non-predicate, and view-related types. Route predicate arguments narrow the circumstances in which a route will be match a request; non-predicate arguments are informational.

Non-Predicate Arguments

name

The name of the route, e.g. myroute. This attribute is required. It must be unique among all defined routes in a given application.

factory

A Python object (often a function or a class) or a dotted Python name which refers to the same object that will generate a Pyramid root resource object when this route matches. For example, mypackage.resources.MyFactory. If this argument is not specified, a default root factory will be used. See The Resource Tree for more information about root factories.

traverse

If you would like to cause the context to be something other than the root object when this route matches, you can spell a traversal pattern as the traverse argument. This traversal pattern will be used as the traversal path: traversal will begin at the root object implied by this route (either the global root, or the object returned by the factory associated with this route).

The syntax of the traverse argument is the same as it is for pattern. For example, if the pattern provided to add_route is articles/{article}/edit, and the traverse argument provided to add_route is /{article}, when a request comes in that causes the route to match in such a way that the article match value is ‘1’ (when the request URI is /articles/1/edit), the traversal path will be generated as /1. This means that the root object’s __getitem__ will be called with the name 1 during the traversal phase. If the 1 object exists, it will become the context of the request. Traversal has more information about traversal.

If the traversal path contains segment marker names which are not present in the pattern argument, a runtime error will occur. The traverse pattern should not contain segment markers that do not exist in the pattern argument.

A similar combining of routing and traversal is available when a route is matched which contains a *traverse remainder marker in its pattern (see Using *traverse In a Route Pattern). The traverse argument to add_route allows you to associate route patterns with an arbitrary traversal path without using a *traverse remainder marker; instead you can use other match information.

Note that the traverse argument to add_route is ignored when attached to a route that has a *traverse remainder marker in its pattern.

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.

Note

New in Pyramid 1.1.

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.

Note

The ability to pass a tuple of items as request_method is new as of Pyramid 1.2. Previous versions allowed only a string.

path_info

This value represents a regular expression pattern that will be tested against the PATH_INFO WSGI environment variable. If the regex matches, this predicate will return True. If this predicate returns False, route matching continues.

request_param

This value can be any string. A view declaration with this argument ensures that the associated route will only match when the request has a key in the request.params dictionary (an HTTP GET or POST variable) that has a name which matches the supplied value. If the value supplied as the argument has a = sign in it, e.g. request_param="foo=123", then the key (foo) must both exist in the request.params dictionary, and the value must match the right hand side of the expression (123) for the route to “match” the current request. If this predicate returns False, route matching continues.

header

This argument represents an HTTP header name or a header name/value pair. If the argument contains a : (colon), it will be considered a name/value pair (e.g. User-Agent:Mozilla/.* or Host:localhost). If the value contains a colon, the value portion should be a regular expression. If the value does not contain a colon, the entire value will be considered to be the header name (e.g. If-Modified-Since). If the value evaluates to a header name only without a value, the header specified by the name must be present in the request for this predicate to be true. If the value evaluates to a header name/value pair, the header specified by the name must be present in the request and the regular expression specified as the value must match the header value. Whether or not the value represents a header name or a header name/value pair, the case of the header name is not significant. If this predicate returns False, route matching continues.

accept

This value represents a match query for one or more mimetypes in the Accept HTTP request header. If this value is specified, it must be in one of the following forms: a mimetype match token in the form text/plain, a wildcard mimetype match token in the form text/* or a match-all wildcard mimetype match token in the form */*. If any of the forms matches the Accept header of the request, this predicate will be true. If this predicate returns False, route matching continues.

effective_principals

If specified, this value should be a principal identifier or a sequence of principal identifiers. If the pyramid.security.effective_principals() method indicates that every principal named in the argument list is present in the current request, this predicate will return True; otherwise it will return False. For example: effective_principals=pyramid.security.Authenticated or effective_principals=('fred', 'group:admins').

New in version 1.4a4.

custom_predicates

This value should be a sequence of references to custom predicate callables. Use custom predicates when no set of predefined predicates does what you need. Custom predicates can be combined with predefined predicates as necessary. Each custom predicate callable should accept two arguments: info and request and should return either True or False after doing arbitrary evaluation of the info and/or the request. If all custom and non-custom predicate callables return True the associated route will be considered viable for a given request. If any predicate callable returns False, route matching continues. Note that the value info passed to a custom route predicate is a dictionary containing matching information; see Custom Route Predicates for more information about info.

predicates

Pass a key/value pair here to use a third-party predicate registered via pyramid.config.Configurator.add_view_predicate(). More than one key/value pair can be used at the same time. See View and Route Predicates for more information about third-party predicates. This argument is new as of Pyramid 1.4.

View-Related Arguments

Warning

The arguments described below have been deprecated as of Pyramid 1.1. Do not use these for new development; they should only be used to support older code bases which depend upon them. Use a separate call to pyramid.config.Configurator.add_view() to associate a view with a route using the route_name argument.

view

Warning

Deprecated as of Pyramid 1.1.

A Python object or dotted Python name to the same object that will be used as a view callable when this route matches. e.g. mypackage.views.my_view.

view_context

Warning

Deprecated as of Pyramid 1.1.

A class or an interface or dotted Python name to the same object which the context of the view should match for the view named by the route to be used. This argument is only useful if the view attribute is used. If this attribute is not specified, the default (None) will be used.

If the view argument is not provided, this argument has no effect.

This attribute can also be spelled as for_ or view_for.

view_permission

Warning

Deprecated as of Pyramid 1.1.

The permission name required to invoke the view associated with this route. e.g. edit. (see Using Pyramid Security With URL Dispatch for more information about permissions).

If the view attribute is not provided, this argument has no effect.

This argument can also be spelled as permission.

view_renderer

Warning

Deprecated as of Pyramid 1.1.

This is either a single string term (e.g. json) or a string implying a path or asset specification (e.g. templates/views.pt). If the renderer value is a single term (does not contain a dot .), the specified term will be used to look up a renderer implementation, and that renderer implementation will be used to construct a response from the view return value. If the renderer term contains a dot (.), the specified term will be treated as a path, and the filename extension of the last element in the path will be used to look up the renderer implementation, which will be passed the full path. The renderer implementation will be used to construct a response from the view return value. See レンダラーを使うビュー Callable を書く for more information.

If the view argument is not provided, this argument has no effect.

This argument can also be spelled as renderer.

view_attr

Warning

Deprecated as of Pyramid 1.1.

The view machinery defaults to using the __call__ method of the view callable (or the function itself, if the view callable is a function) to obtain a response dictionary. The attr value allows you to vary the method attribute used to obtain the response. For example, if your view was a class, and the class has a method named index and you wanted to use this method instead of the class’ __call__ method to return the response, you’d say attr="index" in the view configuration for the view. This is most useful when the view definition is a class.

If the view argument is not provided, this argument has no effect.

add_static_view(name, path, **kw)

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

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

When add_static_view is called with a name argument that is the URL http://example.com/images, 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://example.com/logo.png. The external webserver listening on example.com must be itself configured to respond properly to such a request.

See Serving Static Assets for more information.

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, check_csrf=None, **predicates)

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 レンダラーを使うビュー Callable を書く).

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 ビュー callable レスポンス), 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

Note

This feature is new as of Pyramid 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.

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

Passing an iterable is only supported as of Pyramid 1.4a4.

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.

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

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 one of the strings GET, POST, PUT, DELETE, or HEAD 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 request’s method attribute (aka the REQUEST_METHOD of the WSGI environment) string matches a supplied value. Note that use of GET also implies that the view will respond to HEAD as of Pyramid 1.4.

Note

The ability to pass a tuple of items as request_method is new as of Pyramid 1.2. Previous versions allowed only a string.

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

Note

This feature is new as of Pyramid 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 なリソース 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.

accept

The value of this argument represents a match query for one or more mimetypes in the Accept HTTP request header. If this value is specified, it must be in one of the following forms: a mimetype match token in the form text/plain, a wildcard mimetype match token in the form text/* or a match-all wildcard mimetype match token in the form */*. If any of the forms matches the Accept header of the request, this predicate will be true.

header

This value represents an HTTP header name or a header name/value pair. If the value contains a : (colon), it will be considered a name/value pair (e.g. User-Agent:Mozilla/.* or Host:localhost). The value portion should be a regular expression. If the value does not contain a colon, the entire value will be considered to be the header name (e.g. If-Modified-Since). If the value evaluates to a header name only without a value, the header specified by the name must be present in the request for this predicate to be true. If the value evaluates to a header name/value pair, the header specified by the name must be present in the request and the regular expression specified as the value must match the header value. Whether or not the value represents a header name or a header name/value pair, the case of the header name is not significant.

path_info

This value represents a regular expression pattern that will be tested against the PATH_INFO WSGI environment variable. If the regex matches, this predicate will be True.

check_csrf

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

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

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

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

New in version 1.4a2.

physical_path

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

New in version 1.4a3.

effective_principals

If specified, this value should be a principal identifier or a sequence of principal identifiers. If the pyramid.security.effective_principals() method indicates that every principal named in the argument list is present in the current request, this predicate will return True; otherwise it will return False. For example: effective_principals=pyramid.security.Authenticated or effective_principals=('fred', 'group:admins').

New in version 1.4a4.

custom_predicates

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

predicates

Pass a key/value pair here to use a third-party predicate registered via pyramid.config.Configurator.add_view_predicate(). More than one key/value pair can be used at the same time. See View and Route Predicates for more information about third-party predicates.

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, **predicates)

Add a default notfound view to the current configuration state. The view will be called when Pyramid or application code raises an pyramid.httpexceptions.HTTPForbidden 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)

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

If append_slash is True, when this notfound 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.

Note

This method is new as of Pyramid 1.3.

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, **predicates)

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)

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

Note

This method is new as of Pyramid 1.3.

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

Note

THe **predicates argument is new as of Pyramid 1.4.

Using Security

set_authentication_policy(policy)

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)

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

set_request_property(callable, name=None, reify=False)

Add a property to the request object.

Warning

This method has been docs-deprecated as of Pyramid 1.4. pyramid.config.Configurator.add_request_method() should be used instead.

New in version 1.3.

Using I18N

add_translation_dirs(*specs)

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

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

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, _override=None)

Add a Pyramid asset override to the current configuration state.

to_override is a asset specification to the asset being overridden.

override_with is a asset specification to the asset that is performing the override.

See Static Assets for more information about asset overrides.

Setting Renderer Globals

set_renderer_globals_factory(factory, warn=True)

The object passed as factory should be an callable (or a dotted Python name which refers to an callable) that will be used by the Pyramid rendering machinery as a renderers global factory (see レンダラーグローバルの追加 (非推奨)).

The factory callable must accept a single argument named system (which will be a dictionary) and it must return a dictionary. When an application uses a renderer, the factory’s return dictionary will be merged into the system dictionary, and therefore will be made available to the code which uses the renderer.

Warning

This method is deprecated as of Pyramid 1.1. Use a BeforeRender event subscriber as documented in the フックの使用 chapter instead.

Note

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

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

When you add a traverser as described in トラバーサーの変更, 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 pyramid.request.Request.resource_url() の URL 生成方法の変更 for more information.

Note

This API is new in Pyramid 1.3.

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 Pyramid がビューレスポンスを扱う方法の変更 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 トラバーサーの変更 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; intead 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 agsinst 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 トラバーサーの変更 for more information.

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

Note

This feature is new as of Pyramid 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 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 compatibilty with other tweens, just add a fallback of MAIN or INGRESS. For example, under=('mypkg.someothertween', 'mypkg.someothertween2', INGRESS). This constraint will require the tween to be located under both the ‘mypkg.someothertween’ tween, the ‘mypkg.someothertween2’ tween, and INGRESS. If any of these is not in the current configuration, this constraint will only organize itself based on the tweens that are present.

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

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

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

For more information, see “tween” の登録.

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

factory should be a predicate factory.

See View and Route Predicates for more information.

Note

This method is new as of Pyramid 1.4.

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

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.

See View and Route Predicates for more information.

Note

This method is new as of Pyramid 1.4.

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 should argument 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 ビューマッパーの変更.

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 using the package supplied as the package argument to the new 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 ビュー callable をクラスとして定義する 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, authentication_policy=None, authorization_policy=None, renderers=None, debug_logger=None, locale_negotiator=None, request_factory=None, renderer_globals_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, groupids=(), permissive=True, remember_result=None, forget_result=None)

Unit/integration testing helper: Registers a pair of faux Pyramid security policies: a authentication policy and a authorization policy.

The behavior of the registered authorization policy depends on the permissive argument. If permissive is true, a permissive authorization policy is registered; this policy allows all access. If permissive is false, a nonpermissive authorization policy is registered; this policy denies all access.

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

Note

remember_result is new as of Pyramid 1.4.

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

Note

forget_result is new as of Pyramid 1.4.

The behavior of the registered authentication policy depends on the values provided for the userid and groupids argument. The authentication policy will return the userid identifier implied by the userid argument and the group ids implied by the groupids argument when the pyramid.security.authenticated_userid() or pyramid.security.effective_principals() APIs are used.

This function is most useful when testing code that uses the APIs named pyramid.security.has_permission(), pyramid.security.authenticated_userid(), pyramid.security.effective_principals(), and pyramid.security.principals_allowed_by_permission().

Attributes

introspectable

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

Note

This attribute is new as of Pyramid 1.3.

introspector

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

Note

This attribute is new as of Pyramid 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 per 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.