API consistency: no StopIteration from terminals; filter_map, unique, min_max and more

[virgesmith]

Why

A StopIteration escaping a map/filter callback silently ends the enclosing iteration instead of raising. Several terminal methods raised StopIteration for a missing item, so an innocent-looking chain could drop data without any error:

>>> Itr([[1, 2], [], [3]]).map(lambda g: Itr(g).reduce(max)).collect()
(2,)   # before: no error, group [3] silently lost

Breaking changes

• position returns None when nothing matches, consistent with find (and Rust's Option).
• Missing items raise the exception their builtin counterpart does:
  • nth past the end raises IndexError, as indexing a sequence does.
  • reduce on empty input raises TypeError, as functools.reduce does.
  • peek raises ValueError; it has no builtin counterpart, so this matches last, max and min.
• next() deliberately still raises StopIteration, like the builtin. The README and skill now warn against calling it inside callbacks.
• partition calls the predicate once per item (it was twice), buffering items for whichever side isn't being read. It is still lazy and still works on infinite input.

Additions (non-breaking)

• New methods: filter_map, find_map, unique(key=None) (lazy and order-preserving), min_max(key=None), compress, take_last(n).
• chain(*others) and interleave(*others) take any number of iterables.
• zip(..., strict=), groupby(..., sort=False), optional sorted_by key, all()/any() default to truthiness, sum(start=)/prod(start=).
• Itr.__repr__ shows the wrapped iterator without consuming it.
• flat_map now uses chain.from_iterable.

Also

• enumerate gains a doctest and a test. It had been covered only indirectly through the old position implementation, so changing position exposed the gap.
• SKILL.md, README, relnotes, doc/apidoc.md (regenerated) and the examples notebook are updated. The notebook caught an out-of-range nth with suppress(StopIteration).
• The examples notebook now demonstrates every public method (it covered 39 of 66). Five wrong statements are fixed, e.g. groupby was described as grouping consecutive runs, which is chunk_by, and all as never short-circuiting. All cells have been re-executed.
• Relnotes list all of this under Unreleased, so the next release should be a minor bump.

Testing

ruff check, ruff format --check, ty check src and pytest all pass with 100% coverage (264 tests) locally on 3.14; pytest also passes on 3.12 and 3.13. There are new tests for each behaviour change, including a regression test for the silent truncation.

🤖 Generated with Claude Code