clsforge 0.1.0__py3-none-any.whl

clsforge/__init__.py

@@ -0,0 +1,17 @@
+__all__ = (
+    "__version__",
+    "ClsForgeError",
+    "FrozenClassError",
+    "InvalidChoiceError",
+    "FrozenClassMeta",
+    "EnumMixin",
+)
+
+from importlib import metadata
+
+__version__ = metadata.version(__name__)
+
+
+from clsforge.exceptions import ClsForgeError, FrozenClassError, InvalidChoiceError
+from clsforge.meta import FrozenClassMeta
+from clsforge.mixin import EnumMixin

clsforge/exceptions.py

@@ -0,0 +1,19 @@
+__all__ = ["ClsForgeError", "FrozenClassError", "InvalidChoiceError"]
+
+from collections.abc import Sequence
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+class ClsForgeError(Exception): ...
+
+
+class FrozenClassError(ClsForgeError, TypeError): ...
+
+
+class InvalidChoiceError(ClsForgeError, ValueError):
+    """Raised when a value is not one of the allowed choices."""
+
+    def __init__(self, value: T, choices: Sequence[T]) -> None:
+        super().__init__(f"invalid value {value!r}: expected one of {choices!r}")

clsforge/meta.py

@@ -0,0 +1,45 @@
+__all__ = ["FrozenClassMeta"]
+
+
+from clsforge import FrozenClassError
+
+
+class FrozenClassMeta(type):
+    """Metaclass for immutable class definitions.
+
+    Examples
+    --------
+    >>> class UserTable(metaclass=FrozenClassMeta):
+    ...     NAME = "users"
+    ...     PRIMARY_KEY = "id"
+    ...
+    >>> UserTable.NAME
+    'users'
+    >>> UserTable.PRIMARY_KEY
+    'id'
+    >>> UserTable.PRIMARY_KEY = "user_id"  # doctest: +SKIP
+    Traceback (most recent call last):
+        ...
+    FrozenClassError
+    """
+
+    def __call__(cls, *args, **kwargs):
+        raise FrozenClassError(
+            f"Cannot instantiate frozen class '{cls.__name__}'. "
+            f"Frozen classes are class-only definitions and do not support instances."
+        )
+
+    def __setattr__(cls, key, value):
+        raise FrozenClassError(
+            f"Cannot set field '{key}' to {value!r} on frozen class '{cls.__name__}'. "
+            f"Frozen classes are immutable after class creation."
+        )
+
+    def __delattr__(cls, key):
+        raise FrozenClassError(
+            f"Cannot delete field '{key}' from frozen class '{cls.__name__}'. "
+            f"Frozen classes are immutable after class creation."
+        )
+
+    def __new__(mcls, name, bases, namespace):
+        return super().__new__(mcls, name, bases, dict(namespace))

clsforge/mixin.py

@@ -0,0 +1,83 @@
+__all__ = ["EnumMixin"]
+
+from enum import Enum
+from typing import Any, cast
+
+
+class EnumMixin:
+    """Utility mixin for enum classes.
+
+    Examples
+    --------
+    >>> from enum import Enum
+    >>>
+    >>> class Color(EnumMixin, Enum):
+    ...     RED = "red"
+    ...     BLUE = "blue"
+    ...
+    >>> Color.get_count()
+    2
+    >>> Color.get_names()
+    ('RED', 'BLUE')
+    >>> Color.get_values()
+    ('red', 'blue')
+    >>> Color.get_member_by_name("RED")
+    <Color.RED: 'red'>
+    >>> Color.get_member_by_value("red")
+    <Color.RED: 'red'>
+    """
+
+    @classmethod
+    def get_members(cls) -> tuple[Enum, ...]:
+        """Return a tuple of all members."""
+        enum_cls = cast(type[Enum], cls)
+        return tuple(enum_cls)
+
+    @classmethod
+    def get_count(cls) -> int:
+        """Return the number of enum members."""
+        return len(cls.get_members())
+
+    @classmethod
+    def get_names(cls) -> tuple[str, ...]:
+        """Return a tuple of all member names."""
+        return tuple(member.name for member in cls.get_members())
+
+    @classmethod
+    def get_values(cls) -> tuple[Any, ...]:
+        """Return a tuple of all member values."""
+        return tuple(member.value for member in cls.get_members())
+
+    @classmethod
+    def get_member_by_name(cls, name: str, preview: int = 6) -> Enum:
+        """Return an enum member by its name."""
+        enum_cls = cast(type[Enum], cls)
+        try:
+            return enum_cls[name]
+        except KeyError as exc:
+            available = cls._format_preview(cls.get_names(), preview)
+            raise KeyError(
+                f"{cls.__qualname__} has no member named {name!r}. "
+                f"Available names ({cls.get_count()}): {available}"
+            ) from exc
+
+    @classmethod
+    def get_member_by_value(cls, value: Any, preview: int = 6) -> Enum:
+        """Return an enum member by its value."""
+        enum_cls = cast(type[Enum], cls)
+        try:
+            return enum_cls(value)
+        except ValueError as exc:
+            available = cls._format_preview(cls.get_values(), preview)
+            raise ValueError(
+                f"{cls.__qualname__} has no member with value {value!r}. "
+                f"Available values ({cls.get_count()}): {available}"
+            ) from exc
+
+    @staticmethod
+    def _format_preview(items: tuple[Any, ...], n: int) -> str:
+        """Return a formatted preview string of items, truncated after n items."""
+        preview = ", ".join(map(repr, items[:n]))
+        if len(items) > n:
+            preview += ", ..."
+        return preview

clsforge-0.1.0.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.3
+Name: clsforge
+Version: 0.1.0
+Summary: 
+Author: oyghen
+Author-email: oyghen <oyghen@duck.com>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# clsforge
+
+[![GitHub](https://img.shields.io/badge/github-code-blue?label=GitHub)](https://github.com/oyghen/clsforge)
+[![PyPI](https://img.shields.io/pypi/v/clsforge?label=PyPI)](https://pypi.org/project/clsforge)
+[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://github.com/oyghen/clsforge/blob/main/LICENSE)
+[![CI](https://github.com/oyghen/clsforge/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/oyghen/clsforge/actions/workflows/ci.yml)
+
+</div>
+
+```shell
+pip install clsforge
+```

clsforge-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+clsforge/__init__.py,sha256=Yyq7vDy94mF6q9SaCj5ikRLNOu1hq3BXIXRt7vJkwC0,383
+clsforge/exceptions.py,sha256=Dm1lrvDipIy9xfMpVX2HRjAqCQL02OoPxKEEtjpKQ0A,514
+clsforge/meta.py,sha256=Zz8NTND7J1CaQqbckjHa7RMOT6IDG_O65tOVyL5un5s,1316
+clsforge/mixin.py,sha256=IIhJriQTdBS46o8Uz3NccNXgPyf8EzgEAsbGpwfRJtI,2572
+clsforge/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clsforge-0.1.0.dist-info/WHEEL,sha256=iCTolw4aw2dP3yfM-EQCGTDsFCXL_ymmbYnBRVH7plA,81
+clsforge-0.1.0.dist-info/METADATA,sha256=S3_CU9jCLaWrt39I863VWTYFn9qViFb7GQZ1i9wR1Do,744
+clsforge-0.1.0.dist-info/RECORD,,

clsforge-0.1.0.dist-info/WHEEL

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