parts module
Minimal library that enables partitioning of iterable objects in a concise manner.
- parts.parts.parts(xs, number=None, length=None)[source]
This function splits an
Iterable
object into either the specified number of parts or a number of parts each of the specified length. When input parameters lead to ambiguous or conflicting constraints, either elements are distributed in a best-effort manner or an exception is raised (depending on the specific scenario).- Parameters
In the simplest case, the target number of parts can be specified.
>>> list(parts([1, 2, 3, 4, 5, 6, 7], 1)) [[1, 2, 3, 4, 5, 6, 7]] >>> list(parts([1, 2, 3, 4, 5, 6, 7], 2)) [[1, 2, 3], [4, 5, 6, 7]] >>> list(parts([1, 2, 3, 4, 5, 6, 7], 3)) [[1, 2], [3, 4], [5, 6, 7]] >>> list(parts([1, 2, 3, 4, 5, 6, 7], 4)) [[1], [2, 3], [4, 5], [6, 7]] >>> list(parts([1, 2, 3, 4, 5, 6, 7], 5)) [[1], [2], [3], [4, 5], [6, 7]] >>> list(parts([1, 2, 3, 4, 5, 6, 7], 6)) [[1], [2], [3], [4], [5], [6, 7]] >>> list(parts([1, 2, 3, 4, 5, 6, 7], 7)) [[1], [2], [3], [4], [5], [6], [7]]
The target length for each part can be specified; the number of parts will be determined based on the length and the available number of items.
>>> list(parts([1, 2, 3, 4, 5, 6, 7], length=1)) [[1], [2], [3], [4], [5], [6], [7]] >>> list(parts([1, 2, 3, 4, 5, 6, 7], length=2)) [[1, 2], [3, 4], [5, 6], [7]] >>> list(parts([1, 2, 3, 4, 5, 6, 7], length=3)) [[1, 2, 3], [4, 5, 6], [7]] >>> list(parts([1, 2, 3, 4, 5, 6, 7], length=4)) [[1, 2, 3, 4], [5, 6, 7]] >>> list(parts([1, 2, 3, 4, 5, 6, 7], length=5)) [[1, 2, 3, 4, 5], [6, 7]] >>> list(parts([1, 2, 3, 4, 5, 6, 7], length=6)) [[1, 2, 3, 4, 5, 6], [7]] >>> list(parts([1, 2, 3, 4, 5, 6, 7], length=7)) [[1, 2, 3, 4, 5, 6, 7]] >>> list(map(list, parts(iter([1, 2, 3, 4, 5, 6, 7]), length=4))) [[1, 2, 3, 4], [5, 6, 7]]
An iterable of length values can be specified. The entry at each position in the iterable of lengths dictates the length of the part in the corresponding position in the output.
>>> list(parts([1, 2, 3, 4, 5, 6, 7], 7, [1, 1, 1, 1, 1, 1, 1])) [[1], [2], [3], [4], [5], [6], [7]] >>> list(parts([1, 2, 3, 4, 5, 6, 7], length=[1, 1, 1, 1, 1, 1, 1])) [[1], [2], [3], [4], [5], [6], [7]] >>> list(parts([1, 2, 3, 4, 5, 6], length=[2, 2, 2])) [[1, 2], [3, 4], [5, 6]] >>> list(parts([1, 2, 3, 4, 5, 6], length=[1, 2, 3])) [[1], [2, 3], [4, 5, 6]]
The type of input objects (for built-in types) is preserved in the output.
>>> isinstance(next(parts([1, 2, 3, 4, 5], length=2)), list) True >>> isinstance(next(parts([1, 2, 3, 4, 5], length=[2, 2, 1])), list) True >>> isinstance(next(parts([1, 2, 3, 4, 5], number=2)), list) True >>> isinstance(next(parts([1, 2, 3, 4], number=2, length=2)), list) True >>> isinstance(next(parts([1, 2, 3, 4], number=2, length=[2, 2])), list) True >>> isinstance(next(parts((1, 2, 3, 4, 5), length=2)), tuple) True >>> isinstance(next(parts((1, 2, 3, 4, 5), length=[2, 2, 1])), tuple) True >>> isinstance(next(parts((1, 2, 3, 4, 5), number=2)), tuple) True >>> isinstance(next(parts((1, 2, 3, 4), number=2, length=2)), tuple) True >>> isinstance(next(parts((1, 2, 3, 4), number=2, length=[2, 2])), tuple) True >>> isinstance(next(parts('abc', length=2)), str) True >>> isinstance(next(parts('abc', length=[2, 1])), str) True >>> isinstance(next(parts('abc', number=2)), str) True >>> isinstance(next(parts('abcd', number=2, length=2)), str) True >>> isinstance(next(parts('abcd', number=2, length=[2, 2])), str) True >>> isinstance(next(parts(bytes([1, 2, 3, 4, 5]), length=2)), bytes) True >>> isinstance(next(parts(bytes([1, 2, 3, 4, 5]), length=[2, 2, 1])), bytes) True >>> isinstance(next(parts(bytes([1, 2, 3, 4, 5]), number=2)), bytes) True >>> isinstance(next(parts(bytes([1, 2, 3, 4]), number=2, length=2)), bytes) True >>> isinstance(next(parts(bytes([1, 2, 3, 4]), number=2, length=[2, 2])), bytes) True >>> isinstance(next(parts(bytearray([1, 2, 3, 4, 5]), length=2)), bytearray) True >>> isinstance(next(parts(bytearray([1, 2, 3, 4, 5]), length=[2, 2, 1])), bytearray) True >>> isinstance(next(parts(bytearray([1, 2, 3, 4, 5]), number=2)), bytearray) True >>> isinstance(next(parts(bytearray([1, 2, 3, 4]), number=2, length=2)), bytearray) True >>> isinstance(next(parts(bytearray([1, 2, 3, 4]), number=2, length=[2, 2])), bytearray) True >>> isinstance(next(parts(range(0, 10), length=2)), range) True >>> isinstance(next(parts(range(0, 5), length=[2, 2, 1])), range) True >>> isinstance(next(parts(range(0, 10), number=2)), range) True >>> isinstance(next(parts(range(0, 4), number=2, length=2)), range) True >>> isinstance(next(parts(range(0, 4), number=2, length=[2, 2])), range) True >>> isinstance(next(parts(iter([1, 2, 3, 4]), length=2)), Iterable) True
The type of input
Sequence
objects is preserved in the output.>>> class wrap: ... def __init__(self, xs): self.xs = xs ... def __len__(self): return len(self.xs) ... def __getitem__(self, key): return wrap(self.xs[key]) ... def __repr__(self): return 'wrap(' + str(self.xs) + ')' >>> isinstance(next(parts(wrap([1, 2, 3, 4]), number=2)), wrap) True >>> list(parts(wrap([1, 2, 3, 4]), number=2)) [wrap([1, 2]), wrap([3, 4])] >>> list(parts(wrap([1, 2, 3, 4]), length=2)) [wrap([1, 2]), wrap([3, 4])] >>> list(parts(wrap([1, 2, 3, 4]), length=[2, 2])) [wrap([1, 2]), wrap([3, 4])] >>> list(parts(wrap([1, 2, 3, 4]), number=2, length=2)) [wrap([1, 2]), wrap([3, 4])] >>> list(parts(wrap([1, 2, 3, 4]), number=2, length=[2, 2])) [wrap([1, 2]), wrap([3, 4])]
The type of input objects derived from a
Sequence
type is also preserved in the output.>>> class inherit(tuple): ... def __getitem__(self, key): return inherit(tuple(self)[key]) ... def __repr__(self): return 'inherit' + str(tuple(self)) >>> isinstance(next(parts(inherit([1, 2, 3, 4]), 2)), inherit) True >>> list(parts(inherit([1, 2, 3, 4]), number=2)) [inherit(1, 2), inherit(3, 4)] >>> list(parts(inherit([1, 2, 3, 4]), length=2)) [inherit(1, 2), inherit(3, 4)] >>> list(parts(inherit([1, 2, 3, 4]), length=[2, 2])) [inherit(1, 2), inherit(3, 4)] >>> list(parts(inherit([1, 2, 3, 4]), number=2, length=2)) [inherit(1, 2), inherit(3, 4)] >>> list(parts(inherit([1, 2, 3, 4]), number=2, length=[2, 2])) [inherit(1, 2), inherit(3, 4)]
Iterable inputs yield iterable outputs when possible.
>>> def iterable(): ... for i in range(10): ... yield i >>> isinstance((next(parts(iterable(), number=2))), Iterable) Traceback (most recent call last): ... TypeError: object must have length to determine part lengths from number parameter >>> isinstance((next(parts(iterable(), length=2))), Iterable) True >>> isinstance((next(parts(iterable(), length=[2, 2]))), Iterable) True >>> ps = parts(iterable(), number=2, length=2) >>> isinstance(next(ps), Iterable) Traceback (most recent call last): ... TypeError: object must have length to determine if number of parts having specified length(s) can be retrieved >>> ps = parts(iterable(), number=2, length=[2, 2]) >>> isinstance(next(ps), Iterable) Traceback (most recent call last): ... TypeError: object must have length to determine if number of parts having specified length(s) can be retrieved >>> not isinstance((next(parts(iterable(), length=2))), list) True >>> list(parts(123, length=2)) Traceback (most recent call last): ... TypeError: object does not support retrieval of slices
A descriptive exception is raised when parameter values cannot be satisfied, cause a conflict, or have an incorrect type.
>>> list(parts([1, 2, 3, 4, 5, 6], 2, 3)) [[1, 2, 3], [4, 5, 6]] >>> list(parts([1, 2, 3, 4, 5, 6], number=3, length=2)) [[1, 2], [3, 4], [5, 6]] >>> list(parts(iter([1, 2, 3, 4, 5, 6]), number=3, length=2)) Traceback (most recent call last): ... TypeError: object must have length to determine if number of parts having specified length(s) can be retrieved >>> list(parts(iter([1, 2, 3, 4, 5, 6, 7]), 1)) Traceback (most recent call last): ... TypeError: object must have length to determine part lengths from number parameter >>> list(parts([1, 2, 3, 4, 5, 6], 1.2)) Traceback (most recent call last): ... TypeError: number parameter must be an integer >>> list(parts([1, 2, 3, 4, 5, 6], length=1.23)) Traceback (most recent call last): ... TypeError: length parameter must be an integer or iterable of integers >>> list(parts([1, 2, 3, 4, 5, 6], length=[1.23])) Traceback (most recent call last): ... TypeError: length parameter must be an integer or iterable of integers >>> list(parts([1, 2, 3, 4, 5, 6], 2, length=[1, 2, 3])) Traceback (most recent call last): ... ValueError: number parameter does not match number of specified part lengths >>> list(parts([1, 2, 3, 4, 5, 6, 7], number=3, length=2)) Traceback (most recent call last): ... ValueError: cannot retrieve 3 parts from object given part length parameter of 2 >>> list(parts([1, 2, 3], length=4)) [[1, 2, 3]] >>> list(parts([1, 2, 3], number=2, length=[1, 2])) [[1], [2, 3]] >>> list(parts([1, 2, 3], number=3, length=[1, 2, 3])) Traceback (most recent call last): ... ValueError: object has too few items to retrieve parts having specified part lengths >>> list(parts([1, 2, 3])) Traceback (most recent call last): ... ValueError: missing number of parts parameter and part length(s) parameter >>> list(parts([1, 2, 3], length=[4])) [[1, 2, 3]] >>> list(parts([1, 2, 3], length=[3, 1])) Traceback (most recent call last): ... ValueError: object has too few items to retrieve parts having specified part lengths >>> list(parts([1, 2, 3], number=2, length=[1, 1])) Traceback (most recent call last): ... ValueError: object has too many items to retrieve parts having specified part lengths >>> list(parts([1, 2, 3], number=1, length=[4])) [[1, 2, 3]] >>> list(parts([1, 2, 3], number=2, length=[3, 1])) Traceback (most recent call last): ... ValueError: object has too few items to retrieve parts having specified part lengths >>> list(parts([1, 2, 3], length=[1, 1, 1, 1])) Traceback (most recent call last): ... ValueError: object has too few items to retrieve parts having specified part lengths >>> list(parts([1, 2, 3], number=1, length=[1.2])) Traceback (most recent call last): ... TypeError: length parameter must be an integer or list of integers
- Return type