enumplus 1.0.0__py3-none-any.whl

enumplus/__init__.py

@@ -0,0 +1,6 @@
+from enumplus.enum import Enum, OrderedEnum
+from enumplus.serialize import SerializableEncoder
+
+__version__ = "0.1.0"
+
+__all__ = ["Enum", "OrderedEnum", "SerializableEncoder", "__version__"]

enumplus/enum.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+import enum
+from typing import Any, cast
+
+try:
+    from typing import dataclass_transform
+except ImportError:
+    from typing_extensions import dataclass_transform
+
+_SENTINEL = object()
+
+
+@dataclass_transform()
+class EnumMeta(enum.EnumMeta):
+    """Base metaclass for enumplus enums."""
+
+    def __new__(
+        cls,
+        name: str,
+        bases: tuple[type, ...],
+        namespace: Any,
+        **kwargs: Any,
+    ) -> EnumMeta:
+        member_metadata: dict[str, dict[str, Any]] = {}
+
+        member_names: list[str] = list(getattr(namespace, "_member_names", []))
+        last_values: list[Any] = getattr(namespace, "_last_values", [])
+
+        for key, value in list(namespace.items()):
+            if isinstance(value, tuple) and len(value) == 2 and isinstance(value[1], dict):
+                actual_value, metadata = value
+                member_metadata[key] = metadata
+                if key in member_names:
+                    idx = member_names.index(key)
+                    last_values[idx] = actual_value
+                dict.__setitem__(namespace, key, actual_value)
+
+        new_cls = super().__new__(cls, name, bases, namespace, **kwargs)
+
+        members: list[Any] = list(new_cls)
+        for index, member in enumerate(members):
+            metadata = member_metadata.get(member.name, {})
+            member._metadata_ = metadata
+
+            label = metadata.get("label")
+            if not label:
+                member._label_ = member.name.title()
+            else:
+                member._label_ = label
+
+            member._index_ = index
+
+        return new_cls
+
+    def __contains__(cls, item: Any) -> bool:
+        if isinstance(item, cls):
+            return True
+        member: Any
+        for member in cls:
+            if member.value == item:
+                return True
+        return False
+
+
+class Enum(enum.Enum, metaclass=EnumMeta):
+    """Base enum class for enumplus."""
+
+    _label_: str
+    _metadata_: dict[str, Any]
+    _index_: int
+
+    @property
+    def label(self) -> str:
+        return self._label_
+
+    @property
+    def metadata(self) -> dict[str, Any]:
+        return self._metadata_
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        try:
+            return self._metadata_[name]
+        except KeyError:
+            raise AttributeError(
+                f"{type(self).__name__}.{self.name!s} has no attribute {name!r}"
+            ) from None
+
+    def __str__(self) -> str:
+        return self._label_
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__}.{self.name}: {self.value!r}>"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, enum.Enum):
+            return self is other
+        return bool(self.value == other)
+
+    def __hash__(self) -> int:
+        return hash(self.value)
+
+    @classmethod
+    def choices(cls) -> list[tuple[Any, str]]:
+        return [(member.value, member.label) for member in cls]
+
+    @classmethod
+    def from_value(cls, value: Any, default: Any = _SENTINEL) -> Enum:
+        member: Any
+        for member in cls:
+            if member.value == value:
+                return cast(Enum, member)
+        if default is not _SENTINEL:
+            return cast(Enum, default)
+        raise ValueError(f"{value!r} is not a valid {cls.__name__} value")
+
+    @classmethod
+    def from_name(cls, name: str, default: Any = _SENTINEL) -> Enum:
+        member = cls.__members__.get(name)
+        if member is not None:
+            return member
+        if default is not _SENTINEL:
+            return cast(Enum, default)
+        raise KeyError(f"{name!r} is not a valid {cls.__name__} name")
+
+    @classmethod
+    def is_valid(cls, value: Any) -> bool:
+        member: Any
+        for member in cls:
+            if member.value == value or member is value:
+                return True
+        return False
+
+    @classmethod
+    def validate(cls, value: Any) -> Enum:
+        return cls.from_value(value)
+
+    @classmethod
+    def values(cls) -> list[Any]:
+        return [member.value for member in cls]
+
+    @classmethod
+    def names(cls) -> list[str]:
+        return [member.name for member in cls]
+
+    @classmethod
+    def labels(cls) -> list[str]:
+        return [member.label for member in cls]
+
+    @classmethod
+    def filter(cls, **kwargs: Any) -> list[Enum]:
+        if not kwargs:
+            return list(cls)
+        result: list[Enum] = []
+        member: Any
+        for member in cls:
+            if all(
+                key in member._metadata_ and member._metadata_[key] == value
+                for key, value in kwargs.items()
+            ):
+                result.append(cast(Enum, member))
+        return result
+
+    @classmethod
+    def to_json(cls) -> str:
+        from enumplus.serialize import to_json
+
+        return to_json(cls)
+
+    @classmethod
+    def from_json(cls, data: str) -> dict[str, Any]:
+        from enumplus.serialize import from_json
+
+        return from_json(data)
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source_type: Any, handler: Any) -> Any:
+        from enumplus.pydantic import get_pydantic_core_schema
+
+        return get_pydantic_core_schema(cls, source_type, handler)
+
+
+class OrderedEnum(Enum):
+    """Enum mixin with ordering based on declaration order."""
+
+    def __lt__(self, other: OrderedEnum) -> bool:
+        if not isinstance(other, type(self)):
+            return NotImplemented
+        return self._index_ < other._index_
+
+    def __le__(self, other: OrderedEnum) -> bool:
+        if not isinstance(other, type(self)):
+            return NotImplemented
+        return self._index_ <= other._index_
+
+    def __gt__(self, other: OrderedEnum) -> bool:
+        if not isinstance(other, type(self)):
+            return NotImplemented
+        return self._index_ > other._index_
+
+    def __ge__(self, other: OrderedEnum) -> bool:
+        if not isinstance(other, type(self)):
+            return NotImplemented
+        return self._index_ >= other._index_

enumplus/pydantic.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from enumplus.enum import Enum
+
+if TYPE_CHECKING:
+    from pydantic import GetCoreSchemaHandler
+    from pydantic_core import CoreSchema
+
+
+def get_pydantic_core_schema(
+    cls: type[Enum], source_type: Any, handler: GetCoreSchemaHandler
+) -> CoreSchema:
+    from pydantic_core import core_schema
+
+    def validate(value: Any) -> Any:
+        if isinstance(value, cls):
+            return value
+        return cls.from_value(value)
+
+    return core_schema.no_info_after_validator_function(
+        validate,
+        core_schema.any_schema(),
+        serialization=core_schema.plain_serializer_function_ser_schema(
+            lambda v: v.value,
+            return_schema=core_schema.any_schema(),
+        ),
+    )

enumplus/serialize.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import json
+from typing import Any, cast
+
+from enumplus.enum import Enum
+
+
+def to_json(cls: type[Enum]) -> str:
+    data: dict[str, Any] = {
+        "name": cls.__name__,
+        "members": [
+            {
+                "name": member.name,
+                "value": member.value,
+                "label": member.label,
+                "metadata": member._metadata_,
+            }
+            for member in cls
+        ],
+    }
+    return json.dumps(data, ensure_ascii=False, indent=2)
+
+
+def from_json(data: str) -> dict[str, Any]:
+    try:
+        return cast(dict[str, Any], json.loads(data))
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Invalid JSON: {e}") from None
+
+
+class SerializableEncoder(json.JSONEncoder):
+    def default(self, obj: Any) -> Any:
+        from enumplus.enum import Enum
+
+        if isinstance(obj, Enum):
+            return obj.value
+        return super().default(obj)

enumplus-1.0.0.dist-info/METADATA

@@ -0,0 +1,300 @@
+Metadata-Version: 2.5
+Name: enumplus
+Version: 1.0.0
+Summary: Enhanced Python enums with metadata, serialization, and choices
+Author-email: Mathias Paulenko <mathias.paulenko@outlook.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: choices,enum,enumeration,metadata,serialization
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pydantic; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: typing-extensions; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# enumplus — Enhanced Enums for Python
+
+![PyPI](https://img.shields.io/pypi/v/enumplus)
+![Python](https://img.shields.io/badge/python-3.11+-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Tests](https://img.shields.io/badge/tests-116%20passing-brightgreen)
+
+## Why
+
+Python's `enum.Enum` is basic. `enumplus` adds display names, metadata, JSON serialization, `choices()`, and value-based comparison — all with zero dependencies and full stdlib compatibility. Just change your import and everything still works.
+
+## Installation
+
+```bash
+pip install enumplus
+```
+
+## Quick Start
+
+```python
+from enumplus import Enum
+
+class Color(Enum):
+    RED = ("red", {"label": "Red", "hex": "#FF0000"})
+    GREEN = ("green", {"label": "Green", "hex": "#00FF00"})
+    BLUE = "blue"  # no metadata needed
+
+# Display names
+print(Color.RED.label)          # "Red"
+print(str(Color.RED))           # "Red"
+
+# Metadata access
+print(Color.RED.hex)            # "#FF0000"
+print(Color.RED.metadata)       # {"label": "Red", "hex": "#FF0000"}
+
+# choices() for forms/dropdowns
+print(Color.choices())          # [("red", "Red"), ("green", "Green"), ("blue", "Blue")]
+
+# Lookup by value
+print(Color.from_value("red"))  # Color.RED
+
+# Compare with values directly
+print(Color.RED == "red")       # True
+
+# Membership test
+print("red" in Color)           # True
+```
+
+## Features
+
+### Display Names (label)
+
+Every member gets a human-readable label, auto-generated from the member name or set explicitly via metadata.
+
+```python
+class Status(Enum):
+    PENDING = "pending"                              # label: "Pending"
+    IN_PROGRESS = ("in_progress", {"label": "In Progress"})
+
+print(Status.PENDING.label)       # "Pending"
+print(Status.IN_PROGRESS.label)   # "In Progress"
+print(str(Status.IN_PROGRESS))    # "In Progress"
+```
+
+### Metadata
+
+Attach arbitrary metadata to enum members using `(value, dict)` tuples. Access via attribute or the `metadata` property.
+
+```python
+class Color(Enum):
+    RED = ("red", {"hex": "#FF0000", "description": "Pure red"})
+
+print(Color.RED.hex)           # "#FF0000"
+print(Color.RED.description)   # "Pure red"
+print(Color.RED.metadata)      # {"hex": "#FF0000", "description": "Pure red"}
+```
+
+### choices()
+
+Returns a list of `(value, label)` tuples — perfect for forms and dropdowns.
+
+```python
+class Priority(Enum):
+    LOW = 1
+    MEDIUM = 2
+    HIGH = 3
+
+print(Priority.choices())   # [(1, "Low"), (2, "Medium"), (3, "High")]
+```
+
+### from_value() / from_name()
+
+Look up members by value or name, with optional defaults.
+
+```python
+class Color(Enum):
+    RED = "red"
+    GREEN = "green"
+
+Color.from_value("red")              # Color.RED
+Color.from_value("blue")             # raises ValueError
+Color.from_value("blue", default=None)  # None
+
+Color.from_name("RED")               # Color.RED
+Color.from_name("BLUE", default=None)   # None
+```
+
+### is_valid() / validate()
+
+Check if a value is valid, or validate and raise.
+
+```python
+class Color(Enum):
+    RED = "red"
+
+Color.is_valid("red")       # True
+Color.is_valid("blue")      # False
+Color.is_valid(Color.RED)   # True
+
+Color.validate("red")       # Color.RED
+Color.validate("blue")      # raises ValueError
+```
+
+### values() / names() / labels()
+
+Get lists of all values, names, or labels.
+
+```python
+class Color(Enum):
+    RED = ("red", {"label": "Red"})
+    GREEN = ("green", {"label": "Green"})
+
+Color.values()   # ["red", "green"]
+Color.names()    # ["RED", "GREEN"]
+Color.labels()   # ["Red", "Green"]
+```
+
+### filter()
+
+Filter members by metadata key-value pairs (AND logic).
+
+```python
+class Color(Enum):
+    RED = ("red", {"hex": "#FF0000", "category": "warm"})
+    GREEN = ("green", {"hex": "#00FF00", "category": "cool"})
+
+Color.filter(category="warm")              # [Color.RED]
+Color.filter(hex="#FF0000", category="warm")  # [Color.RED]
+Color.filter()                             # [Color.RED, Color.GREEN]
+```
+
+### Comparison with values (==)
+
+Members compare equal to their values directly.
+
+```python
+class Color(Enum):
+    RED = "red"
+
+Color.RED == "red"          # True
+Color.RED == Color.RED      # True
+Color.RED == "RED"          # False (name != value)
+Color.RED != 42             # True
+```
+
+### Membership test (in)
+
+Check if a value or member belongs to an enum.
+
+```python
+class Color(Enum):
+    RED = "red"
+
+"red" in Color          # True
+"blue" not in Color     # True
+Color.RED in Color      # True
+42 not in Color         # True
+```
+
+### OrderedEnum
+
+Order members by declaration order using `<`, `<=`, `>`, `>=`.
+
+```python
+from enumplus import OrderedEnum
+
+class Priority(OrderedEnum):
+    LOW = 1
+    MEDIUM = 2
+    HIGH = 3
+
+Priority.LOW < Priority.HIGH    # True
+Priority.HIGH > Priority.LOW    # True
+sorted([Priority.HIGH, Priority.LOW, Priority.MEDIUM])  # [LOW, MEDIUM, HIGH]
+min(Priority)   # Priority.LOW
+max(Priority)   # Priority.HIGH
+```
+
+### JSON Serialization (to_json / from_json)
+
+Serialize an enum class to JSON and parse it back.
+
+```python
+class Color(Enum):
+    RED = ("red", {"hex": "#FF0000"})
+
+json_str = Color.to_json()
+# {
+#   "name": "Color",
+#   "members": [
+#     {"name": "RED", "value": "red", "label": "Red", "metadata": {"hex": "#FF0000"}}
+#   ]
+# }
+
+data = Color.from_json(json_str)   # parse back to dict
+```
+
+### SerializableEncoder
+
+Serialize enum members to their values in JSON via a custom encoder.
+
+```python
+import json
+from enumplus import Enum, SerializableEncoder
+
+class Color(Enum):
+    RED = "red"
+
+json.dumps(Color.RED, cls=SerializableEncoder)           # '"red"'
+json.dumps([Color.RED], cls=SerializableEncoder)         # '["red"]'
+json.dumps({"color": Color.RED}, cls=SerializableEncoder)  # '{"color": "red"}'
+```
+
+### Pydantic v2
+
+`enumplus` works with Pydantic v2 out of the box. Members validate from values and serialize to values.
+
+```python
+from pydantic import BaseModel
+from enumplus import Enum
+
+class Color(Enum):
+    RED = "red"
+    GREEN = "green"
+
+class MyModel(BaseModel):
+    color: Color
+
+model = MyModel(color="red")     # validates "red" -> Color.RED
+print(model.color)               # Color.RED
+print(model.model_dump())        # {"color": "red"}
+print(model.model_dump_json())   # '{"color":"red"}'
+```
+
+### Type hints in metadata
+
+The `@dataclass_transform()` decorator on the metaclass enables type checkers to recognize metadata fields.
+
+```python
+class Color(Enum):
+    RED = ("red", {"hex": "#FF0000"})
+
+# Type checkers recognize .hex as a valid attribute
+reveal_type(Color.RED.hex)  # str
+```
+
+## Migration from stdlib
+
+Just change one import:
+
+```python
+# Before
+from enum import Enum
+
+# After
+from enumplus import Enum
+```
+
+All existing enum code continues to work — `Enum["RED"]`, `Enum("red")`, `list(Enum)`, `len(Enum)`, `@unique`, `auto()`, `isinstance` checks, everything.
+
+## License
+
+MIT

enumplus-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+enumplus/__init__.py,sha256=E-sfSE4vS4wUpc6jjCS2mq-DqVrVzMzKql7U6O0V-vo,191
+enumplus/enum.py,sha256=EEusNqwxj0_SIsTDXirMolPfGmF1rEKOSSSyZZyam9I,6072
+enumplus/pydantic.py,sha256=6SNeR7HRwv434IiaD3mVPrVDV2AoG1vVnYeHhL3E2FA,789
+enumplus/serialize.py,sha256=u3jqLZKVYqEGkLIf3xwdrlJP2_pUc1e7VMQxsOLEWYc,953
+enumplus-1.0.0.dist-info/METADATA,sha256=Jy4YsVUPfuvg08CfN1b2npBuGxozvJcsEZ0QKLxqmK0,7379
+enumplus-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+enumplus-1.0.0.dist-info/licenses/LICENSE,sha256=2avxMtQSuO0Ok5IE7aIJP5luiqV6eIKG35wu3NI-rEM,1073
+enumplus-1.0.0.dist-info/RECORD,,

enumplus-1.0.0.dist-info/WHEEL

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

enumplus-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mathias Paulenko
+
+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.