Metadata-Version: 2.4
Name: qiu-python-encore
Version: 0.1.0
Summary: Small enhancements of the Python standard library, e.g. enums comparing equal to their values.
Keywords: enum,standard library,utilities
Author: Siavash Davani
Author-email: Siavash Davani <siavash.davani@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Maintainer: Siavash Davani
Maintainer-email: Siavash Davani <siavash.davani@gmail.com>
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/BlackWild/qiu/tree/master/packages/qiu-python-encore
Project-URL: Documentation, https://blackwild.github.io/qiu/qiu-python-encore/
Project-URL: Repository, https://github.com/BlackWild/qiu
Project-URL: Issues, https://github.com/BlackWild/qiu/issues
Project-URL: Changelog, https://github.com/BlackWild/qiu/blob/master/packages/qiu-python-encore/CHANGELOG.md
Description-Content-Type: text/markdown

# Python Encore

[![PyPI](https://img.shields.io/pypi/v/qiu-python-encore)](https://pypi.org/project/qiu-python-encore/) [![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://www.python.org/) [![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/BlackWild/qiu/blob/master/LICENSE) [![CI](https://github.com/BlackWild/qiu/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/BlackWild/qiu/actions/workflows/ci.yml) [![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://blackwild.github.io/qiu/qiu-python-encore/)

Small enhancements of the Python standard library, used across this monorepo. It has no dependencies.

## Installation

```sh
pip install qiu-python-encore
```

## `qiu_python_encore.enum.ExtendedEnum`

An `Enum` whose members also compare equal to their raw values, so that code can accept either a member or its value, e.g. from a configuration file or a `hypothesis` strategy:

```python
from qiu_python_encore.enum import ExtendedEnum


class Color(ExtendedEnum):
    RED = "red"
    GREEN = "green"


assert Color.RED == "red"
assert Color("red") is Color.RED  # normalize raw values to members
assert Color.list() == ["red", "green"]  # the raw values, in definition order
assert {Color.RED: 1}["red"] == 1  # members hash like their values
```

Compared to a standard `Enum`:

- A member equals its raw value (`Color.RED == "red"`), but not its name (`Color.RED != "RED"`).
- A member equals a member of any other `Enum` with the same value.
- Members hash like their raw values, consistently with the equality above, so they can be used in sets, as dict keys and with `functools.cache`.
- `list()` returns the raw values of the members.

## Documentation

The documentation, with the API reference from the docstrings, is built from `docs/` with MkDocs and published at <https://blackwild.github.io/qiu/qiu-python-encore/>. To serve it locally, from the repository root:

```sh
uv run mkdocs serve -f packages/qiu-python-encore/mkdocs.yml
```

## Tests

From the repository root:

```sh
uv run pytest packages/qiu-python-encore
```
