- Added tabulate dependency.

- Minor documentation changes.
- iter: Added unnest and batch_by_group, and deprecated batch_iter.
- misc: added bin_array.

Author: T-Flet

README.md

@@ -21,6 +21,16 @@ This package contains convenient functions not found in Python's Standard Librar
 It also contains a variety of convenience functions for the
 [numba](https://numba.pydata.org/) JIT compiler library.
 
+
+
+## Installation:
+
+```pip install generic-util```
+
+
+
+## Overview
+
 See the [documentation][rtd-link] for details, but functions are grouped as follows:
 - `Generic_Util.benchmarking`: functions covering typical code-timing scenarios,
     such as a "with" statement context, an n-executions timer,

pyproject.toml

@@ -28,6 +28,7 @@ dependencies = [
   "numpy>=1.23.5",
   "numba>=0.56.4",
   "sortedcontainers>=2.4.0",
+  "tabulate>=0.8.0"
 ]
 
 [project.optional-dependencies]

src/Generic_Util/benchmarking.py

@@ -53,8 +53,8 @@ def time_n(f: Callable, n = 2, *args, **kwargs):
 #       - how often the function at each position won (to see whether ordering had a big effect)
 #       - how well each function performed in each sample size
 #       - no need to check how smaller-sample calls were better, as they should be worse than large-sample ones
-#   - MAYBE NOT: option to check whether the outputs of (single) calls to each function are equal
-#       - Difficulty: not all objects are amenable to ==; could ask for the comparison function, but finnicky
+#   - USEFUL BUT NEEDS WARNING: option to check whether the outputs of (single) calls to each function are equal
+#       - Difficulty: not all objects are amenable to ==; could ask for the comparison function, or simply warn about this
 def compare_implementations(fs_with_shared_args: dict[str, Callable], n = 200, wait = 1, verbose = True,
                             fs_with_own_args: dict[str, tuple[Callable, list, dict]] = None, args: list = None, kwargs: dict = None):
     '''Benchmark multiple implementations of the same function called n times (each with the same args and kwargs), with a break between functions.

src/Generic_Util/iter.py

@@ -6,6 +6,7 @@
 from itertools import chain, combinations, islice
 from functools import reduce
 from collections import defaultdict
+from collections.abc import MutableMapping
 from sortedcontainers import SortedKeyList
 import operator as op
 import numpy as np
@@ -39,6 +40,18 @@ def deep_extract(xss_: Iterable[Iterable], *key_path) -> Generator:
     for k in key_path: level = level[k]
     return deep_flatten(level)
 
+def unnest(nested_dict, prefix = '', sep = '.'):
+    '''Recursively unnest dictionaries and lists in a dictionary, concatenating keys with sep. All keys are assumed to be strings.
+        Example: {'a': [{'b': 2}, {'c': 3}], 'd': 4, 'e': {'f': 6}} -> {'a.0.b': 2, 'a.1.c': 3, 'd': 4, 'e.f': 6}'''
+    out = {}
+    for k, v in nested_dict.items():
+        new_k = prefix + sep + k if prefix else k
+        if isinstance(v, MutableMapping): out.update(unnest(v, new_k, sep=sep))
+        elif isinstance(v, list):
+            for i, vi in enumerate(v): out.update(unnest(vi, new_k + sep + str(i), sep=sep))
+        else: out[new_k] = v
+    return out
+
 
 
 ## Iterable-Combining (and Combinatory) Functions
@@ -273,7 +286,10 @@ def intersperse_val(xs: Sequence[_a], y: _a, n: int, prepend = False, append = F
 ## Batching functions
 
 def batch_iter(n: int, xs: Iterable[_a]) -> Generator[_a, None, None]:
-    '''Batch an iterable in batches of size n (possibly except the last). If len(xs) is knowable use batch_seq instead.'''
+    '''*Soft deprecation* for Python>=3.12 since itertools now contains batched(iterable, n).
+    Batch an iterable in batches of size n (possibly except the last). If len(xs) is knowable use batch_seq instead.'''
+    from warnings import warn
+    warn('batch_iter() is deprecated from Python>=3.12 and will be removed in a future release.\nUse itertools.batched(iterable, n) instead.', DeprecationWarning, stacklevel=2)
     iterator = iter(xs)
     while batch := list(islice(iterator, n)): yield batch
 
@@ -342,4 +358,22 @@ def batch_seq_by_into(by: Callable[[_a], float], k: int, xs: Sequence[_a], keep_
                 count += weight
             if batch: yield batch
 
+def batch_by_group(by: Callable[[_a], Any], n: int, xs: Iterable[_a]) -> Generator[_a, None, None]:
+    '''Batch an iterable into batches of length <= n in which not two elements are from the same group as determined with by.
+    Note: the order of items in and across the batches is reversed from the original iterable;
+    might want to reverse it beforehand (or have a deque.popleft toggle?)'''
+    groups = defaultdict(list)
+    for x in xs: groups[by(x)].append(x)
+
+    while any(groups.values()):
+        batch = []
+        for grp in list(groups.keys()):  # casting to list makes it a copy, so not affected by .pop
+            if len(batch) >= n:
+                break
+            if groups[grp]:
+                batch.append(groups[grp].pop())
+            else:
+                del groups[grp]
+        yield batch
+
 

src/Generic_Util/misc.py

@@ -36,3 +36,11 @@ def min_max(xs: Sequence[_a]) -> tuple[_a, _a]:
     return min, max
 
 
+
+## Binary Functions
+
+def bin_array(n: int) -> list[int]:
+    '''Returns the binary representation of an integer as a list of binary values WITHOUT converting to string'''
+    return [(n >> i) & 1 for i in range(n.bit_length()-1, -1, -1)]
+
+

src/Generic_Util/numba/types.py

@@ -69,7 +69,7 @@
 chA = ch[::1] # Same as typeof(np.array(['a', '']))
 chA2 = ch[:, ::1] # Same as typeof(np.array([['a', ''],['','b']]))
 
-ch_NP = '<U1'
+ch_NP = np.dtype('<U1')
 chA_NP = cA2_NP = NDArray[ch_NP]
 
 def nTup(*args): return Tuple(args)