clsforge 0.1.0__tar.gz

clsforge-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,14 @@
+<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/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "clsforge"
+version = "0.1.0"
+description = ""
+readme = "README.md"
+authors = [
+    { name = "oyghen", email = "oyghen@duck.com" }
+]
+requires-python = ">=3.11"
+dependencies = []
+
+[build-system]
+requires = ["uv_build>=0.11.9,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.6.0",
+    "pytest>=9.0.3",
+    "ruff>=0.15.12",
+]

clsforge-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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