Metadata-Version: 2.5
Name: ulidx
Version: 0.0.1
Summary: ULID generation and conversion: sortable, monotonic, thread-safe.
Project-URL: Homepage, https://github.com/lqxnjk/ulidx
Project-URL: Source, https://github.com/lqxnjk/ulidx
Author: lqxnjk
License: MIT
License-File: LICENSE
Keywords: id,identifier,monotonic,sortable,ulid,uuid
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# ulidx

ULID generation and conversion. A ULID is a 128-bit identifier that is both
**lexicographically sortable by creation time** and **random enough to be used
as a primary key** — 26 characters in Crockford base32, no hyphens.

## Install

```console
pip install ulidx
```

## Usage

```python
from ulidx import Ulid

# plain generation
Ulid.generate()                       # '01J8Z9K2M3N4P5Q6R7S8T9V0WX'

# guaranteed strictly increasing within a process, even in the same millisecond
Ulid.generate(n_monotonic=True)

# pin the timestamp (aware or naive datetime, or epoch seconds)
Ulid.generate(n_timestamp=1700000000)

# bulk
Ulid.generate_batch(1000)

# back and forth
value = Ulid.generate()
Ulid.to_timestamp(value)              # float, epoch seconds
Ulid.to_time(value)                   # datetime in UTC+8
Ulid.to_bytes(value)                  # 16 raw bytes
Ulid.by_bytes(Ulid.to_bytes(value))   # round trip
Ulid.to_uuid(value)                   # uuid.UUID
Ulid.from_uuid(some_uuid)             # 26-char str
```

## API

| Method | Description |
| --- | --- |
| `generate(ts=None, monotonic=False)` | New 26-character ULID |
| `generate_batch(count, ...)` | List of ULIDs |
| `generate_uuid(ts=None, ...)` | New ULID as `uuid.UUID` |
| `by_bytes(data)` | 16 bytes to ULID string |
| `to_bytes(ulid)` | ULID (str / bytes / UUID) to 16 bytes |
| `to_timestamp(ulid)` | Epoch seconds encoded in the ULID |
| `to_time(ulid, hour_offset=8)` | `datetime` in the given UTC offset |
| `to_uuid(ulid)` / `from_uuid(uuid)` | Convert between ULID and `uuid.UUID` |

## Monotonicity

`n_monotonic=True` keeps the generator state per thread, so concurrent threads
never share a counter. Within a thread, ULIDs produced in the same millisecond
strictly increase, which keeps sorting stable when several IDs are created in
one tick.

## License

MIT
