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.

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: uuid6.UUID property

The UUID represented by this TypeID.

Returns:

Type	Description
UUID	The decoded UUID value.

Notes

• This decodes self.suffix each time it is accessed.
• The UUID type here follows uuid6.UUID used by the project.

__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.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.