itertools — 0.1.0

org.pycforge.itertools · Author: PyCForge

License: GPL-3.0-only · Created: 2026-11-12

Runtime conversion · Direct declared calls

Function index

chain · islice · pairwise

Overview

Reusable lazy record transforms with shared iterator state and retained-input ownership.

Using this import

Use *import itertools as s. Compose chain, islice and pairwise with for loops, next, list and ordinary imports. Keep caller-owned files inside their with block while consuming the pipeline.

Author's limitations

Runtime lazy iterators over admitted lists, tuples, ranges, Unicode strings, dictionaries/views, sets, owned vectors, text files and Runtime iterators. No custom __iter__/__next__, generators, callbacks, bytes or cross-context inputs. chain accepts zero to eight positional inputs; islice accepts (iterable, stop), (iterable, start, stop) or (iterable, start, stop, step); pairwise accepts one input. No keywords or *args/**kwargs expansion. Arguments evaluate once, left to right. Slice bounds are nonnegative signed-int64 or None; None means start=0, no stop or step=1. Step must be positive; bool is accepted as an index. Positions use checked unsigned arithmetic: CPython 3.12 can yield an extra item when an unbounded slice index plus step overflows signed int64; this profile follows non-wrapping slice positions instead. Factories consume no elements. chain acquires each input lazily; the other factories validate their iterable immediately. Iterators retain input references and share state through aliases; consuming them advances supplied iterators/files. Sequence/dictionary mutation follows the underlying Runtime iterator rules. islice consumes skipped items and, when fully exhausted, up to max(start, stop) items for a finite stop, regardless of step. pairwise retains one previous item and yields new two-item tuples with shared element references. No eager copy of the input or full result is made. Exhaustion is permanent and releases retained references; it does not close a caller-owned file. A chain input-next error can be retried; an invalid next input ends chain. An input error ends islice/pairwise. Consumed input is never rewound. Type/index/input errors are catchable. Work, allocation and nesting limits follow Runtime fatal exhaustion (128 nested dispatches). Each factory and non-exhausted next request costs a work step, in addition to underlying iteration work. Failed factories release partial allocations. Retained values participate in active GC; helpers do not collect internally. Results require live roots at collection boundaries. This profile selects three reviewed iterator kernels; it does not admit author state machines, arbitrary objects, chain.from_iterable or other itertools members.

Release notes

Initial bounded lazy iterator contracts.

Examples are author-supplied fixture snapshots. The SDK reports verification for its recorded environment; PyCForge registration does not rerun them.

Conversion contract

Use *import itertools in the module preamble. Each signature states accepted positions, names and defaults. A slash marks positional-only parameters; a star marks keyword-only parameters. Argument expansion, function values and Typed conversion are unsupported.

Runtime lazy iterators over admitted lists, tuples, ranges, Unicode strings, dictionaries/views, sets, owned vectors, text files and Runtime iterators. No custom __iter__/__next__, generators, callbacks, bytes or cross-context inputs. chain accepts zero to eight positional inputs; islice accepts (iterable, stop), (iterable, start, stop) or (iterable, start, stop, step); pairwise accepts one input. No keywords or *args/**kwargs expansion. Arguments evaluate once, left to right. Slice bounds are nonnegative signed-int64 or None; None means start=0, no stop or step=1. Step must be positive; bool is accepted as an index. Positions use checked unsigned arithmetic: CPython 3.12 can yield an extra item when an unbounded slice index plus step overflows signed int64; this profile follows non-wrapping slice positions instead. Factories consume no elements. chain acquires each input lazily; the other factories validate their iterable immediately. Iterators retain input references and share state through aliases; consuming them advances supplied iterators/files. Sequence/dictionary mutation follows the underlying Runtime iterator rules. islice consumes skipped items and, when fully exhausted, up to max(start, stop) items for a finite stop, regardless of step. pairwise retains one previous item and yields new two-item tuples with shared element references. No eager copy of the input or full result is made. Exhaustion is permanent and releases retained references; it does not close a caller-owned file. A chain input-next error can be retried; an invalid next input ends chain. An input error ends islice/pairwise. Consumed input is never rewound. Type/index/input errors are catchable. Work, allocation and nesting limits follow Runtime fatal exhaustion (128 nested dispatches). Each factory and non-exhausted next request costs a work step, in addition to underlying iteration work. Failed factories release partial allocations. Retained values participate in active GC; helpers do not collect internally. Results require live roots at collection boundaries. This profile selects three reviewed iterator kernels; it does not admit author state machines, arbitrary objects, chain.from_iterable or other itertools members.

itertools.chain(*iterables [0..8 positional inputs]) -> runtime-iterator

Read consecutive inputs lazily.

Normalized semantic slots: iterables. These slots are supplied by the engine; the signature above defines source arguments and defaults.

Yield each input in turn; acquire later inputs only when reached. The iterables documentation slot describes all zero to eight source arguments.

No input is inspected or consumed at construction. Exhaustion advances to the next input.

Argument 1: Zero to eight positional iterables, acquired in order when reached.

Returns: A shared-state lazy iterator.

View example: record-differences

itertools.islice(iterable, stop, /) or itertools.islice(iterable, start, stop, step=1, /) -> runtime-iterator

Select a range of input positions lazily.

Normalized semantic slots: iterable, start, stop, step. These slots are supplied by the engine; the signature above defines source arguments and defaults.

Select positions lazily; the two-argument form supplies stop with start=0 and step=1. An empty slice still skips to start when consumed.

Skipping advances a supplied iterator. A finite exhausted slice consumes up to max(start, stop), even when start is beyond stop.

Argument 1: An admitted iterable or iterator.

Argument 2: Starting position; zero in the two-argument form.

Argument 3: Exclusive stop, or None for no stop.

Argument 4: Positive step; omitted or None means one.

Returns: A lazy iterator over selected positions.

View example: record-differences

itertools.pairwise(iterable, /) -> runtime-iterator

Read overlapping adjacent record pairs.

Normalized semantic slots: iterable. These slots are supplied by the engine; the signature above defines source arguments and defaults.

Yield overlapping adjacent pairs in fresh tuples; an input with fewer than two items yields nothing.

Adjacent tuples share element references. Fewer than two items produce no pairs.

Argument 1: An admitted iterable or iterator.

Returns: A lazy iterator of new two-item tuples.

View example: record-differences

Authored fixture examples

Expected output is supplied by the author. Consult verification provenance for the checks performed; conversion-only SDK evidence does not test runtime behavior.

Example: record-differences

*import itertools as s
def main():
    records = s.chain([10, 12], [15, 21])
    chosen = s.islice(records, 1, None)
    for before, after in s.pairwise(chosen):
        print(after - before)
    print(next(records, "finished"))
    print(list(s.islice(range(8), 3)))
    return 0

Expected standard output:

3
6
finished
[0, 1, 2]

Expected exit code: 0