literalenum 0.3.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.3.0 → literalenum-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: literalenum
-Version: 0.3.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

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

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "literalenum"
-version = "0.3.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.3.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(

{literalenum-0.3.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