TypeID

Bases: Generic[PrefixT]

A TypeID is a human-meaningful, UUID-backed identifier.

A TypeID is rendered as:

<prefix>_<suffix>   or just   <suffix>  (when prefix is None/empty)

• prefix: optional semantic label (e.g. "user", "order"). It is not part of the UUID. Prefixes are validated for allowed characters/shape (see validate_prefix).
• suffix: a compact, URL-safe Base32 encoding of a UUID (UUIDv7 by default). Suffixes are validated structurally (see validate_suffix).

Design notes: - A TypeID is intended to be safe to store as a string (e.g. in logs / URLs). - The underlying UUID can always be recovered via .uuid. - Ordering (>, >=) is based on lexicographic order of the string representation, which corresponds to time-ordering if the UUID version is time-sortable (UUIDv7).

Class Type Parameters:

Name	Bound or Constraints	Description	Default
PrefixT		a type-level constraint for the prefix (often str or a Literal).	required

Create a new TypeID.

If suffix is not provided, a new UUIDv7 is generated and encoded as Base32. If prefix is provided, it is validated.

Parameters:

Name	Type	Description	Default
prefix	Optional[PrefixT]	Optional prefix. If None, the TypeID has no prefix and its string form will be just the suffix. If provided, it must pass validate_prefix.	None
suffix	Optional[str]	Optional Base32-encoded UUID string. If None, a new UUIDv7 is generated.	None

Raises:

Type	Description
InvalidTypeIDStringException (or another project-specific exception)	If suffix is invalid, or if prefix is invalid.

created_at: Optional[datetime] property

Creation time embedded in the underlying UUID, if available.

TypeID typically uses UUIDv7 for generated IDs. UUIDv7 encodes the Unix timestamp (milliseconds) in the most significant 48 bits of the 128-bit UUID.

Returns:

Type	Description
Optional[datetime]	A timezone-aware UTC datetime if the underlying UUID is version 7,
Optional[datetime]	otherwise None.

prefix: str property

The prefix portion of the TypeID, as a string.

Returns:

Type	Description
str	The configured prefix, or "" if the TypeID is prefix-less.

Notes

• Empty string is the presentation of "no prefix". Internally, _prefix remains Optional to preserve the distinction between None and a real value.

suffix: str property

The Base32-encoded UUID portion of the TypeID (always present).

Notes

• This is the identity-carrying part.
• It is validated at construction time.

uuid: uuid_utils.UUID property

The UUID represented by this TypeID.

Returns:

Type	Description
UUID	The decoded UUID value.

uuid_bytes: bytes property

Raw bytes of the underlying UUID.

This returns the canonical 16-byte representation of the UUID encoded in this TypeID. The value is derived lazily from the suffix and cached on first access.

Returns:

Type	Description
bytes	A 16-byte bytes object representing the UUID.

__eq__(value: object) -> bool

Equality based on prefix and suffix.

Notes

• Two TypeIDs are considered equal if both their string components match.
• This is stricter than "same UUID" because prefix is part of the public ID.

__ge__(other) -> bool

Compare TypeIDs by lexicographic order of their string form (>=).

See __gt__ for rationale and notes.

__gt__(other) -> bool

Compare TypeIDs by lexicographic order of their string form.

This is useful because TypeID suffixes based on UUIDv7 are time-sortable, so string order typically corresponds to creation time order (within a prefix).

Returns:

Type	Description
bool	True/False if other is a TypeID, otherwise NotImplemented.

__hash__() -> int

Hash based on (prefix, suffix), allowing TypeIDs to be used as dict keys / set members.

__repr__()

Developer-friendly representation.

Uses a constructor-like form to make debugging and copy/paste easier.

__str__() -> str

Render the TypeID into its canonical string representation.

Returns:

Type	Description
str	"_" if prefix is present, otherwise "".

from_string(string: str) -> TypeID classmethod

Parse a TypeID from its string form.

The input can be either: - "_" - "" (prefix-less)

Parameters:

Name	Type	Description	Default
string	str	String representation of a TypeID.	required

Returns:

Type	Description
TypeID	A TypeID instance.

Raises:

Type	Description
InvalidTypeIDStringException (or another project-specific exception)	If the string cannot be split/parsed or if the extracted parts are invalid.

from_uuid(suffix: uuid_utils.UUID, prefix: Optional[PrefixT] = None) -> TypeID classmethod

Construct a TypeID from an existing UUID.

This is useful when you store UUIDs in a database but want to expose TypeIDs at the application boundary.

Parameters:

Name	Type	Description	Default
suffix	UUID	UUID value to encode into the TypeID suffix.	required
prefix	Optional[PrefixT]	Optional prefix to attach (validated if provided).	None

Returns:

Type	Description
TypeID	A TypeID whose .uuid equals the provided UUID.