Skip to content

pUUID - API Reference

Exceptions

puuid.PUUIDError

Bases: Exception

Base exception for pUUID related errors.

Base Interface

All versioned pUUIDs (v1-v8) inherit from this base class

puuid.PUUIDBase

Bases: ABC

Abstract Generic Base Class for Prefixed UUIDs.

uuid: UUID property

Return the underlying UUID object.

Returns:

Type Description
UUID

The native UUID instance.

prefix() -> str classmethod

Return the defined prefix for the class.

Returns:

Type Description
str

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.

Versioned Variants

puuid.PUUIDv1

Bases: PUUIDBase[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() -> str classmethod

Return the defined prefix for the class.

Returns:

Type Description
str

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: PUUIDBase[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() -> str classmethod

Return the defined prefix for the class.

Returns:

Type Description
str

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: PUUIDBase[TPrefix]

Prefixed UUID Version 4 (randomly generated).

uuid: UUID property

Return the underlying UUID object.

Returns:

Type Description
UUID

The native UUID instance.

prefix() -> str classmethod

Return the defined prefix for the class.

Returns:

Type Description
str

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: PUUIDBase[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() -> str classmethod

Return the defined prefix for the class.

Returns:

Type Description
str

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: PUUIDBase[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() -> str classmethod

Return the defined prefix for the class.

Returns:

Type Description
str

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: PUUIDBase[TPrefix]

Prefixed UUID Version 7 (time-ordered).

uuid: UUID property

Return the underlying UUID object.

Returns:

Type Description
UUID

The native UUID instance.

prefix() -> str classmethod

Return the defined prefix for the class.

Returns:

Type Description
str

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: PUUIDBase[TPrefix]

Prefixed UUID Version 8 (custom implementation).

uuid: UUID property

Return the underlying UUID object.

Returns:

Type Description
UUID

The native UUID instance.

prefix() -> str classmethod

Return the defined prefix for the class.

Returns:

Type Description
str

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.

Integrations

puuid.sqlalchemy.SqlPUUID

Bases: TypeDecorator[PUUIDBase[TPrefix]]

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[PUUIDBase[TPrefix]]) -> None

Initialize the SqlPUUID type.

Parameters:

Name Type Description Default
puuid_cls type[PUUIDBase[TPrefix]]

The pUUID class (e.g., PUUIDv4[Literal["user"]]) to associate with this column.

 required