API Reference¶
Wires Package¶
Python Wires
Wires Class¶
Python Wires Wires
Class.
Wires
objects hold callables as attributes that spring into existence
on first access; each such callable is a
WiresCallable
object.
>>> w = Wires()
>>> c = w.one_callable # Springs into existence.
>>> callable(c) # Is callable.
True
Callables can also be accessed via indexing:
>>> w['one_callable'] is w.one_callable
True
Wires
objects support dir()
, len()
and iteration:
>>> dir(w) # Get callable name list.
['one_callable']
>>> len(w) # How many callables?
1
>>> for c in w: # Iterating over all callables.
... print(c)
<WiresCallable 'one_callable' at 0x1018d4a90>
Deleting attributes deletes the associated callable:
>>> del w.one_callable # Delete and check it's gone.
>>> len(w)
0
-
class
wires._wires.
Wires
(min_wirings=None, max_wirings=None, returns=False, ignore_exceptions=True)¶ Wires
Class.-
__init__
(min_wirings=None, max_wirings=None, returns=False, ignore_exceptions=True)¶ Initialization arguments determine default settings for this object’s
WiresCallable
s.Optional, per-
WiresCallable
settings override these settings and, single use, call-time overriding is supported via calls to self: see__call__()
.Parameters: - min_wirings (
int
> 0 orNone
) – Minimum wiring count. - max_wirings (
int
> 0 orNone
) – Maximum wiring count. - returns (
bool
) – IfTrue
, calling callables returns results/raises exceptions. - ignore_exceptions (
bool
) – IfTrue
, all wired callables will be called, regardless of raised exceptions; ifFalse
, wired callable calling will stop after the first exception.
- min_wirings (
-
__repr__
()¶ Evaluating creates a new object with the same initialization arguments.
-
__getattr__
(name)¶ Attribute based access to
WiresCallable
s.
-
__getitem__
(name)¶ Index based access to
WiresCallable
s.
-
__delattr__
(name)¶ Deletes
WiresCallable
s or any other attributes.
-
__dir__
()¶ Default dir() implementation.
-
__len__
()¶ Existing
WiresCallable
count.
-
__iter__
()¶ Iterate over existing
WiresCallable
s.
-
__call__
(returns=None, ignore_exceptions=None)¶ Call-time settings override.
Parameters: - returns (
bool
) – IfTrue
, calling callables returns results/raises exceptions. - ignore_exceptions (
bool
) – IfTrue
, all wired callables will be called, regardless of raised exceptions; ifFalse
, wired callable calling will stop after the first exception.
Usage example:
>>> w = Wires(returns=False) >>> w.one_callable() # returns is False >>> w(returns=True).one_callable() # returns is True for this call only [] >>> w.one_callable() # returns is still False
- returns (
-
WiresCallable Class¶
Python Wires WiresCallable
Class.
WiresCallable
s are callable objects used exclusively as
Wires
object attributes.
>>> w = Wires()
>>> callable(w.one_callable)
True
Each WiresCallable
has zero or more wirings: functions/callables
wired to it. Their wire
method is used to add
wirings, including optional wire-time arguments:
>>> w.one_callable.wire(print, 'hi') # Wire `print`: one wire-time positional arg.
>>> w.one_callable.wire(print, 'bye') # 2nd `print` wiring: different wire-time arg.
Calling a WiresCallable
calls its wirings, in wiring order, passing
them a combination of the optional wire-time and optional call-time arguments:
>>> w.one_callable('world', end='!\n') # Call with call-time positional and named args.
hi world!
bye world!
WiresCallable
s have a wirings
attribute, representing all current wirings, and include support for len()
,
returning the wiring count:
>>> w.one_callable.wirings
[(<built-in function print>, ('hi',), {}), (<built-in function print>, ('bye',), {})]
>>> len(w.one_callable)
2
WiresCallable
objects behave differently depending on their
Wires
object’s settings and on their own
min_wirings
,
max_wirings
,
returns
and
ignore_exceptions
attributes.
-
class
wires._callable.
WiresCallable
(_wires, _name, _wires_settings)¶ WiresCallable
Class.-
__init__
(_wires, _name, _wires_settings)¶ IMPORTANT
Do not instantiate
WiresCallable
objects;Wires
objects do that, when needed. The class name and all its initialization arguments are considered private and may change in the future without prior notice.To ensure future compatibility, it should be used strictly in the context of
Wires
objects, along with its public attributes, properties and methods.
-
__repr__
()¶ Return repr(self).
-
min_wirings
¶ Minimum number of wirings or
None
, meaning no limit.Reading returns the per-
WiresCallable
value, if set, falling back to the containingWires
’s setting. Writing assigns a per-WiresCallable
value that, if non-None
, must be:- An
int
> 0. - Less than or equal to
max_wirings
. - Less than or equal to the wiring count, if there are wirings.
Raises: ValueError – When assigned invalid values. - An
-
max_wirings
¶ Maximum number of wirings or
None
, meaning no limit.Reading returns the per-
WiresCallable
value, if set, falling back to the containingWires
’s setting. Writing assigns a per-WiresCallable
value that, if non-None
, must be:- An
int
> 0. - Greater than or equal to
min_wirings
. - Greater than or equal to the wiring count, if there are wirings.
Raises: ValueError – When assigned non-conforming values. - An
-
returns
¶ bool
value defining call-time coupling behaviour: see__call__()
.Reading returns the per-
WiresCallable
value, if set, falling back to the containingWires
’s setting. Writing assigns a per-WiresCallable
value.
-
ignore_exceptions
¶ bool
value defining call-time coupling behaviour: see__call__()
.Reading returns the per-
WiresCallable
value, if set, falling back to the containingWires
’s setting. Writing assigns a per-WiresCallable
value.
-
set
(min_wirings=<object object>, max_wirings=<object object>, returns=<object object>, ignore_exceptions=<object object>, _next_call_only=False)¶ Sets one or more per-
WiresCallable
settings.Parameters: - min_wirings – See
min_wirings
. - max_wirings – See
max_wirings
. - returns – See
returns
. - ignore_exceptions – See
ignore_exceptions
. - _next_call_only – IMPORTANT: This argument is considered private and may be changed or removed in future releases.
Raises: May raise exceptions. Refer to the per-attribute documentation.
The uncommon defaults are used as a guard to identify non-set arguments, given than
None
is a valid value formin_wirings
andmax_wirings
.- min_wirings – See
-
__delattr__
(name)¶ Removes per-
WiresCallable
settings.Parameters: name ( str
) – An existing attribute name.Raises: May raise exceptions if the resulting settings would be invalid.
-
wire
(function, *args, **kwargs)¶ Adds a new wiring to
function
, withargs
andkwargs
as wire-time arguments.Raises: - TypeError – If
function
is notcallable()
. - RuntimeError – If
max_wirings
would be violated.
- TypeError – If
-
unwire
(function, *args, **kwargs)¶ Removes the first wiring to
function
.If
args
orkwargs
are passed, unwires the first wiredfunction
with those wire-time arguments; otherwise, unwires the first wiredfunction
, regardless of wire-time arguments.Raises: - TypeError – If
function
is notcallable()
. - ValueError – If no matching wiring is found.
- RuntimeError – If
min_wirings
would be violated.
- TypeError – If
-
wirings
¶ List of
(<function>, <args>, <kwargs>)
wiring tuples, in wiring order, where<args>
and<kwargs>
are the wire-time arguments passed towire()
.
-
__call__
(*args, **kwargs)¶ Calls wired callables, in wiring order.
Raises: ValueError – If the wiring count is lower than min_wirings
, when set to anint
> 0.Argument passing:
- Wired callables are passed a combination of the wire-time and call-time arguments; wire-time positional arguments will be passed first, followed by the call-time ones; wire-time named arguments may be overridden by call-time ones.
Call-time coupling depends on:
returns
: ifFalse
, calling returnsNone
; otherwise, returns or raises (see below).ignore_exceptions
: ifFalse
, calling wirings stops on the first wiring-raised exception; otherwise, all wirings will be called.
Returns: A list of (<exception>, <result>)
tuples, in wiring order, where:<exception>
isNone
and<result>
holds the returned value from that wiring, if no exception was raised; otherwise,<exception>
is the raised exception and<result>
isNone
.Raises: RuntimeError – Only if returns
isTrue
,ignore_exceptions
isFalse
, and a wiring raises an exception. The exception arguments will be a tuple of(<exception>, <result>)
tuples, much like the returned ones, where only the last one will have<exception>
as a non-None
value.
-
__len__
()¶ Wiring count.
-