Declarative Configuration using ZCML

The mode of configuration detailed in the examples within the Pyramid documentation is "imperative" configuration. This is the configuration mode in which a developer cedes the least amount of control to the framework; it's "imperative" because you express the configuration directly in Python code, and you have the full power of Python at your disposal as you issue configuration statements. However, another mode of configuration exists For Pyramid within pyramid_zcml named ZCML which is declarative. In ZCML, configuration statements are made via an domain specific language implemented in XML. There is no opportunity for conditionals or loops. Declarative languages are less powerful than their imperative counterparts; this is attractive in environments where consistency is more important than brevity.

A complete listing of ZCML directives is available within ZCML Directives. This chapter provides an overview of how you might get started with ZCML and highlights some common tasks performed when you use ZCML.

ZCML Configuration

A Pyramid application can be configured "declaratively", if so desired. Declarative configuration relies on declarations made external to the code in a configuration file format named ZCML (Zope Configuration Markup Language), an XML dialect.

A Pyramid application configured declaratively requires not one, but two files: a Python file and a ZCML file.

In a file named helloworld.py:

 1from paste.httpserver import serve
 2from pyramid.response import Response
 3from pyramid.config import Configurator
 4
 5def hello_world(request):
 6    return Response('Hello world!')
 7
 8if __name__ == '__main__':
 9    config = Configurator()
10    config.include('pyramid_zcml')
11    config.load_zcml('configure.zcml')
12    app = config.make_wsgi_app()
13    serve(app, host='0.0.0.0')

In a file named configure.zcml in the same directory as the previously created helloworld.py:

1<configure xmlns="http://pylonshq.com/pyramid">
2
3  <include package="pyramid_zcml" />
4
5  <view
6    view="helloworld.hello_world"
7   />
8
9</configure>

This pair of files forms an application functionally equivalent to the application we created earlier in Imperative Configuration. Let's examine the differences between that code listing and the code above.

In Imperative Configuration, we had the following lines within the if __name__ == '__main__' section of helloworld.py:

1if __name__ == '__main__':
2    config = Configurator()
3    config.add_view(hello_world)
4    app = config.make_wsgi_app()
5    serve(app, host='0.0.0.0')

In our "declarative" code, we've removed the call to add_view and replaced it with a call to the pyramid_zcml.load_zcml() method so that it now reads as:

1if __name__ == '__main__':
2    config = Configurator()
3    config.include('pyramid_zcml')
4    config.load_zcml('configure.zcml')
5    app = config.make_wsgi_app()
6    serve(app, host='0.0.0.0')

Everything else is much the same.

The config.include('pyramid_zcml') line makes the load_zcml method available on the configurator. The config.load_zcml('configure.zcml') line tells the configurator to load configuration declarations from the file named configure.zcml which sits next to helloworld.py on the filesystem. Let's take a look at that configure.zcml file again:

1<configure xmlns="http://pylonshq.com/pyramid">
2
3   <include package="pyramid_zcml" />
4
5   <view
6     view="helloworld.hello_world"
7    />
8
9</configure>

Note that this file contains some XML, and that the XML contains a <view> configuration declaration tag that references a dotted Python name. This dotted name refers to the hello_world function that lives in our helloworld Python module.

This <view> declaration tag performs the same function as the add_view method that was employed within Imperative Configuration. In fact, the <view> tag is effectively a "macro" which calls the pyramid.config.Configurator.add_view() method on your behalf.

The <view> tag is an example of a Pyramid declaration tag. Other such tags include <route> and <scan>. Each of these tags is effectively a "macro" which calls methods of a pyramid.config.Configurator object on your behalf.

Essentially, using a ZCML file and loading it from the filesystem allows us to put our configuration statements within this XML file rather as declarations, rather than representing them as method calls to a Configurator object. Otherwise, declarative and imperative configuration are functionally equivalent.

Using declarative configuration has a number of benefits, the primary benefit being that applications configured declaratively can be overridden and extended by third parties without requiring the third party to change application code. If you want to build a framework or an extensible application, using declarative configuration is a good idea.

Declarative configuration has an obvious downside: you can't use plain-old-Python syntax you probably already know and understand to configure your application; instead you need to use ZCML.

ZCML Conflict Detection

A minor additional feature of ZCML is conflict detection. If you define two declaration tags within the same ZCML file which logically "collide", an exception will be raised, and the application will not start. For example, the following ZCML file has two conflicting <view> tags:

 1 <configure xmlns="http://pylonshq.com/pyramid">
 2
 3   <include package="pyramid_zcml" />
 4
 5   <view
 6     view="helloworld.hello_world"
 7    />
 8
 9   <view
10     view="helloworld.hello_world"
11    />
12
13 </configure>

If you try to use this ZCML file as the source of ZCML for an application, an error will be raised when you attempt to start the application. This error will contain information about which tags might have conflicted.

Hello World, Goodbye World (Declarative)

Another almost entirely equivalent mode of application configuration exists named declarative configuration. Pyramid can be configured for the same "hello world" application "declaratively", if so desired.

To do so, first, create a file named helloworld.py:

 1from pyramid.config import Configurator
 2from pyramid.response import Response
 3from paste.httpserver import serve
 4
 5def hello_world(request):
 6    return Response('Hello world!')
 7
 8def goodbye_world(request):
 9    return Response('Goodbye world!')
10
11if __name__ == '__main__':
12    config = Configurator()
13    config.include('pyramid_zcml')
14    config.load_zcml('configure.zcml')
15    app = config.make_wsgi_app()
16    serve(app, host='0.0.0.0')

Then create a file named configure.zcml in the same directory as the previously created helloworld.py:

 1<configure xmlns="http://pylonshq.com/pyramid">
 2
 3  <include package="pyramid_zcml" />
 4
 5  <view
 6    view="helloworld.hello_world"
 7   />
 8
 9  <view
10    name="goodbye"
11    view="helloworld.goodbye_world"
12   />
13
14</configure>

This pair of files forms an application functionally equivalent to the application we created earlier in Hello World. We can run it the same way.

$ python helloworld.py
serving on 0.0.0.0:8080 view at http://127.0.0.1:8080

Let's examine the differences between the code in that section and the code above. In Application Configuration, we had the following lines within the if __name__ == '__main__' section of helloworld.py:

1if __name__ == '__main__':
2    config = Configurator()
3    config.add_view(hello_world)
4    config.add_view(goodbye_world, name='goodbye')
5    app = config.make_wsgi_app()
6    serve(app, host='0.0.0.0')

In our "declarative" code, we've added a call to the pyramid_zcml.load_zcml() method with the value configure.zcml, and we've removed the lines which read config.add_view(hello_world) and config.add_view(goodbye_world, name='goodbye'), so that it now reads as:

1if __name__ == '__main__':
2    config = Configurator()
3    config.include('pyramid_zcml')
4    config.load_zcml('configure.zcml')
5    app = config.make_wsgi_app()
6    serve(app, host='0.0.0.0')

Everything else is much the same.

The config.load_zcml('configure.zcml') line tells the configurator to load configuration declarations from the configure.zcml file which sits next to helloworld.py. Let's take a look at the configure.zcml file now:

 1<configure xmlns="http://pylonshq.com/pyramid">
 2
 3   <include package="pyramid_zcml" />
 4
 5   <view
 6     view="helloworld.hello_world"
 7    />
 8
 9   <view
10     name="goodbye"
11     view="helloworld.goodbye_world"
12    />
13
14</configure>

We already understand what the view code does, because the application is functionally equivalent to the application described in Hello World, but use of ZCML is new. Let's break that down tag-by-tag.

The <configure> Tag

The configure.zcml ZCML file contains this bit of XML:

1 <configure xmlns="http://pylonshq.com/pyramid">
2
3    <!-- other directives -->
4
5 </configure>

Because ZCML is XML, and because XML requires a single root tag for each document, every ZCML file used by Pyramid must contain a configure container directive, which acts as the root XML tag. It is a "container" directive because its only job is to contain other directives.

See also configure and A Word On XML Namespaces.

The <include> Tag

The configure.zcml ZCML file contains this bit of XML within the <configure> root tag:

1<include package="pyramid_zcml" />

This self-closing tag instructs Pyramid to load a ZCML file from the Python package with the dotted Python name pyramid_zcml, as specified by its package attribute. This particular <include> declaration is required because it actually allows subsequent declaration tags (such as <view>, which we'll see shortly) to be recognized. The <include> tag effectively just includes another ZCML file, causing its declarations to be executed. In this case, we want to load the declarations from the file named configure.zcml within the pyramid_zcml Python package. We know we want to load the configure.zcml from this package because configure.zcml is the default value for another attribute of the <include> tag named file. We could have spelled the include tag more verbosely, but equivalently as:

1<include package="pyramid_zcml"
2         file="configure.zcml"/>

The <include> tag that includes the ZCML statements implied by the configure.zcml file from the Python package named pyramid_zcml is basically required to come before any other named declaration in an application's configure.zcml. If it is not included, subsequent declaration tags will fail to be recognized, and the configuration system will generate an error at startup. However, the <include package="pyramid_zcml"/> tag needs to exist only in a "top-level" ZCML file, it needn't also exist in ZCML files included by a top-level ZCML file.

See also include.

The <view> Tag

The configure.zcml ZCML file contains these bits of XML after the <include> tag, but within the <configure> root tag:

1<view
2  view="helloworld.hello_world"
3 />
4
5<view
6  name="goodbye"
7  view="helloworld.goodbye_world"
8 />

These <view> declaration tags direct Pyramid to create two view configuration registrations. The first <view> tag has an attribute (the attribute is also named view), which points at a dotted Python name, referencing the hello_world function defined within the helloworld package. The second <view> tag has a view attribute which points at a dotted Python name, referencing the goodbye_world function defined within the helloworld package. The second <view> tag also has an attribute called name with a value of goodbye.

These effect of the <view> tag declarations we've put into our configure.zcml is functionally equivalent to the effect of lines we've already seen in an imperatively-configured application. We're just spelling things differently, using XML instead of Python.

In our previously defined application, in which we added view configurations imperatively, we saw this code:

1config.add_view(hello_world)
2config.add_view(goodbye_world, name='goodbye')

Each <view> declaration tag encountered in a ZCML file effectively invokes the pyramid.config.Configurator.add_view() method on the behalf of the developer. Various attributes can be specified on the <view> tag which influence the view configuration it creates.

Since the relative ordering of calls to pyramid.config.Configurator.add_view() doesn't matter (see the sidebar entitled View Dispatch and Ordering within Adding Configuration), the relative order of <view> tags in ZCML doesn't matter either. The following ZCML orderings are completely equivalent:

Hello Before Goodbye

1<view
2  view="helloworld.hello_world"
3 />
4
5<view
6  name="goodbye"
7  view="helloworld.goodbye_world"
8 />

Goodbye Before Hello

1<view
2  name="goodbye"
3  view="helloworld.goodbye_world"
4 />
5
6<view
7  view="helloworld.hello_world"
8 />

We've now configured a Pyramid helloworld application declaratively. More information about this mode of configuration is available in ZCML Configuration.

ZCML Granularity

It's extremely helpful to third party application "extenders" (aka "integrators") if the ZCML that composes the configuration for an application is broken up into separate files which do very specific things. These more specific ZCML files can be reintegrated within the application's main configure.zcml via <include file="otherfile.zcml"/> declarations. When ZCML files contain sets of specific declarations, an integrator can avoid including any ZCML he does not want by including only ZCML files which contain the declarations he needs. He is not forced to "accept everything" or "use nothing".

For example, it's often useful to put all <route> declarations in a separate ZCML file, as <route> statements have a relative ordering that is extremely important to the application: if an extender wants to add a route to the "middle" of the routing table, he will always need to disuse all the routes and cut and paste the routing configuration into his own application. It's useful for the extender to be able to disuse just a single ZCML file in this case, accepting the remainder of the configuration from other ZCML files in the original application.

Granularizing ZCML is not strictly required. An extender can always disuse all your ZCML, choosing instead to copy and paste it into his own package, if necessary. However, doing so is considerate, and allows for the best reusability. Sometimes it's possible to include only certain ZCML files from an application that contain only the registrations you really need, omitting others. But sometimes it's not. For brute force purposes, when you're getting view or route registrations that you don't actually want in your overridden application, it's always appropriate to just not include any ZCML file from the overridden application. Instead, just cut and paste the entire contents of the configure.zcml (and any ZCML file included by the overridden application's configure.zcml) into your own package and omit the <include package=""/> ZCML declaration in the overriding package's configure.zcml.

Scanning via ZCML

ZCML can invoke a scan via its <scan> directive. If a ZCML file is processed that contains a scan directive, the package the ZCML file points to is scanned.

 1# helloworld.py
 2
 3from paste.httpserver import serve
 4from pyramid.response import Response
 5from pyramid.view import view_config
 6
 7@view_config()
 8def hello(request):
 9    return Response('Hello')
10
11if __name__ == '__main__':
12    from pyramid.config import Configurator
13    config = Configurator()
14    config.include('pyramid_zcml')
15    config.load_zcml('configure.zcml')
16    app = config.make_wsgi_app()
17    serve(app, host='0.0.0.0')
1<configure xmlns="http://pylonshq.com/pyramid">
2
3  <!-- configure.zcml -->
4
5  <include package="pyramid_zcml"/>
6  <scan package="."/>
7
8</configure>

See also scan.

Which Mode Should I Use?

A combination of imperative configuration, declarative configuration via ZCML and scanning can be used to configure any application. They are not mutually exclusive.

Declarative configuration was the more traditional form of configuration used in Pyramid applications; the first releases of Pyramid and all releases of Pyramid's predecessor named repoze.bfg included ZCML in the core. However, by virtue of this package, it has been externalized from the Pyramid core because it has proven that imperative mode configuration can be simpler to understand and document.

However, you can choose to use imperative configuration, or declarative configuration via ZCML. Use the mode that best fits your brain as necessary.

View Configuration Via ZCML

You may associate a view with a URL by adding view declarations via ZCML in a configure.zcml file. An example of a view declaration in ZCML is as follows:

1<view
2  context=".resources.Hello"
3  view=".views.hello_world"
4  name="hello.html"
5 />

The above maps the .views.hello_world view callable function to the following set of resource location results:

  • A context object which is an instance (or subclass) of the Python class represented by .resources.Hello

  • A view name equalling hello.html.

Note

Values prefixed with a period (.) for the context and view attributes of a view declaration (such as those above) mean "relative to the Python package directory in which this ZCML file is stored". So if the above view declaration was made inside a configure.zcml file that lived in the hello package, you could replace the relative .resources.Hello with the absolute hello.resources.Hello; likewise you could replace the relative .views.hello_world with the absolute hello.views.hello_world. Either the relative or absolute form is functionally equivalent. It's often useful to use the relative form, in case your package's name changes. It's also shorter to type.

You can also declare a default view callable for a resource type:

1<view
2  context=".resources.Hello"
3  view=".views.hello_world"
4 />

A default view callable simply has no name attribute. For the above registration, when a context is found that is of the type .resources.Hello and there is no view name associated with the result of resource location, the default view callable will be used. In this case, it's the view at .views.hello_world.

A default view callable can alternately be defined by using the empty string as its name attribute:

1<view
2  context=".resources.Hello"
3  view=".views.hello_world"
4  name=""
5 />

You may also declare that a view callable is good for any context type by using the special * character as the value of the context attribute:

1<view
2  context="*"
3  view=".views.hello_world"
4  name="hello.html"
5 />

This indicates that when Pyramid identifies that the view name is hello.html and the context is of any type, the .views.hello_world view callable will be invoked.

A ZCML view declaration's view attribute can also name a class. In this case, the rules described in Defining a View Callable as a Class apply for the class which is named.

See view for complete ZCML directive documentation.

Configuring a Route via ZCML

Instead of using the imperative pyramid.config.Configurator.add_route() method to add a new route, you can alternately use ZCML. route statements in a ZCML file. For example, the following ZCML declaration causes a route to be added to the application.

1<route
2  name="myroute"
3  pattern="/prefix/{one}/{two}"
4  view=".views.myview"
5 />

Note

Values prefixed with a period (.) within the values of ZCML attributes such as the view attribute of a route mean "relative to the Python package directory in which this ZCML file is stored". So if the above route declaration was made inside a configure.zcml file that lived in the hello package, you could replace the relative .views.myview with the absolute hello.views.myview Either the relative or absolute form is functionally equivalent. It's often useful to use the relative form, in case your package's name changes. It's also shorter to type.

The order that routes are evaluated when declarative configuration is used is the order that they appear relative to each other in the ZCML file.

See route for full route ZCML directive documentation.

Serving Static Assets Using ZCML

Use of the static ZCML directive makes static assets available at a name relative to the application root URL, e.g. /static.

Note that the path provided to the static ZCML directive may be a fully qualified asset specification, a package-relative path, or an absolute path. The path with the value a/b/c/static of a static directive in a ZCML file that resides in the "mypackage" package will resolve to a package-qualified assets such as some_package:a/b/c/static.

Here's an example of a static ZCML directive that will serve files up under the /static URL from the /var/www/static directory of the computer which runs the Pyramid application using an absolute path.

1<static
2  name="static"
3  path="/var/www/static"
4 />

Here's an example of a static directive that will serve files up under the /static URL from the a/b/c/static directory of the Python package named some_package using a fully qualified asset specification.

1<static
2  name="static"
3  path="some_package:a/b/c/static"
4 />

Here's an example of a static directive that will serve files up under the /static URL from the static directory of the Python package in which the configure.zcml file lives using a package-relative path.

1<static
2  name="static"
3  path="static"
4 />

Whether you use for path a fully qualified asset specification, an absolute path, or a package-relative path, When you place your static files on the filesystem in the directory represented as the path of the directive, you will then be able to view the static files in this directory via a browser at URLs prefixed with the directive's name. For instance if the static directive's name is static and the static directive's path is /path/to/static, http://localhost:6543/static/foo.js will return the file /path/to/static/dir/foo.js. The static directory may contain subdirectories recursively, and any subdirectories may hold files; these will be resolved by the static view as you would expect.

While the path argument can be a number of different things, the name argument of the static ZCML directive can also be one of a number of things: a view name or a URL. The above examples have shown usage of the name argument as a view name. When name is a URL (or any string with a slash (/) in it), static assets can be served from an external webserver. In this mode, the name is used as the URL prefix when generating a URL using pyramid.url.static_url().

For example, the static ZCML directive may be fed a name argument which is http://example.com/images:

1<static
2  name="http://example.com/images"
3  path="mypackage:images"
4 />

Because the static ZCML directive is provided with a name argument that is the URL prefix http://example.com/images, subsequent calls to pyramid.url.static_url() with paths that start with the path argument passed to pyramid.url.static_url() 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. The pyramid.url.static_url() API is discussed in more detail later in this chapter.

The pyramid.config.Configurator.add_static_view() method offers an imperative equivalent to the static ZCML directive. Use of the add_static_view imperative configuration method is completely equivalent to using ZCML for the same purpose. See Serving Static Assets for more information.

The asset ZCML Directive

Instead of using pyramid.config.Configurator.override_asset() during imperative configuration, an equivalent ZCML directive can be used. The ZCML asset tag is a frontend to using pyramid.config.Configurator.override_asset().

An individual Pyramid asset ZCML statement can override a single asset. For example:

1 <asset
2   to_override="some.package:templates/mytemplate.pt"
3   override_with="another.package:othertemplates/anothertemplate.pt"
4  />

The string value passed to both to_override and override_with attached to an asset directive is called an "asset specification". The colon separator in a specification separates the package name from the asset name. The colon and the following asset name are optional. If they are not specified, the override attempts to resolve every lookup into a package from the directory of another package. For example:

1 <asset
2   to_override="some.package"
3   override_with="another.package"
4  />

Individual subdirectories within a package can also be overridden:

1 <asset
2   to_override="some.package:templates/"
3   override_with="another.package:othertemplates/"
4  />

If you wish to override an asset directory with another directory, you must make sure to attach the slash to the end of both the to_override specification and the override_with specification. If you fail to attach a slash to the end of an asset specification that points to a directory, you will get unexpected results.

The package name in an asset specification may start with a dot, meaning that the package is relative to the package in which the ZCML file resides. For example:

1 <asset
2   to_override=".subpackage:templates/"
3   override_with="another.package:templates/"
4  />

See also asset.

Enabling an Authorization Policy Via ZCML

If you'd rather use ZCML to specify an authorization policy than imperative configuration, modify the ZCML file loaded by your application (usually named configure.zcml) to enable an authorization policy.

For example, to enable a policy which compares the value of an "auth ticket" cookie passed in the request's environment which contains a reference to a single principal against the principals present in any ACL found in the resource tree when attempting to call some view, modify your configure.zcml to look something like this:

 1<configure xmlns="http://pylonshq.com/pyramid">
 2
 3  <!-- views and other directives before this... -->
 4
 5  <authtktauthenticationpolicy
 6    secret="iamsosecret"/>
 7
 8  <aclauthorizationpolicy/>
 9
10 </configure>

"Under the hood", these statements cause an instance of the class pyramid.authentication.AuthTktAuthenticationPolicy to be injected as the authentication policy used by this application and an instance of the class pyramid.authorization.ACLAuthorizationPolicy to be injected as the authorization policy used by this application.

Pyramid ships with a number of authorization and authentication policy ZCML directives that should prove useful. See Built-In Authentication Policy ZCML Directives and Built-In Authorization Policy ZCML Directives for more information.

Built-In Authentication Policy ZCML Directives

Instead of configuring an authentication policy and authorization policy imperatively, Pyramid ships with a few "pre-chewed" authentication policy ZCML directives that you can make use of within your application.

authtktauthenticationpolicy

When this directive is used, authentication information is obtained from an "auth ticket" cookie value, assumed to be set by a custom login form.

An example of its usage, with all attributes fully expanded:

 1<authtktauthenticationpolicy
 2  secret="goshiamsosecret"
 3  callback=".somemodule.somefunc"
 4  cookie_name="mycookiename"
 5  secure="false"
 6  include_ip="false"
 7  timeout="86400"
 8  reissue_time="600"
 9  max_age="31536000"
10  path="/"
11  http_only="false"
12 />

See authtktauthenticationpolicy for details about this directive.

remoteuserauthenticationpolicy

When this directive is used, authentication information is obtained from a REMOTE_USER key in the WSGI environment, assumed to be set by a WSGI server or an upstream middleware component.

An example of its usage, with all attributes fully expanded:

1<remoteuserauthenticationpolicy
2  environ_key="REMOTE_USER"
3  callback=".somemodule.somefunc"
4 />

See remoteuserauthenticationpolicy for detailed information.

repozewho1authenticationpolicy

When this directive is used, authentication information is obtained from a repoze.who.identity key in the WSGI environment, assumed to be set by repoze.who middleware.

An example of its usage, with all attributes fully expanded:

1<repozewho1authenticationpolicy
2  identifier_name="auth_tkt"
3  callback=".somemodule.somefunc"
4 />

See repozewho1authenticationpolicy for detailed information.

Built-In Authorization Policy ZCML Directives

aclauthorizationpolicy

When this directive is used, authorization information is obtained from ACL objects attached to resources.

An example of its usage, with all attributes fully expanded:

1<aclauthorizationpolicy/>

In other words, it has no configuration attributes; its existence in a configure.zcml file enables it.

See aclauthorizationpolicy for detailed information.

Adding and Changing Renderers via ZCML

New templating systems and serializers can be associated with Pyramid renderer names. To this end, configuration declarations can be made which change an existing renderer factory and which add a new renderer factory.

Adding or changing an existing renderer via ZCML is accomplished via the renderer ZCML directive.

For example, to add a renderer which renders views which have a renderer attribute that is a path that ends in .jinja2:

1<renderer
2  name=".jinja2"
3  factory="my.package.MyJinja2Renderer"
4 />

The factory attribute is a dotted Python name that must point to an implementation of a renderer factory.

The name attribute is the renderer name.

Registering a Renderer Factory

See Adding a New Renderer for more information for the definition of a renderer factory. Here's an example of the registration of a simple renderer factory via ZCML:

1<renderer
2  name="amf"
3  factory="my.package.MyAMFRenderer"
4 />

Adding the above ZCML to your application will allow you to use the my.package.MyAMFRenderer renderer factory implementation in view configurations by subsequently referring to it as amf in the renderer attribute of a view configuration:

1<view
2  view="mypackage.views.my_view"
3  renderer="amf"
4 />

Here's an example of the registration of a more complicated renderer factory, which expects to be passed a filesystem path:

1<renderer
2  name=".jinja2"
3  factory="my.package.MyJinja2Renderer"
4 />

Adding the above ZCML to your application will allow you to use the my.package.MyJinja2Renderer renderer factory implementation in view configurations by referring to any renderer which ends in .jinja in the renderer attribute of a view configuration:

1<view
2  view="mypackage.views.my_view"
3  renderer="templates/mytemplate.jinja2"
4 />

When a view configuration which has a name attribute that does contain a dot, such as templates/mytemplate.jinja2 above is encountered at startup time, the value of the name attribute is split on its final dot. The second element of the split is typically the filename extension. This extension is used to look up a renderer factory for the configured view. Then the value of renderer is passed to the factory to create a renderer for the view. In this case, the view configuration will create an instance of a Jinja2Renderer for each view configuration which includes anything ending with .jinja2 as its renderer value. The name passed to the Jinja2Renderer constructor will be whatever the user passed as renderer= to the view configuration.

See also renderer and pyramid.config.Configurator.add_renderer().

Changing an Existing Renderer

You can associate more than one filename extension with the same existing renderer implementation as necessary if you need to use a different file extension for the same kinds of templates. For example, to associate the .zpt extension with the Chameleon ZPT renderer factory, use:

1<renderer
2  name=".zpt"
3  factory="pyramid.chameleon_zpt.renderer_factory"
4 />

After you do this, Pyramid will treat templates ending in both the .pt and .zpt filename extensions as Chameleon ZPT templates.

To change the default mapping in which files with a .pt extension are rendered via a Chameleon ZPT page template renderer, use a variation on the following in your application's ZCML:

1<renderer
2  name=".pt"
3  factory="my.package.pt_renderer"
4 />

After you do this, the renderer factory in my.package.pt_renderer will be used to render templates which end in .pt, replacing the default Chameleon ZPT renderer.

To ochange the default mapping in which files with a .txt extension are rendered via a Chameleon text template renderer, use a variation on the following in your application's ZCML:

1<renderer
2  name=".txt"
3  factory="my.package.text_renderer"
4 />

After you do this, the renderer factory in my.package.text_renderer will be used to render templates which end in .txt, replacing the default Chameleon text renderer.

To associate a default renderer with all view configurations (even ones which do not possess a renderer attribute), use a variation on the following (ie. omit the name attribute to the renderer tag):

1<renderer
2  factory="pyramid.renderers.json_renderer_factory"
3 />

See also renderer and pyramid.config.Configurator.add_renderer().

Adding a Translation Directory via ZCML

You can add a translation directory via ZCML by using the translationdir ZCML directive:

1<translationdir dir="my.application:locale/"/>

A message catalog in a translation directory added via translationdir will be merged into translations from a message catalog added earlier if both translation directories contain translations for the same locale and translation domain.

See also translationdir and Adding a Translation Directory.

Adding a Custom Locale Negotiator via ZCML

You can add a custom locale negotiator via ZCML by using the localenegotiator ZCML directive:

1 <localenegotiator
2   negotiator="my_application.my_module.my_locale_negotiator"
3  />

See also Using a Custom Locale Negotiator and localenegotiator.

Configuring an Event Listener via ZCML

You can configure an subscriber by modifying your application's configure.zcml. Here's an example of a bit of XML you can add to the configure.zcml file which registers the above mysubscriber function, which we assume lives in a subscribers.py module within your application:

1<subscriber
2  for="pyramid.events.NewRequest"
3  handler=".subscribers.mysubscriber"
4 />

See also subscriber and Using Events.

Configuring a Not Found View via ZCML

If your application uses ZCML, you can replace the Not Found view by placing something like the following ZCML in your configure.zcml file.

1<view
2  view="helloworld.views.notfound_view"
3  context="pyramid.exceptions.NotFound"
4 />

Replace helloworld.views.notfound_view with the Python dotted name to the notfound view you want to use.

See Changing the Not Found View for more information.

Configuring a Forbidden View via ZCML

If your application uses ZCML, you can replace the Forbidden view by placing something like the following ZCML in your configure.zcml file.

1<view
2  view="helloworld.views.notfound_view"
3  context="pyramid.exceptions.Forbidden"
4 />

Replace helloworld.views.forbidden_view with the Python dotted name to the forbidden view you want to use.

See Changing the Forbidden View for more information.

Configuring an Alternate Traverser via ZCML

Use an adapter stanza in your application's configure.zcml to change the default traverser:

1 <adapter
2   factory="myapp.traversal.Traverser"
3   provides="pyramid.interfaces.ITraverser"
4   for="*"
5  />

Or to register a traverser for a specific resource type:

1 <adapter
2   factory="myapp.traversal.Traverser"
3   provides="pyramid.interfaces.ITraverser"
4   for="myapp.resources.MyRoot"
5  />

See Changing the Traverser for more information.

Using features to make ZCML configurable

Using features you can make ZCML somewhat configurable. That is, you can exclude or include parts of a ZCML configuration using the features argument to pyramid_zcml.load_zcml(). For example:

1config.load_zcml('configure.zcml', features=['my_feature'])

With this ZCML file:

 1<configure
 2     xmlns="http://pylonshq.com/pyramid"
 3     xmlns:zcml="http://namespaces.zope.org/zcml"
 4     >
 5
 6  <include package="pyramid_zcml" />
 7
 8  <view
 9    view="helloworld.always_configured"
10   />
11
12  <view
13    zcml:condition="not-have my_feature"
14    view="helloworld.hello_world"
15   />
16
17  <view
18    zcml:condition="have my_feature"
19    view="helloworld.alternate_hello_world"
20   />
21
22</configure>

Will configure the views always_configured and alternate_hello_world but NOT hello_world.

Changing resource_url URL Generation via ZCML

You can change how pyramid.url.resource_url() generates a URL for a specific type of resource by adding an adapter statement to your configure.zcml.

1 <adapter
2   factory="myapp.traversal.URLGenerator"
3   provides="pyramid.interfaces.IContextURL"
4   for="myapp.resources.MyRoot *"
5  />

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

Changing the Request Factory via ZCML

A MyRequest class can be registered via ZCML as a request factory through the use of the ZCML utility directive. In the below, we assume it lives in a package named mypackage.mymodule.

1<utility
2   component="mypackage.mymodule.MyRequest"
3   provides="pyramid.interfaces.IRequestFactory"
4 />

See Changing the Request Factory for more information.

Changing the Renderer Globals Factory via ZCML

Warning

The (internal) pyramid.interfaces.IRendererGlobals interface was removed in Pyramid 1.5a2. These arguments, methods and interfaces had been deprecated since 1.1. Use a BeforeRender event subscriber as documented in Using the Before Render Event in the "Hooks" chapter of the Pyramid narrative documentation instead of providing renderer globals values to the configurator.

A renderer globals factory can be registered via ZCML through the use of the ZCML utility directive. In the below, we assume a renderers_globals_factory function lives in a package named mypackage.mymodule.

1<utility
2   component="mypackage.mymodule.renderer_globals_factory"
3   provides="pyramid.interfaces.IRendererGlobalsFactory"
4 />

Using Broken ZCML Directives

Some Zope and third-party ZCML directives use the zope.component.getGlobalSiteManager API to get "the registry" when they should actually be calling zope.component.getSiteManager.

zope.component.getSiteManager can be overridden by Pyramid via pyramid.config.Configurator.hook_zca(), while zope.component.getGlobalSiteManager cannot. Directives that use zope.component.getGlobalSiteManager are effectively broken; no ZCML directive should be using this function to find a registry to populate.

You cannot use ZCML directives which use zope.component.getGlobalSiteManager within a Pyramid application without passing the ZCA global registry to the Configurator constructor at application startup, as per Enabling the ZCA global API by using the ZCA global registry.

One alternative exists: fix the ZCML directive to use getSiteManager rather than getGlobalSiteManager. If a directive disuses getGlobalSiteManager, the hook_zca method of using a component registry as documented in Enabling the ZCA global API by using hook_zca will begin to work, allowing you to make use of the ZCML directive without also using the ZCA global registry.