interplot.iter: Iteration Tools Documentation and API reference

Tools to iterate Python objects.

zip_smart

interplot.zip_smart(*iterables, 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 interplot.conf.NON_ITERABLE_TYPES 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

  • will be ignored on Python <3.10

  • raises a warning if ignored, unless interplot.conf.MUTE_STRICT_ZIP_WARNING is set to False

• always raises an error if an item is repeated using interplot.repeat(), 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 interplot.zip_smart(
...     ("A", "B", "C", "D"),
...     True,
...     [1, 2, 3, 4, 5],  # notice the extra element won't be unpacked
...     "always the same",
...     interplot.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

interplot.repeat(arg, 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 interplot.zip_smart(
...     ("A", "B", "C", "D"),
...     True,
...     [1, 2, 3, 4, 5],  # notice the extra element won't be unpacked
...     "always the same",
...     interplot.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

interplot.filter_nozip(iterable, no_iter_types=None, depth=0, length=(2,))

Prevent certain patterns from being unpacked in interplot.zip_smart.

Wraps fixed patterns into interplot.repeat, so that they are not unpacked in interplot.zip_smart.

By default, iterables of length 2 containing only float, int, and datetime objects will not be unpacked.

Parameters:

iterable: Any

The object to potentially iterate.

no_iter_types, tuple, optional

If only these types are found in the iterable, it will not be unpacked, given it has the correct length.

Default: (float, int, datetime)

depth: int, default: 0

Maximum depth to recurse.

Depth 0 will only check the first level, depth 1 will check two levels, …

Set to -1 to recurse infinitely.

length: tuple, default: (2, )

If the iterable has one of the lengths in this tuple, it will not be unpacked.

Returns:

either iterable or repeat(iterable)

sum_nested

interplot.sum_nested(inp, 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, interplot.CUSTOM_DIGESTION will be used: Dicts will be digested to a list of their values.

Returns:

sum

Deprecated

class interplot.NoZip(iterable)

DEPRECATED: use interplot.repeat instead.

Avoid iteration in zip and interplot.zip_smart

Methods

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

release()

Return the original iterable variable.