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
