tagged-enum 1.0.0__py3-none-any.whl

tagged_enum/TaggedEnum.py

@@ -0,0 +1,262 @@
+from typing import (List, Type, Dict, ForwardRef, Self,
+                    Union, Any, get_origin, get_args, ClassVar)
+from types import UnionType, NoneType
+from enum import Enum, EnumMeta
+
+
+class TaggedEnumMeta(EnumMeta):
+    @property
+    def Kind(cls) -> Type[Self]:
+        return cls
+    
+    def __new__(mcls, name: str, bases, namespace: Dict[str, Any], **kw):
+        declared: Dict[str, Type[Any]] = {}
+        fresh = mcls.__prepare__(name, bases)
+        next_case = 0
+    
+        for k, v in namespace.items():
+            if k.startswith('_') or not k.isupper():
+                fresh[k] = v
+                continue
+
+            if (isinstance(v, type) 
+                or get_origin(v) is not None 
+                or isinstance(v, str)):
+                declared[k] = v
+                fresh[k] = next_case
+                next_case += 1
+            elif v is None:
+                declared[k] = NoneType
+                fresh[k] = next_case
+                next_case += 1
+            else:
+                fresh[k] = v
+
+        cls = super().__new__(mcls, name, bases, fresh, **kw)
+
+        def sanitize_type(
+            t: Type[Any] | ForwardRef | None
+        ) -> Type[Any] | str:
+            if t is None:
+                return NoneType
+            
+            # Keep self-references as strings instead of ForwardRefs
+            if isinstance(t, str) and t == name:
+                return name
+            
+            # Convert ForwardRefs back to strings if they reference self
+            if isinstance(t, ForwardRef):
+                forward_name = t.__forward_arg__
+                if forward_name == name:
+                    return name 
+                return forward_name
+            
+            # Handle regular strings (non-self references)
+            if isinstance(t, str):
+                return t  # Keep as string
+            
+            origin = get_origin(t)
+            if origin is not None:
+                args = get_args(t)
+                new_args = tuple(sanitize_type(arg) for arg in args)
+                
+                # Reconstruct the generic type
+                if isinstance(t, UnionType):
+                    return Union[*new_args]
+                else:
+                    # For generic types like List, Tuple, etc.
+                    return origin[new_args]
+            
+            # Regular types (int, str, custom classes, etc.)
+            return t
+        
+        sanitized_declared_types = {}
+        for member_name, t in declared.items():
+            sanitized_types = sanitize_type(t)
+            sanitized_declared_types[member_name] = sanitized_types
+
+        cls._declared_types = sanitized_declared_types
+        return cls
+
+
+class TaggedEnum(Enum, metaclass=TaggedEnumMeta):
+    """
+    Base class for tagged enums with payloads.
+
+    Each uppercase attribute will be considered an **enum case**.
+    Each case should be a Python type representing the payload type.
+    Collection types are allowed.
+
+    `None` denotes no payload.
+
+    ### Usage:
+    ```
+    class Message(TaggedEnum):
+        PING = None
+        STRING = str
+        COORDINATES = tuple[int, int]
+
+    ping_msg = Message.PING()
+    string_msg = Message.STRING("hello world")
+    coords_msg = Message.COORDINATES((1, -1))
+    ```
+        
+    `TaggedEnum`s can be unpacked using `match` statements:
+    ```
+    match message:
+        case Message(kind=Message.PING):
+            # handle ping
+        case Message(kind=Message.STRING, payload=string):
+            # handle string
+        case Message(kind=Message.COORDINATES, payload=(x, y)):
+            # handle coords (x, y)
+        case _:
+            raise ValueError
+    ```
+
+    The `.kind` property returns the static enum member (the "tag")
+    associated with an instance, allowing for simplified matching
+    when the payload is not required:
+    ```
+    if message.kind is Message.Kind.STRING:
+        print("This is a string message")
+
+    match message.kind:
+        case Message.Kind.PING:
+            ...
+        case Message.Kind.STRING:
+            ...
+    ```
+
+    ### Members vs. Instances
+    **Member**: the static class attribute (e.g., `Message.STRING`)
+    representing the variant's definition, referred to as its _kind_.
+
+    **Instance**: the object created by calling a member with a data payload
+    (e.g., `Message.STRING("hello")`). The instance holds a reference to the
+    concrete `payload` value.
+
+    The `Kind` type attribute serves as a type-level representation of all
+    available members. While an instance contains specific data, its `.kind`
+    property returns the member itself, allowing for
+    type-safe dispatching and matching without inspecting the underlying
+    payload.
+    """
+
+    Kind: ClassVar[type[Self]]
+
+    def __call__(self, *args, **kwargs) -> Self:
+        if not self.is_member:
+            raise TypeError
+        return self._construct(self, *args, **kwargs)
+
+    @classmethod
+    def _construct(cls: Type['TaggedEnum'], 
+                   member: 'TaggedEnum', 
+                   *args: List[Any]) -> 'TaggedEnum':
+        t: Type[Any] = cls._declared_types[member.name]
+        arg = args[0] if len(args) > 0 else None
+        
+        # Type check
+        if not cls._typecheck(arg, t):
+            raise TypeError(f"{member.name}: expected {t}, got {type(arg)}")
+        
+        # Create instance
+        inst = object.__new__(cls)
+        inst._member_ = member
+        inst._name_ = member.name
+        inst._value_ = member.value
+
+        inst._payload = arg
+        inst._kind = member
+
+        return inst
+
+    @classmethod
+    def make(cls, kind: int, payload: Any) -> 'TaggedEnum':
+        member = cls(kind)
+        return cls._construct(member, payload)
+
+    # Pattern matching support
+    __match_args__ = ("kind", "payload")
+
+    @classmethod
+    def _typecheck(cls, value: Any, typ: Any) -> bool:
+        # Handle string forward references - skip validation
+        if isinstance(typ, str):
+            return True
+        
+        origin = get_origin(typ)
+        args = get_args(typ)
+        
+        # Handle Union types (including | syntax)
+        if origin is Union or origin is UnionType:
+            return any(cls._typecheck(value, arg) for arg in args)
+        
+        # Handle Optional (which is Union[T, None])
+        if origin is Union and len(args) == 2 and type(None) in args:
+            non_none_type = args[0] if args[1] is type(None) else args[1]
+            return value is None or cls._typecheck(value, non_none_type)
+        
+        # Handle parameterized generics like list[int]
+        if origin is not None:
+            # Check the container type, skip checking type parameters for now
+            return isinstance(value, origin)
+        
+        # Handle regular types
+        if isinstance(typ, type):
+            return isinstance(value, typ)
+        
+        return True
+    
+    @classmethod
+    def payload_type(cls, kind: int) -> Type[Any]:
+        kind_name = cls._value2member_map_[kind].name
+        return cls._declared_types[kind_name]
+
+    """ Instance Methods """
+
+    @property
+    def kind(self) -> Self:
+        return self if self.is_member else self._kind
+
+    @property
+    def payload(self) -> Any:
+        return self._payload
+
+    @property
+    def is_member(self) -> bool:
+        return not hasattr(self, "_payload")
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, self.__class__):
+            return False
+        elif self.value is not other.value:
+            return False
+        elif self.is_member != other.is_member:
+            return False
+        elif not self.is_member:
+            return self.payload == other.payload
+        else:
+            return True
+
+    def __hash__(self) -> int:
+        if not self.is_member:
+            return hash((self.value, self.payload))
+        else:
+            return hash(self.value)
+
+    def __repr__(self):
+        if not self.is_member:
+            return f"{self.__class__.__name__}.{self.name}({self.payload!r})"
+        else:
+            return f"{self.__class__.__name__}.{self.name}"
+        
+    def __str__(self):
+        return repr(self)
+
+    # Ensure immutability
+    def __setattr__(self, key: str, value: Any):
+        if hasattr(self, key):
+            raise AttributeError("TaggedEnum instances are immutable")
+        super().__setattr__(key, value)

tagged_enum/__init__.py

@@ -0,0 +1,7 @@
+"""Tagged enums (sum types / algebraic data types) for Python, built on `enum.Enum`."""
+
+from .TaggedEnum import TaggedEnum, TaggedEnumMeta
+
+__all__ = ["TaggedEnum", "TaggedEnumMeta"]
+
+__version__ = "1.0.0"

tagged_enum-1.0.0.dist-info/METADATA

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: tagged-enum
+Version: 1.0.0
+Summary: Tagged enums for Python
+Project-URL: Homepage, https://github.com/rob-barker/tagged-enum
+Project-URL: Repository, https://github.com/rob-barker/tagged-enum
+Project-URL: Issues, https://github.com/rob-barker/tagged-enum/issues
+Author-email: Rob Barker <rob.barker.official@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: discriminated-union,enum,pattern-matching,tagged-enum,tagged-union
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# tagged-enum
+
+Tagged enums for Python 🐍. 
+
+Tagged enums (a.k.a. discriminated unions, enums with associated values, etc.)
+are enums where each case carries a typed **payload**. 
+
+```python
+from tagged_enum import TaggedEnum
+
+# Declare a tagged enum
+class Shape(TaggedEnum):
+    CIRCLE = float                   # radius
+    RECTANGLE = tuple[float, float]  # width, height
+    TRIANGLE = tuple[float, float]   # base, height
+
+def area(shape: Shape) -> float:
+    # match over enum cases
+    match shape:
+        case Shape(kind=Shape.CIRCLE, payload=radius):
+            return 3.14159 * radius ** 2
+        case Shape(kind=Shape.RECTANGLE, payload=(w, h)):
+            return w * h
+        case Shape(kind=Shape.TRIANGLE, payload=(b, h)):
+            return 0.5 * b * h
+
+shapes = [Shape.CIRCLE(2.0), 
+          Shape.RECTANGLE((3.0, 4.0)), 
+          Shape.TRIANGLE((6.0, 2.0))]
+
+[area(s) for s in shapes] # [12.57, 12.0, 6.0]
+```
+
+This is one of my favorite features from [Swift](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/enumerations/#Associated-Values) and [Rust](https://doc.rust-lang.org/rust-by-example/custom_types/enum.html) so I brought it to Python 😈.
+
+## ⬇ Installation
+
+```bash
+pip install tagged-enum
+```
+
+Requires Python 3.11+
+
+## 🤔 How to use
+
+Each uppercase attribute on a `TaggedEnum` subclass declares a *case*. The
+value assigned to it is the *type* of payload that case carries. `None`
+means the case carries nothing.
+
+```python
+class GameEvent(TaggedEnum):
+    PLAYER_JOINED = str             # player name
+    DAMAGE_DEALT = tuple[str, int]  # target, amount
+    GAME_OVER = None                # void
+```
+
+Calling a case constructs an **instance**, and the payload is checked against
+the declared type on instantiation.
+
+```python
+GameEvent.PLAYER_JOINED("Ada")            # 👍
+GameEvent.DAMAGE_DEALT(("Jeff", 42))      # 👍
+GameEvent.GAME_OVER()                     # 👍
+GameEvent.PLAYER_JOINED(-1)               # 👎 - TypeError
+```
+
+### 🧩 Typing
+
+Payload declarations may be plain types, generic containers, unions, custom types, or forward references to the enclosing class for recursive structures:
+
+```python
+class Json(TaggedEnum):
+    NULL = None
+    NUMBER = float
+    STRING = str
+    ARRAY = list["Json"]
+    OBJECT = dict[str, "Json"]
+    CUSTOM = MyDataclass
+
+Json.OBJECT({
+    "name": Json.STRING("Ada"),
+    "tags": Json.ARRAY([Json.STRING("math"), Json.NUMBER(1815.0)]),
+    "other": Json.CUSTOM(MyDataclass())
+})
+```
+
+`Union[...]` or `X | Y` and `Optional[...]` payloads are also valid types. Construction succeeds if the value matches any member of the union:
+
+```python
+class ID(TaggedEnum):
+    VALUE = int | str
+
+ID.VALUE(42)     # 👍
+ID.VALUE("abc")  # 👍
+ID.VALUE(4.2)    # 👎 - TypeError
+```
+
+Type checking validates the outer container (e.g. `list`, `dict`, which
+member of a `Union`) but does not recurse into generic type parameters, and
+skips validation entirely for unresolved forward references like `"Json"`
+above.
+
+### ✨ Pattern Matching
+
+Tagged enums are unpacked with Python's native [match statement](https://docs.python.org/3/tutorial/controlflow.html#match-statements) using the `kind`/`payload` attributes:
+
+```python
+def handle(event: GameEvent) -> str:
+    match event:
+        case GameEvent(kind=GameEvent.PLAYER_JOINED, payload=name):
+            return f"{name} joined the game"
+        case GameEvent(kind=GameEvent.DAMAGE_DEALT, payload=(target, amount)):
+            return f"{target} took {amount} damage"
+        case GameEvent(kind=GameEvent.GAME_OVER):
+            return "Game over"
+
+handle(GameEvent.DAMAGE_DEALT(("Grendel", 42)))
+# 'Grendel took 42 damage'
+```
+
+When you only care about which case you're looking at and not the payload, use `.kind` to return the tag itself (also called the **member**):
+
+```python
+if event.kind is GameEvent.Kind.PLAYER_JOINED:
+    print("player joined")
+
+match event.kind:
+    case GameEvent.Kind.PLAYER_JOINED:
+        ...
+    case GameEvent.Kind.GAME_OVER:
+        ...
+```
+
+`GameEvent.PLAYER_JOINED` (the **member**) and
+`GameEvent.PLAYER_JOINED(...)` (an **instance**) are different objects and ideas. The member is a singleton tag you compare with `is`, while the instance carries the actual data payload. Members and instances are not equal (by `==`). Instances of the same kind/case are equal if and only if their payload values are equal. 
+
+The `Kind` type attribute is a type-level alias for annotating variables that should hold a case rather than an instance.
+
+```python
+def describe(kind: GameEvent.Kind) -> str:
+    if kind is GameEvent.Kind.PLAYER_JOINED:
+        do_something()
+
+describe(event.kind) # 'damage was dealt'
+```
+
+## 🤓 Development
+
+This project uses [`uv`](https://docs.astral.sh/uv/) for dependency management.
+
+```bash
+uv sync
+uv run pytest
+```
+
+### Building
+
+Build the sdist/wheel into `dist/`:
+
+```bash
+uv build
+```
+
+To try the library locally without installing it anywhere:
+
+```bash
+# drop into a REPL
+uv run python
+# OR run a script inside the project's environment
+uv run python my_script.py
+```
+
+### 🧪 Testing 
+
+Tests live in `tests/`, split by topic (construction, equality/hashing,
+pattern matching, generic payloads, etc.) so a single area can be run in
+isolation, e.g.:
+
+```bash
+uv run pytest tests/test_generic_payloads.py
+```
+
+Without `uv`, the equivalent is:
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+## 🛠️ Contribution Guidelines
+
+This repository is open source, though maintenance is infrequent. Please be
+patient 🥺.
+
+- **File an issue first:** Anything beyond a small fix should be discussed in an issue
+  before you put work into a PR.
+- **Keep PRs focused:** One change or feature per PR, branched off `Development`
+  and rebased/updated before you submit.
+- **Branch naming:** `issues/<issue-number>`, optionally with a short
+  description, e.g. `issues/123-fix-a-bug`.
+- **Include a description and test coverage:** Explain what changed and
+  why, add or update tests under `tests/`, and reference the issue it
+  closes.
+
+Thanks for helping keep this repo clean and organized! 😁

tagged_enum-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+tagged_enum/TaggedEnum.py,sha256=O7nsHHT97aXu45HbDZFPMPecMG7QSycR3SPMqUek_pw,8653
+tagged_enum/__init__.py,sha256=FFPUU9Vapxvph7oWn1ix85072QQLJdGKMsf2zHCOVS4,214
+tagged_enum/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tagged_enum-1.0.0.dist-info/METADATA,sha256=mKBbJBf11_nh4R34jIIbpri-9nSnwxENZHBqfK-VVaE,7187
+tagged_enum-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+tagged_enum-1.0.0.dist-info/licenses/LICENSE,sha256=uIIPB9pZIhCeJFhlhTmp-L8g-8ubl3xOVMjbUX0ZAek,1091
+tagged_enum-1.0.0.dist-info/RECORD,,

tagged_enum-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

tagged_enum-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Barker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.