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__()
.
-
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 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. - 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)¶ 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.
-
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
isTrue
, then only methods decorated with aninsert
will be added.
-
-
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
-
class
mush.plug.
insert
(label=None)¶ A decorator to explicitly mark that a method of a
Plug
should be added to a runner byadd_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.
-
class
mush.plug.
ignore
¶ A decorator to explicitly mark that a method of a
Plug
should not be added to a runner byadd_to()
-
class
mush.plug.
append
¶ A decorator to mark that this method of a
Plug
should be added to the end of a runner byadd_to()
.
-
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
isTrue
, then only methods decorated with aninsert
will be added.
-