{"id":7502,"library":"pksuid","title":"Python Prefixed KSUID","description":"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.","status":"active","version":"1.1.2","language":"en","source_language":"en","source_url":"https://github.com/sashahilton00/python-pksuid","tags":["ksuid","uuid","id generation","prefixed id","sortable id"],"install":[{"cmd":"pip install pksuid","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"PKSUID","correct":"from pksuid import PKSUID"}],"quickstart":{"code":"from pksuid import PKSUID\n\n# Generate a new unique identifier with the prefix 'usr'\nuid = PKSUID('usr')\nprint(f\"Generated PKSUID: {uid}\")\n\n# Access components\nprint(f\"Prefix: {uid.get_prefix()}\")\nprint(f\"Timestamp (KSUID epoch): {uid.get_timestamp()}\")\nprint(f\"Datetime (UTC): {uid.get_datetime()}\")\nprint(f\"Payload: {uid.get_payload()}\")\n\n# Convert from a string representation back to PKSUID\nuid_from_string = PKSUID.parse('usr_24OnhzwMpa4sh0NQmTmICTYuFaD')\nprint(f\"Parsed PKSUID: {uid_from_string}\")\nprint(f\"Parsed Datetime (UTC): {uid_from_string.get_datetime()}\")\n\n# Conversion to and parsing from bytes is also possible\nuid_as_bytes = uid.bytes()\nuid_from_bytes = PKSUID.parse_bytes(uid_as_bytes)\nprint(f\"Parsed from bytes: {uid_from_bytes}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"PKSUID prefixes are limited to a maximum of 16 bytes. Providing a prefix longer than this will result in a `ValueError` during object instantiation.","severity":"gotcha","affected_versions":">=1.0.0"},{"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())`.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"PKSUID 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install pksuid` to install the library.","cause":"The 'pksuid' package is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'pksuid'"},{"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).","cause":"The prefix string provided when creating a `PKSUID` object exceeds the maximum allowed length of 16 bytes.","error":"ValueError: Prefix length must be between 0 and 16 bytes"},{"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')`.","cause":"You are attempting to call a method like `get_prefix()` on a string representation of a PKSUID, not on a `PKSUID` object itself.","error":"AttributeError: 'str' object has no attribute 'get_prefix'"}]}