Computing The Resolution Order (Priority)

Just as Python classes have a method resolution order that determines which implementation of a method gets used when inheritance is used, interfaces have a resolution order that determines their ordering when searching for adapters.

That order is computed by zope.interface.ro.ro. This is an internal module not generally needed by a user of zope.interface, but its documentation can be helpful to understand how orders are computed.

zope.interface.ro

Compute a resolution order for an object and its bases.

Changed in version 5.0: The resolution order is now based on the same C3 order that Python uses for classes. In complex instances of multiple inheritance, this may result in a different ordering.

In older versions, the ordering wasn’t required to be C3 compliant, and for backwards compatibility, it still isn’t. If the ordering isn’t C3 compliant (if it is inconsistent), zope.interface will make a best guess to try to produce a reasonable resolution order. Still (just as before), the results in such cases may be surprising.

Environment Variables

Due to the change in 5.0, certain environment variables can be used to control errors and warnings about inconsistent resolution orders. They are listed in priority order, with variables at the bottom generally overriding variables above them.

ZOPE_INTERFACE_WARN_BAD_IRO

If this is set to “1”, then if there is at least one inconsistent resolution order discovered, a warning (InconsistentResolutionOrderWarning) will be issued. Use the usual warning mechanisms to control this behaviour. The warning text will contain additional information on debugging.

ZOPE_INTERFACE_TRACK_BAD_IRO

If this is set to “1”, then zope.interface will log information about each inconsistent resolution order discovered, and keep those details in memory in this module for later inspection.

ZOPE_INTERFACE_STRICT_IRO

If this is set to “1”, any attempt to use ro() that would produce a non-C3 ordering will fail by raising InconsistentResolutionOrderError.

Important

ZOPE_INTERFACE_STRICT_IRO is intended to become the default in the future.

There are two environment variables that are independent.

ZOPE_INTERFACE_LOG_CHANGED_IRO

If this is set to “1”, then if the C3 resolution order is different from the legacy resolution order for any given object, a message explaining the differences will be logged. This is intended to be used for debugging complicated IROs.

ZOPE_INTERFACE_USE_LEGACY_IRO

If this is set to “1”, then the C3 resolution order will not be used. The legacy IRO will be used instead. This is a temporary measure and will be removed in the future. It is intended to help during the transition. It implies ZOPE_INTERFACE_LOG_CHANGED_IRO.

Debugging Behaviour Changes in zope.interface 5

Most behaviour changes from zope.interface 4 to 5 are related to inconsistent resolution orders. ZOPE_INTERFACE_STRICT_IRO is the most effective tool to find such inconsistent resolution orders, and we recommend running your code with this variable set if at all possible. Doing so will ensure that all interface resolution orders are consistent, and if they’re not, will immediately point the way to where this is violated.

Occasionally, however, this may not be enough. This is because in some cases, a C3 ordering can be found (the resolution order is fully consistent) that is substantially different from the ad-hoc legacy ordering. In such cases, you may find that you get an unexpected value returned when adapting one or more objects to an interface. To debug this, also enable ZOPE_INTERFACE_LOG_CHANGED_IRO and examine the output. The main thing to look for is changes in the relative positions of interfaces for which there are registered adapters.

exception zope.interface.ro.InconsistentResolutionOrderError(c3, base_tree_remaining)

Bases: TypeError

The error raised when an invalid IRO is requested in strict mode.

exception zope.interface.ro.InconsistentResolutionOrderWarning

Bases: PendingDeprecationWarning

The warning issued when an invalid IRO is requested.

zope.interface.ro.ro(C) → list

Compute the precedence list (mro) according to C3.

Returns:

A fresh list object.

Changed in version 5.0.0: Add the strict, log_changed_ro and use_legacy_ro keyword arguments. These are provisional and likely to be removed in the future. They are most useful for testing.