Skip to content

Core API

Runtime DTO derivation

For an entity User, derive read, write, or combined DTO classes:

from fastsprout.core import (
    derive_read_dto,
    derive_read_write_dto,
    derive_write_dto,
)

UserRead = derive_read_dto(User)
UserCreate = derive_write_dto(User)
UserUpdate = derive_read_write_dto(User)

Each function reuses its class for the same entity. Visibility is enforced at runtime; type checkers see type[User]. For static field restrictions, declare class UserRead(ReadDTO, User): ... instead.

typed_pyd_dataclass module-attribute 

typed_pyd_dataclass = typed_pydantic_dataclass

inject_depends module-attribute 

inject_depends: DependencyInjector = DependencyInjector()

Undefined module-attribute 

Undefined: Final[UndefinedType] = UndefinedType()

__all__ module-attribute 

__all__ = [
    "ActionGroupable",
    "Actionable",
    "BaseFastSproutError",
    "BaseSchema",
    "Chunk",
    "Context",
    "DependencyInjector",
    "Depends",
    "EntityVisibility",
    "ExtraReadDTO",
    "ExtraReadField",
    "ExtraReadWriteDTO",
    "ExtraWriteDTO",
    "ExtraWriteField",
    "FastSproutError",
    "Field",
    "IDType",
    "IdentificatorType",
    "InternalField",
    "PublicIDType",
    "ReadDTO",
    "ReadField",
    "ReadWriteDTO",
    "Schema",
    "TriggerActionable",
    "Undefined",
    "UndefinedType",
    "WriteDTO",
    "WriteField",
    "dataclass",
    "derive_read_dto",
    "derive_read_write_dto",
    "derive_write_dto",
    "dto",
    "hidden_lazy_await",
    "inject_depends",
    "lazy_await",
    "typed_dataclass",
    "typed_fields",
    "typed_pyd_dataclass",
]

IdentificatorType 

IdentificatorType = IdentificatableType

IDType 

IDType = IdentificatableType

PublicIDType 

PublicIDType = IdentificatableType

Actionable

Bases: Protocol

Atomic unit of work in fastsprout.

Actions take a single typed payload and return a typed result. Exposed through channels (REST, CLI, task, event) via decorators from interface layers.

__call__ async 

__call__(payload: I) -> O

ActionGroupable

Bases: Protocol

Group of actions — class with multiple decorated methods.

__action_group__ class-attribute 

__action_group__: bool

TriggerActionable

Bases: Protocol

Action triggered without payload (cron jobs, no-input commands).

__call__ async 

__call__() -> O

DependencyInjector

Resolve Depends providers with per-call caching and callable overrides.

dependency_providers instance-attribute 

dependency_providers: dict[Callable[..., Any], Callable[..., Any]] = {}

dependency_overrides instance-attribute 

dependency_overrides: dict[Callable[..., Any], Callable[..., Any]] = {}

__init__ 

__init__() -> None

marker staticmethod 

marker(parameter: Parameter, annotation: Any) -> tuple[Any, Any]

provider 

provider(marker: Any, annotation: Any) -> Callable[..., Any]

dependency_key 

dependency_key[**P, R](
    provider: Callable[P, R], active: frozenset[int] = frozenset()
) -> UUID | None

call_sync staticmethod 

call_sync(provider: Callable[..., Any], bound: BoundArguments) -> Any

call_async async staticmethod 

call_async(provider: Callable[..., Any], bound: BoundArguments) -> Any

arguments 

arguments(
    function: Callable[..., Any],
    args: tuple[Any, ...],
    kwargs: dict[str, Any],
    supplied: BoundArguments | None = None,
) -> tuple[inspect.BoundArguments, list[tuple[str, Any, Any]]]

bind 

bind(bound: BoundArguments, supplied: BoundArguments | None) -> None

resolve_dependency 

resolve_dependency(
    marker: Any,
    annotation: Any,
    cache: dict[object, Any],
    active: set[Callable[..., Any]],
) -> Any

aresolve_dependency async 

aresolve_dependency(
    marker: Any,
    annotation: Any,
    cache: dict[object, Any],
    active: set[Callable[..., Any]],
    supplied: BoundArguments | None = None,
) -> Any

resolve 

resolve(marker: Any, annotation: Any) -> Any

aresolve async 

aresolve(marker: Any, annotation: Any) -> Any

inject 

inject(
    function: Callable[..., Any], args: tuple[Any, ...], kwargs: dict[str, Any]
) -> inspect.BoundArguments

ainject async 

ainject(
    function: Callable[..., Any],
    args: tuple[Any, ...],
    kwargs: dict[str, Any],
    extra_dependencies: Sequence[DependsClass] = (),
    supplied: BoundArguments | None = None,
) -> inspect.BoundArguments

__call__ 

__call__[**P, R](function: Callable[P, R]) -> Callable[P, R]

ExtraReadDTO

Bases: DTO

Read fields including explicitly requested extra read fields.

__fastsprout_operations__ class-attribute 

__fastsprout_operations__: frozenset[str] = frozenset({'read', 'extra_read'})

fastsprout_visibility property 

fastsprout_visibility: Literal['extra_read']

ExtraReadWriteDTO

Bases: DTO

Read and write fields including both kinds of extra fields.

__fastsprout_operations__ class-attribute 

__fastsprout_operations__: frozenset[str] = frozenset(
    {"read", "write", "extra_read", "extra_write"}
)

fastsprout_visibility property 

fastsprout_visibility: Literal['extra_read_write']

ExtraWriteDTO

Bases: DTO

Write fields including explicitly requested extra write fields.

__fastsprout_operations__ class-attribute 

__fastsprout_operations__: frozenset[str] = frozenset({"write", "extra_write"})

fastsprout_visibility property 

fastsprout_visibility: Literal['extra_write']

ReadDTO

Bases: DTO

Use first in the bases of a read DTO, followed by the source entity.

__fastsprout_operations__ class-attribute 

__fastsprout_operations__: frozenset[str] = frozenset({'read'})

fastsprout_visibility property 

fastsprout_visibility: Literal['read']

ReadWriteDTO

Bases: DTO

Union of read and write fields; internal fields are still forbidden.

__fastsprout_operations__ class-attribute 

__fastsprout_operations__: frozenset[str] = frozenset({'read', 'write'})

fastsprout_visibility property 

fastsprout_visibility: Literal['read_write']

WriteDTO

Bases: DTO

Use first in the bases of a write DTO, followed by the source entity.

__fastsprout_operations__ class-attribute 

__fastsprout_operations__: frozenset[str] = frozenset({'write'})

fastsprout_visibility property 

fastsprout_visibility: Literal['write']

BaseFastSproutError

Bases: Exception

Base for all fastsprout exceptions.

FastSproutError

Bases: BaseFastSproutError

Fastsprout exceptions.

EntityVisibility

Unrestricted source; DTO bases supply a concrete visibility mode.

Only this private marker is Any. Field value types remain fully typed. The open marker allows a DTO to narrow visibility without an incompatible override of a literal-valued member on its source entity.

fastsprout_visibility property 

fastsprout_visibility: Any

ExtraReadField

Bases: Field[T, ExtraReadable]

Excluded from ordinary DTOs; requires extended read visibility.

__fastsprout_ops__ class-attribute 

__fastsprout_ops__: frozenset[str] = frozenset({'extra_read'})

ExtraWriteField

Bases: Field[T, ExtraWritable]

Excluded from ordinary DTOs; requires extended write visibility.

__fastsprout_ops__ class-attribute 

__fastsprout_ops__: frozenset[str] = frozenset({'extra_write'})

Field

Bases: Generic[T, FieldOwner, FieldOrm]

Typed field descriptor.

Annotation form: is_active: Field[bool]

Behavior
  • On class: Hero.is_active → FieldRef[Hero, bool, OrmCtor] (carries entity binding for repository.select; the SQLAlchemy overload types .orm as Mapped[T])
  • On instance: hero.is_active → bool (the value)

Defaults are declared through the specifier, not raw assignment — this keeps both the type checker and the runtime model build happy:

class Hero(BaseSchema):
    age: Field[int] = Field(default=0)
    uid: Field[UUID] = Field(default_factory=uuid4)

Use .set(value) for partial-update assignment objects: Hero.is_active.set(True) # FieldAssignment[bool]

__slots__ class-attribute instance-attribute 

__slots__ = ('default', 'default_factory', 'name', 'orm')

__fastsprout_ops__ class-attribute 

__fastsprout_ops__: frozenset[str] = frozenset({'read', 'write'})

name instance-attribute 

name: str = ''

orm instance-attribute 

orm: FieldOrm | None = None

default instance-attribute 

default: T | UndefinedType = default

default_factory instance-attribute 

default_factory: Callable[[], T] | None = default_factory

__init__ 

__init__(
    *,
    default: T | UndefinedType = Undefined,
    default_factory: Callable[[], T] | None = None,
) -> None

descriptor classmethod 

descriptor(name: str, orm: FieldOrm | None = None) -> Self

Internal: build the descriptor installed on model classes.

Bypasses the public specifier constructor — framework use only (metaclasses), never part of the user-facing API.

__set_name__ 

__set_name__(owner: type, name: str) -> None

set 

set(value: T) -> FieldAssignment[T]

__get__ 

__get__[E: SQLExtraReadable](
    instance: None, owner: type[E]
) -> FieldRef[E, T, Mapped[T]]

__get__[E: SQLExtraWritable](
    instance: None, owner: type[E]
) -> FieldRef[E, T, Mapped[T]]

__get__[E: SQLReadable](
    instance: None, owner: type[E]
) -> FieldRef[E, T, Mapped[T]]

__get__[E: SQLWritable](
    instance: None, owner: type[E]
) -> FieldRef[E, T, Mapped[T]]

__get__[E: SQLInternalable](
    instance: None, owner: type[E]
) -> FieldRef[E, T, Mapped[T]]

__get__[E: SQLFieldable](
    instance: None, owner: type[E]
) -> FieldRef[E, T, Mapped[T]]

__get__[E: Readable](
    instance: None, owner: type[E]
) -> FieldRef[E, T, FieldOrm | None]

__get__[OrmCtor](
    instance: None, owner: type[HasOrm[OrmCtor]]
) -> FieldRef[Any, T, OrmCtor]

__get__[E](instance: None, owner: type[E]) -> FieldRef[E, T, FieldOrm | None]

__get__(
    instance: None, owner: type[FieldOwner]
) -> FieldRef[FieldOwner, T, FieldOrm | None]

__get__(instance: FieldOwner, owner: type[FieldOwner]) -> T

__get__(instance: object | None, owner: type) -> FieldRef[Any, T, Any] | T

default_value 

default_value(owner_name: str) -> T

check_visibility 

check_visibility(owner: type) -> None

__set__ 

__set__(instance: FieldOwner, value: T) -> None

__repr__ 

__repr__() -> str

InternalField

Bases: Field[T, Internalable]

Accessible on the entity, excluded from every public DTO.

__fastsprout_ops__ class-attribute 

__fastsprout_ops__: frozenset[str] = frozenset({'internal'})

ReadField

Bases: Field[T, Readable]

Included in read DTOs, excluded from write-only DTOs.

__fastsprout_ops__ class-attribute 

__fastsprout_ops__: frozenset[str] = frozenset({'read'})

WriteField

Bases: Field[T, Writable]

Included in write DTOs, excluded from read-only DTOs.

__fastsprout_ops__ class-attribute 

__fastsprout_ops__: frozenset[str] = frozenset({'write'})

BaseSchema

Bases: Schema, EntityVisibility, BaseModel

Base schema with type-safe field descriptors.

Subclasses declare fields with Field[T] annotations:

class Hero(BaseSchema):
    id: Field[UUID]
    is_active: Field[bool]
    name: Field[str]
Then

hero = Hero(id=uuid(), is_active=True, name="SuperMan") hero.is_active # bool Hero.is_active # Field[bool] Hero.is_active.set(True) # FieldAssignment[bool]

model_config class-attribute 

model_config: ConfigDict = ConfigDict(
    alias_generator=AliasGenerator(
        alias=to_snake, validation_alias=to_camel, serialization_alias=to_camel
    ),
    populate_by_name=True,
)

Schema

Declare a FastSprout schema without requiring runtime validation.

__slots__ class-attribute instance-attribute 

__slots__ = ()

Chunk

Bases: AsyncIterable[T]

A lazy input batch that dependencies may replace.

source instance-attribute 

source: AnyIterable[T] = source

__init__ 

__init__(source: AnyIterable[T]) -> None

__aiter__ 

__aiter__() -> AsyncIterator[T]

UndefinedType

Sentinel type for 'no value provided'.

fastsprout's own PydanticUndefined: a single shared singleton, falsy, safe to copy/pickle, usable anywhere a missing value must be distinguished from None (which is a real value).

__slots__ class-attribute instance-attribute 

__slots__ = ()

__bool__ 

__bool__() -> bool

__copy__ 

__copy__() -> UndefinedType

__deepcopy__ 

__deepcopy__(memo: dict[int, Any]) -> UndefinedType

__reduce__ 

__reduce__() -> str

__repr__ 

__repr__() -> str

Context 

Context(provider: Callable[..., Schema] | None = None) -> Any

Request a typed value from the current invocation or its provider.

hidden_lazy_await 

hidden_lazy_await[**P, R](method: Callable[P, Awaitable[R]]) -> Callable[P, R]

hidden_lazy_await[**P, R](method: Callable[P, R]) -> Callable[P, R]

hidden_lazy_await[**P, R](
    method: Callable[P, Awaitable[R] | R],
) -> Callable[P, R]

typed_dataclass 

typed_dataclass[C](
    cls: type[C], *, frozen: bool = False, kw_only: bool = False
) -> type[C]

typed_dataclass[C](
    cls: None = None, *, frozen: bool = False, kw_only: bool = False
) -> Callable[[type[C]], type[C]]

typed_dataclass[C](
    cls: type[C] | None = None, *, frozen: bool = False, kw_only: bool = False
) -> type[C] | Callable[[type[C]], type[C]]

Apply stdlib @dataclass + install Field[T] descriptors.

Auto-generated init, repr, eq. No runtime validation.

Example

@typed_dataclass class User: field_int: Field[int] field_str: Field[str]

Depends 

Depends(
    dependency: Callable[..., Any] | None = None, *, use_cache: bool = True
) -> Any

derive_read_dto 

derive_read_dto[E](entity: type[E]) -> type[E]

Derive a DTO exposing fields marked for reading.

derive_read_write_dto 

derive_read_write_dto[E](entity: type[E]) -> type[E]

Derive a DTO exposing read and write fields, excluding internal fields.

derive_write_dto 

derive_write_dto[E](entity: type[E]) -> type[E]

Derive a DTO exposing fields marked for writing.

dataclass 

typed_dataclass[C](
    cls: type[C], *, frozen: bool = False, kw_only: bool = False
) -> type[C]

typed_dataclass[C](
    cls: None = None, *, frozen: bool = False, kw_only: bool = False
) -> Callable[[type[C]], type[C]]

dataclass[C](
    cls: type[C] | None = None, *, frozen: bool = False, kw_only: bool = False
) -> type[C] | Callable[[type[C]], type[C]]

Apply stdlib @dataclass + install Field[T] descriptors.

Auto-generated init, repr, eq. No runtime validation.

Example

@typed_dataclass class User: field_int: Field[int] field_str: Field[str]