Metadata-Version: 2.4
Name: pUUID
Version: 2.0.0
Summary: Prefixed UUIDs for Python with Pydantic & SQLAlchemy support.
Author: Jendrik Potyka, Fabian Preiss
Author-email: Jendrik Potyka <jpotyka@digon.io>, Fabian Preiss <fpreiss@digon.io>
License-Expression: LGPL-3.0-only
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Dist: pydantic>=2.12.5 ; extra == 'pydantic'
Requires-Dist: sqlalchemy>=2.0.45 ; extra == 'sqlalchemy'
Maintainer: Jendrik Potyka, Fabian Preiss
Maintainer-email: Jendrik Potyka <jpotyka@digon.io>, Fabian Preiss <fpreiss@digon.io>
Requires-Python: >=3.14
Provides-Extra: pydantic
Provides-Extra: sqlalchemy
Description-Content-Type: text/markdown

![Logo: pUUID - Prefixed UUIDs for Python](https://gitlab.com/DigonIO/puuid/-/raw/main/assets/logo_font_path.svg "pUUID Logo")

**pUUID** - Prefixed UUIDs for Python with **Pydantic** & **SQLAlchemy** support.

[![repository](https://img.shields.io/badge/src-GitLab-orange)](https://gitlab.com/DigonIO/puuid)
[![mirror](https://img.shields.io/badge/mirror-GitHub-orange)](https://github.com/DigonIO/puuid)
[![License: LGPLv3](https://gitlab.com/DigonIO/puuid/-/raw/main/assets/badges/license.svg)](https://spdx.org/licenses/LGPL-3.0-only.html)
[![pipeline status](https://gitlab.com/DigonIO/puuid/badges/main/pipeline.svg)](https://gitlab.com/DigonIO/puuid/-/pipelines)
[![coverage report](https://gitlab.com/DigonIO/puuid/badges/main/coverage.svg)](https://gitlab.com/DigonIO/puuid/-/pipelines)
[![Code style: black](https://gitlab.com/DigonIO/puuid/-/raw/main/assets/badges/black.svg)](https://github.com/psf/black)
[![Imports: isort](https://gitlab.com/DigonIO/puuid/-/raw/main/assets/badges/isort.svg)](https://pycqa.github.io/isort/)

[![pkgversion](https://img.shields.io/pypi/v/pUUID)](https://pypi.org/project/pUUID/)
[![versionsupport](https://img.shields.io/pypi/pyversions/pUUID)](https://pypi.org/project/pUUID/)
[![Downloads Week](https://pepy.tech/badge/puuid/week)](https://pepy.tech/project/puuid)
[![Downloads Total](https://pepy.tech/badge/puuid)](https://pepy.tech/project/puuid)

---

# pUUID - Prefixed UUIDs for Python

Raw UUIDs like `019b9a2e-9856-...` are annoying to work with. They provide no context in logs, traces or bug reports and offer no safe guards against accidental ID swapping in code. `pUUID` provides prefixed UUIDs for python with minimal overhead and strong type guarantees.

## Features

- **Human-Friendly:** Immediate context with prefixed UUIDs (e.g. `user_019b9a2e...`).
- **Strong type guarantees:** Prevent passing of a `CustomerID` into a `payment_id` field.
- **Standard Compliant:** Supports all UUID versions from [RFC 9562](https://www.rfc-editor.org/rfc/rfc9562.html).
- **Pydantic support.** [(Read more)](https://puuid.digon.io/quick_start/#pydantic-integration)
- **FastAPI support** (just use Pydantic as you want)
- **SQLAlchemy support.** [(Read more)](https://puuid.digon.io/quick_start/#sqlalchemy-integration)

## Installation

```bash
# NOTE: pUUID requires python 3.14+
pip install pUUID

# For Pydantic support:
pip install 'pUUID[pydantic]'

# For SQLAlchemy support:
pip install 'pUUID[sqlalchemy]'
```

## Usage

Define a domain-specific ID by inheriting from a versioned base:

```python
from typing import Literal
from puuid import PUUIDv7

class UserUUID(PUUIDv7[Literal["user"]]): ...

# Generation
uid = UserUUID.factory()
print(uid) # user_019b956e-ed25-70db-9d0a-0f30fb9047c2

# Deserialization
uid2 = UserUUID.from_string("user_019b956e-ed25-70db-9d0a-0f30fb9047c2")
```

## Resources

- [Online documentation](https://puuid.digon.io)
- [API Reference](https://puuid.digon.io/api_ref)
- [Changelog](https://puuid.digon.io/changelog)
- [Coverage Report](https://puuid.digon.io/coverage)
- [How to contribute](https://gitlab.com/DigonIO/puuid/-/blob/main/CONTRIBUTING.md)

## Alternatives

If you only need lexicographically sortable IDs and want to build the **SQLAlchemy** support yourself, these two projects might be for you:

- [**TypeID**](https://github.com/akhundMurad/typeid-python) - **pUUID** supports all **UUID** versions because it uses Python’s standard `uuid` library for **UUID** generation, while **TypeID** uses a custom generator that comes with performance improvements but only supports **UUIDv7**. **TypeID** does not support **SQLAlchemy** out of the box.
- [**UPID**](https://github.com/carderne/upid) - **UPID** implements a modified version of the **ULID** standard, which was designed before **UUIDv7** was available. **UPID** does not support **SQLAlchemy** out of the box.

## Sponsor

![Digon.IO GmbH Logo](https://gitlab.com/DigonIO/puuid/-/raw/main/assets/logo_digon.io_gmbh.png "Digon.IO GmbH")

Digon.IO provides dev & data end-to-end consulting for SMEs and software companies. [(Website)](https://digon.io) [(Technical Blog)](https://digon.io/en/blog)

*The sponsor logo is the property of Digon.IO GmbH. Standard trademark and copyright restrictions apply to any use outside this repository.*

## License

- **Library source code:** Licensed under [LGPLv3](https://spdx.org/licenses/LGPL-3.0-only.html).
