Metadata-Version: 2.4
Name: prettyid
Version: 0.3.3
Summary: Pretty cool IDs for your APIs
Keywords: 
Author: Alexander Pushkov
Author-email: Alexander Pushkov <alexander@notpushk.in>
License-Expression: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Requires-Dist: uuid-utils>=0.9.0,<0.10.0 ; python_full_version < '3.14'
Requires-Python: >=3.12
Project-URL: Repository, https://codeberg.org/prettyid/python.git
Project-URL: Bug Tracker, https://codeberg.org/prettyid/python/issues
Description-Content-Type: text/markdown

# PrettyId

Pretty cool IDs for your APIs.

```bash
poetry add prettyid
```

## Synopsis

Generate prefixed IDs, like Stripe does:

```python
>>> from pretty_id import PrettyId
>>> pid = PrettyId.random("task")
PrettyId("task_068n34jrjdth1fqr2nm9a0sh50")
>>> pid.type, pid.id
('task', '068n34jrjdth1fqr2nm9a0sh50')
>>> pid.bytes
b'...'
```

Backwards compatible with UUID:

```python
>>> pid = PrettyId.from_uuid("1d4e2ea4-c1ab-4a98-8eeb-898051ef0f71", type="task")
PrettyId("task_3n72x961nd59h3qbh6053vrfe4")
>>> pid.uuid
UUID('1d4e2ea4-c1ab-4a98-8eeb-898051ef0f71')
```

Works with Pydantic and FastAPI:

```python
@app.route("/tasks/{id}")
def get_task_by_id(id: FriendlyId):
    if id.type != "task":
        raise HTTPException(status_code=400, detail="ID should start with 'task_'")

    return {
        "id": id,
        "title": "TODO",
    }
```

And with SQLAlchemy:

```python
from pretty_id.ext.sqlalchemy import PrettyIdBinaryType

class TaskModel(Base):
    id: Mapped[PrettyId] = mapped_column(
        PrettyIdBinaryType("task"),
        index=True,
        unique=True,
        primary_key=True,
        default=partial(PrettyId.random, "task")
    )
    title: Mapped[str]

# Pass PrettyId instance or just string
select(TaskModel).filter(
    TaskModel.id == "task_068n34jrjdth1fqr2nm9a0sh50"
)
```


## Design

Generated IDs use UUIDv7 underneath:

```python
>>> u = UUID(bytes=pid.bytes)
UUID('01917192-7b9b-7b10-bf5b-15ec95039128')
>>> u.version
7
```

This means they inherit some useful properties:

- **Natural Sorting:** UUIDv7 values are time-sortable, which means you can sort them in increasing order based on when they were generated. Databases often require additional timestamp columns to sort records based on creation time. With PrettyId, you can achieve this sorting using the ID itself, eliminating the need for extra columns.

- **Optimized Indexing:** Since UUIDv7 is time-sortable, database indexing mechanisms can better optimize the storage and retrieval processes, leading to faster query times especially for time-based queries.

- **Concurrency and Distribution:** In distributed systems, generating unique, sequential IDs can be a challenge. UUIDv7 can be generated concurrently across multiple nodes without the risk of collisions, making it suitable for distributed architectures.

IDs are encoded as lowercase Base32 using [Douglas Crockford’s alphabet][crockford]. This makes them compact, readable, and case-insensitive.

[crockford]: https://www.crockford.com/base32.html

In database, IDs are stored without prefix using a native UUID type or `BINARY(16)`. (We assume that the prefix can be determined from the table name.)
