PythonIota

A zero-dependency Python toolkit of from-scratch building blocks — Go-style iota enumerations, lazy sequence generators, and a Pike-VM regex engine.

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 valid match after selecting a shorter branch.
• Ordered enum members now hash consistently with equal numeric values and equal members of other enums, preserving dictionary and set lookups.

What's inside

• Enums — Go-style iota, bit flags, string enums (pythoniota.IotaEnum, ...)
• Sequences — lazy, chainable generators (pythoniota.iota)
• Regex — a from-scratch NFA (Pike VM) engine, no catastrophic backtracking (pythoniota.regex)
• CLI — a from-scratch argparse-style argument parser (pythoniota.cli)

---

Enums

Go-style iota

iota starts at 0 and auto-increments each time it is read. Literal assignments do not consume it.

from pythoniota import IotaEnum

class Color(IotaEnum):
    Red   = iota   # 0
    Green = iota   # 1
    Blue  = iota   # 2

Color.Green          # 1
Color.names()        # ['Red', 'Green', 'Blue']
Color.values()       # [0, 1, 2]
list(Color)          # [('Red', 0), ('Green', 1), ('Blue', 2)]
0 in Color           # True (by value)
'Red' in Color       # True (by name)
Color.from_value(2)  # 'Blue'

iota works inside expressions — the value is the current counter:

class Perm(IotaEnum):
    Read  = 1 << iota          # 1
    Write = 1 << iota          # 2
    Exec  = 1 << iota          # 4
    All   = Read | Write | Exec # 7

class Size(IotaEnum):
    KB = 1 << (iota + 10)      # 1024
    MB = 1 << (iota + 10)      # 2048
    GB = 1 << (iota + 10)      # 4096

Skipping values & custom start/step

class Errno(IotaEnum):
    EPERM = iota   # 0
    skip(2)        # skip 1, 2
    EBADF = iota   # 3

class Port(IotaEnum):
    _iota_start_ = 8000
    _iota_step_  = 10
    HTTP  = iota   # 8000
    HTTPS = iota   # 8010

_ = iota also skips a single value (Go's blank identifier).

Immutability, aliases, serialization

Color.Red = 99          # AttributeError: cannot modify enum member
Color.alias('R', 'Red') # Color.R == 0
Color.to_dict()         # {'Red': 0, 'Green': 1, 'Blue': 2}
Color.to_json()         # '{"Red": 0, "Green": 1, "Blue": 2}'
Color.from_json(s)      # -> dict of members
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

from pythoniota import unique

@unique
class Status(IotaEnum):
    Active   = iota
    Inactive = iota
# raises ValueError if two members share a value

Ordered enums

Add _ordered_ = True to make members comparable by declaration order:

class Priority(IotaEnum):
    _ordered_ = True
    Low    = iota
    Medium = iota
    High   = iota

Priority.Low < Priority.High   # True

Bit flags

from pythoniota import IotaBitFlags, FlagScope

class Access(IotaBitFlags):
    Read  = 1 << iota   # 1
    Write = 1 << iota   # 2
    Exec  = 1 << iota   # 4

flags = Access.Read | Access.Write
flags.has(Access.Read)              # True
flags.has_all(Access.Read, Access.Exec)  # False
flags.has_any(Access.Read, Access.Exec)  # True
list(flags.decompose())             # [BitFlag(1), BitFlag(2)]

with FlagScope() as scope:
    scope.grant(Access.Read, Access.Write)
    scope.revoke(Access.Write)
    scope.has(Access.Read)          # True

String enums

Members resolve to their own name, or a custom format:

from pythoniota import IotaStringEnum

class Color(IotaStringEnum):
    Red  = iota   # 'Red'
    Blue = iota   # 'Blue'

class Code(IotaStringEnum):
    _format_ = "{name}_{index:03d}"
    OK    = iota  # 'OK_000'
    Error = iota  # 'Error_001'

@iota_enum decorator

Turn a plain class into an enum:

from pythoniota import iota_enum

@iota_enum
class Color:
    Red = 0
    Green = 1
    Blue = 2

@iota_enum(ordered=True)
class Priority:
    Low = 0
    High = 1

match / case

Enum members match by value:

match color:
    case Color.Red:   ...
    case Color.Blue:  ...
    case _:           ...

---

Sequences

iota(...) is a lazy, composable sequence. Construction mirrors range, plus an optional map:

from pythoniota import iota

iota()                       # 0, 1, 2, ...        (infinite)
iota(5)                      # 0, 1, 2, 3, 4
iota(2, 10, 2)               # 2, 4, 6, 8
iota(5, map=lambda i: i*i)   # 0, 1, 4, 9, 16

s = iota(10)
len(s)          # 10        (O(1))
s[7]            # 7         (O(1) arithmetic indexing)
s[2:5]          # [2, 3, 4]
list(reversed(s))   # 9, 8, ... 0   (lazy)
5 in s          # True      (O(1))
s.take(3)       # [0, 1, 2]

Operators

iota(3) + iota(3, 6)   # concat: 0,1,2,3,4,5
iota(3) * 2            # repeat: 0,1,2,0,1,2
iota(3) | iota(3, 6)   # interleave: 0,3,1,4,2,5
iota(3) @ iota(3, 6)   # zip: (0,3),(1,4),(2,5)

Lazy combinators

iota(10).filter(lambda x: x % 2 == 0)   # 0,2,4,6,8
iota().map(lambda x: x*x)               # 0,1,4,9,...
iota().takewhile(lambda x: x < 5)       # 0,1,2,3,4
iota(10).dropwhile(lambda x: x < 7)     # 7,8,9
iota(4).pairwise()                      # (0,1),(1,2),(2,3)
iota(5).window(3)                       # (0,1,2),(1,2,3),(2,3,4)
iota(7).chunk(3)                        # [0,1,2],[3,4,5],[6]
iota(6).map(lambda x: x % 3).distinct() # 0,1,2
seq.flatten()                           # flatten one level
iota().enumerate()  .accumulate()  .zip(other)

Chainable iterator pipelines

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); known-infinite base sequences reject exhaustive terminals. Iterator pipelines consume their remaining elements.

iota(1, 101).sum()      # 5050   (closed-form, O(1))
iota(3, 10).min()       # 3
iota(3, 10).max()       # 9
iota(0, 10, 2).count()  # 5
iota(5).last()          # 4
iota(10).nth(3)         # 3
iota().first()          # 0
iota().find(lambda x: x > 100)   # 101
iota(1, 5).all(lambda x: x > 0)  # True
iota(5).any(lambda x: x == 3)    # True
iota(3).reduce(lambda a, b: a + b)  # 3

iota(3).to_list()                     # [0, 1, 2]
iota(3).to_tuple()                    # (0, 1, 2)
iota(3).to_set()                      # {0, 1, 2}
iota(3).to_dict(value=lambda x: x*x)  # {0: 0, 1: 1, 2: 4}

Async iteration

async for x in iota(5):
    ...

---

Recipes

from pythoniota.recipes import (
    fibonacci, lucas, factorial, catalan, harmonic,
    triangle, powers, geometric, primes, primes_sieve,
    pascal_row, collatz, repeat, cycle,
)

fibonacci(10).to_list()   # 0,1,1,2,3,5,8,13,21,34
lucas(7).to_list()        # 2,1,3,4,7,11,18
factorial(6).to_list()    # 1,1,2,6,24,120
catalan(6).to_list()      # 1,1,2,5,14,42
harmonic(4).to_list()     # 1.0, 1.5, 1.833..., 2.083...
triangle(5).to_list()     # 0,1,3,6,10
powers(2, 8).to_list()    # 1,2,4,...,128
geometric(3, 2, 4).to_list()  # 3,6,12,24
primes(5).to_list()       # 2,3,5,7,11        (first n primes)
primes_sieve(20).to_list()# 2,3,5,7,11,13,17,19  (< limit, Eratosthenes)
pascal_row(4).to_list()   # 1,4,6,4,1
collatz(6).to_list()      # 6,3,10,5,16,8,4,2,1
repeat('x', 3).to_list()  # ['x','x','x']
cycle([1,2], 5).to_list() # 1,2,1,2,1

Recipes without a count argument produce infinite sequences: fibonacci().take(20), primes().takewhile(lambda p: p < 100).

---

Safe expression evaluation

safe_eval evaluates arithmetic expressions over a whitelisted AST (no eval, no names/calls beyond provided variables):

from pythoniota import safe_eval

safe_eval("2 ** 10")                 # 1024
safe_eval("a * b + 1", {"a": 3, "b": 4})  # 13

---

Regex

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.

from pythoniota import regex

m = regex.match(r"(\d{4})-(\d{2})-(\d{2})", "2026-08-02")
m.groups()                                   # ('2026', '08', '02')

regex.findall(r"\w+", "hello world")          # ['hello', 'world']
regex.sub(r"\s+", "_", "a  b   c")            # 'a_b_c'
regex.split(r"[,;]\s*", "a, b; c,d")          # ['a', 'b', 'c', 'd']

named = regex.search(r"(?P<user>\w+)@(?P<host>\w+)", "user@host")
named.groupdict()                             # {'user': 'user', 'host': 'host'}

Supported: literals, ., * + ? and their lazy forms *? +? ??, alternation |, groups (...) / non-capturing (?:...) / named (?P<name>...), lookahead (?=...) / (?!...), fixed-width lookbehind (?<=...) / (?<!...), conditionals (?(id/name)yes|no), character classes [...], counted repeats {m,n}, shorthands \d \w \s (and \D \W \S), word boundaries \b \B, anchors ^ $ \A \Z, and hex escapes \xHH / \uHHHH. Flags: IGNORECASE, MULTILINE, DOTALL, VERBOSE (also inline (?imsx)). API mirrors re: compile, match, fullmatch, search, findall, finditer, sub, subn, split, escape, with Match.group / groups / span / groupdict / expand.

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 match immediately after an empty one at the same position.

regex.search(r"(a+)+$", "a" * 40 + "!")       # None, without backtracking

Execution limits and diagnostics

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

A faithful subset of the standard library's argparse, built from scratch:

from pythoniota import cli

p = cli.ArgumentParser(prog="greet", description="say hello")
p.add_argument("name")
p.add_argument("-n", "--times", type=int, default=1)
p.add_argument("-v", "--verbose", action="store_true")

args = p.parse_args(["world", "--times", "3", "-v"])
args.name, args.times, args.verbose      # ('world', 3, True)

Supported:

• positional & optional arguments, nargs (N / ? / * / +)
• type / choices / default / required
• actions: store, store_true, store_false, store_const, append, count
• --opt=value, clustered short flags (-abc), the -- end-of-options marker
• an auto-generated -h/--help, and sub-commands via add_subparsers

Bad input prints a usage line and raises SystemExit(2) — the same contract as argparse, so it drops into scripts and tests unchanged. parse_known_args returns (namespace, extras) instead of erroring on unknown tokens.

Sub-commands

p = cli.ArgumentParser(prog="git")
sub = p.add_subparsers(dest="cmd")

add = sub.add_parser("add", help="stage files")
add.add_argument("path")
add.add_argument("-f", "--force", action="store_true")

rm = sub.add_parser("rm", help="remove files")
rm.add_argument("path")

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

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

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

MIT