API Reference

class mush.Plug

Base class for a ‘plug’ that can add to several points in a runner.

add_to(runner)

Add methods of the instance to the supplied runner. By default, all methods will be added and the name of the method will be used as the label in the runner at which the method will be added. If no such label exists, a KeyError will be raised.

If explicit is True, then only methods decorated with an insert will be added.

explicit = False

Control whether methods need to be decorated with insert in order to be added by this Plug.

class mush.Runner(*objects)

A chain of callables along with declarations of their required and returned resources along with tools to manage the order in which they will be called.

__add__(other)

Return a new Runner containing the contents of the two Runner instances being added together.

__call__(context=None)

Execute the callables in this runner in the required order storing objects that are returned and providing them as arguments or keyword parameters when required.

A runner may be called multiple times. Each time a new Context will be created meaning that no required objects are kept between calls and all callables will be called each time.

Parameters

context – Used for passing a context when context managers are used. You should never need to pass this parameter.

__getitem__(label)

Retrieve a Modifier for a previous labelled point in the runner.

add(obj, requires=None, returns=None, label=None, lazy=False)

Add a callable to the runner.

Parameters

• obj – The callable to be added.

• requires – The resources to required as parameters when calling obj. These can be specified by passing a single type, a string name or a requires object.

• returns – The resources that obj will return. These can be specified as a single type, a string name or a returns, returns_mapping, returns_sequence object.

• label – If specified, this is a string that adds a label to the point where obj is added that can later be retrieved with Runner.__getitem__().

• lazy – If true, obj will only be called the first time it is needed.

add_label(label)

Add a label to the the point currently at the end of the runner.

clone(start_label=None, end_label=None, include_start=False, include_end=False, added_using=None)

Return a copy of this Runner.

Parameters

• start_label – An optional string specifying the point at which to start cloning.

• end_label – An optional string specifying the point at which to stop cloning.

• include_start – If True, the point specified in start_label will be included in the cloned runner.

• include_end – If True, the point specified in end_label will be included in the cloned runner.

• added_using – An optional string specifying that only points added using the label specified in this option should be cloned. This filtering is applied in addition to the above options.

extend(*objs)

Add the specified callables to this runner.

If any of the objects passed is a Runner, the contents of that runner will be added to this runner.

replace(original, replacement, requires=None, returns=None)

Replace all instances of one callable with another.

No changes in requirements or call ordering will be made unless the replacements have been decorated with requirements, or either requires or returns have been specified.

Parameters

• requires – The resources to required as parameters when calling obj. These can be specified by passing a single type, a string name or a requires object.

• returns – The resources that obj will return. These can be specified as a single type, a string name or a returns, returns_mapping, returns_sequence object.

class mush.attr(type, *names)

A how that indicates the callable requires the named attribute from the decorated type.

process(o)

Extract the required part of the object passed in. missing should be returned if the required part cannot be extracted. missing may be passed in and is usually be handled by returning missing immediately.

class mush.item(type, *names)

A how that indicates the callable requires the named item from the decorated type.

process(o)

Extract the required part of the object passed in. missing should be returned if the required part cannot be extracted. missing may be passed in and is usually be handled by returning missing immediately.

class mush.optional(type, *names)

A how that indicates the callable requires the wrapped requirement only if it’s present in the Context.

process(o)

Extract the required part of the object passed in. missing should be returned if the required part cannot be extracted. missing may be passed in and is usually be handled by returning missing immediately.

class mush.requires(*args, **kw)

Represents requirements for a particular callable.

The passed in args and kw should map to the types, including any required how, for the matching arguments or keyword parameters the callable requires.

String names for resources must be used instead of types where the callable returning those resources is configured to return the named resource.

__call__(obj)

Call self as a function.

__iter__()

When iterated over, yields tuples representing individual types required by arguments or keyword parameters in the form (keyword_name, decorated_type).

If the keyword name is None, then the type is for a positional argument.

class mush.returns(*args)

Declaration that specifies names for returned resources or overrides the type of a returned resource.

This declaration can be used to indicate the type or name of a single returned resource or, if multiple arguments are passed, that the callable will return a sequence of values where each one should be named or have its type overridden.

class mush.returns_mapping

Declaration that indicates a callable returns a mapping of type or name to resource.

class mush.returns_result_type

Default declaration that indicates a callable’s return value should be used as a resource based on the type of the object returned.

None is ignored as a return value.

class mush.returns_sequence

Declaration that indicates a callable’s returns a sequence of values that should be used as a resources based on the type of the object returned.

Any None values in the sequence are ignored.

class mush.context.Context

Stores resources for a particular run.

add(it, type)

Add a resource to the context.

Optionally specify the type to use for the object rather than the type of the object itself.

exception mush.context.ContextError(text, point=None, context=None)

Errors likely caused by incorrect building of a runner.

class mush.modifier.Modifier(runner, callpoint, label)

Used to make changes at a particular point in a runner. These are returned by Runner.add() and Runner.__getitem__().

add(obj, requires=None, returns=None, label=None, lazy=False)

Parameters

• obj – The callable to be added.

• requires – The resources to required as parameters when calling obj. These can be specified by passing a single type, a string name or a requires object.

• returns – The resources that obj will return. These can be specified as a single type, a string name or a returns, returns_mapping, returns_sequence object.

• label – If specified, this is a string that adds a label to the point where obj is added that can later be retrieved with Runner.__getitem__().

• lazy – If true, obj will only be called the first time it is needed.

If no label is specified but the point which this Modifier represents has any labels, those labels will be moved to the newly inserted point.

add_label(label, callpoint=None)

Add a label to the point represented by this Modifier.

Parameters

callpoint – For internal use only.

class mush.declarations.how(type, *names)

The base class for type decorators that indicate which part of a resource is required by a particular callable.

Parameters

• type – The resource type to be decorated.

• names – Used to identify the part of the resource to extract.

process(o)

Extract the required part of the object passed in. missing should be returned if the required part cannot be extracted. missing may be passed in and is usually be handled by returning missing immediately.

mush.declarations.nothing = requires()

A singleton that be used as a requires to indicate that a callable has no required arguments or as a returns to indicate that anything returned from a callable should be ignored.

mush.declarations.result_type = returns_result_type()

A singleton indicating that a callable’s return value should be stored based on the type of that return value.

mush.declarations.update_wrapper(wrapper, wrapped, assigned=('__module__', '__name__', '__qualname__', '__doc__', '__annotations__', '__mush__requires__', '__mush_returns__'), updated=('__dict__',))

An extended version of functools.update_wrapper() that also preserves Mush’s annotations.

class mush.plug.Plug

Base class for a ‘plug’ that can add to several points in a runner.

add_to(runner)

Add methods of the instance to the supplied runner. By default, all methods will be added and the name of the method will be used as the label in the runner at which the method will be added. If no such label exists, a KeyError will be raised.

If explicit is True, then only methods decorated with an insert will be added.

explicit = False

Control whether methods need to be decorated with insert in order to be added by this Plug.

class mush.plug.append

A decorator to mark that this method of a Plug should be added to the end of a runner by add_to().

class mush.plug.ignore

A decorator to explicitly mark that a method of a Plug should not be added to a runner by add_to()

class mush.plug.insert(label=None)

A decorator to explicitly mark that a method of a Plug should be added to a runner by add_to(). The label parameter can be used to indicate a different label at which to add the method, instead of using the name of the method.