Factory Functions¶

Functions for creating TypedUUID classes.

create_typed_uuid_class¶

The primary factory function for creating TypedUUID subclasses.

create_typed_uuid_class ¶

create_typed_uuid_class(class_name: str, type_id: str) -> Type[T]

Create or retrieve a TypedUUID subclass with the specified type_id. If a class with the given type_id already exists, returns the existing class.

This function is thread-safe.

Parameters:

Name	Type	Description	Default
`class_name`	`str`	Name for the new class	required
`type_id`	`str`	Type identifier for the UUID (alphanumeric characters only)	required

Returns:

Type	Description
`Type[T]`	Type[T]: New or existing TypedUUID subclass

Usage¶

from typed_uuid import create_typed_uuid_class

# Create a new TypedUUID class
UserUUID = create_typed_uuid_class('User', 'user')

# The class name includes 'UUID' suffix
print(UserUUID.__name__)  # 'UserUUID'

# Create instances
user_id = UserUUID()
print(user_id)  # 'user-550e8400-e29b-41d4-a716-446655440000'

Parameters¶

Parameter	Type	Description
`class_name`	`str`	Base name for the class (becomes `{name}UUID`)
`type_id`	`str`	Type identifier prefix for UUID strings

Returns¶

A new TypedUUID subclass with the specified type_id.

Thread Safety¶

This function is thread-safe. Multiple threads can safely create classes concurrently.

Registry Behavior¶

If a class with the same type_id already exists, the existing class is returned:

UserUUID1 = create_typed_uuid_class('User', 'user')
UserUUID2 = create_typed_uuid_class('User', 'user')

print(UserUUID1 is UserUUID2)  # True

create_typed_uuid_classes¶

Utility function that creates both a TypedUUID class and its SQLAlchemy type.

create_typed_uuid_classes ¶

create_typed_uuid_classes(name: str, type_id: str) -> Union[Tuple[Type[TypedUUID], Any], Type[TypedUUID]]

Create a TypedUUID class and optionally its corresponding SQLAlchemy type if available.

Parameters:

Name	Type	Description	Default
`name`	`str`	The base name for the classes	required
`type_id`	`str`	The type identifier for the UUID	required

Returns:

Type	Description
`Union[Tuple[Type[TypedUUID], Any], Type[TypedUUID]]`	If SQLAlchemy is available: Tuple[Type[TypedUUID], Type[TypedUUIDType]]: The generated TypedUUID and TypedUUIDType classes
`Union[Tuple[Type[TypedUUID], Any], Type[TypedUUID]]`	If SQLAlchemy is not available: Type[TypedUUID]: Just the generated TypedUUID class

Example

With SQLAlchemy¶

UserUUID, UserUUIDType = create_typed_uuid_classes('User', 'user')

Without SQLAlchemy¶

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

Usage¶

from typed_uuid import create_typed_uuid_classes

# Returns tuple when SQLAlchemy is available
UserUUID, UserUUIDType = create_typed_uuid_classes('User', 'user')

# Use in SQLAlchemy models
class User(Base):
    id = Column(UserUUIDType(), primary_key=True, default=UserUUID)

Parameters¶

Parameter	Type	Description
`name`	`str`	Base name for the classes
`type_id`	`str`	Type identifier prefix

Returns¶

With SQLAlchemy: Tuple[Type[TypedUUID], Type[TypedUUIDType]]
Without SQLAlchemy: Type[TypedUUID]

Behavior¶

This function:

Creates a TypedUUID class using create_typed_uuid_class()
Adds FastAPI methods if FastAPI is available
Creates a SQLAlchemy TypedUUIDType if SQLAlchemy is available
Returns a tuple or single class depending on available dependencies

_reconstruct_typed_uuid¶

Internal helper for pickle support.

_reconstruct_typed_uuid ¶

_reconstruct_typed_uuid(type_id: str, uuid_str: str) -> TypedUUID

Reconstruct a TypedUUID instance from pickle data.

This function is used by reduce to enable pickling of dynamically created TypedUUID subclasses.

Internal Function

This function is used internally for pickle serialization and should not be called directly.

Best Practices¶

Define Classes at Module Level¶

# ids.py - Define all your ID types here
from typed_uuid import create_typed_uuid_class

UserUUID = create_typed_uuid_class('User', 'user')
OrderUUID = create_typed_uuid_class('Order', 'order')
ProductUUID = create_typed_uuid_class('Product', 'product')

Use Consistent Naming¶

# Good: Consistent lowercase type_ids
create_typed_uuid_class('User', 'user')
create_typed_uuid_class('Order', 'order')

# Good: Consistent abbreviated type_ids
create_typed_uuid_class('User', 'usr')
create_typed_uuid_class('Order', 'ord')

# Avoid: Mixed conventions
create_typed_uuid_class('User', 'user')
create_typed_uuid_class('Order', 'ORD')  # Inconsistent

Handle Optional Dependencies¶

from typed_uuid import create_typed_uuid_classes

result = create_typed_uuid_classes('User', 'user')

# Check if SQLAlchemy type was created
if isinstance(result, tuple):
    UserUUID, UserUUIDType = result
else:
    UserUUID = result
    UserUUIDType = None  # SQLAlchemy not available