API Reference¶
-
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 twoRunner
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.
-
add
(obj, requires=None, returns=None, label=None)¶ 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__()
.
-
clone
(start_label=None, end_label=None, include_start=False, include_end=False)¶ 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 instart_label
will be included in the cloned runner. - include_end – If
True
, the point specified inend_label
will be included in the cloned 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.
-
-
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.
-
__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.
optional
(type, *names)¶ A
how
that indicates the callable requires the wrapped requirement only if it’s present in theContext
.
-
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_mapping
¶ Declaration that indicates a callable returns a mapping of type or name to resource.
-
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.
returns
(*args)¶ Declaration that specified 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.
attr
(type, *names)¶ A
how
that indicates the callable requires the named attribute from the decorated type.
-
class
mush.
item
(type, *names)¶ A
how
that indicates the callable requires the named item from the decorated type.
-
class
mush.
Plug
¶ Base class for a ‘Plug’ that can add to several points in a runner.
-
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=None)¶ Used to make changes at a particular point in a runner. These are returned by
Runner.add()
andRunner.__getitem__()
.-
add
(obj, requires=None, returns=None, label=None)¶ 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__()
.
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.
-
-
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 returningmissing
immediately.
-
mush.declarations.
nothing
= requires()¶ A singleton
requires
indicating that a callable has no required arguments.
-
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