vcti-enum 1.0.3__tar.gz

vcti_enum-1.0.3/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2018-2026 Visual Collaboration Technologies Inc.
+All Rights Reserved.
+
+This software is proprietary and confidential. Unauthorized copying,
+distribution, or use of this software, via any medium, is strictly
+prohibited. Access is granted only to authorized VCollab developers
+and individuals explicitly authorized by Visual Collaboration
+Technologies Inc.

vcti_enum-1.0.3/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: vcti-enum
+Version: 1.0.3
+Summary: Value-generated string enums with automatic naming conventions for Python
+Author: Visual Collaboration Technologies Inc.
+Requires-Python: <3.15,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pydantic; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Dynamic: license-file
+
+# Enum Framework
+
+## Purpose
+
+Python's `StrEnum` requires manually writing string values for each member.
+When enums follow a naming convention (lowercase, camelCase, PascalCase, etc.),
+the values are predictable from the member names. The `vcti-enum` package
+provides base classes that auto-generate member values from naming conventions,
+plus an `EnumCoder` for flexible serialization and Pydantic integration helpers.
+
+This package has **zero external dependencies**.
+
+---
+
+## Installation
+
+```bash
+pip install vcti-enum
+```
+
+### In `requirements.txt`
+
+```
+vcti-enum>=1.0.3
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-enum>=1.0.3",
+]
+```
+
+---
+
+## Quick Start
+
+### Value-generated enums
+
+```python
+from vcti.enum import EnumValueLowerCase, auto_enum_value
+
+class FileFormat(EnumValueLowerCase):
+    JSON = auto_enum_value()    # value: "json"
+    CSV = auto_enum_value()     # value: "csv"
+    PARQUET = auto_enum_value() # value: "parquet"
+
+FileFormat.JSON.value  # "json"
+FileFormat.JSON == "json"  # True (StrEnum)
+```
+
+### EnumCoder for serialization
+
+```python
+from enum import Enum
+from vcti.enum import EnumCoder
+
+class Color(Enum):
+    RED = 1
+    GREEN = 2
+
+coder = EnumCoder(Color, value_generator=lambda e: e.name.lower(), default=Color.RED)
+
+coder.encode(Color.RED)    # "red"
+coder.decode("green")      # Color.GREEN
+coder.default              # "red"
+coder.list                 # ["red", "green"]
+```
+
+### Pydantic integration
+
+```python
+from pydantic import BaseModel, Field
+from vcti.enum import EnumValueLowerCase, auto_enum_value, enum_for_pydantic
+
+@enum_for_pydantic(default="JSON")
+class FileFormat(EnumValueLowerCase):
+    JSON = auto_enum_value()
+    CSV = auto_enum_value()
+
+class Config(BaseModel):
+    format: FileFormat = Field(default=FileFormat.DEFAULT_VALUE)
+
+Config().format  # "json"
+```
+
+---
+
+## Enum Base Classes
+
+| Class | Convention | `FIRST_VALUE` becomes |
+|-------|-----------|----------------------|
+| `EnumValueSameAsName` | Unchanged | `FIRST_VALUE` |
+| `EnumValueLowerCase` | lower_case | `first_value` |
+| `EnumValueCamelCase` | camelCase | `firstValue` |
+| `EnumValuePascalCase` | PascalCase | `FirstValue` |
+| `EnumValueCapitalizedPhrase` | Title Case | `First Value` |
+| `EnumValueSpaceSeparatedLower` | space lower | `first value` |
+
+All classes extend `StrEnum` -- members are string instances.
+
+---
+
+## Public API
+
+| Symbol | Import | Purpose |
+|--------|--------|---------|
+| `auto_enum_value()` | `vcti.enum` | Triggers automatic value generation |
+| `create_enum_class()` | `vcti.enum` | Factory to create custom enum base classes |
+| `EnumValueSameAsName` | `vcti.enum` | Base class: value = member name |
+| `EnumValueLowerCase` | `vcti.enum` | Base class: value = lowercase |
+| `EnumValueCamelCase` | `vcti.enum` | Base class: value = camelCase |
+| `EnumValuePascalCase` | `vcti.enum` | Base class: value = PascalCase |
+| `EnumValueCapitalizedPhrase` | `vcti.enum` | Base class: value = Title Case |
+| `EnumValueSpaceSeparatedLower` | `vcti.enum` | Base class: value = space separated |
+| `EnumCoder` | `vcti.enum` | Flexible enum serialization/deserialization |
+| `setup_enum_for_pydantic()` | `vcti.enum` | Attach coder attributes to enum class |
+| `enum_for_pydantic()` | `vcti.enum` | Decorator version of setup |
+| `get_enum_field_description()` | `vcti.enum` | Generate Pydantic Field description |
+
+---
+
+## Documentation
+
+- [Design](docs/design.md) -- Concepts, factory pattern, and architecture decisions
+- [Source Guide](docs/source-guide.md) -- File descriptions and execution flow traces
+- [Extension Guide](docs/extending.md) -- How to add new enum base classes
+- [API Reference](docs/api.md) -- Autodoc for all modules

vcti_enum-1.0.3/README.md

@@ -0,0 +1,129 @@
+# Enum Framework
+
+## Purpose
+
+Python's `StrEnum` requires manually writing string values for each member.
+When enums follow a naming convention (lowercase, camelCase, PascalCase, etc.),
+the values are predictable from the member names. The `vcti-enum` package
+provides base classes that auto-generate member values from naming conventions,
+plus an `EnumCoder` for flexible serialization and Pydantic integration helpers.
+
+This package has **zero external dependencies**.
+
+---
+
+## Installation
+
+```bash
+pip install vcti-enum
+```
+
+### In `requirements.txt`
+
+```
+vcti-enum>=1.0.3
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-enum>=1.0.3",
+]
+```
+
+---
+
+## Quick Start
+
+### Value-generated enums
+
+```python
+from vcti.enum import EnumValueLowerCase, auto_enum_value
+
+class FileFormat(EnumValueLowerCase):
+    JSON = auto_enum_value()    # value: "json"
+    CSV = auto_enum_value()     # value: "csv"
+    PARQUET = auto_enum_value() # value: "parquet"
+
+FileFormat.JSON.value  # "json"
+FileFormat.JSON == "json"  # True (StrEnum)
+```
+
+### EnumCoder for serialization
+
+```python
+from enum import Enum
+from vcti.enum import EnumCoder
+
+class Color(Enum):
+    RED = 1
+    GREEN = 2
+
+coder = EnumCoder(Color, value_generator=lambda e: e.name.lower(), default=Color.RED)
+
+coder.encode(Color.RED)    # "red"
+coder.decode("green")      # Color.GREEN
+coder.default              # "red"
+coder.list                 # ["red", "green"]
+```
+
+### Pydantic integration
+
+```python
+from pydantic import BaseModel, Field
+from vcti.enum import EnumValueLowerCase, auto_enum_value, enum_for_pydantic
+
+@enum_for_pydantic(default="JSON")
+class FileFormat(EnumValueLowerCase):
+    JSON = auto_enum_value()
+    CSV = auto_enum_value()
+
+class Config(BaseModel):
+    format: FileFormat = Field(default=FileFormat.DEFAULT_VALUE)
+
+Config().format  # "json"
+```
+
+---
+
+## Enum Base Classes
+
+| Class | Convention | `FIRST_VALUE` becomes |
+|-------|-----------|----------------------|
+| `EnumValueSameAsName` | Unchanged | `FIRST_VALUE` |
+| `EnumValueLowerCase` | lower_case | `first_value` |
+| `EnumValueCamelCase` | camelCase | `firstValue` |
+| `EnumValuePascalCase` | PascalCase | `FirstValue` |
+| `EnumValueCapitalizedPhrase` | Title Case | `First Value` |
+| `EnumValueSpaceSeparatedLower` | space lower | `first value` |
+
+All classes extend `StrEnum` -- members are string instances.
+
+---
+
+## Public API
+
+| Symbol | Import | Purpose |
+|--------|--------|---------|
+| `auto_enum_value()` | `vcti.enum` | Triggers automatic value generation |
+| `create_enum_class()` | `vcti.enum` | Factory to create custom enum base classes |
+| `EnumValueSameAsName` | `vcti.enum` | Base class: value = member name |
+| `EnumValueLowerCase` | `vcti.enum` | Base class: value = lowercase |
+| `EnumValueCamelCase` | `vcti.enum` | Base class: value = camelCase |
+| `EnumValuePascalCase` | `vcti.enum` | Base class: value = PascalCase |
+| `EnumValueCapitalizedPhrase` | `vcti.enum` | Base class: value = Title Case |
+| `EnumValueSpaceSeparatedLower` | `vcti.enum` | Base class: value = space separated |
+| `EnumCoder` | `vcti.enum` | Flexible enum serialization/deserialization |
+| `setup_enum_for_pydantic()` | `vcti.enum` | Attach coder attributes to enum class |
+| `enum_for_pydantic()` | `vcti.enum` | Decorator version of setup |
+| `get_enum_field_description()` | `vcti.enum` | Generate Pydantic Field description |
+
+---
+
+## Documentation
+
+- [Design](docs/design.md) -- Concepts, factory pattern, and architecture decisions
+- [Source Guide](docs/source-guide.md) -- File descriptions and execution flow traces
+- [Extension Guide](docs/extending.md) -- How to add new enum base classes
+- [API Reference](docs/api.md) -- Autodoc for all modules

vcti_enum-1.0.3/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vcti-enum"
+version = "1.0.3"
+description = "Value-generated string enums with automatic naming conventions for Python"
+readme = "README.md"
+authors = [
+    {name = "Visual Collaboration Technologies Inc."}
+]
+requires-python = ">=3.12,<3.15"
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-cov", "pydantic"]
+lint = ["ruff"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["vcti.enum", "vcti.enum.*"]
+
+[tool.pytest.ini_options]
+addopts = "--cov=vcti.enum --cov-report=term-missing --cov-fail-under=95 --strict-markers"
+
+[tool.setuptools]
+zip-safe = true
+
+[tool.ruff]
+target-version = "py312"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP"]

vcti_enum-1.0.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vcti_enum-1.0.3/src/vcti/enum/__init__.py

@@ -0,0 +1,40 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""vcti.enum package."""
+
+from importlib.metadata import version
+
+from .enum_coder import EnumCoder
+from .enum_pydantic_helpers import (
+    enum_for_pydantic,
+    get_enum_field_description,
+    setup_enum_for_pydantic,
+)
+from .value_generated_enums import (
+    EnumValueCamelCase,
+    EnumValueCapitalizedPhrase,
+    EnumValueLowerCase,
+    EnumValuePascalCase,
+    EnumValueSameAsName,
+    EnumValueSpaceSeparatedLower,
+    auto_enum_value,
+    create_enum_class,
+)
+
+__version__ = version("vcti-enum")
+
+__all__ = [
+    "__version__",
+    "auto_enum_value",
+    "create_enum_class",
+    "EnumValueSameAsName",
+    "EnumValueLowerCase",
+    "EnumValueCamelCase",
+    "EnumValuePascalCase",
+    "EnumValueCapitalizedPhrase",
+    "EnumValueSpaceSeparatedLower",
+    "EnumCoder",
+    "setup_enum_for_pydantic",
+    "enum_for_pydantic",
+    "get_enum_field_description",
+]

vcti_enum-1.0.3/src/vcti/enum/enum_coder.py

@@ -0,0 +1,157 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Enhanced Enum utilities for flexible serialization with configurable string mappings."""
+
+from collections.abc import Callable
+from enum import Enum
+from typing import Any
+
+
+class EnumCoder[E: Enum]:
+    """
+    Provides flexible serialization/deserialization for Enums with configurable string mappings.
+
+    Example:
+        class Color(Enum):
+            RED = 1
+            GREEN = 2
+
+        # Create serializer with lowercase mapping
+        color_coder = EnumCoder(
+            Color,
+            value_generator=lambda enum_var: enum_var.name.lower(),
+            default=Color.RED
+        )
+
+        # Serialize/Encode
+        color_coder.encode(Color.RED)  # "red"
+
+        # Deserialize/Decode
+        color_coder.decode("green")  # Color.GREEN
+    """
+
+    def __init__(
+        self,
+        enum_class: type[E],
+        value_generator: Callable[[E], str] = lambda enum_var: enum_var.name,
+        default: E | None = None,
+    ):
+        """
+        Initialize the serializer.
+
+        Args:
+            enum_class: The Enum class to serialize
+            value_generator: Function that converts enums to string values
+            default: Default enum value for this serializer
+        """
+        self.enum_class: type[E] = enum_class
+        self.value_generator: Callable[[E], str] = value_generator
+
+        # Generate mappings
+        self._enum_to_string: dict[E, str] = {
+            member: value_generator(member) for member in enum_class
+        }
+        self._string_to_enum: dict[str, E] = {v: k for k, v in self._enum_to_string.items()}
+
+        # Detect collisions in the reverse mapping
+        if len(self._string_to_enum) != len(self._enum_to_string):
+            from collections import Counter
+
+            counts = Counter(self._enum_to_string.values())
+            duplicates = {v for v, c in counts.items() if c > 1}
+            raise ValueError(f"value_generator produced duplicate string values: {duplicates}")
+
+        # Pre-compute stringified default
+        self._default = self._enum_to_string.get(default) if default is not None else None
+
+    def __repr__(self) -> str:
+        default_part = f", default={self._default!r}" if self._default is not None else ""
+        return f"EnumCoder({self.enum_class.__name__}{default_part})"
+
+    @property
+    def default(self) -> str | None:
+        """The string representation of the default enum value (None if no default set)."""
+        return self._default
+
+    @property
+    def tuple(self) -> tuple[str, ...]:
+        """All possible string values for this enum."""
+        return tuple(self._enum_to_string.values())
+
+    @property
+    def list(self) -> list[str]:
+        """List of all possible string values."""
+        return list(self.tuple)
+
+    @property
+    def Literal(self) -> Any:
+        """
+        Literal type containing all possible string values.
+
+        Note: This creates a Literal type dynamically at runtime for use in type annotations.
+        Due to Python's type system limitations, the return type is Any.
+
+        Example:
+            LogLevelStr = LogLevelCoder.Literal  # Get the Literal type
+            my_level: LogLevelStr = "info"  # Type-checked value
+        """
+        from typing import Literal
+
+        return Literal[*self.tuple]  # type: ignore
+
+    def encode(self, enum_value: E) -> str:
+        """Convert enum to its string representation.
+
+        Args:
+            enum_value: The enum member to encode.
+
+        Returns:
+            String representation of the enum value.
+
+        Raises:
+            ValueError: If enum_value is not a member of the configured enum class.
+        """
+        try:
+            return self._enum_to_string[enum_value]
+        except KeyError:
+            raise ValueError(
+                f"'{enum_value}' is not a member of {self.enum_class.__name__}. "
+                f"Valid members: {tuple(m.name for m in self.enum_class)}"
+            ) from None
+
+    def decode(self, string_value: str) -> E:
+        """Convert string back to enum value.
+
+        Args:
+            string_value: The string to decode into an enum member.
+
+        Returns:
+            The enum member corresponding to string_value.
+
+        Raises:
+            ValueError: If string_value doesn't match any enum value.
+        """
+        try:
+            return self._string_to_enum[string_value]
+        except KeyError:
+            raise ValueError(
+                f"'{string_value}' is not a valid representation. Valid values: {self.tuple}"
+            ) from None
+
+    def get_mapping_info(self) -> dict[str, Any]:
+        """Get complete mapping information as a dictionary.
+
+        Returns:
+            Dictionary with keys: enum_class, values, default, mapping.
+        """
+        return {
+            "enum_class": self.enum_class.__name__,
+            "values": self.tuple,
+            "default": self.default,
+            "mapping": {e.name: self.encode(e) for e in self.enum_class},
+        }
+
+
+__all__ = [
+    "EnumCoder",
+]

vcti_enum-1.0.3/src/vcti/enum/enum_pydantic_helpers.py

@@ -0,0 +1,180 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Pydantic integration helpers for EnumCoder.
+
+This module provides utilities to seamlessly integrate EnumCoder with Pydantic models,
+making it easy to use enums with custom string representations.
+
+Example:
+    >>> from vcti.enum import EnumValueLowerCase, auto_enum_value, setup_enum_for_pydantic
+    >>>
+    >>> class FileFormat(EnumValueLowerCase):
+    ...     JSON = auto_enum_value()
+    ...     CSV = auto_enum_value()
+    >>>
+    >>> # Setup for Pydantic usage
+    >>> setup_enum_for_pydantic(
+    ...     FileFormat,
+    ...     value_generator=lambda e: e.value,
+    ...     default_member='JSON'
+    ... )
+    >>>
+    >>> # Now you can use in Pydantic:
+    >>> class MyModel(BaseModel):
+    ...     format: FileFormat.LITERAL = Field(default=FileFormat.DEFAULT_VALUE)
+"""
+
+from collections.abc import Callable
+from enum import Enum
+from typing import Any
+
+from .enum_coder import EnumCoder
+
+
+def setup_enum_for_pydantic[E: Enum](
+    enum_class: type[E],
+    value_generator: Callable[[E], str] | None = None,
+    default_member: str | None = None,
+) -> EnumCoder[E]:
+    """Setup an enum class for use in Pydantic models.
+
+    This function creates an EnumCoder and attaches it and its properties
+    to the enum class, making it easy to use in Pydantic Field definitions.
+
+    Adds these attributes to the enum class:
+    - CODER: The EnumCoder instance
+    - DEFAULT_VALUE: Default string value
+    - LIST: List of all string values
+    - TUPLE: Tuple of all string values
+    - LITERAL: Literal type of all values
+
+    Args:
+        enum_class: The enum class to setup
+        value_generator: Function to convert enum to string (default: uses enum.value)
+        default_member: Name of enum member to use as default
+
+    Returns:
+        The EnumCoder instance (also attached to enum_class.CODER)
+
+    Example:
+        >>> class Status(EnumValueLowerCase):
+        ...     PENDING = auto_enum_value()
+        ...     ACTIVE = auto_enum_value()
+        >>>
+        >>> setup_enum_for_pydantic(Status, default_member='PENDING')
+        >>>
+        >>> # Now available:
+        >>> Status.DEFAULT_VALUE  # 'pending'
+        >>> Status.LIST           # ['pending', 'active']
+        >>> Status.CODER.encode(Status.ACTIVE)  # 'active'
+    """
+    # Default value generator: use the enum's value
+    if value_generator is None:
+
+        def _default_value_generator(e):
+            return e.value
+
+        value_generator = _default_value_generator
+
+    # Determine default enum member
+    default_enum = None
+    if default_member:
+        default_enum = getattr(enum_class, default_member)
+    else:
+        # Use first member as default
+        default_enum = next(iter(enum_class))
+
+    # Create the coder
+    coder = EnumCoder(enum_class, value_generator=value_generator, default=default_enum)
+
+    # Attach coder and properties to enum class
+    setattr(enum_class, "CODER", coder)
+    setattr(enum_class, "DEFAULT_VALUE", coder.default)
+    setattr(enum_class, "LIST", coder.list)
+    setattr(enum_class, "TUPLE", coder.tuple)
+    setattr(enum_class, "LITERAL", coder.Literal)
+
+    return coder
+
+
+def enum_for_pydantic[E: Enum](
+    default: str | None = None, value_generator: Callable[[Any], str] | None = None
+) -> Callable[[type[E]], type[E]]:
+    """Decorator version of setup_enum_for_pydantic.
+
+    Args:
+        default: Name of default enum member
+        value_generator: Function to convert enum to string
+
+    Returns:
+        Decorator function
+
+    Example:
+        >>> @enum_for_pydantic(default='JSON')
+        ... class FileFormat(EnumValueLowerCase):
+        ...     JSON = auto_enum_value()
+        ...     CSV = auto_enum_value()
+        >>>
+        >>> FileFormat.DEFAULT_VALUE  # 'json'
+    """
+
+    def decorator(enum_class: type[E]) -> type[E]:
+        setup_enum_for_pydantic(
+            enum_class, value_generator=value_generator, default_member=default
+        )
+        return enum_class
+
+    return decorator
+
+
+def get_enum_field_description(enum_class: type[Enum], include_default: bool = True) -> str:
+    """Generate a description string for a Pydantic Field using this enum.
+
+    Args:
+        enum_class: The enum class (must have LIST and DEFAULT_VALUE attributes)
+        include_default: Whether to include default value in description
+
+    Returns:
+        Description string suitable for Pydantic Field
+
+    Example::
+
+        from pydantic import BaseModel, Field
+        from vcti.enum import (
+            EnumValueLowerCase, auto_enum_value,
+            enum_for_pydantic, get_enum_field_description,
+        )
+
+        @enum_for_pydantic(default='JSON')
+        class FileFormat(EnumValueLowerCase):
+            JSON = auto_enum_value()
+            CSV = auto_enum_value()
+
+        get_enum_field_description(FileFormat)
+        # 'Supported values: (json/csv). Default: json'
+
+        get_enum_field_description(FileFormat, include_default=False)
+        # 'Supported values: (json/csv)'
+
+        # Use in a Pydantic model Field:
+        class ExportConfig(BaseModel):
+            format: FileFormat = Field(
+                default=FileFormat.DEFAULT_VALUE,
+                description=get_enum_field_description(FileFormat),
+            )
+    """
+    enum_list = getattr(enum_class, "LIST", [member.value for member in enum_class])
+    values_str = "/".join(str(v) for v in enum_list)
+
+    if include_default and hasattr(enum_class, "DEFAULT_VALUE"):
+        default_value = getattr(enum_class, "DEFAULT_VALUE")
+        return f"Supported values: ({values_str}). Default: {default_value}"
+    else:
+        return f"Supported values: ({values_str})"
+
+
+__all__ = [
+    "setup_enum_for_pydantic",
+    "enum_for_pydantic",
+    "get_enum_field_description",
+]