ulid-py

library1.1.0pypypi✓ verified 29d ago

The `ulid-py` library (version 1.1.0) provides a minimal, self-contained Python 3 implementation of the Universally Unique Lexicographically Sortable Identifier (ULID) specification. It aims for a lightweight implementation without external dependencies. The project is currently in maintenance mode, with its last release in March 2022.

serialization

pip install ulid-py

github ↗package ↗

INSTALL

IMPORT

SIG · ULID-PY

ulid-py

serializationpythonv1.1.0

Install

1.5s avg

Import

34ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.038s · 18MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.030s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

new

✓ import ulid ulid.new()

✗ from ulid import ULID; ULID()

The `ahawker/ulid` library primarily uses `ulid.new()` for generating new ULIDs, unlike other ULID implementations that might use `ULID()` directly.

from_timestamp

✓ import ulid ulid.from_timestamp(some_datetime_obj)

Used to create a ULID from a datetime or timestamp value.

from_uuid

✓ import ulid ulid.from_uuid(some_uuid_obj)

Used to create a ULID from a UUID object.

Demonstrates generating new ULIDs, creating them from existing timestamps, and accessing their components and other representations.

import ulid import datetime # Create a brand new ULID u = ulid.new() print(f"New ULID: {u}") print(f"String representation: {str(u)}") # Create a new ULID from an existing datetime object dt = datetime.datetime(1999, 1, 1, tzinfo=datetime.timezone.utc) u_from_dt = ulid.from_timestamp(dt) print(f"ULID from datetime: {u_from_dt}") # Access timestamp and randomness parts print(f"Timestamp part: {u.timestamp()}") print(f"Randomness part: {u.randomness()}") # Convert to UUID import uuid uuid_val = u.to_uuid() print(f"As UUID: {uuid_val}")

Debug

Known issues

breakingPython 2 support was dropped in version 1.0.0. This library (v1.1.0) requires Python 3.5 or newer.

fix

Ensure your project runs on Python 3.5+.

affects: >=1.0.0

gotchaPotential confusion with other Python ULID libraries. While this entry is for `ulid-py` (ahawker's implementation), there are other popular and more actively maintained libraries like `python-ulid` (mdomke's implementation) with different APIs (e.g., `ULID()` constructor vs. `ulid.new()`).

fix

Always check the specific documentation for the `ulid` package you have installed and verify the GitHub repository or PyPI page to ensure you are using the intended library.

affects: All versions

gotchaAPI differences for accessing ULID components. In `ulid-py` (ahawker), `timestamp()` and `randomness()` are methods. In some other ULID libraries, these might be properties (e.g., `ulid.timestamp`).

fix

Use `ulid_instance.timestamp()` and `ulid_instance.randomness()` to access these components in `ulid-py`.

affects: All versions

gotchaSecurity considerations when using ULIDs. Although `ulid-py` does not explicitly implement monotonic incrementing of the random component for same-millisecond generation by default (based on available documentation for this specific library), the timestamp component of ULIDs can still expose creation times. For applications requiring strong unpredictability (e.g., password reset tokens), a cryptographically secure random identifier might be more appropriate.

fix

Do not use ULIDs where cryptographic randomness is a strict requirement for security. Consider adding an additional layer of cryptographic randomness or using a UUIDv4/other cryptographically secure identifier.

affects: All versions

Errors

Common errors & fixes

AttributeError: module 'ulid' has no attribute 'new'

The `new` function for creating ULIDs is part of the `ulid.api` submodule, not directly exposed at the top-level `ulid` package when doing a simple `import ulid`.

fix

Import the `new` function explicitly from `ulid.api` or use the `ULID()` constructor from the main `ulid` package.

```python
# Fix 1: Import new function directly
from ulid.api import new
ulid_obj = new()

# Fix 2: Use the ULID constructor
from ulid import ULID
ulid_obj = ULID()
```

TypeError: ULID() takes 0 or 2 positional arguments but 1 was given

This error occurs when attempting to parse a ULID string by passing it directly to the `ULID` class constructor, which expects either no arguments or specific `timestamp` and `entropy` arguments, not a string for parsing.

fix

To parse a ULID string into a `ULID` object, use the `ULID.from_str()` class method instead of the constructor.

```python
from ulid import ULID

# Correct way to parse a ULID string
ulid_string = "01ARZ3RCK538M5064X1J0YSBPK"
ulid_obj = ULID.from_str(ulid_string)
print(ulid_obj)
```

ValueError: Invalid ULID string.

This error is raised when `ULID.from_str()` or `ulid.api.parse()` attempts to convert a string that does not conform to the ULID specification (e.g., incorrect length, invalid characters, or invalid Crockford base32 encoding).

fix

Ensure the input string is a valid 26-character ULID string in Crockford Base32 encoding. Validate the source of the ULID string.

```python
from ulid import ULID

# Correct: A valid ULID string
valid_ulid_string = "01GS81E0F1T2Q3M4N5P6R7S8T9"
parsed_ulid = ULID.from_str(valid_ulid_string)
print(parsed_ulid)

# Incorrect example (would raise the ValueError)
# invalid_ulid_string = "not-a-ulid"
# parsed_ulid = ULID.from_str(invalid_ulid_string)
```

ModuleNotFoundError: No module named 'ulid'

The `ulid-py` library, or specifically the `ulid` package it provides, is not installed in your current Python environment.

fix

Install the `ulid-py` package using pip.

```bash
pip install ulid-py
```

After installation, you should be able to import the module:
```python
import ulid
from ulid import ULID
```

Upgrade

Version history

1.1.0latest on PyPI · released Sep 15, 2020

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ahawker/ulid ↗

packagehttps://pypi.org/project/ulid-py/ ↗