PythonIota 1.7.1__tar.gz → 1.8.0__tar.gz

pythoniota-1.8.0/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include tests *.py
+include src/pythoniota/py.typed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: PythonIota
-Version: 1.7.1
+Version: 1.8.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
@@ -18,7 +18,7 @@ Description-Content-Type: text/markdown
 # PythonIota
 
 A **zero-dependency Python toolkit** of from-scratch building blocks — Go-style
-`iota` enumerations, lazy sequence generators, and a linear-time regex engine.
+`iota` enumerations, lazy sequence generators, and a Pike-VM regex engine.
 
 ```bash
 pip install PythonIota
@@ -26,6 +26,26 @@ pip install PythonIota
 
 Requires Python 3.10+.
 
+## 1.8.0
+
+### New features
+
+- Generic, single-pass `IotaIterator` pipelines support continuous chaining.
+- CLI options support explicit JSON/mapping configuration, opt-in environment
+  values and metadata-only completion candidates.
+- Regex operations support shared step/time budgets and structured diagnostics.
+
+### Fixes
+
+- Mapping derived sequences preserves their lazy iteration, element types and
+  finite/infinite behavior; `filter` still returns an iterator.
+- Empty regex matches, conditional capture states and zero-width repetitions
+  retain the appropriate alternatives and iteration order.
+- Parent CLI positionals are validated before subcommand dispatch.
+- Enum aliases cannot overwrite existing or reserved names; alias identifiers
+  must already be NFKC-normalized to agree with Python attribute syntax.
+- Sequence APIs carry generic element types, and distributions include `py.typed`.
+
 ## 1.7.1 fixes
 
 - Full matching now considers complete alternatives instead of rejecting a
@@ -109,6 +129,10 @@ Color.has('Red')        # True
 Color.get('Nope', -1)   # -1
 ```
 
+Alias names must be public Python identifiers. Existing members, aliases,
+methods and reserved/internal names cannot be overwritten; rejected aliases
+leave the enum unchanged.
+
 ### `@unique` — reject duplicate values
 
 ```python
@@ -251,9 +275,33 @@ seq.flatten()                           # flatten one level
 iota().enumerate()  .accumulate()  .zip(other)
 ```
 
+### Chainable iterator pipelines
+
+```python
+from pythoniota import IotaIterator, iota
+
+windows = iota(20).filter(lambda x: x % 2 == 0).map(str).window(3)
+windows.take(2)  # [('0', '2', '4'), ('2', '4', '6')]
+next(windows)   # ('4', '6', '8'): continues the same stream
+IotaIterator([1, 2, 3]).map(lambda x: x * 10).to_list()  # [10, 20, 30]
+iota().filter(lambda x: x % 2 == 0).map(str).take(3)    # ['0', '2', '4']
+```
+
+`filter`, `accumulate`, `enumerate`, `zip`, `chunk`, `window`, `takewhile`,
+`dropwhile`, `pairwise`, `flatten` and `distinct` return `IotaIterator` pipelines,
+which can continue chaining. They are lazy and single-pass (`iter(pipe) is pipe`),
+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.
+
 ### Terminal operations
 
-Reductions on plain arithmetic sequences are O(1); infinite sequences raise where they would not terminate.
+Reductions on plain arithmetic sequences are O(1); known-infinite base sequences
+reject exhaustive terminals. Iterator pipelines consume their remaining elements.
 
 ```python
 iota(1, 101).sum()      # 5050   (closed-form, O(1))
@@ -327,10 +375,12 @@ safe_eval("a * b + 1", {"a": 3, "b": 4})  # 13
 
 ## Regex
 
-A from-scratch regular-expression engine. Unlike Python's backtracking `re`, it
-compiles the pattern to a tiny bytecode and runs it with a **Pike VM** (a
-thread-list NFA simulation), so matching is linear in `len(text) × len(program)`
-— pathological patterns like `(a+)+$` finish instantly instead of hanging.
+A from-scratch regular-expression engine that runs bytecode with an ordered
+**Pike VM**. Plain patterns such as `(a+)+$` avoid catastrophic backtracking and
+run in linear time in the text length for a fixed pattern. This is not a
+universal complexity guarantee: lookaround can rescan suffixes, and conditionals
+can retain multiple capture-participation states. Use explicit `max_steps` and
+`timeout` limits when matching potentially expensive patterns.
 
 ```python
 from pythoniota import regex
@@ -361,15 +411,46 @@ 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: they can't be matched
-by a finite automaton in linear time — that's the price of the no-backtracking
-guarantee (the same trade-off Go's `regexp` and RE2 make).
+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
+match immediately after an empty one at the same position.
+
+```python
+regex.search(r"(a+)+$", "a" * 40 + "!")       # None, without backtracking
+```
+
+### Execution limits and diagnostics
 
 ```python
-# no ReDoS: this returns in microseconds, where re takes ~13s at length 28
-regex.search(r"(a+)+$", "a" * 40 + "!")       # None, instantly
+pattern = regex.compile(r"(?=a*$)")
+try:
+    result = pattern.search("a" * 100 + "!", max_steps=1000, timeout=0.1)
+except regex.RegexLimitError as error:
+    print(error.reason, error.steps)
+
+structure = pattern.explain()  # JSON-serializable bytecode, groups and nested assertions
+report = pattern.diagnose("aaaa!", max_steps=1000)
+print(report["status"], report["steps"], report["op_counts"])
 ```
 
+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.
+Nested lookarounds and all matches within one call share a single budget.
+`finditer` starts its timeout when created, including pauses between yields.
+
+Limit exhaustion raises `RegexLimitError`, never a false no-match result.
+`diagnose` supports `match`, `fullmatch` and `search`, instead returning an explicit
+`limit_exceeded` status with its reason, counters, peak pending threads and elapsed
+time. `explain` and `diagnose` also exist as module-level functions.
+
+Limits apply after pattern compilation. Timeouts are cooperative: they cannot
+preempt Python replacement callbacks, compilation or a single long native
+operation; elapsed time is checked again after callbacks. For hard isolation of
+untrusted patterns/callbacks, use a separate process and external resource limits.
+
 ---
 
 ## CLI
@@ -417,6 +498,56 @@ args = p.parse_args(["add", "README.md", "-f"])
 args.cmd, args.path, args.force          # ('add', 'README.md', True)
 ```
 
+Parent positionals declared before `add_subparsers` are consumed and validated
+before the command. Parent options may occur before the command; trailing
+options are parsed only by the selected child. As with argparse, variable
+`nargs` are greedy and command names are not special delimiters, so prefer
+fixed-count parent positionals for predictable subcommand syntax.
+
+### Configuration and environment values
+
+```python
+p = cli.ArgumentParser(config={"port": 8000, "mode": "fast"}, env_prefix="APP_")
+p.add_argument("--port", type=int, default=3000)
+p.add_argument("--mode", choices=["fast", "slow"])
+p.add_argument("--token", env_var="SERVICE_TOKEN")
+args = p.parse_args(["--port", "9000"])  # --port overrides APP_PORT and config
+```
+
+`config` accepts a mapping or a UTF-8 JSON-object path, read again on each parse.
+Keys are this parser's optional-argument destinations, not option spellings;
+unknown keys and malformed files are errors. Sources do not fill positionals.
+Precedence is explicit CLI > enabled environment > config > argument default;
+only the winning value is converted and checked against `choices`. Required
+options may be supplied by config/environment. Explicit caller `Namespace`
+values are retained unless the CLI changes them, but do not by themselves
+satisfy required options.
+
+Environment lookup is opt-in via `env_prefix` or an exact `env_var`; children
+configure their own sources with `add_parser(config=..., env_prefix=...)`.
+Scalar environment values are literal strings. Multi-value options use JSON
+arrays; `append` uses an array of occurrences (nested arrays for multi-value
+occurrences). Boolean values accept true/false, yes/no, on/off and 1/0; counts
+must be nonnegative integers. Explicit CLI append/count replaces lower sources,
+while legacy accumulation from argument defaults is retained when no external
+source applies. No configuration contents are executed as code or shell text.
+
+### Completion candidates
+
+```python
+p.complete([], "--po")             # ['--port']
+p.complete(["--mode"], "s")         # ['slow']
+p.complete([], "--mode=f")         # ['--mode=fast']
+```
+
+`complete(tokens, prefix="")` accepts finished words without the program/current
+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.
+
 ---
 
 ## License