API Reference

class mush.Context

Stores requirements, callables and resources for a particular run.

__iter__()

When iterated over, the context will yield tuples containing the requirements for a callable and the callable itself in the form (requirements, object).

This can only be done once for a given context. A context that has been partially iterated over will remember where it had got to and pick up from there when iteration begins again.

add(it, type=None)

Add a resource to the context.

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

get(type)

Get an object of the specified type from the context.

This will raise a KeyError if no object of that type can be located.

class mush.Marker

Type for Marker classes

class mush.Periods

A collection of lists used to store the callables that require a particular resource type.

__iter__()

Yields callables in the order in which they require the resource this instance is used for.

first = None

The callables that require first use of a particular resource.

last = None

The callables that require last use of a particular resource.

normal = None

The callables that require use of a particular resource in the order to which they’re added to the Runner.

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

Represents requirements for a particular callable

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

__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.

returns

An override for the type that this callable will return.

alias of not_specified

class mush.Runner(*objs, **debug)

Used to run callables in the order in which they require particular resources and then, having taken that into account, in the order they are added to the runner.

Parameters:

• objs – The callables to add to the runner as it is created.
• debug – If passed, debug information will be written whenever an object is added to the runner. If True, it will be written to stderr. A file-like object can also be passed, in which case the information will be written to that object.

__add__(other)

Concatenate two runners, returning a new runner.

The order of the new runner is as if the callables had been added in order from runner on the left-hand side of expression and then in order from the runner on the right-hand side of the expression.

__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.

add(obj, *args, **kw)

Add a callable to the runner.

If either args or kw are specified, they will be used to create the Requirements in this runner for the callable added in favour of any decoration done with requires.

add_returning(obj, returns, *args, **kw)

Add a callable to the runner and specify that it should be treated as returning the type specified in returns, regardless of the actual type returned by calling obj.

If either args or kw are specified, they will be used to create the Requirements in this runner for the callable added in favour of any decoration done with requires.

clone()

Return a copy of this runner.

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)

Replace all instances of one callable with another.

No changes in requirements or call ordering will be made.

mush.after(type)

A type wrapper that specifies the callable marked as requiring this type should not be passed an object of this type but should only be called once an object of that type is available, and should be done so in the last period.

class mush.attr(type, *names)

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

class mush.first(type=<class 'NoneType'>)

A when that indicates the callable requires first use of the decorated type.

class mush.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 type to be decorated.
• name – The part of the type required by the callable.

class mush.ignore(type, *names)

A how that indicates the callable should not be passed an object of the decorated type.

class mush.item(type, *names)

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

class mush.last(type=<class 'NoneType'>)

A when that indicates the callable requires last use of the decorated type.

mush.marker(name)

Return a Marker for the given name, creating if needed.

mush.nothing = Requirements()

A singleton Requirements indicating that a callable requires no resources.

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

A decorator used for marking a callable with the Requirements it needs.

These are stored in an attribute called __requires__ on the callable meaning that the callable can be used in its original form after decoration.

If you need to specify requirements for a callable that cannot have attributes added to it, then use the add() method to do so.

class mush.returns(type)

A decorator to indicate that a callable should be treated as returning the type passed to returns() rather than the type of the actual return value.

class mush.when(type=<class 'NoneType'>)

The base class for type decorators that indicate when a callable requires a particular type.

Parameters:type – The type to be decorated.