API Reference¶

Wires Package¶

Python Wires

class wires.Wires(min_wirings=None, max_wirings=None, returns=False, ignore_exceptions=True)¶: Wires Class.

wires.w = Shared Wires instance.¶: Wires Class.

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

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 or None) – Minimum wiring count.
max_wirings (int > 0 or None) – Maximum wiring count.
returns (bool) – If True, calling callables returns results/raises exceptions.
ignore_exceptions (bool) – If True, all wired callables will be called, regardless of raised exceptions; if False, wired callable calling will stop after the first exception.

__repr__()¶: Evaluating creates a new object with the same initialization arguments.

__getattr__(name)¶: Attribute based access to WiresCallables.

__getitem__(name)¶: Index based access to WiresCallables.

__delattr__(name)¶: Deletes WiresCallables or any other attributes.

__dir__()¶: Default dir() implementation.

__len__()¶: Existing WiresCallable count.

__iter__()¶: Iterate over existing WiresCallables.

__call__(returns=None, ignore_exceptions=None)¶

Call-time settings override.

Parameters:	returns (`bool`) – If `True`, calling callables returns results/raises exceptions. ignore_exceptions (`bool`) – If `True`, all wired callables will be called, regardless of raised exceptions; if `False`, 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

WiresCallable Class¶

Python Wires WiresCallable Class.

WiresCallables 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!

WiresCallables 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 containing Wires’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.

max_wirings¶

Maximum number of wirings or None, meaning no limit.

Reading returns the per-WiresCallable value, if set, falling back to the containing Wires’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.

returns¶

bool value defining call-time coupling behaviour: see __call__().

Reading returns the per-WiresCallable value, if set, falling back to the containing Wires’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 containing Wires’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 for min_wirings and max_wirings.

__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, with args and kwargs as wire-time arguments.

Raises:	TypeError – If `function` is not `callable()`. RuntimeError – If `max_wirings` would be violated.

unwire(function, *args, **kwargs)¶

Removes the first wiring to function.

If args or kwargs are passed, unwires the first wired function with those wire-time arguments; otherwise, unwires the first wired function, regardless of wire-time arguments.

Raises:	TypeError – If `function` is not `callable()`. ValueError – If no matching wiring is found. RuntimeError – If `min_wirings` would be violated.

wirings¶: List of (<function>, <args>, <kwargs>) wiring tuples, in wiring order, where <args> and <kwargs> are the wire-time arguments passed to wire().

__call__(*args, **kwargs)¶

Calls wired callables, in wiring order.

Raises:	ValueError – If the wiring count is lower than `min_wirings`, when set to an `int` > 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: if False, calling returns None; otherwise, returns or raises (see below).
ignore_exceptions: if False, 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>` is `None` and `<result>` holds the returned value from that wiring, if no exception was raised; otherwise, `<exception>` is the raised exception and `<result>` is `None`.
Raises:	RuntimeError – Only if `returns` is `True`, `ignore_exceptions` is `False`, 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.