PythonIota 1.2.0__py3-none-any.whl → 1.7.0__py3-none-any.whl

pythoniota/__init__.py

@@ -3,12 +3,14 @@ from pythoniota._bitflag import BitFlag
 from pythoniota._safe_eval import safe_eval
 from pythoniota.enum import (
     IotaEnum, IotaBitFlags, IotaStringEnum,
-    FlagScope, iota_enum, _EnumMemberProxy,
+    FlagScope, iota_enum, unique, _EnumMemberProxy,
 )
 from pythoniota.sequence import IotaSequence as iota
 from pythoniota import recipes
+from pythoniota import regex
+from pythoniota import cli
 
-__version__ = "1.2.0"
+__version__ = "1.7.0"
 __all__ = [
     "Iota",
     "IotaEnum",
@@ -18,6 +20,9 @@ __all__ = [
     "BitFlag",
     "FlagScope",
     "iota_enum",
+    "unique",
     "safe_eval",
     "recipes",
+    "regex",
+    "cli",
 ]

pythoniota/cli/__init__.py

@@ -0,0 +1,27 @@
+"""A from-scratch, zero-dependency command-line argument parser.
+
+A small, faithful subset of the standard library's ``argparse``:
+
+    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 and optional arguments, ``nargs`` (``N`` / ``?`` / ``*``
+/ ``+``), ``type`` / ``choices`` / ``default`` / ``required``, actions
+``store`` / ``store_true`` / ``store_false`` / ``store_const`` / ``append`` /
+``count``, ``--opt=value`` and clustered short flags (``-abc``), the ``--``
+end-of-options marker, an auto-generated ``-h/--help``, and sub-commands via
+``add_subparsers``. Bad user input prints usage and raises ``SystemExit``.
+"""
+
+from ._argument import Argument
+from ._errors import ArgumentError
+from ._namespace import Namespace
+from ._parser import ArgumentParser
+
+__all__ = ["ArgumentParser", "Namespace", "Argument", "ArgumentError"]

pythoniota/cli/_argument.py

@@ -0,0 +1,70 @@
+"""A single argument specification (the result of one ``add_argument`` call)."""
+
+INF = float("inf")
+
+# Actions that consume no value from the command line.
+_ZERO_ACTIONS = ("store_true", "store_false", "store_const", "count", "help")
+
+
+class Argument:
+    def __init__(self, option_strings, dest, action, nargs, const, default,
+                 type, choices, required, metavar, help):
+        self.option_strings = option_strings      # [] for positionals
+        self.dest = dest
+        self.action = action
+        self.nargs = nargs
+        self.const = const
+        self.default = default
+        self.type = type
+        self.choices = choices
+        self.required = required
+        self.metavar = metavar
+        self.help = help
+
+    @property
+    def is_positional(self):
+        return not self.option_strings
+
+    def takes_value(self):
+        return self.action not in _ZERO_ACTIONS
+
+    def get_default(self):
+        if self.action == "store_true":
+            return False
+        if self.action == "store_false":
+            return True
+        return self.default
+
+    def count_range(self):
+        """(min, max) number of command-line tokens this argument consumes."""
+        if not self.takes_value():
+            return (0, 0)
+        n = self.nargs
+        if n is None:
+            return (1, 1)
+        if n == "?":
+            return (0, 1)
+        if n == "*":
+            return (0, INF)
+        if n == "+":
+            return (1, INF)
+        return (n, n)                             # an int
+
+    def display_name(self):
+        return "/".join(self.option_strings) if self.option_strings else self.metavar
+
+    def convert_one(self, raw, parser):
+        if self.type is not None:
+            try:
+                value = self.type(raw)
+            except (ValueError, TypeError):
+                tname = getattr(self.type, "__name__", str(self.type))
+                parser.error(f"argument {self.display_name()}: "
+                             f"invalid {tname} value: {raw!r}")
+        else:
+            value = raw
+        if self.choices is not None and value not in self.choices:
+            choices = ", ".join(repr(c) for c in self.choices)
+            parser.error(f"argument {self.display_name()}: "
+                         f"invalid choice: {value!r} (choose from {choices})")
+        return value

pythoniota/cli/_errors.py

@@ -0,0 +1,9 @@
+"""Exceptions raised while *building* a parser (bad add_argument calls).
+
+Parse-time problems (bad user input) go through ``ArgumentParser.error`` and
+raise ``SystemExit`` instead, matching the standard library.
+"""
+
+
+class ArgumentError(Exception):
+    """A malformed argument specification."""

pythoniota/cli/_formatter.py

@@ -0,0 +1,93 @@
+"""Usage/help text generation. Layout is clean and readable; it deliberately
+does not try to reproduce the standard library's column math byte-for-byte."""
+
+
+def _value_pattern(arg):
+    """The ``METAVAR`` portion of an argument's usage, honoring nargs."""
+    if not arg.takes_value():
+        return ""
+    m, n = arg.metavar, arg.nargs
+    if n is None:
+        return m
+    if n == "?":
+        return f"[{m}]"
+    if n == "*":
+        return f"[{m} ...]"
+    if n == "+":
+        return f"{m} [{m} ...]"
+    return " ".join([m] * n)                       # an int
+
+
+def _optional_usage(arg):
+    flag = arg.option_strings[0]
+    value = _value_pattern(arg)
+    piece = f"{flag} {value}" if value else flag
+    return piece if arg.required else f"[{piece}]"
+
+
+def _positional_usage(arg):
+    m = arg.metavar
+    n = arg.nargs
+    if n == "?":
+        return f"[{m}]"
+    if n == "*":
+        return f"[{m} ...]"
+    if n == "+":
+        return f"{m} [{m} ...]"
+    if isinstance(n, int):
+        return " ".join([m] * n)
+    return m
+
+
+def format_usage(parser):
+    parts = [f"usage: {parser.prog}"]
+    for arg in parser._arguments:
+        if arg.option_strings:
+            parts.append(_optional_usage(arg))
+    for arg in parser._arguments:
+        if not arg.option_strings:
+            parts.append(_positional_usage(arg))
+    if parser._subparsers is not None:
+        names = ",".join(parser._subparsers.choices)
+        parts.append(f"{{{names}}} ...")
+    return " ".join(parts) + "\n"
+
+
+def _row(invocation, help):
+    if not help:
+        return f"  {invocation}\n"
+    if len(invocation) <= 20:
+        return f"  {invocation:<20}  {help}\n"
+    return f"  {invocation}\n{'':<24}{help}\n"
+
+
+def format_help(parser):
+    out = [format_usage(parser)]
+    if parser.description:
+        out.append("\n" + parser.description + "\n")
+
+    positionals = [a for a in parser._arguments if not a.option_strings]
+    optionals = [a for a in parser._arguments if a.option_strings]
+
+    if positionals or parser._subparsers is not None:
+        out.append("\npositional arguments:\n")
+        for arg in positionals:
+            out.append(_row(arg.metavar, arg.help))
+        if parser._subparsers is not None:
+            sp = parser._subparsers
+            out.append(_row("{" + ",".join(sp.choices) + "}", sp.help))
+            for name in sp.choices:
+                out.append(_row("  " + name, sp._help.get(name)))
+
+    if optionals:
+        out.append("\noptions:\n")
+        for arg in optionals:
+            invocation = ", ".join(arg.option_strings)
+            value = _value_pattern(arg)
+            if value:
+                invocation += " " + value
+            out.append(_row(invocation, arg.help))
+
+    if parser.epilog:
+        out.append("\n" + parser.epilog + "\n")
+    return "".join(out)

pythoniota/cli/_namespace.py

@@ -0,0 +1,17 @@
+"""The object ``parse_args`` fills in — attribute access over parsed values."""
+
+
+class Namespace:
+    def __init__(self, **kwargs):
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+
+    def __eq__(self, other):
+        return isinstance(other, Namespace) and vars(self) == vars(other)
+
+    def __contains__(self, key):
+        return key in self.__dict__
+
+    def __repr__(self):
+        items = ", ".join(f"{k}={v!r}" for k, v in self.__dict__.items())
+        return f"Namespace({items})"

pythoniota/cli/_parser.py

@@ -0,0 +1,321 @@
+"""A from-scratch, ``argparse``-style command-line parser.
+
+The parser turns ``add_argument`` calls into :class:`Argument` specs, then does
+a single left-to-right scan of ``argv``: options are consumed as they appear,
+leftover tokens are matched against the positional specs by their (min, max)
+counts. Errors print a usage line and raise ``SystemExit(2)`` — same contract
+as the standard library, so it drops into scripts and tests unchanged.
+"""
+
+import os
+import sys
+
+from ._argument import Argument, INF
+from ._errors import ArgumentError
+from ._namespace import Namespace
+from . import _formatter
+
+
+class _SubParsers:
+    """The object returned by ``add_subparsers``; holds the command table."""
+
+    def __init__(self, parent, dest, required, help, metavar):
+        self.parent = parent
+        self.dest = dest
+        self.required = required
+        self.help = help
+        self.metavar = metavar
+        self.choices = {}                         # name -> ArgumentParser
+        self._help = {}                           # name -> help string
+
+    def add_parser(self, name, help=None, **kwargs):
+        kwargs.setdefault("prog", f"{self.parent.prog} {name}")
+        parser = ArgumentParser(**kwargs)
+        self.choices[name] = parser
+        self._help[name] = help
+        return parser
+
+
+class ArgumentParser:
+    def __init__(self, prog=None, description=None, epilog=None,
+                 add_help=True, prefix_chars="-"):
+        self.prog = prog or os.path.basename(sys.argv[0] or "prog")
+        self.description = description
+        self.epilog = epilog
+        self.prefix = prefix_chars[0]
+        self._arguments = []
+        self._optionmap = {}                      # option string -> Argument
+        self._subparsers = None
+        self._seen = set()
+        if add_help:
+            self.add_argument(self.prefix + "h", self.prefix * 2 + "help",
+                              action="help", help="show this help message and exit")
+
+    # -- building ----------------------------------------------------------- #
+    def add_argument(self, *names, **kwargs):
+        action = kwargs.get("action", "store")
+        if names and names[0].startswith(self.prefix):
+            option_strings = list(names)
+            dest = kwargs.get("dest")
+            if dest is None:
+                longs = [n for n in names if n.startswith(self.prefix * 2)]
+                base = (longs[0] if longs else names[0]).lstrip(self.prefix)
+                dest = base.replace("-", "_")
+            required = kwargs.get("required", False)
+        else:
+            if len(names) != 1:
+                raise ArgumentError("positional arguments take a single name")
+            option_strings = []
+            dest = kwargs.get("dest", names[0])
+            required = kwargs.get("nargs") not in ("?", "*")
+
+        const = kwargs.get("const")
+        if action == "store_const" and const is None:
+            raise ArgumentError("action 'store_const' requires 'const='")
+
+        metavar = kwargs.get("metavar")
+        if metavar is None:
+            metavar = dest.upper() if option_strings else dest
+
+        arg = Argument(
+            option_strings=option_strings,
+            dest=dest,
+            action=action,
+            nargs=kwargs.get("nargs"),
+            const=const,
+            default=kwargs.get("default"),
+            type=kwargs.get("type"),
+            choices=kwargs.get("choices"),
+            required=required,
+            metavar=metavar,
+            help=kwargs.get("help"),
+        )
+        self._arguments.append(arg)
+        for opt in option_strings:
+            self._optionmap[opt] = arg
+        return arg
+
+    def add_subparsers(self, dest=None, required=False, help=None, metavar=None):
+        if self._subparsers is not None:
+            raise ArgumentError("cannot have multiple subparser sets")
+        self._subparsers = _SubParsers(self, dest, required, help, metavar)
+        return self._subparsers
+
+    # -- parsing ------------------------------------------------------------ #
+    def parse_args(self, argv=None, namespace=None):
+        ns, extras = self.parse_known_args(argv, namespace)
+        if extras:
+            self.error("unrecognized arguments: " + " ".join(extras))
+        return ns
+
+    def parse_known_args(self, argv=None, namespace=None):
+        if argv is None:
+            argv = sys.argv[1:]
+        argv = list(argv)
+        if namespace is None:
+            namespace = Namespace()
+        self._seen = set()
+
+        for arg in self._arguments:
+            if arg.action != "help" and not hasattr(namespace, arg.dest):
+                setattr(namespace, arg.dest, arg.get_default())
+
+        extras = []                               # (original_index, token)
+        if self._subparsers is not None:
+            return self._parse_with_subparsers(argv, namespace, extras)
+
+        positionals_raw = []                      # (original_index, token)
+        i, after_ddash = 0, False
+        while i < len(argv):
+            tok = argv[i]
+            if not after_ddash and tok == self.prefix * 2:
+                after_ddash = True
+                i += 1
+            elif not after_ddash and self._is_option(tok):
+                i = self._consume_optional(argv, i, namespace, extras)
+            else:
+                positionals_raw.append((i, tok))
+                i += 1
+
+        self._match_positionals(positionals_raw, namespace, extras)
+        self._check_required(namespace)
+        return namespace, self._order_extras(extras)
+
+    # -- option scanning ---------------------------------------------------- #
+    def _is_option(self, tok):
+        if not tok.startswith(self.prefix) or tok == self.prefix:
+            return False
+        if tok.startswith(self.prefix * 2):
+            return True
+        return not tok[1].isdigit()               # '-5' is a value, '-x' an option
+
+    def _consume_optional(self, argv, i, namespace, extras):
+        tok = argv[i]
+        if tok.startswith(self.prefix * 2):
+            name, eq, val = tok.partition("=")
+            arg = self._optionmap.get(name)
+            if arg is None:
+                extras.append((i, tok))
+                return i + 1
+            return self._apply_option(arg, name, val if eq else None,
+                                      argv, i + 1, namespace)
+
+        # short cluster, e.g. -v, -vvv, -abc, -o value, -ovalue
+        j = 1
+        while j < len(tok):
+            oname = self.prefix + tok[j]
+            arg = self._optionmap.get(oname)
+            if arg is None:
+                extras.append((i, tok))
+                return i + 1
+            if not arg.takes_value():
+                self._store_zero(arg, oname, namespace)
+                j += 1
+                continue
+            rest = tok[j + 1:]
+            return self._apply_option(arg, oname, rest or None,
+                                      argv, i + 1, namespace)
+        return i + 1
+
+    def _apply_option(self, arg, name, explicit, argv, i, namespace):
+        if not arg.takes_value():
+            if explicit is not None:
+                self.error(f"argument {name}: ignored explicit argument {explicit!r}")
+            self._store_zero(arg, name, namespace)
+            return i
+
+        lo, hi = arg.count_range()
+        values = []
+        if explicit is not None:
+            values.append(explicit)
+        while len(values) < hi and i < len(argv):
+            nxt = argv[i]
+            if nxt == self.prefix * 2 or self._is_option(nxt):
+                break
+            values.append(nxt)
+            i += 1
+        if len(values) < lo:
+            expected = f"at least {lo}" if hi == INF else str(lo)
+            self.error(f"argument {name}: expected {expected} argument(s)")
+        self._store_values(arg, values, namespace)
+        return i
+
+    # -- storing ------------------------------------------------------------ #
+    def _store_zero(self, arg, name, namespace):
+        if arg.action == "help":
+            self.print_help()
+            self.exit(0)
+        elif arg.action == "store_true":
+            setattr(namespace, arg.dest, True)
+        elif arg.action == "store_false":
+            setattr(namespace, arg.dest, False)
+        elif arg.action == "store_const":
+            setattr(namespace, arg.dest, arg.const)
+        elif arg.action == "count":
+            current = getattr(namespace, arg.dest, None) or 0
+            setattr(namespace, arg.dest, current + 1)
+        self._seen.add(arg.dest)
+
+    def _store_values(self, arg, raw_values, namespace):
+        converted = [arg.convert_one(v, self) for v in raw_values]
+        if arg.nargs is None:
+            value = converted[0]
+        elif arg.nargs == "?":
+            if converted:
+                value = converted[0]
+            else:
+                value = arg.const if arg.option_strings else arg.default
+        else:                                     # int, '*', '+'
+            value = converted
+
+        if arg.action == "append":
+            current = getattr(namespace, arg.dest, None)
+            lst = list(current) if current else []
+            lst.append(value)
+            setattr(namespace, arg.dest, lst)
+        else:
+            setattr(namespace, arg.dest, value)
+        self._seen.add(arg.dest)
+
+    def _match_positionals(self, pairs, namespace, extras):
+        positionals = [a for a in self._arguments if a.is_positional]
+        toks = [t for _, t in pairs]
+        idx, n = 0, len(toks)
+        for k, arg in enumerate(positionals):
+            lo, hi = arg.count_range()
+            remaining_min = sum(p.count_range()[0] for p in positionals[k + 1:])
+            avail = n - idx - remaining_min
+            if avail < lo:
+                self.error("the following arguments are required: " + arg.metavar)
+            take = int(min(hi, avail))
+            chunk = toks[idx:idx + take]
+            idx += take
+            self._store_values(arg, chunk, namespace)
+        if idx < n:
+            extras.extend(pairs[idx:])
+
+    @staticmethod
+    def _order_extras(extras):
+        return [tok for _, tok in sorted(extras, key=lambda pair: pair[0])]
+
+    def _check_required(self, namespace):
+        missing = [a.option_strings[0] for a in self._arguments
+                   if a.option_strings and a.required and a.dest not in self._seen]
+        if missing:
+            self.error("the following arguments are required: " + ", ".join(missing))
+
+    # -- subcommands -------------------------------------------------------- #
+    def _parse_with_subparsers(self, argv, namespace, extras):
+        sp = self._subparsers
+        i, after_ddash = 0, False
+        while i < len(argv):
+            tok = argv[i]
+            if not after_ddash and tok == self.prefix * 2:
+                after_ddash = True
+                i += 1
+            elif not after_ddash and self._is_option(tok):
+                i = self._consume_optional(argv, i, namespace, extras)
+            else:
+                break
+        self._check_required(namespace)
+
+        if i >= len(argv):
+            if sp.required:
+                self.error("the following arguments are required: "
+                           + (sp.metavar or sp.dest or "command"))
+            return namespace, self._order_extras(extras)
+
+        command = argv[i]
+        if command not in sp.choices:
+            choices = ", ".join(repr(c) for c in sp.choices)
+            self.error(f"argument command: invalid choice: {command!r} "
+                       f"(choose from {choices})")
+        if sp.dest:
+            setattr(namespace, sp.dest, command)
+        _, child_extras = sp.choices[command].parse_known_args(argv[i + 1:], namespace)
+        return namespace, self._order_extras(extras) + child_extras
+
+    # -- help / errors ------------------------------------------------------ #
+    def format_usage(self):
+        return _formatter.format_usage(self)
+
+    def format_help(self):
+        return _formatter.format_help(self)
+
+    def print_usage(self, file=None):
+        (file or sys.stdout).write(self.format_usage())
+
+    def print_help(self, file=None):
+        (file or sys.stdout).write(self.format_help())
+
+    def error(self, message):
+        self.print_usage(sys.stderr)
+        self.exit(2, f"{self.prog}: error: {message}\n")
+
+    def exit(self, status=0, message=None):
+        if message:
+            sys.stderr.write(message)
+        raise SystemExit(status)
+
+    def __repr__(self):
+        return f"ArgumentParser(prog={self.prog!r})"

pythoniota/enum.py

@@ -113,20 +113,32 @@ class IotaNamespace(dict):  # type: ignore[type-arg]
     def __init__(self) -> None:
         super().__init__()
         self._counter = 0
+        self._step = 1
         self._member_names: list[str] = []
 
+    def _skip(self, n: int = 1) -> None:
+        """Advance the iota counter by `n` steps without defining a member (Go's blank `_`)."""
+        self._counter += n * self._step
+        return None
+
     def __getitem__(self, key: str) -> Any:
         if key == "iota":
             val = _IotaCounter(self._counter)
-            self._counter += 1
+            self._counter += self._step
             return val
+        if key == "skip":
+            return self._skip
         return super().__getitem__(key)
 
     def __setitem__(self, key: str, value: Any) -> None:
+        if key == "_iota_start_":
+            self._counter = int(value)
+        elif key == "_iota_step_":
+            self._step = int(value)
         super().__setitem__(key, value)
         if (
             not key.startswith("_")
-            and key != "iota"
+            and key not in ("iota", "skip")
             and isinstance(value, (int, float, str, _IotaCounter))
         ):
             if key not in self._member_names:
@@ -182,7 +194,7 @@ class IotaEnumMeta(type):
                 members[mname] = flag
                 type.__setattr__(cls, mname, flag)
         elif is_ordered:
-            for order, (mname, mval) in builtins_enumerate(members.items()):
+            for order, (mname, mval) in enumerate(members.items()):
                 proxy = _EnumMemberProxy(mname, mval, cls, order)
                 members[mname] = proxy
                 type.__setattr__(cls, mname, proxy)
@@ -388,6 +400,14 @@ class IotaEnum(metaclass=IotaEnumMeta):
                 return alias
         return None
 
+    @classmethod
+    def has(cls, name: str) -> bool:
+        return name in cls._members_  # type: ignore[attr-defined]
+
+    @classmethod
+    def get(cls, name: str, default: Any = None) -> Any:
+        return cls._members_.get(name, default)  # type: ignore[attr-defined]
+
     @classmethod
     def alias(cls, alias_name: str, target_name: str) -> None:
         if target_name not in cls._members_:  # type: ignore[attr-defined]
@@ -397,13 +417,21 @@ class IotaEnum(metaclass=IotaEnumMeta):
 
     @classmethod
     def to_dict(cls) -> dict[str, Any]:
-        return dict(cls._members_)  # type: ignore[attr-defined]
+        d = {}
+        for k, v in cls._members_.items():  # type: ignore[attr-defined]
+            d[k] = v._value if isinstance(v, _EnumMemberProxy) else v
+        return d
 
     @classmethod
     def to_json(cls, **kwargs: Any) -> str:
         d = {}
         for k, v in cls._members_.items():  # type: ignore[attr-defined]
-            d[k] = int(v) if isinstance(v, (BitFlag, float)) and not isinstance(v, str) else v
+            if isinstance(v, _EnumMemberProxy):
+                d[k] = v._value
+            elif isinstance(v, BitFlag):
+                d[k] = int(v)
+            else:
+                d[k] = v
         return json.dumps(d, **kwargs)
 
     @classmethod
@@ -443,6 +471,14 @@ class IotaBitFlags(metaclass=IotaEnumMeta):
                 return name
         return None
 
+    @classmethod
+    def has(cls, name: str) -> bool:
+        return name in cls._members_  # type: ignore[attr-defined]
+
+    @classmethod
+    def get(cls, name: str, default: Any = None) -> Any:
+        return cls._members_.get(name, default)  # type: ignore[attr-defined]
+
     @classmethod
     def to_dict(cls) -> dict[str, int]:
         return {k: int(v) for k, v in cls._members_.items()}  # type: ignore[attr-defined]
@@ -536,5 +572,22 @@ def iota_enum(cls: type | None = None, *, ordered: bool = False) -> Any:
     return _wrap
 
 
-import builtins
-builtins_enumerate = builtins.enumerate
+def _member_value(val: Any) -> Any:
+    if isinstance(val, _EnumMemberProxy):
+        return val._value
+    if isinstance(val, BitFlag):
+        return int(val)
+    return val
+
+
+def unique(cls: type) -> type:
+    """Class decorator that rejects an enum with duplicate member values."""
+    seen: dict[Any, str] = {}
+    for name, val in cls._members_.items():  # type: ignore[attr-defined]
+        v = _member_value(val)
+        if v in seen:
+            raise ValueError(
+                f"duplicate value {v!r} in {cls.__name__}: {seen[v]} and {name}"
+            )
+        seen[v] = name
+    return cls