GitHub - svix/python-ksuid: A pure-Python KSUID implementation (original) (raw)

This library is inspired by Segment's KSUID implementation:https://github.com/segmentio/ksuid

For the Rust version, please check out https://github.com/svix/rust-ksuid

What is a ksuid?

A ksuid is a K sorted UID. In other words, a KSUID also stores a date component, so that ksuids can be approximately sorted based on the time they were created.

Usage

from ksuid import Ksuid

ksuid = Ksuid()

Higher timestamp accuracy mode

Ksuids have a 1 second accuracy which is not sufficient for all use-cases. That's why this library exposes a higher accuracy mode which supports accuracy of up to 4ms.

It's fully compatible with normal ksuids, in fact, it outputs valid ksuids. The difference is that it sacrifices one byte of the random payload in favor of this accuracy.

The code too is fully compatible:

from ksuid import KsuidMs

ksuid = KsuidMs()

Examples

Default ksuid

Generate a ksuid without passing a specific datetime

In [1]: from ksuid import Ksuid

In [2]: ksuid = Ksuid()

In [3]: f"Base62: {ksuid}" Out[3]: 'Base62: 1srOrx2ZWZBpBUvZwXKQmoEYga2'

In [4]: f"Bytes: {bytes(ksuid)}" Out[4]: "Bytes: b'\r5\xc43\xe1\x93>7\xf2up\x87c\xad\xc7tZ\xf5\xe7\xf2'"

In [5]: f"Datetime: {ksuid.datetime}" Out[5]: 'Datetime: 2021-05-21 14:04:03'

In [6]: f"Timestamp: {ksuid.timestamp}" Out[6]: 'Timestamp: 1621627443'

In [7]: f"Payload: {ksuid.payload}" Out[7]: "Payload: b'\xe1\x93>7\xf2up\x87c\xad\xc7tZ\xf5\xe7\xf2'"

ksuid from datetime

In [1]: datetime = datetime(year=2021, month=5, day=19, hour=1, minute=1, second=1, microsecond=1)

In [2]: datetime Out[2]: datetime.datetime(2021, 5, 19, 1, 1, 1, 1)

In [3]: ksuid = Ksuid(datetime)

In [4]: ksuid.datetime Out[4]: datetime.datetime(2021, 5, 19, 1, 1, 1)

In [5]: ksuid.timestamp Out[5]: 1621407661

ksuid from base62

In [1]: ksuid = Ksuid()

In [2]: ksuid.timestamp Out[2]: 1621634852

In [3]: f"Base62: {ksuid}" Out[3]: 'Base62: 1srdszO8Xy2cR6CnARnvxCfRmK4'

In [4]: ksuid_from_base62 = Ksuid.from_base62("1srdszO8Xy2cR6CnARnvxCfRmK4")

In [5]: ksuid_from_base62.timestamp Out[5]: 1621634852

ksuid from bytes

In [1]: ksuid = Ksuid()

In [2]: ksuid_from_bytes = ksuid.from_bytes(bytes(ksuid))

In [3]: f"ksuid: {ksuid}, ksuid_from_bytes: {ksuid_from_bytes}" Out[3]: 'ksuid: 1sreAHoz6myPhXghsOdVBoec3Vr, ksuid_from_bytes: 1sreAHoz6myPhXghsOdVBoec3Vr'

In [4]: ksuid == ksuid_from_bytes Out[4]: True

Compare ksuid(s)

In [1]: ksuid_1 = Ksuid()

In [2]: ksuid_2 = Ksuid.from_bytes(bytes(ksuid_1))

In [3]: f"ksuid_1: {ksuid_1}, ksuid_2: {ksuid_2}" Out[3]: 'ksuid_1: 1sreAHoz6myPhXghsOdVBoec3Vr, ksuid_2: 1sreAHoz6myPhXghsOdVBoec3Vr'

In [4]: ksuid_1 == ksuid_2 Out[4]: True

In [5]: ksuid_1 Out[5]: 1tM9eRSTrHIrrH5SMEW24rtvIOF

In [6]: ksuid_2 Out[6]: 1tM9eRSTrHIrrH5SMEW24rtvIOF

Order of ksuid(s)

In [1]: ksuid_1 = Ksuid()

In [2]: ksuid_1.timestamp Out[2]: 1621963256

In [3]: ksuid_2 = Ksuid()

In [4]: ksuid_2.timestamp Out[4]: 1621963266

In [5]: ksuid_1 < ksuid_2 Out[5]: True

In [6]: ksuid_1 <= ksuid_2 Out[6]: True

In [7]: ksuid_1 >= ksuid_2 Out[7]: False

In [8]: ksuid_1 > ksuid_2 Out[8]: False

License

ksuid source code is available under an MIT License.

Development

This application uses uv for virtualenv management by default.

To lint, use uv run scripts/lint.sh
To run tests, use uv run pytest

This repository also has pre-commit hooks set up using prek. They will be checked in CI, but if you'd like to run them locally you can use the prek tool.