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.base.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., |
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., |
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., |
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., |
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, *, check_version: bool = True) -> None
Initialize a PUUIDv1.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
uuid
|
UUID
|
An UUIDv1 instance. |
required |
Raises:
| Type | Description |
|---|---|
PUUIDError
|
If the UUID version is incorrect. |
factory(*, node: int | None = None, clock_seq: int | None = None) -> Self
classmethod
Create a new PUUIDv1 instance. using current time and MAC address.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
node
|
int | None
|
MAC address. |
None
|
clock_seq
|
int | None
|
The current time. |
None
|
Returns:
| Type | Description |
|---|---|
Self
|
A new PUUIDv1 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., |
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., |
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, *, check_version: bool = True) -> None
Initialize a PUUIDv3.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
uuid
|
UUID
|
An UUIDv3 instance. |
required |
Raises:
| Type | Description |
|---|---|
PUUIDError
|
If the UUID version is incorrect. |
factory(*, namespace: UUID, name: str | bytes) -> Self
classmethod
Create a new PUUIDv3.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
namespace
|
UUID | None
|
Namespace UUID. |
required |
name
|
str | bytes | None
|
The name used for hashing. |
required |
Returns:
| Type | Description |
|---|---|
Self
|
A new PUUIDv3 instance. |
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., |
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., |
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, *, check_version: bool = True) -> None
Initialize a PUUIDv4.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
uuid
|
UUID
|
An UUIDv4 instance. |
required |
Raises:
| Type | Description |
|---|---|
PUUIDError
|
If the UUID version is incorrect. |
factory() -> Self
classmethod
Create a new PUUIDv4 instance using random generation.
Returns:
| Type | Description |
|---|---|
Self
|
A new PUUIDv4 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., |
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., |
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, *, check_version: bool = True) -> None
Initialize a PUUIDv5.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
uuid
|
UUID
|
Existing UUIDv5 instance. |
required |
Raises:
| Type | Description |
|---|---|
PUUIDError
|
If the UUID version is incorrect. |
factory(*, namespace: UUID, name: str | bytes) -> Self
classmethod
Create a new PUUIDv5 instance using random generation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
namespace
|
UUID
|
Namespace UUID. |
required |
name
|
str | bytes
|
The name used for hashing. |
required |
Returns:
| Type | Description |
|---|---|
Self
|
A new PUUIDv5 instance. |
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., |
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., |
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, *, check_version: bool = True) -> None
Initialize a PUUIDv6.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
uuid
|
UUID
|
An UUIDv6 instance. |
required |
Raises:
| Type | Description |
|---|---|
PUUIDError
|
If the UUID version is incorrect. |
factory(*, node: int | None = None, clock_seq: int | None = None) -> Self
classmethod
Create a new PUUIDv6 instance. using current time and MAC address.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
node
|
int | None
|
MAC address. |
None
|
clock_seq
|
int | None
|
The current time. |
None
|
Returns:
| Type | Description |
|---|---|
Self
|
A new PUUIDv6 instance. |
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., |
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., |
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, *, check_version: bool = True) -> None
Initialize a PUUIDv7.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
uuid
|
UUID
|
An UUIDv7 instance. |
required |
Raises:
| Type | Description |
|---|---|
PUUIDError
|
If the UUID version is incorrect. |
factory() -> Self
classmethod
Create a new PUUIDv7 instance using random generation.
Returns:
| Type | Description |
|---|---|
Self
|
A new PUUIDv7 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., |
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., |
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, *, check_version: bool = True) -> None
Initialize a PUUIDv8.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
uuid
|
UUID
|
An UUIDv8 instance. |
required |
Raises:
| Type | Description |
|---|---|
PUUIDError
|
If the UUID version is incorrect. |
factory(*, a: int | None = None, b: int | None = None, c: int | None = None) -> Self
classmethod
Create a new PUUIDv8 instance using custom generation.
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
|
Returns:
| Type | Description |
|---|---|
Self
|
A new PUUIDv8 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., |
required |