Registry / serialization / typeid-python

typeid-python

library0.3.9pypypi✓ verified 86d ago

typeid-python is a Python implementation of TypeIDs, offering type-safe, K-sortable, and globally unique identifiers inspired by Stripe IDs. It is actively maintained with frequent releases, focusing on performance, robustness, and developer experience.

serialization database

pip install typeid-python

github ↗package ↗

INSTALL

IMPORT

SIG · TYPEID-PYTHON

typeid-python

serializationpythonv0.3.9

Install

1.7s avg

Import

66ms

Disk

17MB

Pass rate

6/ 10

Env Coverage6 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.3.9 · 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

glibc

py 3.10

✕ build_error

✓ 1.75s

py 3.11

✕ build_error

✓ 1.73s

py 3.12

✕ build_error

✓ 1.53s

py 3.13

✕ build_error

✓ 1.68s

py 3.9

✓ —

✓ 1.78s

17MB installed

● package 17MB

Code

Verified usage

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

TypeID

✓ from typeid import TypeID

This example demonstrates how to generate a new TypeID, extract its components, convert it to and from its string representation, and compare TypeID objects.

from typeid import TypeID # Generate a new TypeID with a prefix (uses a new UUIDv7 internally) user_id = TypeID("user") print(f"Generated TypeID: {user_id}") print(f"Prefix: {user_id.prefix}") print(f"UUID: {user_id.uuid}") # Raw UUID object # Get the string representation user_id_str = str(user_id) print(f"String representation: {user_id_str}") # Parse a TypeID from a string parsed_id = TypeID.from_string(user_id_str) print(f"Parsed TypeID: {parsed_id}") # Compare TypeIDs assert user_id == parsed_id

Debug

Known issues

breakingPython 3.8 and 3.9 support was dropped. The library now requires Python 3.10 or newer.

fix

Upgrade your Python environment to version 3.10 or later. For example, `pyenv install 3.10.12 && pyenv local 3.10.12`.

affects: >=0.3.2

breakingThe prefix validation was updated in v0.3.0 to adhere strictly to the TypeID specification regex (`[a-z]{0,63}`). Prefixes that were previously accepted but did not conform will now raise an error.

fix

Ensure all TypeID prefixes conform to the regex `[a-z]{0,63}` (lowercase alphanumeric, max 63 characters).

affects: >=0.3.0

gotchaStarting from v0.3.5, the library introduced optional Rust acceleration, which became standard in v0.3.7 for improved performance in base32 encoding/decoding and UUIDv7 generation. While a pure-Python fallback exists, users might experience performance differences on platforms where native wheels aren't available or if the Rust extension fails to build.

fix

No direct fix is typically needed as the library handles fallbacks. However, for optimal performance, ensure a compatible environment for Rust-powered wheels. Check documentation for specific platform build troubleshooting if performance is critical and seems suboptimal.

affects: >=0.3.5

gotchaPrior to v0.3.9, there was an issue with Pydantic JSON schema generation for FastAPI/OpenAPI, leading to incorrect schema definitions. This was fixed in v0.3.9.

fix

Upgrade to `typeid-python` version 0.3.9 or later to ensure correct Pydantic JSON schema generation for FastAPI/OpenAPI integrations.

affects: <0.3.9

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'typeid'

The 'typeid-python' library has not been installed in the current Python environment or the import statement is incorrect.

fix

Install the library using pip: `pip install typeid-python`. Then import using `from typeid import TypeID`.

ValueError: Invalid TypeID string

The string provided to the `TypeID.parse()` method does not conform to the TypeID specification (e.g., incorrect format, invalid characters).

fix

Ensure the input string is a valid TypeID format. Implement error handling with a `try-except ValueError` block for robustness.

TypeError: object of type 'TypeID' is not JSON serializable

A `TypeID` object is a custom class instance, and Python's default JSON encoder does not know how to convert it to a standard JSON type (like a string).

fix

Convert the `TypeID` object to its string representation using `str(typeid_obj)` or `typeid_obj.typeid` before JSON serialization.

ValueError: Prefix must be lowercase letters only, and up to 63 characters long

The prefix provided when creating a new `TypeID` instance does not meet the specified validation rules (e.g., contains uppercase letters, numbers, symbols, or is too long).

fix

Ensure the prefix consists only of lowercase ASCII letters (a-z) and has a maximum length of 63 characters.

Upgrade

Version history

0.3.9latest on PyPI · released Jan 28, 2026

Audit

Dependencies

uuid-utilsrequiredUsed for UUIDv7 generation. It is a direct dependency.

Agent activity

23 hits · last 30 days

node