literalenum 0.2.0__tar.gz → 0.4.0__tar.gz

literalenum-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,129 @@
+# Contributing to LiteralEnum
+
+Thanks for your interest in contributing. This document covers setup, project layout, and guidelines.
+
+## Setup
+
+```bash
+git clone https://github.com/modularizer/LiteralEnum.git
+cd LiteralEnum
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+pip install pytest
+```
+
+Requires Python 3.10+.
+
+## Project layout
+
+```
+src/
+  typing_literalenum.py              # Core module (proposed for typing_extensions / stdlib)
+  literalenum/
+    __init__.py                      # Package entry point
+    literal_enum.py                  # Extended metaclass wrapping the core
+    mypy_plugin.py                   # mypy plugin
+    stubgen.py                       # .pyi stub generator (lestub CLI)
+    compatibility_extensions/        # Converters to other frameworks
+      enum.py, str_enum.py, ...
+tests/
+  test_typing_literalenum.py         # Tests for the core module
+  test_literalenum.py                # Tests for the package (extended metaclass + compat)
+  test_typing.py                     # mypy type-checking validation
+```
+
+The two-module split is intentional:
+
+- **`typing_literalenum`** is the minimal, zero-dependency core proposed for the standard library. It should stay lean.
+- **`literalenum`** is the full package with ecosystem integrations (Pydantic, SQLAlchemy, Django, GraphQL, etc.). This is what gets published to PyPI.
+
+## Running tests
+
+```bash
+# All tests
+pytest
+
+# Core module only
+pytest tests/test_typing_literalenum.py
+
+# Package only
+pytest tests/test_literalenum.py
+
+# Verbose
+pytest -v
+```
+
+Tests for optional dependencies (strawberry, graphene, sqlalchemy, pydantic, click) are automatically skipped if the dependency isn't installed.
+
+## What goes where
+
+| Change                                                                      | File(s)                                                                                                                                                     |
+|-----------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Core runtime behavior (iteration, containment, validation, aliases, extend) | `src/typing_literalenum.py` + `tests/test_typing_literalenum.py`                                                                                            |
+| New compatibility converter (e.g. marshmallow, attrs)                       | New file in `compatibility_extensions/`, method in `literal_enum.py`, export in `compatibility_extensions/__init__.py`, test in `tests/test_literalenum.py` |
+| Stub generation                                                             | `src/literalenum/stubgen.py`                                                                                                                                |
+| mypy plugin                                                                 | `src/literalenum/mypy_plugin.py`                                                                                                                            |
+
+## Adding a compatibility extension
+
+1. Create `src/literalenum/compatibility_extensions/my_thing.py`:
+   ```python
+   def my_thing(cls):
+       # cls is a LiteralEnum class with _ordered_values_, _members_, etc.
+       ...
+   ```
+
+2. Export it in `compatibility_extensions/__init__.py`:
+   ```python
+   from .my_thing import my_thing
+   ```
+
+3. Add the method to `LiteralEnumMeta` in `literal_enum.py`:
+   ```python
+   def my_thing(cls):
+       return compat.my_thing(cls)
+   ```
+
+4. Add tests in `tests/test_literalenum.py`. If the extension requires an optional dependency, use `pytest.importorskip`:
+   ```python
+   def test_my_thing(self):
+       pytest.importorskip("some_library")
+       result = HttpMethod.my_thing()
+       assert ...
+   ```
+
+## Guidelines
+
+- **Don't add dependencies.** The core module has zero dependencies and must stay that way. The package has zero required dependencies; optional integrations use local imports.
+- **Keep the core minimal.** `typing_literalenum.py` is a standard library proposal. Only add features there if they belong in `typing_extensions`.
+- **Test what you add.** Every new method needs tests. Core features go in `test_typing_literalenum.py`, package features in `test_literalenum.py`.
+- **Avoid breaking changes to the metaclass protocol.** Existing LiteralEnum subclasses shouldn't break when upgrading.
+
+## Stub generation
+
+The `lestub` CLI generates `.pyi` stubs for LiteralEnum subclasses:
+
+```bash
+# From a dotted import
+lestub myapp.models
+
+# From a file
+lestub src/myapp/models.py
+
+# From a directory
+lestub src/myapp/
+
+# Write overlay stubs to a directory
+lestub myapp --out typings
+```
+
+If you change the public API surface of `LiteralEnumMeta`, update `_render_enum_blocks` in `stubgen.py` to match.
+
+## Reporting issues
+
+Open an issue at https://github.com/modularizer/LiteralEnum/issues.
+
+## License
+
+This project is released under [The Unlicense](LICENSE) (public domain). By contributing, you agree that your contributions are released under the same terms.

literalenum-0.4.0/PITCH.md

@@ -0,0 +1,32 @@
+# What if one object could be a namespace AND a typehint?
+
+```python
+# Wouldn't it be nice if this worked?
+from typing import LiteralEnum
+
+class HttpMethod(LiteralEnum):
+    GET = "GET"
+    POST = "POST"
+
+def handle(method: HttpMethod) -> None: ...  # when used as a typehint, HttpMethod would behave like Literal["GET", "POST"]
+
+# core
+handle("GET")                # type-checks: "GET" is a valid HttpMethod
+handle(HttpMethod.POST)      # type-checks: HttpMethod.POST is just "POST"
+handle("PATCH")              # type error: not a valid HttpMethod
+assert list(HttpMethod) == ["GET", "POST"]
+assert "GET" in HttpMethod   # runtime validation
+
+# NOTHING fancy, value is JUST the literal, not a subclass, not an instance of HttpMethod, not an instance of LiteralEnum, not modified in any way
+assert HttpMethod.GET == "GET" and type(HttpMethod.GET) is str and HttpMethod.GET.__class__.__bases__ == (object,)
+
+HttpMethod.validate(x)       # raises ValueError if invalid
+assert dict(HttpMethod.mapping) == {"GET": "GET", "POST": "POST"}
+assert HttpMethod.names_by_value[HttpMethod.POST] == "POST"
+```
+
+One definition. Plain raw literals at runtime. Exhaustive checking at type-check time. 
+
+- A realistic runtime version is available at `pip install literalenum` (but is not as good as advertised above)
+- Support in the [Python Community Discussion](https://discuss.python.org/t/proposal-literalenum-runtime-literals-with-static-exhaustiveness/106000/15) 
+  would be needed to have a shot at a PEP that could improve Python

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

@@ -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 → literalenum-0.4.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.4.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "literalenum"
-version = "0.2.0"
+version = "0.4.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.4.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.4.0}/src/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

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

@@ -250,6 +250,36 @@ class TestMappings:
         assert isinstance(HttpMethod.__members__, MappingProxyType)
         assert dict(HttpMethod.__members__) == dict(HttpMethod.mapping)
 
+    def test_name_mapping(self):
+        assert isinstance(HttpMethod.name_mapping, MappingProxyType)
+        assert dict(HttpMethod.name_mapping) == {
+            "GET": "GET", "POST": "POST", "DELETE": "DELETE",
+        }
+
+    def test_name_mapping_returns_canonical(self):
+        assert dict(WithAliases.name_mapping) == {"GET": "GET", "POST": "POST"}
+
+    def test_name_mapping_int(self):
+        assert dict(StatusCode.name_mapping) == {200: "OK", 404: "NOT_FOUND"}
+
+    def test_names_mapping(self):
+        assert isinstance(HttpMethod.names_mapping, MappingProxyType)
+        assert dict(HttpMethod.names_mapping) == {
+            "GET": ("GET",), "POST": ("POST",), "DELETE": ("DELETE",),
+        }
+
+    def test_names_mapping_with_aliases(self):
+        assert dict(WithAliases.names_mapping) == {
+            "GET": ("GET", "get"),
+            "POST": ("POST", "post"),
+        }
+
+    def test_name_mapping_empty(self):
+        assert dict(Empty.name_mapping) == {}
+
+    def test_names_mapping_empty(self):
+        assert dict(Empty.names_mapping) == {}
+
 
 # ===================================================================
 # Aliases
@@ -629,6 +659,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
 # ===================================================================