literalenum 0.1.1__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: literalenum
-Version: 0.1.1
+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
@@ -60,10 +60,36 @@ This repo is currently set up as a package under `src/`.
 #source .venv/bin/activate
 pip install literalenum
 ```
-
+## Realistic Current Usage
 ```python
+from typing import Literal
 from literalenum import LiteralEnum
 
+HttpMethodT = Literal["GET", "POST", "DELETE"]
+class HttpMethod(LiteralEnum):
+    GET = "GET"
+    POST = "POST"
+    DELETE = "DELETE"
+
+def handle(method: HttpMethodT) -> None:
+    print(f"{method=}")
+
+handle("GET")          # this should type-check ✅ 
+handle(HttpMethod.GET) # this should type-check ✅ 
+handle("git")          # ❌ should be rejected by a type checker
+
+assert HttpMethod.GET == "GET"
+assert list(HttpMethod) == ["GET", "POST", "DELETE"]
+assert "GET" in HttpMethod
+print(HttpMethod.keys())
+print(HttpMethod.values())
+print(HttpMethod.mapping)
+```
+
+## Optimistic Future Usage
+```python
+from typing import LiteralEnum # NOT valid right now
+
 class HttpMethod(LiteralEnum):
     GET = "GET"
     POST = "POST"
@@ -72,8 +98,8 @@ class HttpMethod(LiteralEnum):
 def handle(method: HttpMethod) -> None:
     print(f"{method=}")
 
-handle("GET")          # ✅ should type-check
-handle(HttpMethod.GET) # ✅ should type-check
+handle("GET")          # the GOAL is that this should type-check ✅ , in reality: it will not unless typecheckers change
+handle(HttpMethod.GET) # the GOAL is that this should type-check ✅ , in reality: it will not unless typecheckers change
 handle("git")          # ❌ should be rejected by a type checker
 
 assert HttpMethod.GET == "GET"

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

@@ -46,10 +46,36 @@ This repo is currently set up as a package under `src/`.
 #source .venv/bin/activate
 pip install literalenum
 ```
-
+## Realistic Current Usage
 ```python
+from typing import Literal
 from literalenum import LiteralEnum
 
+HttpMethodT = Literal["GET", "POST", "DELETE"]
+class HttpMethod(LiteralEnum):
+    GET = "GET"
+    POST = "POST"
+    DELETE = "DELETE"
+
+def handle(method: HttpMethodT) -> None:
+    print(f"{method=}")
+
+handle("GET")          # this should type-check ✅ 
+handle(HttpMethod.GET) # this should type-check ✅ 
+handle("git")          # ❌ should be rejected by a type checker
+
+assert HttpMethod.GET == "GET"
+assert list(HttpMethod) == ["GET", "POST", "DELETE"]
+assert "GET" in HttpMethod
+print(HttpMethod.keys())
+print(HttpMethod.values())
+print(HttpMethod.mapping)
+```
+
+## Optimistic Future Usage
+```python
+from typing import LiteralEnum # NOT valid right now
+
 class HttpMethod(LiteralEnum):
     GET = "GET"
     POST = "POST"
@@ -58,8 +84,8 @@ class HttpMethod(LiteralEnum):
 def handle(method: HttpMethod) -> None:
     print(f"{method=}")
 
-handle("GET")          # ✅ should type-check
-handle(HttpMethod.GET) # ✅ should type-check
+handle("GET")          # the GOAL is that this should type-check ✅ , in reality: it will not unless typecheckers change
+handle(HttpMethod.GET) # the GOAL is that this should type-check ✅ , in reality: it will not unless typecheckers change
 handle("git")          # ❌ should be rejected by a type checker
 
 assert HttpMethod.GET == "GET"

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

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "literalenum"
-version = "0.1.1"
+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.1.1 → 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")
 
-        out.append(f"    values: ClassVar[Iterable[{alias}]]\n")
-        out.append(f"    mapping: ClassVar[dict[str, {alias}]]\n\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")
+
+        # -- 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")
 
@@ -384,9 +424,50 @@ def _parse_out_args(raw: list[str] | None) -> list[Path]:
     return uniq
 
 
+def _resolve_root(raw: str) -> str:
+    """Resolve *raw* to a dotted module name importable by Python.
+
+    Accepts:
+      - A dotted import path:  ``myapp.models``
+      - A file path:           ``src/myapp/models.py``
+      - A directory path:      ``src/myapp/``
+
+    When a file or directory is given its parent is added to ``sys.path``
+    so that ``importlib`` can find it.
+    """
+    import sys
+
+    p = Path(raw)
+
+    # --- file path: /some/path/module.py ---
+    if p.is_file() and p.suffix == ".py":
+        parent = str(p.parent.resolve())
+        if parent not in sys.path:
+            sys.path.insert(0, parent)
+        return p.stem if p.name != "__init__.py" else p.parent.name
+
+    # --- directory path: /some/path/package/ ---
+    if p.is_dir():
+        parent = str(p.parent.resolve())
+        if parent not in sys.path:
+            sys.path.insert(0, parent)
+        return p.name
+
+    # --- dotted import name (ensure cwd is on path) ---
+    cwd = str(Path.cwd())
+    if cwd not in sys.path:
+        sys.path.insert(0, cwd)
+    return raw
+
+
 def main() -> int:
     ap = argparse.ArgumentParser()
-    ap.add_argument("root", help="Root import (package or module) to scan, e.g. myapp")
+    ap.add_argument(
+        "root",
+        help="Root to scan: a dotted import (myapp), "
+             "a .py file (src/myapp/models.py), "
+             "or a directory (src/myapp/).",
+    )
     ap.add_argument(
         "--out",
         action="append",
@@ -402,7 +483,8 @@ def main() -> int:
 
     write_adjacent: bool = not args.no_adjacent
     out_roots: list[Path] = _parse_out_args(args.out) if args.out else []
-    infos = _find_literal_enums(args.root)
+    root = _resolve_root(args.root)
+    infos = _find_literal_enums(root)
 
     by_module: dict[str, list[EnumInfo]] = {}
     for e in infos:

{literalenum-0.1.1 → 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.1.1 → 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
 # ===================================================================

literalenum-0.1.1/pyrightconfig.json

@@ -1,3 +0,0 @@
-{
-  "stubPath": "typings"
-}