PythonIota 1.8.0__tar.gz → 1.9.0__tar.gz

{pythoniota-1.8.0 → pythoniota-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: PythonIota
-Version: 1.8.0
+Version: 1.9.0
 Summary: A zero-dependency Python toolkit: Go-style iota enums, sequence generators, a from-scratch regex engine, and an argparse-style CLI parser
 Author: Equinox
 License: MIT
@@ -26,6 +26,24 @@ pip install PythonIota
 
 Requires Python 3.10+.
 
+## 1.9.0
+
+### New features
+
+- Regex searches skip impossible starts using a conservative literal prefix;
+  diagnostics expose the prefix and account for prefilter operations.
+- CLI mutually exclusive groups, version output and static completion scripts for
+  Bash, Zsh and PowerShell extend the existing metadata-only completion API.
+- Sequence pipelines add bounded `limit`, grouping, Top-K, partitioning, iterator
+  copies and combinatorics, with protection for known non-exhausting inputs.
+
+### Fixes
+
+- Pattern backreferences now fail explicitly instead of silently matching digits.
+- Out-of-range regex positions are clamped to the text, matching `re` semantics.
+- Counted nullable repetitions stop after zero-width iterations without losing
+  the preferred non-empty alternative during iteration.
+
 ## 1.8.0
 
 ### New features
@@ -294,9 +312,50 @@ with element types preserved through generic transformations. `take(n)` still
 returns a list. Chunk/window sizes must be positive and are checked before consumption.
 
 Base sequences and their `.map()` results remain reusable. Iterator pipelines
-have no length or infinite-status metadata: exhaustive terminals such as
-`to_list()`, `sum()` and `last()` can run forever on an unbounded stream. Take a
-bounded prefix first when needed.
+have no length, but expose `infinite`: `True` for known non-exhausting sources,
+`False` for known finite sources, and `None` when unknown. Exhaustive terminals
+reject known non-exhausting pipelines before consuming them. Filtering/distinct
+can yield few values without ever exhausting their infinite input; these retain
+the protection. Arbitrary generators and early-stopping `takewhile` may remain
+unknown, so this is not a general termination detector.
+
+Use `.limit(n)` to keep a bounded prefix chainable (`take(n)` still returns a list):
+
+```python
+iota().filter(lambda x: x % 2 == 0).limit(5).sum()  # 20
+```
+
+`limit` bounds the number of returned elements, not the time to produce one:
+`iota().filter(lambda x: False).limit(1)` still cannot yield a value. Short-circuit
+operations (`first`, `find`, `any`, `all`, `take`) remain available on infinite input.
+
+### Grouping, selection and iterator utilities
+
+```python
+iota(6).group_by(lambda x: x % 2)  # {0: [0, 2, 4], 1: [1, 3, 5]}
+iota(10).top_k(3)                 # [9, 8, 7]
+iota(10).top_k(3, largest=False)  # [0, 1, 2]
+iota(2).zip_longest(["a"], fillvalue="-").to_list()  # [(0, 'a'), (1, '-')]
+iota(2).product(["a", "b"]).to_list()  # [(0, 'a'), (0, 'b'), (1, 'a'), (1, 'b')]
+iota(3).permutations(2).take(3)   # [(0, 1), (0, 2), (1, 0)]
+
+odds, evens = iota(6).partition(lambda x: x % 2 == 0)
+odds.to_list(), evens.to_list()  # ([1, 3, 5], [0, 2, 4])
+left, right = iota(3).tee()
+left.take(2), right.to_list()    # ([0, 1], [0, 1, 2])
+```
+
+`group_by(key=None)` groups globally into lists, preserving key/element insertion
+order; unlike `itertools.groupby`, equal keys need not be adjacent. `top_k` supports
+`key=`, preserves input order for ties and keeps O(k) selection storage, but must
+consume the entire finite input. `top_k(0)` returns immediately without consuming.
+Neither operation can compute a global result from an infinite stream.
+
+`partition` returns false/true branches and evaluates its predicate once per item.
+Like `tee`, it buffers when consumers advance at different rates; that buffer can
+grow without bound. `product` and `permutations` defer input consumption until
+iteration, then cache their inputs like `itertools`; they reject known infinite
+inputs and are not constant-memory streaming operations.
 
 ### Terminal operations
 
@@ -411,9 +470,10 @@ regex.findall(r"[a-z]+", "AbCdEf", regex.IGNORECASE)   # ['AbCdEf']
 regex.findall(r"\d+(?=px)", "10px 20em 30px")           # ['10', '30']  (lookahead)
 ```
 
-Backreferences (`\1`) are intentionally not supported; this is an NFA-based
-engine rather than a general backtracking engine. Empty matches follow the
-iteration and splitting behavior of Python 3.10–3.13 `re`, including a non-empty
+Pattern backreferences (`\1`, `(?P=name)`) raise `RegexError`; this is an NFA-based
+engine rather than a general backtracking engine. Replacement templates still
+support backreferences. Patterns are text strings, not bytes. Empty matches follow
+the iteration and splitting behavior of Python 3.10–3.13 `re`, including a non-empty
 match immediately after an empty one at the same position.
 
 ```python
@@ -434,10 +494,16 @@ report = pattern.diagnose("aaaa!", max_steps=1000)
 print(report["status"], report["steps"], report["op_counts"])
 ```
 
+Search and iteration use a conservative mandatory literal prefix when available.
+`explain()["literal_prefix"]` shows it; case-insensitive patterns and leading
+branching/nullable patterns fall back to the normal VM. Existing higher-priority
+threads keep running: the optimization does not restart the VM for each candidate.
+
 All matching, iteration, splitting and replacement functions accept keyword-only
 `max_steps` (nonnegative integer) and `timeout` (nonnegative seconds), defaulting
-to no limits. A step is a bytecode analysis/visit, including epsilon closure and
-consuming states; counts are implementation-specific, not a portable time unit.
+to no limits. A step is a bytecode analysis/visit or one native prefix lookup
+(`PREFILTER`), including epsilon closure and consuming states; counts are
+implementation-specific, not a portable time unit or a per-character work bound.
 Nested lookarounds and all matches within one call share a single budget.
 `finditer` starts its timeout when created, including pauses between yields.
 
@@ -481,6 +547,28 @@ Bad input prints a usage line and raises `SystemExit(2)` — the same contract a
 argparse, so it drops into scripts and tests unchanged. `parse_known_args`
 returns `(namespace, extras)` instead of erroring on unknown tokens.
 
+### Mutually exclusive options and version output
+
+```python
+p = cli.ArgumentParser(prog="convert")
+mode = p.add_mutually_exclusive_group(required=True)
+mode.add_argument("--json", action="store_true")
+mode.add_argument("--text", action="store_true")
+p.add_argument("--version", action="version", version="%(prog)s 1.0")
+p.parse_args(["--json"])
+```
+
+Groups accept optional arguments only. A required group needs exactly one explicit
+member; an optional group permits zero or one. CLI, environment and configuration
+values count as explicit, even `False` or zero; defaults and caller `Namespace`
+values do not. CLI overrides lower sources for the same destination, not another
+group member: CLI `--json` plus config `text=true` is a conflict. Repeating the same
+member is allowed. Group members cannot themselves be required or share a destination.
+
+A valid version request prints to stdout and exits with status 0 without reading
+configuration or converting unrelated values. It bypasses missing required options
+but still respects argument consumption, subcommand boundaries and `--`.
+
 ### Sub-commands
 
 ```python
@@ -544,9 +632,25 @@ p.complete([], "--mode=f")         # ['--mode=fast']
 word, then returns sorted, unique full replacement words for options, choices
 and subcommands. It does not parse, read config/environment, call type converters,
 execute shells or mutate parse state. Variable-length positionals are best-effort;
-only collection-backed choices are enumerated, not generators. This is an adapter
-API for shells/editors: it does not install shell hooks, quote candidates or
-perform filesystem completion.
+only built-in collections of plain scalar choices are enumerated, not generators
+or custom objects. This is an adapter API for shells/editors: it does not install
+shell hooks, quote candidates or perform filesystem completion.
+
+### Static shell completion scripts
+
+```python
+script = p.completion_script("bash", command="convert")
+# Also accepts "zsh" and "powershell"; save/load the returned text yourself.
+```
+
+This generates a quoted static snapshot of options, subcommands and finite scalar
+choices. It does not run the application, read sources, call converters or change
+shell configuration. Unlike `complete(tokens, prefix)`, the snapshot is not a
+context-sensitive parser: it may suggest candidates from other options or commands.
+Regenerate it after changing parser metadata. Shell metacharacters are emitted as
+literal data, not executable fragments. Command names containing control characters
+are rejected; such candidates are omitted. Zsh requires an initialized completion
+system (`compinit`).
 
 ---