iterquarry 2.1.1__py3-none-any.whl

iterquarry/__init__.py

@@ -0,0 +1,373 @@
+"""Extra tools for working with iterables."""
+
+from iterquarry.augment import (
+    adjacent,
+    count_cycle,
+    groupby_transform,
+    intersperse,
+    mark_ends,
+    padded,
+    repeat_each,
+    repeat_last,
+)
+from iterquarry.combo import (
+    circular_shifts,
+    combination_index,
+    combination_with_replacement_index,
+    derangements,
+    distinct_combinations,
+    distinct_permutations,
+    gray_product,
+    nth_combination_with_replacement,
+    nth_permutation,
+    nth_product,
+    outer_product,
+    partitions,
+    permutation_index,
+    powerset_of_sets,
+    product_index,
+    set_partitions,
+)
+from iterquarry.combine import (
+    collapse,
+    interleave,
+    interleave_evenly,
+    interleave_longest,
+    interleave_randomly,
+    partial_product,
+    sort_together,
+    value_chain,
+    zip_broadcast,
+    zip_offset,
+)
+from iterquarry.concurrency import concurrent_tee, serialize, synchronized
+from iterquarry.grouping import (
+    batched,
+    bucket,
+    chunked,
+    chunked_even,
+    constrained_batches,
+    distribute,
+    divide,
+    ichunked,
+    sliced,
+    split_after,
+    split_at,
+    split_before,
+    split_into,
+    split_when,
+    unzip,
+)
+from iterquarry.lookahead import peekable, seekable, spy
+from iterquarry.numeric import (
+    Stats,
+    dft,
+    idft,
+    nth_prime,
+    numeric_range,
+    running_max,
+    running_mean,
+    running_median,
+    running_min,
+    running_statistics,
+)
+from iterquarry.other import (
+    difference,
+    doublestarmap,
+    iterate,
+    locate,
+    make_decorator,
+    map_if,
+    raise_,
+    replace,
+    rlocate,
+    side_effect,
+    time_limited,
+)
+from iterquarry.recipes import (
+    all_equal,
+    before_and_after,
+    consume,
+    convolve,
+    dotproduct,
+    factor,
+    first_true,
+    flatten,
+    grouper,
+    is_prime,
+    iter_except,
+    iter_index,
+    loops,
+    matmul,
+    multinomial,
+    ncycles,
+    nth,
+    nth_combination,
+    pad_none,
+    padnone,
+    pairwise,
+    partition,
+    polynomial_derivative,
+    polynomial_eval,
+    polynomial_from_roots,
+    powerset,
+    prepend,
+    quantify,
+    random_combination,
+    random_combination_with_replacement,
+    random_derangement,
+    random_permutation,
+    random_product,
+    repeatfunc,
+    reshape,
+    roundrobin,
+    sieve,
+    sliding_window,
+    subslices,
+    sum_of_squares,
+    tabulate,
+    tail,
+    take,
+    totient,
+    transpose,
+    triplewise,
+    unique,
+    unique_everseen,
+    unique_justseen,
+)
+from iterquarry.select import (
+    classify_unique,
+    duplicates_everseen,
+    duplicates_justseen,
+    extract,
+    filter_except,
+    filter_map,
+    first,
+    islice_extended,
+    iter_suppress,
+    last,
+    longest_common_prefix,
+    lstrip,
+    map_except,
+    nth_or_last,
+    one,
+    only,
+    rstrip,
+    strictly_n,
+    strip,
+    takewhile_inclusive,
+    unique_in_window,
+)
+from iterquarry.summarize import (
+    all_unique,
+    argmax,
+    argmin,
+    consecutive_groups,
+    exactly_n,
+    iequals,
+    ilen,
+    is_sorted,
+    join_mappings,
+    map_reduce,
+    minmax,
+    run_length,
+    sample,
+    unique_to_each,
+)
+from iterquarry.windowing import (
+    stagger,
+    substrings,
+    substrings_indexes,
+    windowed,
+    windowed_complete,
+)
+from iterquarry.wrapping import (
+    AbortThread,
+    SequenceView,
+    always_iterable,
+    always_reversible,
+    callback_iter,
+    consumer,
+    countable,
+    sized_iterator,
+    with_iter,
+)
+
+__version__ = "2.1.1"
+
+__all__ = [
+    "AbortThread",
+    "SequenceView",
+    "Stats",
+    "adjacent",
+    "all_equal",
+    "all_unique",
+    "always_iterable",
+    "always_reversible",
+    "argmax",
+    "argmin",
+    "batched",
+    "before_and_after",
+    "bucket",
+    "callback_iter",
+    "chunked",
+    "chunked_even",
+    "circular_shifts",
+    "classify_unique",
+    "collapse",
+    "combination_index",
+    "combination_with_replacement_index",
+    "concurrent_tee",
+    "consecutive_groups",
+    "constrained_batches",
+    "consume",
+    "consumer",
+    "convolve",
+    "count_cycle",
+    "countable",
+    "derangements",
+    "dft",
+    "difference",
+    "distinct_combinations",
+    "distinct_permutations",
+    "distribute",
+    "divide",
+    "dotproduct",
+    "doublestarmap",
+    "duplicates_everseen",
+    "duplicates_justseen",
+    "exactly_n",
+    "extract",
+    "factor",
+    "filter_except",
+    "filter_map",
+    "first",
+    "first_true",
+    "flatten",
+    "gray_product",
+    "grouper",
+    "groupby_transform",
+    "ichunked",
+    "idft",
+    "iequals",
+    "ilen",
+    "interleave",
+    "interleave_evenly",
+    "interleave_longest",
+    "interleave_randomly",
+    "intersperse",
+    "is_prime",
+    "is_sorted",
+    "islice_extended",
+    "iter_except",
+    "iter_index",
+    "iter_suppress",
+    "iterate",
+    "join_mappings",
+    "last",
+    "locate",
+    "longest_common_prefix",
+    "loops",
+    "lstrip",
+    "make_decorator",
+    "map_except",
+    "map_if",
+    "map_reduce",
+    "mark_ends",
+    "matmul",
+    "minmax",
+    "multinomial",
+    "ncycles",
+    "nth",
+    "nth_combination",
+    "nth_combination_with_replacement",
+    "nth_or_last",
+    "nth_permutation",
+    "nth_prime",
+    "nth_product",
+    "numeric_range",
+    "one",
+    "only",
+    "outer_product",
+    "pad_none",
+    "padded",
+    "padnone",
+    "pairwise",
+    "partial_product",
+    "partition",
+    "partitions",
+    "peekable",
+    "permutation_index",
+    "polynomial_derivative",
+    "polynomial_eval",
+    "polynomial_from_roots",
+    "powerset",
+    "powerset_of_sets",
+    "prepend",
+    "product_index",
+    "quantify",
+    "raise_",
+    "random_combination",
+    "random_combination_with_replacement",
+    "random_derangement",
+    "random_permutation",
+    "random_product",
+    "repeat_each",
+    "repeat_last",
+    "repeatfunc",
+    "replace",
+    "reshape",
+    "rlocate",
+    "roundrobin",
+    "rstrip",
+    "run_length",
+    "running_max",
+    "running_mean",
+    "running_median",
+    "running_min",
+    "running_statistics",
+    "sample",
+    "seekable",
+    "serialize",
+    "set_partitions",
+    "side_effect",
+    "sieve",
+    "sized_iterator",
+    "sliced",
+    "sliding_window",
+    "sort_together",
+    "split_after",
+    "split_at",
+    "split_before",
+    "split_into",
+    "split_when",
+    "spy",
+    "stagger",
+    "strictly_n",
+    "strip",
+    "subslices",
+    "substrings",
+    "substrings_indexes",
+    "sum_of_squares",
+    "synchronized",
+    "tabulate",
+    "tail",
+    "take",
+    "takewhile_inclusive",
+    "time_limited",
+    "totient",
+    "transpose",
+    "triplewise",
+    "unique",
+    "unique_everseen",
+    "unique_in_window",
+    "unique_justseen",
+    "unique_to_each",
+    "unzip",
+    "value_chain",
+    "windowed",
+    "windowed_complete",
+    "with_iter",
+    "zip_broadcast",
+    "zip_offset",
+]

iterquarry/augment.py

@@ -0,0 +1,130 @@
+"""Add context to the items of an iterable."""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Iterable
+from itertools import count, groupby, islice, repeat
+
+__all__ = [
+    "adjacent",
+    "count_cycle",
+    "groupby_transform",
+    "intersperse",
+    "mark_ends",
+    "ncycles",
+    "pad_none",
+    "padded",
+    "repeat_each",
+    "repeat_last",
+]
+
+
+def count_cycle(iterable: Iterable, n: int | None = None):
+    """Yield ``(cycle_number, item)`` while cycling through *iterable*."""
+    sequence = tuple(iterable)
+    if not sequence:
+        return
+    cycles = count() if n is None else range(n)
+    for cycle_number in cycles:
+        for item in sequence:
+            yield cycle_number, item
+
+
+def intersperse(e, iterable: Iterable, n: int = 1):
+    """Insert *e* between items, leaving *n* items between separators."""
+    if n < 1:
+        raise ValueError("n must be at least one")
+    iterator = iter(iterable)
+    try:
+        yield next(iterator)
+    except StopIteration:
+        return
+    for index, item in enumerate(iterator, 1):
+        if index % n == 0:
+            yield e
+        yield item
+
+
+def padded(iterable: Iterable, fillvalue=None, n: int | None = None, next_multiple: bool = False):
+    """Yield the items, then *fillvalue* until at least *n* items have been produced."""
+    count_emitted = 0
+    for item in iterable:
+        yield item
+        count_emitted += 1
+    if n is None:
+        yield from repeat(fillvalue)
+        return
+    if n < 1:
+        raise ValueError("n must be at least one")
+    if next_multiple:
+        target = ((count_emitted + n - 1) // n) * n
+    else:
+        target = n
+    if count_emitted < target:
+        yield from repeat(fillvalue, target - count_emitted)
+
+
+def mark_ends(iterable: Iterable):
+    """Yield ``(is_first, is_last, item)``."""
+    iterator = iter(iterable)
+    try:
+        previous = next(iterator)
+    except StopIteration:
+        return
+    first = True
+    for item in iterator:
+        yield first, False, previous
+        first = False
+        previous = item
+    yield first, True, previous
+
+
+def repeat_each(iterable: Iterable, n: int = 2):
+    """Repeat each item *n* times."""
+    if n < 0:
+        raise ValueError("n must be >= 0")
+    for item in iterable:
+        for _ in range(n):
+            yield item
+
+
+def repeat_last(iterable: Iterable, default=None):
+    """Yield the items, then repeat the last one forever."""
+    item = default
+    for item in iterable:
+        yield item
+    yield from repeat(item)
+
+
+def adjacent(predicate, iterable: Iterable, distance: int = 1):
+    """Yield ``(near_match, item)`` where *near_match* covers *distance* neighbors."""
+    if distance < 0:
+        raise ValueError("distance must be >= 0")
+    iterator = iter(iterable)
+    flags = deque([False] * distance, maxlen=distance * 2 + 1)
+    items = deque()
+    for item in iterator:
+        flags.append(bool(predicate(item)))
+        items.append(item)
+        if len(flags) == distance * 2 + 1:
+            yield any(flags), items.popleft()
+    for _ in range(distance):
+        if not items:
+            break
+        flags.append(False)
+        yield any(flags), items.popleft()
+
+
+def groupby_transform(iterable: Iterable, keyfunc=None, valuefunc=None, reducefunc=None):
+    """Group adjacent items and optionally transform the keys, values, and groups."""
+    if keyfunc is None:
+        keyfunc = lambda item: item
+    if valuefunc is None:
+        valuefunc = lambda item: item
+    for key, group in groupby(iterable, keyfunc):
+        mapped = (valuefunc(item) for item in group)
+        if reducefunc is None:
+            yield key, mapped
+        else:
+            yield key, reducefunc(mapped)