ULID-transform

2.2.0 · active · verified Wed Apr 15

ULID-transform is a high-performance Python library designed for creating and transforming ULIDs (Universally Unique Lexicographically Sortable Identifiers). It provides efficient generation of ULIDs and seamless conversion between ULIDs and UUIDs. The library is currently at version 2.2.0 and maintains an active release cadence, frequently incorporating performance enhancements and bug fixes.

Warnings

breaking Version 2.0.0 introduced a significant change in the minimum Python requirement, now mandating Python 3.11 or newer. Prior versions (e.g., 1.x) supported Python 3.8+. This release also involved a complete internal rewrite from Cython to a hand-written C extension for performance, which, while largely maintaining the public API, could introduce subtle behavioral changes.
Fix: Ensure your project is running on Python 3.11 or later before upgrading to `ulid-transform` v2.0.0 or higher. Thoroughly test existing ULID-related logic after upgrading.
gotcha Starting with version 2.1.0, the library replaced the MT19937 random number generator with SplitMix64 for entropy. This optimization improves performance but means that ULIDs generated in sequential calls will produce a different sequence compared to prior versions, even under identical seeding (if applicable). For applications that depend on bit-for-bit deterministic ULID generation across versions (e.g., for specific testing scenarios), this change is relevant.
Fix: Be aware that ULID sequences may differ when upgrading from versions prior to 2.1.0. This is generally not an issue for typical use cases but could affect very specific testing or cryptographic-like scenarios.

Install

pip install ulid-transform Install latest version

Imports

generate_ulid

from ulid_transform import generate_ulid

ulid_to_uuid
```
from ulid_transform import ulid_to_uuid
```
uuid_to_ulid
wrong:
```
from ulid import uuid_to_ulid
```
correct:
```
from ulid_transform import uuid_to_ulid
```
Commonly confused with other 'ulid' libraries; ensure import from 'ulid_transform'.

Quickstart

This quickstart demonstrates how to generate a new ULID and perform conversions between ULID strings and UUID objects using the core functions of the `ulid-transform` library.

import uuid
from ulid_transform import generate_ulid, ulid_to_uuid, uuid_to_ulid

# Generate a new ULID
new_ulid = generate_ulid()
print(f"Generated ULID: {new_ulid}")

# Convert a ULID string to a UUID object
some_ulid_str = "01ARZ3NDEKTSV4RRFFQ69G5FAV"
converted_uuid = ulid_to_uuid(some_ulid_str)
print(f"ULID '{some_ulid_str}' converted to UUID: {converted_uuid}")

# Convert a UUID object (or string) to a ULID string
some_uuid_obj = uuid.uuid4()
converted_ulid = uuid_to_ulid(str(some_uuid_obj))
print(f"UUID '{some_uuid_obj}' converted to ULID: {converted_ulid}")

view raw JSON →