literalenum 0.2.0__tar.gz → 0.3.0__tar.gz

{literalenum-0.2.0 → literalenum-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: literalenum
-Version: 0.2.0
+Version: 0.3.0
 Summary: A Python typing construct that provides namespaced literal constants with advanced typing features.
 Project-URL: Homepage, https://github.com/modularizer/literalenum
 Project-URL: Repository, https://github.com/modularizer/literalenum
@@ -12,8 +12,6 @@ Keywords: python,typehinting
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 
-from sample_str_enum_solutions.a_strenum import HttpMethod
-
 # LiteralEnum
 
 **LiteralEnum** is an experiment/prototype for a proposed Python typing construct: 

{literalenum-0.2.0 → literalenum-0.3.0}/README.md

@@ -1,5 +1,3 @@
-from sample_str_enum_solutions.a_strenum import HttpMethod
-
 # LiteralEnum
 
 **LiteralEnum** is an experiment/prototype for a proposed Python typing construct: 

{literalenum-0.2.0 → literalenum-0.3.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "literalenum"
-version = "0.2.0"
+version = "0.3.0"
 description = "A Python typing construct that provides namespaced literal constants with advanced typing features."
 readme = "README.md"
 requires-python = ">=3.10"

{literalenum-0.2.0 → literalenum-0.3.0}/src/literalenum/stubgen.py

@@ -129,10 +129,10 @@ def _render_enum_blocks(enums: list[EnumInfo]) -> str:
 
     out: list[str] = []
     for e in sorted(enums, key=lambda x: x.name):
-        alias = f"{e.name}T"
+        T = f"{e.name}T"
         values = list(e.members.values())
         literal_union = ", ".join(_py_literal(v) for v in values) if values else ""
-        out.append(f"{alias}: TypeAlias = Literal[{literal_union}]\n\n")
+        out.append(f"{T}: TypeAlias = Literal[{literal_union}]\n\n")
 
         base = _enum_base_decl(e)
         inherited = _inherited_member_names(e)
@@ -141,27 +141,62 @@ def _render_enum_blocks(enums: list[EnumInfo]) -> str:
         own_members = [(k, v) for (k, v) in e.members.items() if k not in inherited]
 
         out.append(f"class {e.name}({base}):\n")
-        out.append(f"    T_ = Literal[{literal_union}]\n")
-        if not own_members:
-            out.append("    ...\n")
-        else:
+
+        # -- Members --
+        if own_members:
             for k, v in own_members:
                 out.append(f"    {k}: Final[Literal[{_py_literal(v)}]] = {_py_literal(v)}\n")
+        else:
+            out.append("    ...\n")
+        out.append("\n")
+
+        # -- Mappings --
+        out.append(f"    mapping: ClassVar[MappingProxyType[str, {T}]]\n")
+        out.append(f"    unique_mapping: ClassVar[MappingProxyType[str, {T}]]\n")
+        out.append(f"    __members__: ClassVar[MappingProxyType[str, {T}]]\n\n")
+
+        # -- Dict-like --
+        out.append("    @classmethod\n")
+        out.append("    def keys(cls) -> tuple[str, ...]: ...\n")
+        out.append("    @classmethod\n")
+        out.append(f"    def values(cls) -> tuple[{T}, ...]: ...\n")
+        out.append("    @classmethod\n")
+        out.append(f"    def items(cls) -> tuple[tuple[str, {T}], ...]: ...\n\n")
 
-        out.append(f"    values: ClassVar[Iterable[{alias}]]\n")
-        out.append(f"    mapping: ClassVar[dict[str, {alias}]]\n\n")
+        # -- Alias introspection --
+        out.append("    @classmethod\n")
+        out.append(f"    def names(cls, value: {T}) -> tuple[str, ...]: ...\n")
+        out.append("    @classmethod\n")
+        out.append(f"    def canonical_name(cls, value: {T}) -> str: ...\n\n")
 
+        # -- Validation --
+        out.append("    @classmethod\n")
+        out.append(f"    def is_valid(cls, x: object) -> TypeGuard[{T}]: ...\n")
+        out.append("    @classmethod\n")
+        out.append(f"    def validate(cls, x: object) -> {T}: ...\n\n")
+
+        # -- Container protocol --
+        out.append(f"    def __iter__(cls) -> Iterator[{T}]: ...\n")
+        out.append(f"    def __reversed__(cls) -> Iterator[{T}]: ...\n")
+        out.append("    def __len__(cls) -> int: ...\n")
+        out.append("    def __bool__(cls) -> bool: ...\n")
+        out.append("    def __contains__(cls, value: object) -> bool: ...\n")
+        out.append(f"    def __getitem__(cls, key: str) -> {T}: ...\n")
+        out.append("    def __repr__(cls) -> str: ...\n\n")
+
+        # -- Operators --
+        out.append("    def __or__(cls, other: LiteralEnumMeta) -> LiteralEnumMeta: ...\n")
+        out.append("    def __and__(cls, other: LiteralEnumMeta) -> LiteralEnumMeta: ...\n\n")
+
+        # -- Constructor --
         if e.call_to_validate:
             out.append("    @overload\n")
-            out.append(f"    def __new__(cls, value: {alias}) -> {alias}: ...\n")
+            out.append(f"    def __new__(cls, value: {T}) -> {T}: ...\n")
             out.append("    @overload\n")
-            out.append(f"    def __new__(cls, value: object) -> {alias}: ...\n\n")
+            out.append(f"    def __new__(cls, value: object) -> {T}: ...\n\n")
         else:
             out.append(f"    def __new__(cls, value: Never) -> NoReturn: ...\n\n")
 
-        out.append("    @classmethod\n")
-        out.append(f"    def is_member(cls, value: object) -> TypeGuard[{alias}]: ...\n\n")
-
     return "".join(out)
 
 
@@ -202,8 +237,9 @@ def _render_overlay_stub_module(enums: list[EnumInfo]) -> str:
     """
     out: list[str] = []
     out.append("from __future__ import annotations\n")
-    out.append("from typing import ClassVar, Final, Literal, Iterable, Never, NoReturn, TypeGuard, TypeAlias, overload\n")
-    out.append("from literalenum import LiteralEnum\n\n")
+    out.append("from types import MappingProxyType\n")
+    out.append("from typing import ClassVar, Final, Iterator, Literal, Never, NoReturn, TypeAlias, TypeGuard, overload\n")
+    out.append("from literalenum import LiteralEnum, LiteralEnumMeta\n\n")
     out.append(_render_enum_blocks(enums))
     return "".join(out)
 
@@ -212,8 +248,9 @@ def _render_overlay_stub_module(enums: list[EnumInfo]) -> str:
 # Adjacent stubs (preserve module)
 # ----------------------------
 
-_TYPING_INJECT = "from typing import ClassVar, Final, Literal, Iterable, Never, NoReturn, TypeGuard, TypeAlias, overload"
-_LITERALENUM_INJECT = "from literalenum import LiteralEnum"
+_TYPES_INJECT = "from types import MappingProxyType"
+_TYPING_INJECT = "from typing import ClassVar, Final, Iterator, Literal, Never, NoReturn, TypeAlias, TypeGuard, overload"
+_LITERALENUM_INJECT = "from literalenum import LiteralEnum, LiteralEnumMeta"
 _FUTURE = "from __future__ import annotations"
 
 
@@ -250,10 +287,12 @@ def _normalize_imports(import_lines: list[str]) -> list[str]:
             continue
         if s.startswith("from literalenum import") and "LiteralEnum" in s:
             continue
+        if s.startswith("from types import") and "MappingProxyType" in s:
+            continue
         if s.startswith("from typing import"):
             # drop any typing line that imports our injected symbols
             # (simple heuristic: if it mentions any of them, drop it)
-            symbols = ["ClassVar", "Final", "Literal", "Iterable", "TypeGuard", "overload"]
+            symbols = ["ClassVar", "Final", "Iterator", "Literal", "TypeGuard", "overload"]
             if any(sym in s for sym in symbols):
                 continue
         out.append(s)
@@ -319,6 +358,7 @@ def _render_adjacent_preserving_stub(module: str, enums: list[EnumInfo]) -> str:
         out.append("\n")
 
     # Inject what enum blocks need, exactly once
+    out.append(_TYPES_INJECT + "\n")
     out.append(_TYPING_INJECT + "\n")
     out.append(_LITERALENUM_INJECT + "\n\n")
 

{literalenum-0.2.0 → literalenum-0.3.0}/src/typing_literalenum.py

@@ -609,6 +609,62 @@ class LiteralEnumMeta(type):
         """
         return validate_is_member(cls, x)
 
+    # ---- Testing utilities ----
+
+    def matches_enum(cls, enum_cls: type) -> bool:
+        """Check whether this LiteralEnum has exactly the same values as *enum_cls*.
+
+        Compares the set of unique values in this LiteralEnum against the
+        ``.value`` of every member in the given ``enum.Enum`` (or subclass).
+        Useful in test suites to assert two parallel definitions stay in sync::
+
+            import enum
+
+            class Color(enum.StrEnum):
+                RED = "red"
+                GREEN = "green"
+
+            class ColorLE(LiteralEnum):
+                RED = "red"
+                GREEN = "green"
+
+            assert ColorLE.matches_enum(Color)
+
+        Returns:
+            ``True`` if the value sets are identical.
+        """
+        try:
+            enum_values = {m.value for m in enum_cls}
+        except TypeError:
+            return False
+        return set(cls._ordered_values_) == enum_values
+
+    def matches_literal(cls, literal_type: Any) -> bool:
+        """Check whether this LiteralEnum has exactly the same values as *literal_type*.
+
+        Extracts the arguments from a ``typing.Literal[...]`` and compares
+        them against this LiteralEnum's unique values.  Useful in test suites
+        to assert a Literal type alias stays in sync with a LiteralEnum::
+
+            from typing import Literal
+
+            ColorLiteral = Literal["red", "green"]
+
+            class Color(LiteralEnum):
+                RED = "red"
+                GREEN = "green"
+
+            assert Color.matches_literal(ColorLiteral)
+
+        Returns:
+            ``True`` if the value sets are identical.
+        """
+        from typing import get_args
+        args = get_args(literal_type)
+        if not args:
+            return False
+        return set(cls._ordered_values_) == set(args)
+
 
 # ---------------------------------------------------------------------------
 # Base class

{literalenum-0.2.0 → literalenum-0.3.0}/tests/test_typing_literalenum.py

@@ -629,6 +629,103 @@ class TestAnd:
         assert list(C) == []  # True and 1 are distinct by strict key
 
 
+# ===================================================================
+# matches_enum / matches_literal
+# ===================================================================
+
+class TestMatchesEnum:
+    def test_matches_identical(self):
+        import enum
+
+        class E(enum.Enum):
+            GET = "GET"
+            POST = "POST"
+            DELETE = "DELETE"
+
+        assert HttpMethod.matches_enum(E) is True
+
+    def test_matches_strenum(self):
+        import enum
+
+        class E(enum.StrEnum):
+            GET = "GET"
+            POST = "POST"
+            DELETE = "DELETE"
+
+        assert HttpMethod.matches_enum(E) is True
+
+    def test_matches_intenum(self):
+        import enum
+
+        class E(enum.IntEnum):
+            OK = 200
+            NOT_FOUND = 404
+
+        assert StatusCode.matches_enum(E) is True
+
+    def test_mismatch_extra_in_enum(self):
+        import enum
+
+        class E(enum.Enum):
+            GET = "GET"
+            POST = "POST"
+            DELETE = "DELETE"
+            PATCH = "PATCH"
+
+        assert HttpMethod.matches_enum(E) is False
+
+    def test_mismatch_missing_in_enum(self):
+        import enum
+
+        class E(enum.Enum):
+            GET = "GET"
+
+        assert HttpMethod.matches_enum(E) is False
+
+    def test_mismatch_different_values(self):
+        import enum
+
+        class E(enum.Enum):
+            GET = "get"
+            POST = "post"
+            DELETE = "delete"
+
+        assert HttpMethod.matches_enum(E) is False
+
+    def test_non_enum_returns_false(self):
+        assert HttpMethod.matches_enum(str) is False
+
+
+class TestMatchesLiteral:
+    def test_matches_identical(self):
+        from typing import Literal
+        assert HttpMethod.matches_literal(Literal["GET", "POST", "DELETE"]) is True
+
+    def test_matches_int_literal(self):
+        from typing import Literal
+        assert StatusCode.matches_literal(Literal[200, 404]) is True
+
+    def test_mismatch_extra(self):
+        from typing import Literal
+        assert HttpMethod.matches_literal(Literal["GET", "POST", "DELETE", "PATCH"]) is False
+
+    def test_mismatch_missing(self):
+        from typing import Literal
+        assert HttpMethod.matches_literal(Literal["GET"]) is False
+
+    def test_order_independent(self):
+        from typing import Literal
+        assert HttpMethod.matches_literal(Literal["DELETE", "GET", "POST"]) is True
+
+    def test_non_literal_returns_false(self):
+        assert HttpMethod.matches_literal(str) is False
+
+    def test_matches_type_alias(self):
+        from typing import Literal
+        MyType = Literal["GET", "POST", "DELETE"]
+        assert HttpMethod.matches_literal(MyType) is True
+
+
 # ===================================================================
 # Edge cases
 # ===================================================================