literalenum 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

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.dist-info → literalenum-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: literalenum
-Version: 0.2.0
+Version: 0.4.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.dist-info → literalenum-0.4.0.dist-info}/RECORD

@@ -1,7 +1,7 @@
 literalenum/__init__.py,sha256=Cle3alhK2TPqkjKZ6yEFB3_2yv-y0EwtdYUnbkRG_-s,477
 literalenum/literal_enum.py,sha256=OfB73GCHeZ5G1cAz3EA99zzZsmQ6jtL3xx3AKK-XP-0,3907
 literalenum/mypy_plugin.py,sha256=JExHoi8NP_QJI0eESRed3TdR3DxEVrj7qA6q-bhj3KU,11020
-literalenum/stubgen.py,sha256=IWT774iThGrbXkYOjVcoCd8Osst9InXpwUJvb3EcG4I,15654
+literalenum/stubgen.py,sha256=PdY4i_5eBHzQkOyMtctitreTtR-3lNOqrLqPocsCZ1g,17544
 literalenum/compatibility_extensions/__init__.py,sha256=nIY32idsLpo9VyXtDREWMzLAfYUU7K7Zm3Cl69mWR0k,551
 literalenum/compatibility_extensions/annotated.py,sha256=68TxWaCzMdcuFgnyWfWHUtzUClP5r99BMydSufdgcRA,146
 literalenum/compatibility_extensions/bare_class.py,sha256=LXhT5BfIBJmfA8ZQmHfAVyF4IpM9911oUcj4xtonLFM,75
@@ -18,10 +18,10 @@ literalenum/compatibility_extensions/regex.py,sha256=4XDtC8VlehMlcZkcE5L9nXbKkR4
 literalenum/compatibility_extensions/sqlalchemy_enum.py,sha256=DF_ce3Q7YNp98mTFXPsyWagQVzTTaczI-dRklOPh_LY,237
 literalenum/compatibility_extensions/str_enum.py,sha256=y-VWFyaEDXmNicgyqzdEpsx-ImUdnydbF_YWhzvEVq0,329
 literalenum/compatibility_extensions/strawberry_enum.py,sha256=mjg3Pyy0w_AggRRB_UtuWQiOguiG66eTN5E_rpwd7cg,526
-typing_literalenum.py,sha256=ZoM0rbr-7Hp72uqohJ6enm-eIhUwAHTGBsb-FsQmXJs,24837
+typing_literalenum.py,sha256=CKU4EBfMDZisrK8d9exWwp6sJhznJYp998oaRM5Igjs,27936
 literalenum/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-literalenum-0.2.0.dist-info/METADATA,sha256=2f2bFRLze4cbkzhiL5xogmz_vJyQU4Rqwd_B-PtqOd4,4879
-literalenum-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-literalenum-0.2.0.dist-info/entry_points.txt,sha256=AK8je10LoLMOXuWLjXSqHV2rsTxPW9HlG7YTJGfwkCY,46
-literalenum-0.2.0.dist-info/licenses/LICENSE,sha256=tQZYOMusRS38hVum5uAxSBrSxoQG9w0h6tkyE3RlPmw,1212
-literalenum-0.2.0.dist-info/RECORD,,
+literalenum-0.4.0.dist-info/METADATA,sha256=JA3sd54K2v5bhuOxtfnVroNnsGVajcRQeNMJ9fFzpVI,4819
+literalenum-0.4.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+literalenum-0.4.0.dist-info/entry_points.txt,sha256=AK8je10LoLMOXuWLjXSqHV2rsTxPW9HlG7YTJGfwkCY,46
+literalenum-0.4.0.dist-info/licenses/LICENSE,sha256=tQZYOMusRS38hVum5uAxSBrSxoQG9w0h6tkyE3RlPmw,1212
+literalenum-0.4.0.dist-info/RECORD,,

typing_literalenum.py

@@ -370,6 +370,48 @@ class LiteralEnumMeta(type):
             for names in cls._value_names_.values()
         })
 
+    @property
+    def name_mapping(cls) -> Mapping[Any, str]:
+        """A read-only ``{value: canonical_name}`` inverse mapping.
+
+        Each unique value maps to its first-declared (canonical) name::
+
+            class Method(LiteralEnum):
+                GET = "GET"
+                get = "GET"       # alias
+
+            Method.name_mapping   # {"GET": "GET"}
+
+        See also :attr:`names_mapping` for all names including aliases.
+        """
+        return MappingProxyType({
+            v: names[0]
+            for v, names in zip(cls._ordered_values_, cls._value_names_.values())
+        })
+
+    @property
+    def names_by_value(cls) -> Mapping[Any, str]:
+        return cls.name_mapping
+
+
+    @property
+    def names_mapping(cls) -> Mapping[Any, tuple[str, ...]]:
+        """A read-only ``{value: (name, ...)}`` inverse mapping.
+
+        Each unique value maps to a tuple of all its declared names
+        (canonical first, then aliases)::
+
+            class Method(LiteralEnum):
+                GET = "GET"
+                get = "GET"       # alias
+
+            Method.names_mapping  # {"GET": ("GET", "get")}
+        """
+        return MappingProxyType({
+            v: names
+            for v, names in zip(cls._ordered_values_, cls._value_names_.values())
+        })
+
     def keys(cls) -> tuple[str, ...]:
         """Return canonical member names in definition order (aliases excluded)."""
         return tuple(
@@ -609,6 +651,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