plox.tools.utilities

Miscellaneous tools/utils that don’t have a specific theme but are still valuable.

from plox.tools import utilities

These functions are not tied to a particular area (e.g. file system utils) but have use cases/functionality that comes up often enough to warrant existing as a tested, well formed module.

It is usually the case that new utilities are added to this location, and potentially, after some time of forming mass, there is enough continuity of a set of function to warrant splitting into their own module (e.g plox.tools.files).

Functions

composite_function(*functions)

Compose multiple functions to a single callable.

is_listlike(thing)

Check if a given thing is seemingly a list.

is_same_list(l1, l2)

Check if two lists are identical.

partition(d, key_fn)

Split a dictionary into two separate ones based on a filtering function.

to_tuples(d)

Convert a dictionary of key:value pairs to a list of tuples.

unnest(*p)

Unnest arbitrarily nested items in a list to flat level list.

window_iterator(seq[, n])

Return a sliding window (of width n) over data from the iterable.

Module Contents

plox.tools.utilities.composite_function(*functions)

Compose multiple functions to a single callable.

Example

>>> def square(x: int) -> int:
...     return x**2
>>>
>>> def half(x: int) -> int:
>>>     return x // 2
>>>
>>> composite_function(square, half)(3)
4
>>> composite_function(square, half)(2)
2
Parameters:

functions (Callable[[Any], Any]) – A variable number of callable functions to compose.

Returns:

The resulting composite function.

Return type:

Callable[[Any], Optional[Any]]

plox.tools.utilities.is_listlike(thing)

Check if a given thing is seemingly a list.

Python has iterable strings, and when iterating over something that is sometimes a list or sometimes a string, usually don’t want to iterate over the chars in the string, but want to iterate over the items in the list (see unnest())

Example

>>> is_listlike("a")
False
>>> is_listlike("[]")
False
>>> is_listlike([])
True
>>> is_listlike([1, 2, 3])
True
Parameters:

thing (Any) – Item to check if behaves like a list.

Returns:

True if item behaves like list, else False.

Return type:

bool

plox.tools.utilities.is_same_list(l1, l2)

Check if two lists are identical.

Parameters:

  • l1 (list[str]) – First list to compare.

  • l2 (list[str]) – Second list to compare.

Returns:

True if identical, false otherwise.

Return type:

bool

plox.tools.utilities.partition(d, key_fn)

Split a dictionary into two separate ones based on a filtering function.

Example

>>> d = {"a": 10, "B": 20, "c": 30, "D": 50}
>>> one, two = partition(d, lambda key: key.islower())
>>> one
{"a": 10, "c": 30}
>>> two
{"B": 20, "D": 50}
Parameters:

  • d (dict[Any, Any]) – The original dictionary to split.

  • key_fn (Callable[[Any], bool]) – The function to operate against each dictionary key in the original dictionary. If successful for a given key, adds key:value to the first dictionary returned. Otherwise, adds the key:value to the second dictionary returned.

Returns:

The two sets of dictionaries resulting from applying the filtering function to every key in the original dictionary.

Return type:

tuple[dict[Any, Any], dict[Any, Any]]

plox.tools.utilities.to_tuples(d)

Convert a dictionary of key:value pairs to a list of tuples.

The list of tuples will be of key:value pairing.

Example

>>> to_tuples({"a": "b", "c": "d"})
[("a", "b"), ("c", "d")]
Parameters:

d (dict[str, Any]) – The dictionary whose values will be split to a list of tuples.

Returns:

A list of tuples representing the input dict’s key:value pairs.

Return type:

list[tuple[str, TupleVal]]

plox.tools.utilities.unnest(*p)

Unnest arbitrarily nested items in a list to flat level list.

Note: This is done particularly because otherwise if a string occurs in the list, it gets exploded to individual characters, which is not desired.

Examples

>>> unnest()
[]
>>> unnest([])
[]
>>> unnest("a", "b", ["c"])
["a", "b", "c"]
>>> unnest("a")
["a"]
>>> unnest(["a"])
["a"]
>>> unnest([[[["a"]]]])
["a"]
>>> unnest("a", {"b": "c"}, ["d", "e"], "f")
["a", {"b": "c"}, "d", "e", "f"]
Parameters:

p (Any) – Arbitrarily nested list to flatten.

Returns:

The input list with 1 level nesting.

Return type:

list[Any]

plox.tools.utilities.window_iterator(seq, n=2)

Return a sliding window (of width n) over data from the iterable.

s -> (s0,s1,…s[n-1]), (s1,s2,…,sn), …

Example

>>> for window in window_iterator(range(10)):
...     print(window)
(0, 1)
(1, 2)
(2, 3)
(3, 4)
(4, 5)
(5, 6)
(6, 7)
(7, 8)
(8, 9)

>>> for window in window_iterator(range(6), 3):
...     print(",".join(map(str, window)))
0,1,2
1,2,3
2,3,4
3,4,5
Parameters:

  • seq (collections.abc.Iterable[_T]) – The iterator to generate windows from.

  • n (int) – The width of window to generate; default is 2.

Returns:

A generator of windows of desired size, containing a tuple of two objects of the same type of the original iterator.

Return type:

Generator[tuple[_T, …], None, None]