Navigation

To support application extensibility, the PyramidConfigurator, 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.

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 of app.py, and
config.add_view(goodbye_world,'hello') on line 17 of app.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.

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

1
2

defadd_routes(config):config.add_route(...)

Don’t call this function directly with config as an argument. Instead,
use pyramid.config.Configuration.include():

You can manually commit a configuration by using the
commit() method between configuration
calls. For example, we prevent conflicts from occurring in the application
we examined previously as the result of adding a commit. Here’s the
application that generates conflicts:

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.

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.

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.

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
his application:

1
2

defadd_routes(config):config.add_route(...)

Rather than calling this function directly with config as an argument.
Instead, use pyramid.config.Configuration.include():

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:

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.