cyksuid

2.1.0 verified Mon Apr 27 auth: no python

A Cython-based implementation of KSUID (K-Sortable Unique IDentifier) for Python. Version 2.1.0 provides fast generation and parsing of KSUIDs with a focus on performance. Released under MIT license.

pip install cyksuid

Common errors

error ModuleNotFoundError: No module named 'cyksuid' ↓

cause Package not installed or installed in a different environment.

fix

Run 'pip install cyksuid' in your current environment.

error AttributeError: module 'cyksuid' has no attribute 'KSUID' ↓

cause Incorrect import path (e.g., from cyksuid.ksuid import KSUID).

fix

Use 'from cyksuid import KSUID'.

error OverflowError: Python int too large to convert to C long ↓

cause Attempting to create a KSUID with an out-of-range timestamp parameter (e.g., negative or > 2^32-1).

fix

Ensure timestamp parameter is a non-negative integer less than 2^32 (max 4294967295) or use default.

Warnings

breaking Version 2.x drops Python 2 support. Requires Python >=3.7. ↓

fix Upgrade Python to 3.7+ or pin cyksuid<2 if Python 2 is required.

gotcha KSUID objects are not JSON serializable by default. Use str(ksuid) or ksuid.string property. ↓

fix Convert to string before serializing: json.dumps({'id': str(ksuid)})

gotcha KSUID constructor with no arguments uses current UTC time. On very fast loops, identical timestamps produce unique payloads but may have identical seconds. ↓

fix If you need strictly monotonic order across sub-second calls, consider using a more sophisticated generation strategy.

Imports

KSUID
```
from cyksuid import KSUID
```

Quickstart

Generate and parse KSUIDs.

from cyksuid import KSUID

# Generate a new KSUID
ksuid = KSUID()
print(ksuid)           # e.g., 1srTbCFx8Z1V6gU3Zf8ZqT6aG8r
print(ksuid.timestamp) # datetime object
print(ksuid.payload)   # bytes payload

# Parse from string
try:
    parsed = KSUID.from_string('1srTbCFx8Z1V6gU3Zf8ZqT6aG8r')
    print(parsed)
except Exception as e:
    print('Invalid KSUID:', e)