Advanced Configuration¶
To support application extensibility, the Pyramid Configurator by default detects configuration conflicts and allows you to include configuration imperatively from other packages or modules. It also by default performs configuration in two separate phases. This allows you to ignore relative configuration statement ordering in some circumstances.
Conflict Detection¶
Here's a familiar example of one of the simplest Pyramid applications, configured imperatively:
1from wsgiref.simple_server import make_server
2from pyramid.config import Configurator
3from pyramid.response import Response
4
5def hello_world(request):
6 return Response('Hello world!')
7
8if __name__ == '__main__':
9 config = Configurator()
10 config.add_view(hello_world)
11 app = config.make_wsgi_app()
12 server = make_server('0.0.0.0', 8080, app)
13 server.serve_forever()
When you start this application, all will be OK. However, what happens if we try to add another view to the configuration with the same set of predicate arguments as one we've already added?
1from wsgiref.simple_server import make_server
2from pyramid.config import Configurator
3from pyramid.response import Response
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
14 config.add_view(hello_world, name='hello')
15
16 # conflicting view configuration
17 config.add_view(goodbye_world, name='hello')
18
19 app = config.make_wsgi_app()
20 server = make_server('0.0.0.0', 8080, app)
21 server.serve_forever()
The application now has two conflicting view configuration statements. When we try to start it again, it won't start. Instead we'll receive a traceback that ends something like this:
1Traceback (most recent call last):
2 File "app.py", line 12, in <module>
3 app = config.make_wsgi_app()
4 File "pyramid/config.py", line 839, in make_wsgi_app
5 self.commit()
6 File "pyramid/pyramid/config.py", line 473, in commit
7 self._ctx.execute_actions()
8 ... more code ...
9pyramid.exceptions.ConfigurationConflictError:
10 Conflicting configuration actions
11 For: ('view', None, '', None, <InterfaceClass pyramid.interfaces.IView>,
12 None, None, None, None, None, False, None, None, None)
13 Line 14 of file app.py in <module>: 'config.add_view(hello_world)'
14 Line 17 of file app.py in <module>: 'config.add_view(goodbye_world)'
This traceback is trying to tell us:
We've got conflicting information for a set of view configuration statements (The
For:
line).There are two statements which conflict, shown beneath the
For:
line:config.add_view(hello_world. 'hello')
on line 14 ofapp.py
, andconfig.add_view(goodbye_world, 'hello')
on line 17 ofapp.py
.
These two configuration statements are in conflict because we've tried to tell
the system that the set of predicate values for both view
configurations are exactly the same. Both the hello_world
and
goodbye_world
views are configured to respond under the same set of
circumstances. This circumstance, the view name represented by the
name=
predicate, is hello
.
This presents an ambiguity that Pyramid cannot resolve. Rather than
allowing the circumstance to go unreported, by default Pyramid raises a
ConfigurationConflictError
error and prevents the application from
running.
Conflict detection happens for any kind of configuration: imperative configuration or configuration that results from the execution of a scan.
Manually Resolving Conflicts¶
There are a number of ways to manually resolve conflicts: by changing
registrations to not conflict, by strategically using
pyramid.config.Configurator.commit()
, or by using an "autocommitting"
configurator.
The Right Thing¶
The most correct way to resolve conflicts is to "do the needful": change your
configuration code to not have conflicting configuration statements. The
details of how this is done depends entirely on the configuration statements
made by your application. Use the detail provided in the
ConfigurationConflictError
to track down the offending conflicts and
modify your configuration code accordingly.
If you're getting a conflict while trying to extend an existing application, and that application has a function which performs configuration like this one:
1def add_routes(config):
2 config.add_route(...)
Don't call this function directly with config
as an argument. Instead, use
pyramid.config.Configurator.include()
:
1config.include(add_routes)
Using include()
instead of calling the
function directly provides a modicum of automated conflict resolution, with the
configuration statements you define in the calling code overriding those of the
included function.
Using config.commit()
¶
You can manually commit a configuration by using the
commit()
method between configuration calls.
After a commit, more configuration declarations may be added to a configurator.
New declarations will not conflict with committed declarations.
The new declarations will override committed declarations.
For example, we prevent conflicts from occurring in the application we examined
previously by adding a commit
.
Here's the application that generates conflicts:
1from wsgiref.simple_server import make_server
2from pyramid.config import Configurator
3from pyramid.response import Response
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
14 config.add_view(hello_world, name='hello')
15
16 # conflicting view configuration
17 config.add_view(goodbye_world, name='hello')
18
19 app = config.make_wsgi_app()
20 server = make_server('0.0.0.0', 8080, app)
21 server.serve_forever()
We can prevent the two add_view
calls from conflicting by issuing a call to
commit()
between them:
1from wsgiref.simple_server import make_server
2from pyramid.config import Configurator
3from pyramid.response import Response
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
14 config.add_view(hello_world, name='hello')
15
16 config.commit() # commit any pending configuration actions
17
18 # no-longer-conflicting view configuration
19 config.add_view(goodbye_world, name='hello')
20
21 app = config.make_wsgi_app()
22 server = make_server('0.0.0.0', 8080, app)
23 server.serve_forever()
In the above example we've issued a call to
commit()
between the two add_view
calls.
commit()
will execute any pending
configuration statements.
Calling commit()
is safe at any time. It
executes all pending configuration actions and leaves the configuration action
list "clean".
Note that commit()
has no effect when you're
using an autocommitting configurator (see Using an Autocommitting Configurator).
Using an Autocommitting Configurator¶
You can also use a heavy hammer to circumvent conflict detection by using a
configurator constructor parameter: autocommit=True
. For example:
1from pyramid.config import Configurator
2
3if __name__ == '__main__':
4 config = Configurator(autocommit=True)
When the autocommit
parameter passed to the Configurator is True
,
conflict detection (and Two-Phase Configuration) is disabled. Configuration
statements will be executed immediately, and succeeding statements will
override preceding ones.
commit()
has no effect when autocommit
is True
.
If you use a Configurator in code that performs unit testing, it's usually a good idea to use an autocommitting Configurator, because you are usually unconcerned about conflict detection or two-phase configuration in test code.
Automatic Conflict Resolution¶
If your code uses the include()
method to
include external configuration, some conflicts are automatically resolved.
Configuration statements that are made as the result of an "include" will be
overridden by configuration statements that happen within the caller of the
"include" method.
Automatic conflict resolution supports this goal. If a user wants to reuse a Pyramid application, and they want to customize the configuration of this application without hacking its code "from outside", they can "include" a configuration function from the package and override only some of its configuration statements within the code that does the include. No conflicts will be generated by configuration statements within the code that does the including, even if configuration statements in the included code would conflict if it was moved "up" to the calling code.
Methods Which Provide Conflict Detection¶
These are the methods of the configurator which provide conflict detection:
add_static_view()
also indirectly provides
conflict detection, because it's implemented in terms of the conflict-aware
add_route
and add_view
methods.
Including Configuration from External Sources¶
Some application programmers will factor their configuration code in such a way that it is easy to reuse and override configuration statements. For example, such a developer might factor out a function used to add routes to their application:
1def add_routes(config):
2 config.add_route(...)
Rather than calling this function directly with config
as an argument,
instead use pyramid.config.Configurator.include()
:
1config.include(add_routes)
Using include
rather than calling the function directly will allow
Automatic Conflict Resolution to work.
include()
can also accept a module
as an argument:
1import myapp
2
3config.include(myapp)
For this to work properly, the myapp
module must contain a callable with
the special name includeme
, which should perform configuration (like the
add_routes
callable we showed above as an example).
include()
can also accept a dotted
Python name to a function or a module.
注釈
See The <include> Tag for a declarative alternative to the
include()
method.
Two-Phase Configuration¶
When a non-autocommitting Configurator is used to do configuration (the default), configuration execution happens in two phases. In the first phase, "eager" configuration actions (actions that must happen before all others, such as registering a renderer) are executed, and discriminators are computed for each of the actions that depend on the result of the eager actions. In the second phase, the discriminators of all actions are compared to do conflict detection.
Due to this, for configuration methods that have no internal ordering
constraints, execution order of configuration method calls is not important.
For example, the relative ordering of
add_view()
and
add_renderer()
is unimportant when a
non-autocommitting configurator is used. This code snippet:
1config.add_view('some.view', renderer='path_to_custom/renderer.rn')
2config.add_renderer('.rn', SomeCustomRendererFactory)
Has the same result as:
1config.add_renderer('.rn', SomeCustomRendererFactory)
2config.add_view('some.view', renderer='path_to_custom/renderer.rn')
Even though the view statement depends on the registration of a custom
renderer, due to two-phase configuration, the order in which the configuration
statements are issued is not important. add_view
will be able to find the
.rn
renderer even if add_renderer
is called after add_view
.
The same is untrue when you use an autocommitting configurator (see Using an Autocommitting Configurator). When an autocommitting configurator is used, two-phase configuration is disabled, and configuration statements must be ordered in dependency order.
Some configuration methods, such as
add_route()
have internal ordering
constraints: the routes they imply require relative ordering. Such ordering
constraints are not absolved by two-phase configuration. Routes are still
added in configuration execution order.
More Information¶
For more information, see the article A Whirlwind Tour of Advanced Configuration Tactics in the Pyramid Community Cookbook.