Skip to content

TypedUUID Class

The core class for type-safe UUID management.

Overview

TypedUUID is the base class for all typed UUID instances. While you typically work with subclasses created via create_typed_uuid_class(), understanding the base class is important for advanced usage.

Class Reference

TypedUUID 

TypedUUID(type_id: str, uuid_value: Optional[Union[UUID, str, TypedUUID]] = None)

A UUID class that includes a type prefix for improved type safety and identification.

This class maintains a registry of all created TypedUUID subclasses, ensuring that each type_id is unique and allowing retrieval of existing classes.

Attributes:

Name Type Description
_type_id ClassVar[str]

Class-level type identifier
_class_registry ClassVar[Dict[str, Type[TypedUUID]]]

Registry of TypedUUID classes

Parameters:

Name Type Description Default
type_id str

The type identifier prefix (alphanumeric only)

 required
uuid_value Optional[Union[UUID, str, TypedUUID]]

Initial UUID value

 None

Raises:

Type Description
ValueError

If type_id is invalid or uuid_value cannot be parsed

Example:

>>> UserUUID = create_typed_uuid_class('User', 'user')

>>> user_id = UserUUID()

>>> str(user_id)

'user-550e8400-e29b-41d4-a716-446655440000'

>>> UserUUID.is_type_registered('user')

True

type_id property 

type_id: str

Get the type identifier.

uuid property 

uuid: UUID

Get the underlying UUID.

short property 

short: str

Get the short base62-encoded representation.

Returns:

Name Type Description
str str

Short format like 'user_7n42DGM5Tflk9n8mt7Fhc7'
Example

user_id = UserUUID() user_id.short 'user_7n42DGM5Tflk9n8mt7Fhc7'

from_string classmethod 

from_string(value: str) -> TypedUUID

Enhanced from_string method that handles multiple string formats: - Full typed UUID: "type-uuid" - Plain UUID: "uuid"

Parameters:

Name Type Description Default
value str

String representation of UUID with optional type prefix

 required

Returns:

Name Type Description
TypedUUID TypedUUID

Instance of the specific TypedUUID subclass

Raises:

Type Description
InvalidUUIDError

If the UUID format is invalid
InvalidTypeIDError

If type_id doesn't match class type

parse classmethod 

parse(value: str) -> TypedUUID

Parse a typed UUID string and return the appropriate TypedUUID subclass instance.

This method automatically detects the type from the string and returns an instance of the correct registered TypedUUID subclass.

Parameters:

Name Type Description Default
value str

String in format 'type-uuid' or 'type_base62' (short format)

 required

Returns:

Name Type Description
TypedUUID TypedUUID

Instance of the appropriate TypedUUID subclass

Raises:

Type Description
InvalidUUIDError

If format is invalid or type is not registered
Example

UserUUID = create_typed_uuid_class('User', 'user') user_id = TypedUUID.parse('user-550e8400-e29b-41d4-a716-446655440000') isinstance(user_id, UserUUID) True

from_short classmethod 

from_short(short_str: str) -> TypedUUID

Create a TypedUUID from a short base62-encoded string.

Parameters:

Name Type Description Default
short_str str

Short format string like 'user_7n42DGM5Tflk9n8mt7Fhc7'

 required

Returns:

Name Type Description
TypedUUID TypedUUID

Instance of the TypedUUID subclass

Raises:

Type Description
InvalidUUIDError

If format is invalid
InvalidTypeIDError

If type doesn't match class type
Example

user_id = UserUUID.from_short('user_7n42DGM5Tflk9n8mt7Fhc7')

format_pattern classmethod 

format_pattern() -> str

Get the regex pattern for UUID format validation.

get_uuid 

get_uuid() -> str

Get the UUID string without the type prefix.

get_registered_class classmethod 

get_registered_class(type_id: str) -> Optional[Type[TypedUUID]]

Get an existing TypedUUID class for a type_id if one exists.

get_class_by_type_id classmethod 

get_class_by_type_id(type_id: str) -> Optional[Type[TypedUUID]]

Get the TypedUUID class for a given type_id.

Parameters:

Name Type Description Default
type_id str

The type identifier to look up

 required

Returns:

Type Description
Optional[Type[TypedUUID]]

Optional[Type['TypedUUID']]: The registered class or None if not found

is_type_registered classmethod 

is_type_registered(type_id: str) -> bool

Check if a type_id is already registered.

Parameters:

Name Type Description Default
type_id str

The type identifier to check

 required

Returns:

Name Type Description
bool bool

True if type_id is registered, False otherwise

list_registered_types classmethod 

list_registered_types() -> List[str]

List all registered type IDs.

Returns:

Type Description
List[str]

List[str]: List of registered type IDs

json_default staticmethod 

json_default(obj)

Default JSON encoder for TypedUUID objects.

__str__ 

__str__() -> str

Return the string representation as 'type-uuid'.

__repr__ 

__repr__() -> str

Return a detailed string representation.

__eq__ 

__eq__(other: Any) -> bool

Support equality comparison.

__ne__ 

__ne__(other: Any) -> bool

Support inequality comparison.

__lt__ 

__lt__(other: Any) -> bool

Support sorting.

__le__ 

__le__(other: Any) -> bool

Support sorting.

__gt__ 

__gt__(other: Any) -> bool

Support sorting.

__ge__ 

__ge__(other: Any) -> bool

Support sorting.

__hash__ 

__hash__() -> int

Generate a hash based on type_id and uuid.

__bytes__ 

__bytes__() -> bytes

Convert to bytes.

Usage Examples

Creating Instances

from typed_uuid import create_typed_uuid_class

UserUUID = create_typed_uuid_class('User', 'user')

# Generate new UUID
user_id = UserUUID()

# From existing UUID string
user_id = UserUUID('550e8400-e29b-41d4-a716-446655440000')

# From typed string
user_id = UserUUID.from_string('user-550e8400-e29b-41d4-a716-446655440000')

Properties

user_id = UserUUID()

# Get the type identifier
print(user_id.type_id)  # 'user'

# Get the underlying UUID object
print(user_id.uuid)  # UUID('550e8400-...')

# Get short format
print(user_id.short)  # 'user_7n42DGM5Tflk9n8mt7Fhc7'

Comparison Operations

user1 = UserUUID('550e8400-e29b-41d4-a716-446655440000')
user2 = UserUUID('550e8400-e29b-41d4-a716-446655440000')
user3 = UserUUID()

# Equality
user1 == user2  # True
user1 == user3  # False

# String comparison
user1 == 'user-550e8400-e29b-41d4-a716-446655440000'  # True

# Ordering
sorted([user3, user1])  # Sorts by UUID value

Registry Operations

from typed_uuid import TypedUUID

# Check if type is registered
TypedUUID.is_type_registered('user')  # True

# List all registered types
TypedUUID.list_registered_types()  # ['user', 'order', ...]

# Get class by type_id
UserUUID = TypedUUID.get_class_by_type_id('user')

Auto-Detection

from typed_uuid import TypedUUID

# Parse any registered type
uuid = TypedUUID.parse('user-550e8400-e29b-41d4-a716-446655440000')
print(type(uuid).__name__)  # 'UserUUID'

# Works with short format too
uuid = TypedUUID.parse('user_7n42DGM5Tflk9n8mt7Fhc7')

Class Attributes

Attribute Type Description
_type_id ClassVar[str] The type identifier for this class
_class_registry ClassVar[Dict] Registry of all TypedUUID classes
_registry_lock ClassVar[Lock] Thread lock for registry access

Instance Attributes

Attribute Type Description
_uuid UUID The underlying UUID object
_instance_type_id str The type identifier for this instance

See Also