Metadata-Version: 2.4
Name: larzuuid
Version: 0.1.0
Summary: Modern sortable IDs in pure Python: UUIDv7, ULID, and nanoid. Time-ordered, index-friendly. Zero dependencies.
Author: larz-scripter
License: MIT
Project-URL: Homepage, https://github.com/larz-scripter/larzuuid
Project-URL: Repository, https://github.com/larz-scripter/larzuuid
Project-URL: Issues, https://github.com/larz-scripter/larzuuid/issues
Keywords: uuid,uuid7,ulid,nanoid,id-generation,sortable-id,unique-id,identifiers,time-ordered,zero-dependency
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# larzuuid

**Modern, sortable IDs — UUIDv7, ULID, nanoid. Pure Python, zero dependencies.**

Random UUIDv4s are unguessable but scatter across a database index, hurting insert
performance and locality. **Time-ordered** ids fix that: they sort by creation
time, cluster in the index, and let you read the timestamp back out. The stdlib
`uuid` module has none of these — larzuuid adds the three you actually want.

```python
from larzuuid import uuid7, ulid, nanoid

uuid7()     # 018f5e...-7...  a real UUID, but time-sortable
ulid()      # 01HZY3K5...     26-char Crockford base32, sortable
nanoid()    # V1StGXR8_Z5jdHi6B-myT   compact, URL-safe
```

## Why

- **UUIDv7** (RFC 9562) — a standard `uuid.UUID`, but the first 48 bits are a
  millisecond timestamp, so it sorts by time and works as a great primary key.
  Read the time back with `uuid7_timestamp()`.
- **ULID** — 26 lexicographically-sortable Crockford-base32 chars; `MonotonicULID`
  guarantees strictly increasing ids even within the same millisecond.
- **nanoid** — a compact, URL-safe random id (21 chars by default), uniform via
  rejection sampling, with a custom alphabet option.
- **Zero dependencies.** No `ulid-py`, no `nanoid`, no `uuid6`.

## Install

```bash
pip install larzuuid
```

## Usage

```python
from larzuuid import uuid7, uuid7_timestamp, ulid, ulid_timestamp, MonotonicULID, nanoid

pk = uuid7()                       # use as a DB key; sorts by creation time
uuid7_timestamp(pk)                # datetime (UTC)

u = ulid(); ulid_timestamp(u)
gen = MonotonicULID(); gen.new(); gen.new()   # strictly increasing

nanoid()          # 21 chars
nanoid(10, alphabet="0123456789abcdef")
```

## Tests

```bash
python -m unittest discover -s tests -v   # 13 tests
```

## The Larz stack

One of 30+ pure-Python, zero-dependency libraries at
[github.com/larz-scripter](https://github.com/larz-scripter).

## License

MIT © larz-scripter
