API

dectate.commit(*apps)

Commit one or more app classes

A commit causes the configuration actions to be performed. The resulting configuration information is stored under the .config class attribute of each App subclass supplied.

This function may safely be invoked multiple times – each time the known configuration is recommitted.

Parameters:*apps – one or more App subclasses to perform configuration actions on.

dectate.autocommit()

Automatically commit all App subclasses.

Dectate keeps track of all App subclasses that have been imported. You can automatically commit configuration for all of them.

class dectate.App

A configurable application object.

Subclass this in your framework and add directives using the App.directive() decorator.

Set the logger_name class attribute to the logging prefix that Dectate should log to. By default it is "dectate.directive".

classmethod directive(name)

Decorator to register a new directive with this application class.

You use this as a class decorator for a dectate.Action or a dectate.Composite subclass:

@MyApp.directive('my_directive')
class FooAction(dectate.Action):
    ...

This needs to be executed before the directive is used and thus might introduce import dependency issues unlike normal Dectate configuration, so beware! An easy way to make sure that all directives are installed before you use them is to make sure you define them in the same module as where you define the App subclass that has them.

classmethod private_action_class(action_class)

Register a private action class.

In some cases action classes can be an implementation detail, for instance in the implementation of a Composite action.

In this case you don’t want the action class to be known but not have a directive.

This function may be used as a decorator like this:

@App.private_action_class
class MyActionClass(dectate.Action):
    ...

logger_name = 'dectate.directive'

The prefix to use for directive debug logging.

class dectate.Action

A configuration action.

Base class of configuration actions.

A configuration action is performed for an object (typically a function or a class object) and affects one or more configuration objects.

Actions can conflict with each other based on their identifier and discriminators. Actions can override each other based on their identifier. Actions can only be in conflict with actions of the same action class or actions with the same action_group.

static after(**kw)

Do setup just after actions in a group are performed.

Can be implemented as a static method by the Action subclass.

Parameters:**kw – a dictionary of configuration objects as specified by the config class attribute.

static before(**kw)

Do setup just before actions in a group are performed.

Can be implemented as a static method by the Action subclass.

Parameters:**kw – a dictionary of configuration objects as specified by the config class attribute.

discriminators(**kw)

Returns a list of immutables to detect conflicts.

Can be implemented by the Action subclass.

Used for additional configuration conflict detection.

Parameters:**kw – a dictionary of configuration objects as specified by the config class attribute.

identifier(**kw)

Returns an immutable that uniquely identifies this config.

Needs to be implemented by the Action subclass.

Used for overrides and conflict detection.

If two actions in the same group have the same identifier in the same configurable, those two actions are in conflict and a ConflictError is raised during commit().

If an action in an extending configurable has the same identifier as the configurable being extended, that action overrides the original one in the extending configurable.

Parameters:**kw – a dictionary of configuration objects as specified by the config class attribute.

perform(obj, **kw)

Do whatever configuration is needed for obj.

Needs to be implemented by the Action subclass.

Raise a DirectiveError to indicate that the action cannot be performed due to incorrect configuration.

Parameters:

• obj – the object that the action should be performed for. Typically a function or a class object.
• **kw – a dictionary of configuration objects as specified by the config class attribute.

code_info

Info about where in the source code the action was invoked.

Is an instance of CodeInfo.

Can be None if action does not have an associated directive but was created manually.

config = {}

Describe configuration.

A dict mapping configuration names to factory functions. The resulting configuration objects are passed into Action.identifier(), Action.discriminators(), Action.perform(), and Action.before() and Action.after().

After commit completes, the configured objects are found as attributes on App.config.

depends = []

List of other action classes to be executed before this one.

The depends class attribute contains a list of other action classes that need to be executed before this one is. Actions which depend on another will be executed after those actions are executed.

Omit if you don’t care about the order.

group_class = None

Action class to group with.

This class attribute can be supplied with the class of another action that this action should be grouped with. Only actions in the same group can be in conflict. Actions in the same group share the config and before and after of the action class indicated by group_class.

By default an action only groups with others of its same class.

class dectate.Composite

A composite configuration action.

Base class of composite actions.

Composite actions are very simple: implement the action method and return a iterable of actions in there.

actions(obj)

Specify a iterable of actions to perform for obj.

The iteratable should yield action, obj tuples, where action is instance of class Action or Composite and obj is the object to perform the action with.

Needs to be implemented by the Composite subclass.

code_info

Info about where in the source code the action was invoked.

Is an instance of CodeInfo.

Can be None if action does not have an associated directive but was created manually.

class dectate.CodeInfo(path, lineno, sourceline)

Information about where code was invoked.

The path attribute gives the path to the Python module that the code was invoked in.

The lineno attribute gives the linenumber in that file.

The sourceline attribute contains the actual source line that did the invocation.

exception dectate.ConfigError

Raised when configuration is bad.

exception dectate.ConflictError(actions)

Bases: dectate.error.ConfigError

Raised when there is a conflict in configuration.

Describes where in the code directives are in conflict.

exception dectate.DirectiveError

Bases: dectate.error.ConfigError

Can be raised by user when there directive cannot be performed.

Raise it in Action.perform() with a message describing what the problem is:

raise DirectiveError("name should be a string, not None")

This is automatically converted by Dectate to a DirectiveReportError.

exception dectate.DirectiveReportError(message, code_info)

Bases: dectate.error.ConfigError

Raised when there’s a problem with a directive.

Describes where in the code the problem occurred.