Metadata-Version: 2.4
Name: philiprehberger-enum-tools
Version: 0.1.6
Summary: Practical utilities for Python enums — lookup, validation, listing, and serialization
Project-URL: Homepage, https://github.com/philiprehberger/py-enum-tools#readme
Project-URL: Repository, https://github.com/philiprehberger/py-enum-tools
Project-URL: Issues, https://github.com/philiprehberger/py-enum-tools/issues
Project-URL: Changelog, https://github.com/philiprehberger/py-enum-tools/blob/main/CHANGELOG.md
Author: Philip Rehberger
License-Expression: MIT
License-File: LICENSE
Keywords: choices,enum,lookup,serialize,utility,validation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# philiprehberger-enum-tools

[![Tests](https://github.com/philiprehberger/py-enum-tools/actions/workflows/publish.yml/badge.svg)](https://github.com/philiprehberger/py-enum-tools/actions/workflows/publish.yml)
[![PyPI version](https://img.shields.io/pypi/v/philiprehberger-enum-tools.svg)](https://pypi.org/project/philiprehberger-enum-tools/)
[![License](https://img.shields.io/github/license/philiprehberger/py-enum-tools)](LICENSE)

Practical utilities for Python enums — lookup, validation, listing, and serialization.

## Installation

```bash
pip install philiprehberger-enum-tools
```

## Usage

```python
from enum import Enum, auto
from philiprehberger_enum_tools import lookup, choices, values, names, validate

class Color(Enum):
    RED = "red"
    GREEN = "green"
    BLUE = "blue"
```

### Safe Lookup

```python
lookup(Color, "red")        # Color.RED
lookup(Color, "yellow")     # None
lookup(Color, "yellow", default=Color.RED)  # Color.RED
```

### Validation

```python
validate(Color, "red")      # Color.RED
validate(Color, "yellow")   # ValueError: 'yellow' is not a valid Color value. Valid values: 'red', 'green', 'blue'
```

### Listing

```python
values(Color)    # ['red', 'green', 'blue']
names(Color)     # ['RED', 'GREEN', 'BLUE']
choices(Color)   # [('red', 'RED'), ('green', 'GREEN'), ('blue', 'BLUE')]
```

### AutoEnum

Enum subclass where `auto()` generates lowercase member names as values.

```python
from philiprehberger_enum_tools import AutoEnum
from enum import auto

class Status(AutoEnum):
    ACTIVE = auto()
    INACTIVE = auto()
    PENDING = auto()

Status.ACTIVE.value   # 'active'
Status.PENDING.value  # 'pending'
```

### SerializableEnum

Enum that serializes to its value in JSON.

```python
import json
from philiprehberger_enum_tools import SerializableEnum, SerializableEncoder

class Priority(SerializableEnum):
    LOW = 1
    MEDIUM = 2
    HIGH = 3

json.dumps({"priority": Priority.HIGH}, cls=SerializableEncoder)
# '{"priority": 3}'
```

## API

| Function / Class | Description |
|---|---|
| `lookup(enum_class, value, *, default=None)` | Safe value-to-member lookup, returns default if not found |
| `choices(enum_class)` | List of (value, name) tuples for forms and CLIs |
| `values(enum_class)` | List of all member values |
| `names(enum_class)` | List of all member names |
| `validate(enum_class, value)` | Lookup or raise ValueError with valid options |
| `AutoEnum` | Enum subclass where auto() generates lowercase name as value |
| `SerializableEnum` | Enum that serializes to its value via SerializableEncoder |
| `SerializableEncoder` | JSON encoder supporting SerializableEnum members |


## Development

```bash
pip install -e .
python -m pytest tests/ -v
```

## License

MIT
