pksuid

library1.1.2pypypi✓ verified 93d ago

PKSUID is a Python library for generating Prefixed K-Sortable Unique IDentifiers. It extends the KSUID specification by allowing an arbitrary string prefix of up to 16 bytes, similar to Stripe's prefixed IDs, which helps developers quickly identify the resource type an identifier refers to. The library is currently at version 1.1.2 and has a stable release cadence.

serialization

pip install pksuid

github ↗package ↗

INSTALL

IMPORT

SIG · PKSUID

pksuid

serializationpythonv1.1.2

Install

1.6s avg

Import

8ms

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.2 · 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.920 runs

installs and imports cleanly · install 0.0s · import 0.003s · 17.8MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.6s · import 0.002s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

PKSUID

✓ from pksuid import PKSUID

This example demonstrates how to generate a new PKSUID with a specified prefix, extract its components like prefix, timestamp, and datetime, and parse a PKSUID from its string or byte representation.

from pksuid import PKSUID # Generate a new unique identifier with the prefix 'usr' uid = PKSUID('usr') print(f"Generated PKSUID: {uid}") # Access components print(f"Prefix: {uid.get_prefix()}") print(f"Timestamp (KSUID epoch): {uid.get_timestamp()}") print(f"Datetime (UTC): {uid.get_datetime()}") print(f"Payload: {uid.get_payload()}") # Convert from a string representation back to PKSUID uid_from_string = PKSUID.parse('usr_24OnhzwMpa4sh0NQmTmICTYuFaD') print(f"Parsed PKSUID: {uid_from_string}") print(f"Parsed Datetime (UTC): {uid_from_string.get_datetime()}") # Conversion to and parsing from bytes is also possible uid_as_bytes = uid.bytes() uid_from_bytes = PKSUID.parse_bytes(uid_as_bytes) print(f"Parsed from bytes: {uid_from_bytes}")

Debug

Known issues

gotchaPKSUID prefixes are limited to a maximum of 16 bytes. Providing a prefix longer than this will result in a `ValueError` during object instantiation.

fix

Ensure your prefix string is 16 bytes or less in length. Use `len(prefix.encode('utf-8'))` to check the byte length if your prefix contains multi-byte characters.

affects: >=1.0.0

gotchaThe `PKSUID.get_timestamp()` method returns the KSUID's internal 32-bit timestamp component, which is relative to a custom KSUID epoch (e.g., May 13th, 2014 for original KSUID specification), not the standard Unix epoch (January 1st, 1970). If you need a standard Unix timestamp or a Python `datetime` object, use `PKSUID.get_datetime()` instead.

fix

For standard epoch timestamps or `datetime` objects, use `uid.get_datetime()` which returns a `datetime.datetime` object in UTC. To convert to a standard Unix timestamp from the `datetime` object, use `int(uid.get_datetime().timestamp())`.

affects: >=1.0.0

gotchaPKSUID objects are immutable once created. Any method that appears to 'modify' a KSUID (e.g., parsing) will return a new `PKSUID` instance rather than altering the existing one. Do not expect in-place modifications.

fix

Always assign the result of methods like `PKSUID.parse()` or `PKSUID.parse_bytes()` to a new variable or overwrite the existing one, as they return new `PKSUID` instances.

affects: >=1.0.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pksuid'

The 'pksuid' package is not installed in your current Python environment.

fix

Run `pip install pksuid` to install the library.

ValueError: Prefix length must be between 0 and 16 bytes

The prefix string provided when creating a `PKSUID` object exceeds the maximum allowed length of 16 bytes.

fix

Shorten your prefix string to be 16 bytes or less. Remember that non-ASCII characters might take up more than one byte (e.g., `len('😀'.encode('utf-8'))` is 4).

AttributeError: 'str' object has no attribute 'get_prefix'

You are attempting to call a method like `get_prefix()` on a string representation of a PKSUID, not on a `PKSUID` object itself.

fix

If you have a PKSUID as a string (e.g., from a database or log), you must first parse it back into a `PKSUID` object using `PKSUID.parse()` before calling its methods. Example: `uid_obj = PKSUID.parse('usr_24OnhzwMpa4sh0NQmTmICTYuFaD')`.

Upgrade

Version history

1.1.2latest on PyPI · released May 7, 2022

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/sashahilton00/python-pksuid ↗

packagehttps://pypi.org/project/pksuid/ ↗