Documentation for repoze.zcml¶
repoze.zcml is a package which provides core ZCML directives for the Zope Component Architecture (particularly, utility, subscriber, and adapter).
Note that zope.configuration already has implementations of handlers that allow similar directives to work. You should only use the repoze.zcml versions of these directives if your application doesn’t need the more advanced features of the “stock” directive types of the same names present in zope.configuration. The “stock” implementations use the concepts of “permissions”, and “trusted” adapters and utilities. In most applications, these features are unnecessary, and exposing them to users may be harmful. Using repoze.zcml in this case makes it possible to use ZCML with fewer Zope Python packages as dependencies, and removes the possibility that your users will attempt to use these advanced features without any understanding of what they do.
Note
The effect of repoze.zcml directives is exactly equivalent to the effect that the “stock” directives would have, save for the omission of more advanced features.
repoze.zcml contains “meta” ZCML that can be included within your application’s ZCML that makes certain directives work (listed below). After this meta ZCML is loaded, you can use the directives.
For an overall description of the concepts backing the directives defined within repoze.zcml, see A Comprehensive Guide to Zope Component Architecture.
Usage¶
To make use of repoze.zcml, you should install the repoze.zcml package, then subsequently include its “meta.zcml” from within some ZCML that is used by your application:
<include package="repoze.zcml" file="meta.zcml"/>
Thereafter, you will be able to use the directive types it defines within your ZCML.
The directives defined in repoze.zcml are defined within the namespace http://namespaces.repoze.org/bfg. Therefore to use any of the repoze.zcml -defined directives without a namespace-qualified name, you should write your ZCML like so:
<configure xmnls="http://namespaces.repoze.org/bfg">
<adapter
factory="some.package.Foo"
provides="some.package.IFoo"
for="some.package.IBar some.package.IBaz"
name="myadapter"
/>
</configure>
On the other hand, if you want to use these directives with a qualified name within another application that already has a default xmlns, you can do so by adding a different XML namespace to the configure tag:
<configure xmnls="http://namespaces.zope.org/zope">
xmlns:bfg="http://namespaces.repoze.org/bfg">
<bfg:adapter
factory="some.package.Foo"
provides="some.package.IFoo"
for="some.package.IBar some.package.IBaz"
name="myadapter"
/>
</configure>
Directives¶
adapter¶
The adapter directive registers an adapter within the component architecture registry.
Example:
<adapter
factory="some.package.Foo"
provides="some.package.IFoo"
for="some.package.IBar some.package.IBaz"
name="myadapter"
/>
factory¶
The factory which creates an adapter (dotted name).
provides¶
This implies the interface that the adapter provides (dotted name).
for¶
This implies the interface(s) which the adapter is “for”. (One or more dotted names).
name¶
The name by which the adapter should be looked up.
utility¶
The utility directive registers a utility within the component architecture registry.
Example:
<utility
factory="some.package.Foo"
provides="some.package.IFoo"
name="myutility"
/>
factory¶
Describes the factory which should create the utility to be registered. This attribute is mutually exlusive with the component attribute.
component¶
Describes the component registered as the adapter. This attribute is mutually exlusive with the factory attribute.
provides¶
Describes the provides interface for an adapter.
for¶
Describes the for interface(s) for an adapter.
name¶
Describes the name of the adapter.
subscriber¶
The subscriber directive registers an event subscriber within the component architecture registry.
Example:
<subscriber
handler="some.package.myhandler"
provides="some.package.IFoo"
for="some.package.IBar"
/>
handler¶
The handler for the subscriber. This is a subscriber which does not require a factory. This attribute is mutually exclusive with the factory directive.
factory¶
The factory which creates an subscriber (dotted name). This attribute is mutually exclusive with the handler directive.
provides¶
This implies the interface that the subscriber adapter provides (dotted name).
for¶
This implies the interface(s) which the subscriber adapter is “for”. (One or more dotted names).
