PythonIota 1.0.0__tar.gz → 1.2.0__tar.gz

{pythoniota-1.0.0 → pythoniota-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PythonIota
-Version: 1.0.0
+Version: 1.2.0
 Summary: Go-style iota enumerations and flexible sequence generators for Python
 Author: Equinox
 License: MIT

{pythoniota-1.0.0 → pythoniota-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "PythonIota"
-version = "1.0.0"
+version = "1.2.0"
 description = "Go-style iota enumerations and flexible sequence generators for Python"
 readme = "README.md"
 license = {text = "MIT"}

{pythoniota-1.0.0 → pythoniota-1.2.0}/src/PythonIota.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PythonIota
-Version: 1.0.0
+Version: 1.2.0
 Summary: Go-style iota enumerations and flexible sequence generators for Python
 Author: Equinox
 License: MIT

{pythoniota-1.0.0 → pythoniota-1.2.0}/src/PythonIota.egg-info/SOURCES.txt

@@ -8,10 +8,16 @@ src/pythoniota/_bitflag.py
 src/pythoniota/_compat.py
 src/pythoniota/_safe_eval.py
 src/pythoniota/enum.py
+src/pythoniota/recipes.py
 src/pythoniota/sequence.py
+tests/test_advanced.py
 tests/test_bitflags.py
 tests/test_compat.py
 tests/test_enum.py
+tests/test_enum_enhanced.py
 tests/test_integration.py
+tests/test_recipes.py
 tests/test_safe_eval.py
-tests/test_sequence.py
+tests/test_sequence.py
+tests/test_serialization.py
+tests/test_string_enum.py

{pythoniota-1.0.0 → pythoniota-1.2.0}/src/pythoniota/__init__.py

@@ -1,15 +1,23 @@
 from pythoniota._compat import Iota
 from pythoniota._bitflag import BitFlag
 from pythoniota._safe_eval import safe_eval
-from pythoniota.enum import IotaEnum, IotaBitFlags
+from pythoniota.enum import (
+    IotaEnum, IotaBitFlags, IotaStringEnum,
+    FlagScope, iota_enum, _EnumMemberProxy,
+)
 from pythoniota.sequence import IotaSequence as iota
+from pythoniota import recipes
 
-__version__ = "1.0.0"
+__version__ = "1.2.0"
 __all__ = [
     "Iota",
     "IotaEnum",
     "IotaBitFlags",
+    "IotaStringEnum",
     "iota",
     "BitFlag",
+    "FlagScope",
+    "iota_enum",
     "safe_eval",
+    "recipes",
 ]

{pythoniota-1.0.0 → pythoniota-1.2.0}/src/pythoniota/_bitflag.py

@@ -69,6 +69,20 @@ class BitFlag:
     def has(self, flag: BitFlag | int) -> bool:
         return flag in self
 
+    def has_any(self, *flags: BitFlag | int) -> bool:
+        for f in flags:
+            fv = f._value if isinstance(f, BitFlag) else int(f)
+            if self._value & fv:
+                return True
+        return False
+
+    def has_all(self, *flags: BitFlag | int) -> bool:
+        for f in flags:
+            fv = f._value if isinstance(f, BitFlag) else int(f)
+            if (self._value & fv) != fv:
+                return False
+        return True
+
     def decompose(self) -> list[BitFlag]:
         result = []
         v = self._value
@@ -87,5 +101,19 @@ class BitFlag:
     def __str__(self) -> str:
         return self._name or str(self._value)
 
+    def __format__(self, format_spec: str) -> str:
+        if not format_spec:
+            return self._name or str(self._value)
+        if format_spec == "v":
+            return str(self._value)
+        if format_spec == "n":
+            return self._name
+        if format_spec == "b":
+            return bin(self._value)
+        return format(self._value, format_spec)
+
+    def __reduce__(self) -> tuple:
+        return (BitFlag, (self._value, self._name))
+
     def __iter__(self) -> Iterator[BitFlag]:
         return iter(self.decompose())

pythoniota-1.2.0/src/pythoniota/enum.py

@@ -0,0 +1,540 @@
+from __future__ import annotations
+
+import json
+import pickle
+from collections import OrderedDict
+from contextlib import contextmanager
+from typing import Any, Callable, Iterator
+
+from pythoniota._bitflag import BitFlag
+
+
+class _IotaCounter:
+    """Sentinel returned by IotaNamespace when 'iota' is read. Holds the current counter value."""
+
+    __slots__ = ("value",)
+
+    def __init__(self, value: int) -> None:
+        self.value = value
+
+    def __int__(self) -> int:
+        return self.value
+
+    def __index__(self) -> int:
+        return self.value
+
+    def __lshift__(self, other: Any) -> int:
+        return self.value << int(other)
+
+    def __rlshift__(self, other: Any) -> int:
+        return int(other) << self.value
+
+    def __rshift__(self, other: Any) -> int:
+        return self.value >> int(other)
+
+    def __rrshift__(self, other: Any) -> int:
+        return int(other) >> self.value
+
+    def __add__(self, other: Any) -> int:
+        return self.value + int(other)
+
+    def __radd__(self, other: Any) -> int:
+        return int(other) + self.value
+
+    def __sub__(self, other: Any) -> int:
+        return self.value - int(other)
+
+    def __rsub__(self, other: Any) -> int:
+        return int(other) - self.value
+
+    def __mul__(self, other: Any) -> int:
+        return self.value * int(other)
+
+    def __rmul__(self, other: Any) -> int:
+        return int(other) * self.value
+
+    def __floordiv__(self, other: Any) -> int:
+        return self.value // int(other)
+
+    def __rfloordiv__(self, other: Any) -> int:
+        return int(other) // self.value
+
+    def __mod__(self, other: Any) -> int:
+        return self.value % int(other)
+
+    def __rmod__(self, other: Any) -> int:
+        return int(other) % self.value
+
+    def __pow__(self, other: Any) -> int:
+        return self.value ** int(other)
+
+    def __rpow__(self, other: Any) -> int:
+        return int(other) ** self.value
+
+    def __or__(self, other: Any) -> int:
+        return self.value | int(other)
+
+    def __ror__(self, other: Any) -> int:
+        return int(other) | self.value
+
+    def __and__(self, other: Any) -> int:
+        return self.value & int(other)
+
+    def __rand__(self, other: Any) -> int:
+        return int(other) & self.value
+
+    def __xor__(self, other: Any) -> int:
+        return self.value ^ int(other)
+
+    def __rxor__(self, other: Any) -> int:
+        return int(other) ^ self.value
+
+    def __neg__(self) -> int:
+        return -self.value
+
+    def __pos__(self) -> int:
+        return +self.value
+
+    def __invert__(self) -> int:
+        return ~self.value
+
+    def __eq__(self, other: Any) -> bool:
+        return self.value == int(other) if isinstance(other, (int, _IotaCounter)) else NotImplemented
+
+    def __hash__(self) -> int:
+        return hash(self.value)
+
+    def __repr__(self) -> str:
+        return f"iota({self.value})"
+
+
+class IotaNamespace(dict):  # type: ignore[type-arg]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._counter = 0
+        self._member_names: list[str] = []
+
+    def __getitem__(self, key: str) -> Any:
+        if key == "iota":
+            val = _IotaCounter(self._counter)
+            self._counter += 1
+            return val
+        return super().__getitem__(key)
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        super().__setitem__(key, value)
+        if (
+            not key.startswith("_")
+            and key != "iota"
+            and isinstance(value, (int, float, str, _IotaCounter))
+        ):
+            if key not in self._member_names:
+                self._member_names.append(key)
+
+
+class IotaEnumMeta(type):
+
+    @classmethod
+    def __prepare__(mcs, name: str, bases: tuple[type, ...], **kwargs: Any) -> IotaNamespace:  # type: ignore[override]
+        return IotaNamespace()
+
+    def __new__(
+        mcs,
+        name: str,
+        bases: tuple[type, ...],
+        namespace: IotaNamespace,  # type: ignore[override]
+        **kwargs: Any,
+    ) -> IotaEnumMeta:
+        member_names = namespace._member_names if isinstance(namespace, IotaNamespace) else []
+        members: OrderedDict[str, Any] = OrderedDict()
+        for mname in member_names:
+            val = namespace[mname] if mname in namespace else 0
+            members[mname] = int(val) if isinstance(val, _IotaCounter) else val
+
+        cls = super().__new__(mcs, name, bases, dict(namespace))
+        cls._members_ = members  # type: ignore[attr-defined]
+        cls._aliases_: dict[str, str] = {}  # type: ignore[attr-defined]
+
+        is_bitflag = any(
+            hasattr(b, "_is_bitflag_base") for b in bases
+        )
+        is_string_enum = any(
+            hasattr(b, "_is_string_enum_base") for b in bases
+        )
+
+        is_ordered = namespace.get("_ordered_", False) or any(
+            getattr(b, "_ordered_", False) for b in bases
+        )
+
+        if is_string_enum:
+            fmt = namespace.get("_format_", None)
+            for mname, mval in list(members.items()):
+                if isinstance(mval, _IotaCounter) or isinstance(mval, int):
+                    if fmt:
+                        members[mname] = fmt.format(name=mname, index=mval if isinstance(mval, int) else int(mval))
+                    else:
+                        members[mname] = mname
+                type.__setattr__(cls, mname, members[mname])
+        elif is_bitflag:
+            for mname, mval in members.items():
+                flag = BitFlag(int(mval), mname)
+                members[mname] = flag
+                type.__setattr__(cls, mname, flag)
+        elif is_ordered:
+            for order, (mname, mval) in builtins_enumerate(members.items()):
+                proxy = _EnumMemberProxy(mname, mval, cls, order)
+                members[mname] = proxy
+                type.__setattr__(cls, mname, proxy)
+        else:
+            for mname, mval in members.items():
+                type.__setattr__(cls, mname, mval)
+
+        doc_lines = [f"{name} enum members:"]
+        for mname, mval in members.items():
+            doc_lines.append(f"  {mname} = {mval}")
+        cls.__doc__ = "\n".join(doc_lines)
+
+        return cls
+
+    def __iter__(cls) -> Iterator[tuple[str, int | float]]:
+        return iter(cls._members_.items())  # type: ignore[attr-defined]
+
+    def __contains__(cls, item: Any) -> bool:
+        if isinstance(item, str):
+            return item in cls._members_  # type: ignore[attr-defined]
+        return item in cls._members_.values()  # type: ignore[attr-defined]
+
+    def __len__(cls) -> int:
+        return len(cls._members_)  # type: ignore[attr-defined]
+
+    def __getitem__(cls, key: str) -> int | float:
+        return cls._members_[key]  # type: ignore[attr-defined]
+
+    def __setattr__(cls, name: str, value: Any) -> None:
+        if hasattr(cls, "_members_") and name in cls._members_:  # type: ignore[attr-defined]
+            raise AttributeError(f"Cannot modify enum member '{name}'")
+        super().__setattr__(name, value)
+
+    def __delattr__(cls, name: str) -> None:
+        if hasattr(cls, "_members_") and name in cls._members_:  # type: ignore[attr-defined]
+            raise AttributeError(f"Cannot delete enum member '{name}'")
+        super().__delattr__(name)
+
+    def __call__(cls, value: Any) -> Any:
+        for name, val in cls._members_.items():  # type: ignore[attr-defined]
+            cmp_val = int(val) if isinstance(val, BitFlag) else val
+            if cmp_val == value:
+                return val
+        raise ValueError(f"{value!r} is not a valid value in {cls.__name__}")
+
+    def __repr__(cls) -> str:
+        items = ", ".join(f"{k}={v}" for k, v in cls._members_.items())  # type: ignore[attr-defined]
+        return f"<{cls.__name__}: {items}>"
+
+    def __reduce__(cls) -> tuple[Any, ...]:
+        return (cls.__class__, (cls.__name__, cls.__bases__, dict(cls._members_)))  # type: ignore[attr-defined]
+
+
+class _EnumMemberProxy:
+    """Wraps an enum member value to support ordered comparison within the same enum."""
+
+    __slots__ = ("_name", "_value", "_enum_cls", "_order")
+
+    def __init__(self, name: str, value: Any, enum_cls: type, order: int) -> None:
+        object.__setattr__(self, "_name", name)
+        object.__setattr__(self, "_value", value)
+        object.__setattr__(self, "_enum_cls", enum_cls)
+        object.__setattr__(self, "_order", order)
+
+    def __int__(self) -> int:
+        return int(self._value)
+
+    def __index__(self) -> int:
+        return int(self._value)
+
+    def __eq__(self, other: Any) -> bool:
+        if isinstance(other, _EnumMemberProxy):
+            return self._value == other._value
+        return self._value == other
+
+    def __ne__(self, other: Any) -> bool:
+        return not self.__eq__(other)
+
+    def __lt__(self, other: Any) -> bool:
+        if isinstance(other, _EnumMemberProxy):
+            if self._enum_cls is not other._enum_cls:
+                raise TypeError(f"'<' not supported between members of '{self._enum_cls.__name__}' and '{other._enum_cls.__name__}'")
+            return self._order < other._order
+        return NotImplemented
+
+    def __le__(self, other: Any) -> bool:
+        if isinstance(other, _EnumMemberProxy):
+            if self._enum_cls is not other._enum_cls:
+                raise TypeError(f"'<=' not supported between members of '{self._enum_cls.__name__}' and '{other._enum_cls.__name__}'")
+            return self._order <= other._order
+        return NotImplemented
+
+    def __gt__(self, other: Any) -> bool:
+        if isinstance(other, _EnumMemberProxy):
+            if self._enum_cls is not other._enum_cls:
+                raise TypeError(f"'>' not supported between members of '{self._enum_cls.__name__}' and '{other._enum_cls.__name__}'")
+            return self._order > other._order
+        return NotImplemented
+
+    def __ge__(self, other: Any) -> bool:
+        if isinstance(other, _EnumMemberProxy):
+            if self._enum_cls is not other._enum_cls:
+                raise TypeError(f"'>=' not supported between members of '{self._enum_cls.__name__}' and '{other._enum_cls.__name__}'")
+            return self._order >= other._order
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash((self._enum_cls, self._value))
+
+    def __repr__(self) -> str:
+        return f"{self._enum_cls.__name__}.{self._name}"
+
+    def __str__(self) -> str:
+        return self._name
+
+    def __format__(self, format_spec: str) -> str:
+        if not format_spec:
+            return self._name
+        if format_spec == "v":
+            return str(self._value)
+        if format_spec == "n":
+            return self._name
+        if format_spec == "r":
+            return repr(self)
+        if format_spec == "nv":
+            return f"{self._name}={self._value}"
+        return format(self._value, format_spec)
+
+    def __bool__(self) -> bool:
+        return True
+
+    def __add__(self, other: Any) -> Any:
+        return self._value + (other._value if isinstance(other, _EnumMemberProxy) else other)
+
+    def __radd__(self, other: Any) -> Any:
+        return other + self._value
+
+    def __sub__(self, other: Any) -> Any:
+        return self._value - (other._value if isinstance(other, _EnumMemberProxy) else other)
+
+    def __rsub__(self, other: Any) -> Any:
+        return other - self._value
+
+    def __mul__(self, other: Any) -> Any:
+        return self._value * (other._value if isinstance(other, _EnumMemberProxy) else other)
+
+    def __rmul__(self, other: Any) -> Any:
+        return other * self._value
+
+    def __or__(self, other: Any) -> Any:
+        return self._value | (other._value if isinstance(other, _EnumMemberProxy) else other)
+
+    def __ror__(self, other: Any) -> Any:
+        return other | self._value
+
+    def __and__(self, other: Any) -> Any:
+        return self._value & (other._value if isinstance(other, _EnumMemberProxy) else other)
+
+    def __rand__(self, other: Any) -> Any:
+        return other & self._value
+
+    def __lshift__(self, other: Any) -> Any:
+        return self._value << (other._value if isinstance(other, _EnumMemberProxy) else other)
+
+    def __rlshift__(self, other: Any) -> Any:
+        return other << self._value
+
+    def __rshift__(self, other: Any) -> Any:
+        return self._value >> (other._value if isinstance(other, _EnumMemberProxy) else other)
+
+    def __rrshift__(self, other: Any) -> Any:
+        return other >> self._value
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        return (_restore_member, (self._enum_cls, self._name))
+
+
+def _restore_member(cls: type, name: str) -> Any:
+    return getattr(cls, name)
+
+
+class IotaEnum(metaclass=IotaEnumMeta):
+
+    @classmethod
+    def names(cls) -> list[str]:
+        return list(cls._members_.keys())  # type: ignore[attr-defined]
+
+    @classmethod
+    def values(cls) -> list[Any]:
+        return list(cls._members_.values())  # type: ignore[attr-defined]
+
+    @classmethod
+    def items(cls) -> list[tuple[str, Any]]:
+        return list(cls._members_.items())  # type: ignore[attr-defined]
+
+    @classmethod
+    def from_value(cls, value: Any) -> str | None:
+        for name, val in cls._members_.items():  # type: ignore[attr-defined]
+            if val == value:
+                return name
+        for alias, target in cls._aliases_.items():  # type: ignore[attr-defined]
+            if cls._members_[target] == value:  # type: ignore[attr-defined]
+                return alias
+        return None
+
+    @classmethod
+    def alias(cls, alias_name: str, target_name: str) -> None:
+        if target_name not in cls._members_:  # type: ignore[attr-defined]
+            raise KeyError(f"'{target_name}' is not a member of {cls.__name__}")
+        cls._aliases_[alias_name] = target_name  # type: ignore[attr-defined]
+        type.__setattr__(cls, alias_name, cls._members_[target_name])  # type: ignore[attr-defined]
+
+    @classmethod
+    def to_dict(cls) -> dict[str, Any]:
+        return dict(cls._members_)  # type: ignore[attr-defined]
+
+    @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
+        return json.dumps(d, **kwargs)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> dict[str, Any]:
+        result = {}
+        for name, value in data.items():
+            if name in cls._members_:  # type: ignore[attr-defined]
+                result[name] = cls._members_[name]  # type: ignore[attr-defined]
+            else:
+                raise KeyError(f"'{name}' is not a member of {cls.__name__}")
+        return result
+
+    @classmethod
+    def from_json(cls, s: str) -> dict[str, Any]:
+        return cls.from_dict(json.loads(s))
+
+
+class IotaBitFlags(metaclass=IotaEnumMeta):
+    _is_bitflag_base = True
+
+    @classmethod
+    def names(cls) -> list[str]:
+        return list(cls._members_.keys())  # type: ignore[attr-defined]
+
+    @classmethod
+    def values(cls) -> list[BitFlag]:
+        return list(cls._members_.values())  # type: ignore[attr-defined]
+
+    @classmethod
+    def items(cls) -> list[tuple[str, BitFlag]]:
+        return list(cls._members_.items())  # type: ignore[attr-defined]
+
+    @classmethod
+    def from_value(cls, value: int) -> str | None:
+        for name, flag in cls._members_.items():  # type: ignore[attr-defined]
+            if int(flag) == value:
+                return name
+        return None
+
+    @classmethod
+    def to_dict(cls) -> dict[str, int]:
+        return {k: int(v) for k, v in cls._members_.items()}  # type: ignore[attr-defined]
+
+    @classmethod
+    def to_json(cls, **kwargs: Any) -> str:
+        return json.dumps(cls.to_dict(), **kwargs)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> dict[str, BitFlag]:
+        result = {}
+        for name in data:
+            if name in cls._members_:  # type: ignore[attr-defined]
+                result[name] = cls._members_[name]  # type: ignore[attr-defined]
+            else:
+                raise KeyError(f"'{name}' is not a member of {cls.__name__}")
+        return result
+
+    @classmethod
+    def from_json(cls, s: str) -> dict[str, BitFlag]:
+        return cls.from_dict(json.loads(s))
+
+
+class IotaStringEnum(IotaEnum):
+    _is_string_enum_base = True
+
+
+class FlagScope:
+    """Context manager for scoped bitflag operations."""
+
+    def __init__(self, initial: BitFlag | int = 0) -> None:
+        self._flags = initial if isinstance(initial, BitFlag) else BitFlag(initial)
+
+    @property
+    def flags(self) -> BitFlag:
+        return self._flags
+
+    def grant(self, *flags: BitFlag | int) -> None:
+        for f in flags:
+            self._flags = self._flags | f
+
+    def revoke(self, *flags: BitFlag | int) -> None:
+        for f in flags:
+            fv = int(f)
+            self._flags = BitFlag(int(self._flags) & ~fv)
+
+    def has(self, flag: BitFlag | int) -> bool:
+        return self._flags.has(flag)
+
+    def __enter__(self) -> FlagScope:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        pass
+
+    def __repr__(self) -> str:
+        return f"FlagScope({self._flags})"
+
+
+def iota_enum(cls: type | None = None, *, ordered: bool = False) -> Any:
+    """Decorator to convert a plain class into an IotaEnum.
+
+    Usage:
+        @iota_enum
+        class Color:
+            Red = 0
+            Green = 1
+            Blue = 2
+
+        @iota_enum(ordered=True)
+        class Priority:
+            Low = 0
+            Medium = 1
+            High = 2
+    """
+    def _wrap(klass: type) -> IotaEnumMeta:
+        ns = IotaNamespace()
+        if ordered:
+            ns["_ordered_"] = True
+        for key, val in vars(klass).items():
+            if key.startswith("_"):
+                continue
+            if callable(val) and not isinstance(val, (int, float, str)):
+                continue
+            ns[key] = val
+            ns._member_names.append(key)
+        return IotaEnumMeta(klass.__name__, (IotaEnum,), ns)
+
+    if cls is not None:
+        return _wrap(cls)
+    return _wrap
+
+
+import builtins
+builtins_enumerate = builtins.enumerate