Skip to content

pUUID - API Reference

puuid.PUUIDError

Bases: Exception

Base exception for pUUID related errors.

puuid.PUUID

Bases: ABC

Abstract Base Class for Prefixed UUIDs.

uuid: UUID property

Return the underlying UUID object.

Returns:

Type Description
UUID

The native UUID instance.

prefix() -> TPrefix classmethod

Return the defined prefix for the class.

Returns:

Type Description
TPrefix

The prefix string.

to_string() -> str

Return the string representation of the Prefixed UUID.

Returns:

Type Description
str

The formatted string (e.g., <prefix>_<uuid-hex-string>).

factory() -> Self classmethod

Create a new instance using default generation.

Supported by version variants that allow generation without arguments.

Returns:

Type Description
Self

A new instance of the pUUID class.

Raises:

Type Description
PUUIDError

If the variant does not support parameterless generation.

from_string(serial_puuid: str) -> Self classmethod

Create a pUUID instance from its string representation.

Parameters:

Name Type Description Default
serial_puuid str

The prefixed UUID string (e.g., user_550e8400-e29b...).

 required

Returns:

Type Description
Self

The deserialized pUUID instance.

Raises:

Type Description
PUUIDError

If the string is malformed or the prefix does not match.

puuid.PUUIDv1

Bases: PUUID[TPrefix]

Prefixed UUID Version 1 (MAC address and time).

uuid: UUID property

Return the underlying UUID object.

Returns:

Type Description
UUID

The native UUID instance.

prefix() -> TPrefix classmethod

Return the defined prefix for the class.

Returns:

Type Description
TPrefix

The prefix string.

to_string() -> str

Return the string representation of the Prefixed UUID.

Returns:

Type Description
str

The formatted string (e.g., <prefix>_<uuid-hex-string>).

from_string(serial_puuid: str) -> Self classmethod

Create a pUUID instance from its string representation.

Parameters:

Name Type Description Default
serial_puuid str

The prefixed UUID string (e.g., user_550e8400-e29b...).

 required

Returns:

Type Description
Self

The deserialized pUUID instance.

Raises:

Type Description
PUUIDError

If the string is malformed or the prefix does not match.

__init__(*, node: int | None = None, clock_seq: int | None = None, uuid: UUID | None = None) -> None 

__init__(
    *, node: int | None = None, clock_seq: int | None = None
) -> None

__init__(*, uuid: UUID) -> None

Initialize a PUUIDv1.

Parameters:

Name Type Description Default
node int | None

Hardware address. If None, uuid1 generates a random value.

 None
clock_seq int | None

Clock sequence.

 None
uuid UUID | None

Existing UUID v1 instance.

 None

Raises:

Type Description
PUUIDError

If arguments are inconsistent or the UUID version is incorrect.

factory() -> Self classmethod

Create a new PUUIDv1 instance using current time and MAC address.

Returns:

Type Description
Self

A new pUUID v1 instance.

puuid.PUUIDv3

Bases: PUUID[TPrefix]

Prefixed UUID Version 3 (MD5 hash of namespace and name).

uuid: UUID property

Return the underlying UUID object.

Returns:

Type Description
UUID

The native UUID instance.

prefix() -> TPrefix classmethod

Return the defined prefix for the class.

Returns:

Type Description
TPrefix

The prefix string.

to_string() -> str

Return the string representation of the Prefixed UUID.

Returns:

Type Description
str

The formatted string (e.g., <prefix>_<uuid-hex-string>).

factory() -> Self classmethod

Create a new instance using default generation.

Supported by version variants that allow generation without arguments.

Returns:

Type Description
Self

A new instance of the pUUID class.

Raises:

Type Description
PUUIDError

If the variant does not support parameterless generation.

from_string(serial_puuid: str) -> Self classmethod

Create a pUUID instance from its string representation.

Parameters:

Name Type Description Default
serial_puuid str

The prefixed UUID string (e.g., user_550e8400-e29b...).

 required

Returns:

Type Description
Self

The deserialized pUUID instance.

Raises:

Type Description
PUUIDError

If the string is malformed or the prefix does not match.

__init__(*, namespace: UUID | None = None, name: str | bytes | None = None, uuid: UUID | None = None) -> None 

__init__(*, namespace: UUID, name: str | bytes) -> None

__init__(*, uuid: UUID) -> None

Initialize a PUUIDv3.

Parameters:

Name Type Description Default
namespace UUID | None

Namespace UUID.

 None
name str | bytes | None

The name used for hashing.

 None
uuid UUID | None

Existing UUID v3 instance.

 None

Raises:

Type Description
PUUIDError

If arguments are inconsistent or the UUID version is incorrect.

puuid.PUUIDv4

Bases: PUUID[TPrefix]

Prefixed UUID Version 4 (randomly generated).

uuid: UUID property

Return the underlying UUID object.

Returns:

Type Description
UUID

The native UUID instance.

prefix() -> TPrefix classmethod

Return the defined prefix for the class.

Returns:

Type Description
TPrefix

The prefix string.

to_string() -> str

Return the string representation of the Prefixed UUID.

Returns:

Type Description
str

The formatted string (e.g., <prefix>_<uuid-hex-string>).

from_string(serial_puuid: str) -> Self classmethod

Create a pUUID instance from its string representation.

Parameters:

Name Type Description Default
serial_puuid str

The prefixed UUID string (e.g., user_550e8400-e29b...).

 required

Returns:

Type Description
Self

The deserialized pUUID instance.

Raises:

Type Description
PUUIDError

If the string is malformed or the prefix does not match.

__init__(uuid: UUID | None = None) -> None

Initialize a PUUIDv4.

Parameters:

Name Type Description Default
uuid UUID | None

Existing UUID v4 instance. If None, a new random UUID is generated.

 None

Raises:

Type Description
PUUIDError

If the provided UUID is not version 4.

factory() -> Self classmethod

Create a new PUUIDv4 instance using random generation.

Returns:

Type Description
Self

A new pUUID v4 instance.

puuid.PUUIDv5

Bases: PUUID[TPrefix]

Prefixed UUID Version 5 (SHA-1 hash of namespace and name).

uuid: UUID property

Return the underlying UUID object.

Returns:

Type Description
UUID

The native UUID instance.

prefix() -> TPrefix classmethod

Return the defined prefix for the class.

Returns:

Type Description
TPrefix

The prefix string.

to_string() -> str

Return the string representation of the Prefixed UUID.

Returns:

Type Description
str

The formatted string (e.g., <prefix>_<uuid-hex-string>).

factory() -> Self classmethod

Create a new instance using default generation.

Supported by version variants that allow generation without arguments.

Returns:

Type Description
Self

A new instance of the pUUID class.

Raises:

Type Description
PUUIDError

If the variant does not support parameterless generation.

from_string(serial_puuid: str) -> Self classmethod

Create a pUUID instance from its string representation.

Parameters:

Name Type Description Default
serial_puuid str

The prefixed UUID string (e.g., user_550e8400-e29b...).

 required

Returns:

Type Description
Self

The deserialized pUUID instance.

Raises:

Type Description
PUUIDError

If the string is malformed or the prefix does not match.

__init__(*, namespace: UUID | None = None, name: str | bytes | None = None, uuid: UUID | None = None) -> None 

__init__(*, namespace: UUID, name: str | bytes) -> None

__init__(*, uuid: UUID) -> None

Initialize a PUUIDv5.

Parameters:

Name Type Description Default
namespace UUID | None

Namespace UUID.

 None
name str | bytes | None

The name used for hashing.

 None
uuid UUID | None

Existing UUID v5 instance.

 None

Raises:

Type Description
PUUIDError

If arguments are inconsistent or the UUID version is incorrect.

puuid.PUUIDv6

Bases: PUUID[TPrefix]

Prefixed UUID Version 6 (reordered v1 for DB locality).

uuid: UUID property

Return the underlying UUID object.

Returns:

Type Description
UUID

The native UUID instance.

prefix() -> TPrefix classmethod

Return the defined prefix for the class.

Returns:

Type Description
TPrefix

The prefix string.

to_string() -> str

Return the string representation of the Prefixed UUID.

Returns:

Type Description
str

The formatted string (e.g., <prefix>_<uuid-hex-string>).

from_string(serial_puuid: str) -> Self classmethod

Create a pUUID instance from its string representation.

Parameters:

Name Type Description Default
serial_puuid str

The prefixed UUID string (e.g., user_550e8400-e29b...).

 required

Returns:

Type Description
Self

The deserialized pUUID instance.

Raises:

Type Description
PUUIDError

If the string is malformed or the prefix does not match.

__init__(*, node: int | None = None, clock_seq: int | None = None, uuid: UUID | None = None) -> None 

__init__(
    *, node: int | None = None, clock_seq: int | None = None
) -> None

__init__(*, uuid: UUID) -> None

Initialize a PUUIDv6.

Parameters:

Name Type Description Default
node int | None

Hardware address.

 None
clock_seq int | None

Clock sequence.

 None
uuid UUID | None

Existing UUID v6 instance.

 None

Raises:

Type Description
PUUIDError

If arguments are inconsistent or the UUID version is incorrect.

factory() -> Self classmethod

Create a new PUUIDv6 instance using reordered time-based generation.

Returns:

Type Description
Self

A new pUUID v6 instance optimized for DB locality.

puuid.PUUIDv7

Bases: PUUID[TPrefix]

Prefixed UUID Version 7 (time-ordered).

uuid: UUID property

Return the underlying UUID object.

Returns:

Type Description
UUID

The native UUID instance.

prefix() -> TPrefix classmethod

Return the defined prefix for the class.

Returns:

Type Description
TPrefix

The prefix string.

to_string() -> str

Return the string representation of the Prefixed UUID.

Returns:

Type Description
str

The formatted string (e.g., <prefix>_<uuid-hex-string>).

from_string(serial_puuid: str) -> Self classmethod

Create a pUUID instance from its string representation.

Parameters:

Name Type Description Default
serial_puuid str

The prefixed UUID string (e.g., user_550e8400-e29b...).

 required

Returns:

Type Description
Self

The deserialized pUUID instance.

Raises:

Type Description
PUUIDError

If the string is malformed or the prefix does not match.

__init__(uuid: UUID | None = None) -> None

Initialize a PUUIDv7.

Parameters:

Name Type Description Default
uuid UUID | None

Existing UUID v7 instance. If None, a new time-ordered UUID is generated.

 None

Raises:

Type Description
PUUIDError

If the provided UUID is not version 7.

factory() -> Self classmethod

Create a new PUUIDv7 instance using time-ordered generation.

Returns:

Type Description
Self

A new pUUID v7 instance.

puuid.PUUIDv8

Bases: PUUID[TPrefix]

Prefixed UUID Version 8 (custom implementation).

uuid: UUID property

Return the underlying UUID object.

Returns:

Type Description
UUID

The native UUID instance.

prefix() -> TPrefix classmethod

Return the defined prefix for the class.

Returns:

Type Description
TPrefix

The prefix string.

to_string() -> str

Return the string representation of the Prefixed UUID.

Returns:

Type Description
str

The formatted string (e.g., <prefix>_<uuid-hex-string>).

from_string(serial_puuid: str) -> Self classmethod

Create a pUUID instance from its string representation.

Parameters:

Name Type Description Default
serial_puuid str

The prefixed UUID string (e.g., user_550e8400-e29b...).

 required

Returns:

Type Description
Self

The deserialized pUUID instance.

Raises:

Type Description
PUUIDError

If the string is malformed or the prefix does not match.

__init__(*, a: int | None = None, b: int | None = None, c: int | None = None, uuid: UUID | None = None) -> None 

__init__(
    *,
    a: int | None = None,
    b: int | None = None,
    c: int | None = None
) -> None

__init__(*, uuid: UUID) -> None

Initialize a PUUIDv8.

Parameters:

Name Type Description Default
a int | None

First custom 48-bit value.

 None
b int | None

Second custom 12-bit value.

 None
c int | None

Third custom 62-bit value.

 None
uuid UUID | None

Existing UUID v8 instance.

 None

Raises:

Type Description
PUUIDError

If arguments are inconsistent or the UUID version is incorrect.

factory() -> Self classmethod

Create a new PUUIDv8 instance using custom generation.

Returns:

Type Description
Self

A new pUUID v8 instance.

puuid.sqlalchemy.SqlPUUID

Bases: TypeDecorator[PUUID[str]]

SQLAlchemy type for storing Prefixed UUIDs.

Maps a PUUID instance to a VARCHAR column in the database and reconstructs the specific PUUID subclass on retrieval.

__init__(puuid_cls: type[PUUID[str]], prefix_length: int = 4) -> None

Initialize the SqlPUUID type.

Parameters:

Name Type Description Default
puuid_cls type[PUUID[str]]

The pUUID class (e.g., UserUUID) to associate with this column.

 required
prefix_length int

The length of the prefix string to calculate the column width.

 4