dto

Construct Pydantic models from SQLAlchemy ORM types.

DTOConfig dataclass

Control the generated DTO.

exclude class-attribute

exclude: set[str] = field(default_factory=set)

Explicitly exclude fields from the generated DTO.

purpose class-attribute

purpose: Purpose

Configure the DTO for "read" or "write" operations.

DTOField dataclass

For configuring DTO behavior on SQLAlchemy model fields.

mark class-attribute

mark: Mark | None = None

Mark the field as read-only, or private.

pydantic_field class-attribute

pydantic_field: FieldInfo | None = None

If provided, used for the pydantic model for this attribute.

pydantic_type class-attribute

pydantic_type: Any | None = None

Override the field type on the pydantic model for this attribute.

validators class-attribute

validators: Iterable[Callable[[Any], Any]] | None = None

Single argument callables that are defined on the DTO as validators for the field.

FromMapped

Bases: BaseModel, Generic[AnyDeclarative]

Produce an SQLAlchemy instance with values from a pydantic model.

Config

Set orm_mode for to_mapped() method.

__class_getitem__

__class_getitem__(item)

Decorate cls with result from factory().

Parameters:

Name	Type	Description	Default
item	Annotated[type[AnyDeclarative], DTOConfig | Literal['read', 'write']]	Can be either of a SQLAlchemy ORM instance, or a typing.Annotated annotation where the first argument is a SQLAlchemy ORM instance, and the second is an instance of DTOConfig.	required

Returns:

Type	Description
type[FromMapped[AnyDeclarative]]	A new Pydantic model type, with cls as its base class, and additional fields derived
type[FromMapped[AnyDeclarative]]	from the SQLAlchemy model, respecting any declared configuration.

__init_subclass__

__init_subclass__(model=None, **kwargs)

Set __sqla_model__ on type.

Parameters:

Name	Type	Description	Default
model	type[AnyDeclarative] | None	Model represented by the DTO	None
kwargs	Any	Passed to super().__init_subclass__()	{}

to_mapped

to_mapped()

Create an instance of self.__sqla_model__

Fill the bound SQLAlchemy model recursively with values from this dataclass.

Mark

Bases: str, Enum

For marking column definitions on the domain models.

Example:

class Model(Base):
    ...
    updated_at: Mapped[datetime] = mapped_column(info={"dto": Mark.READ_ONLY})

PRIVATE class-attribute

PRIVATE = 'private'

To mark a field that can neither be read or updated by clients.

READ_ONLY class-attribute

READ_ONLY = 'read-only'

To mark a field that can be read, but not updated by clients.

Purpose

Bases: str, Enum

For identifying the purpose of a DTO to the factory.

The factory will exclude fields marked as private or read-only on the domain model depending on the purpose of the DTO.

Example:

ReadDTO = dto.factory("AuthorReadDTO", Author, purpose=dto.Purpose.READ)

READ class-attribute

READ = 'read'

To mark a DTO that is to be used to serialize data returned to clients.

WRITE class-attribute

WRITE = 'write'

To mark a DTO that is to deserialize and validate data provided by clients.

config

config(purpose, exclude=None)

Parameters:

Name	Type	Description	Default
purpose	Purpose | Literal['read', 'write']	Is the DTO for parsing "write" data, or serializing "read" data?	required
exclude	set[str] | None	Omit fields from dto by key name.	None

Returns:

Type	Description
DTOConfig	DTOConfig object configured per parameters.

field

field(mark=None, pydantic_type=None, pydantic_field=None, validators=None)

Create dto.DTOField() wrapped in a dict for SQLAlchemy info field.

Parameters:

Name	Type	Description	Default
mark	Mark | Literal['read-only', 'private'] | None	How this field should be treated by the model factory.	None
pydantic_type	Any | None	Override the type annotation for this field.	None
pydantic_field	FieldInfo | None	Result of Pydantic's DTOField() function. Override the FieldInfo instance used by the generated model.	None
validators	Iterable[Callable[[Any], Any]] | None	Added to the generated model as validators, with allow_reuse=True.	None