toolbox.iter Documentation and API reference

Full API documentation of the toolbox.iter Python module.

Tools to iterate Python objects.

zip_smart

iter.zip_smart(*, unpack_nozip=True, strict=False)

Iterate over several iterables in parallel, producing tuples with an item from each one.

Like Python’s builtin zip function, but if an argument is not iterable, it will be repeated each iteration.

Exception: strings will be repeated by default. Override the NON_ITERABLE_TYPES constant of the module to change this behavior.

To be iterated, the item needs to have an __iter__ attribute. Otherwise, it will be repeated.

Pay attention with the strict parameter:

• only working with Python <3.10

• always raises an error if an item is repeated, since the generator is endless.

Parameters:

*iterables: misc

Elements to iterate or repeat.

unpack_nozip: bool, default: True

Unpack a NoZip-wrapped iterable.

strict: bool, default: True

Fail if iterables are not the same length. Warning: Not supported in Python < 3.10.

Returns:

zip object

Use it as you would use zip

Examples

>>> for a, b, c, d, e in zip_smart(
...     ("A", "B", "C", "D"),
...     True,
...     [1, 2, 3, 4],
...     "always the same",
...     repeat((1, 2)),
... ):
...     print(a, b, c, d, e)
A True 1 always the same (1, 2)
B True 2 always the same (1, 2)
C True 3 always the same (1, 2)
D True 4 always the same (1, 2)

repeat

iter.repeat(unpack_nozip=True)

A generator that always returns arg.

Parameters:

arg

Any arbitraty object.

unpack_nozip: bool, default: True

Deprecation: Instead of NoZip, use repeat.

Unpack objects protected by NoZip.

Returns:

generator function

which always returns arg.

Examples

>>> for a, b, c, d, e in zip_smart(
...     ("A", "B", "C", "D"),
...     True,
...     [1, 2, 3, 4],
...     "always the same",
...     repeat((1, 2)),
... ):
...     print(a, b, c, d, e)
A True 1 always the same (1, 2)
B True 2 always the same (1, 2)
C True 3 always the same (1, 2)
D True 4 always the same (1, 2)

filter_nozip

iter.filter_nozip(no_iter_types=None, recursive=False, length=2)

Filter patterns which should not be unpacked in zip.

Parameters:

iterable

no_iter_types, tuple, optional

Types which, if found, indicate this iterable should not be unpacked.

Default: (float, int, datetime)

Returns:

either iterable or repeat(iterable)

sum_nested

iter.sum_nested(iterable_types=None, depth=-1, custom_digestion=None)

Add up all values in iterable objects.

Nested structures are added up recursively. In dictionaries, only the values are used.

Parameters:

inp: iterable

Object to iterate over. If it is not a iterable type, the object itself is returned.

iterable_types: tuple of types, optional

If iterable is one of these types, hand to zip() directly without repeating. Default: (tuple, list, np.ndarray, pandas.Series)

depth: int, optional

Maximum depth to recurse. Set to -1 to recurse infinitely. Default -1.

custom_digestion: tuple of tuples, optional

Each element of the tuple must be a tuple of the following structure:

(

type or tuple of types, lambda function to digest the elements,

)

The result of the lambda function will then be treated like the new type. By default, toolbox.iter.CUSTOM_DIGESTION will be used:

Dicts will be digested to a list of their values.

Returns:

sum

Deprecated

class toolbox.iter.NoZip(iterable)

DEPRECATED: use repeat instead.

Avoid iteration in zip and zip_smart

Methods

__call__()	Call self as a function.
release()	Return the original iterable variable.

release()

Return the original iterable variable.

iter.repeat(unpack_nozip=True)

A generator that always returns arg.

Parameters:

arg

Any arbitraty object.

unpack_nozip: bool, default: True

Deprecation: Instead of NoZip, use repeat.

Unpack objects protected by NoZip.

Returns:

generator function

which always returns arg.

Examples

>>> for a, b, c, d, e in zip_smart(
...     ("A", "B", "C", "D"),
...     True,
...     [1, 2, 3, 4],
...     "always the same",
...     repeat((1, 2)),
... ):
...     print(a, b, c, d, e)
A True 1 always the same (1, 2)
B True 2 always the same (1, 2)
C True 3 always the same (1, 2)
D True 4 always the same (1, 2)