Mutations

Sync helpers

apply_input

apply_input(
    instance: Model,
    data: Any,
    *,
    field_map: dict[str, str] | None = None,
    exclude_fields: list[str] | None = None,
) -> ChangeResult

Set attributes from data onto instance without saving.

Returns a :class:ChangeResult describing fields whose value actually changed. Useful when a service wants to inspect what the input would change before deciding whether to persist.

create_from_input

create_from_input(
    model: type[ModelT],
    data: Any,
    *,
    field_map: dict[str, str] | None = None,
    exclude_fields: list[str] | None = None,
    m2m: dict[str, Any] | None = None,
    children: Mapping[str, ChildSpec] | None = None,
) -> ChangeResult[ModelT]

Build, save(), and return a fresh instance of model.

Regular fields come from data (a dataclass, dict, or object with __dict__); M2M assignments are applied post-save via the m2m kwarg, mapping attribute name to the value to set().

children maps a reverse-FK relation name to a :class:~rest_framework_services.ChildSpec; the matching child rows are read from data[relation] and persisted post-save (recursively). Keep the whole call inside the service's atomic block.

update_from_input

update_from_input(
    instance: ModelT,
    data: Any,
    *,
    field_map: dict[str, str] | None = None,
    exclude_fields: list[str] | None = None,
    m2m: dict[str, Any] | None = None,
    update_fields: bool | list[str] = True,
    children: Mapping[str, ChildSpec] | None = None,
) -> ChangeResult[ModelT]

Update instance with values from data, persisting only deltas.

By default (update_fields=True), the save call uses update_fields=<changed> to write the minimal set of columns. auto_now=True fields (e.g. updated_at) are automatically added to that list so they are refreshed alongside the mutation. Pass False to perform a full save, or an explicit list to control exactly which columns are written (no auto-injection in that case).

children maps a reverse-FK relation name to a :class:~rest_framework_services.ChildSpec. The child rows from data[relation] are reconciled with the existing collection (create / update / orphan-remove per the spec's mode); a relation the input omits is left untouched. Keep the call inside the service's atomic block.

Async helpers

acreate_from_input async

acreate_from_input(
    model: type[ModelT],
    data: Any,
    *,
    field_map: dict[str, str] | None = None,
    exclude_fields: list[str] | None = None,
    m2m: dict[str, Any] | None = None,
    children: Mapping[str, ChildSpec] | None = None,
) -> ChangeResult[ModelT]

Async sibling of :func:create_from_input using asave()/aset().

aupdate_from_input async

aupdate_from_input(
    instance: ModelT,
    data: Any,
    *,
    field_map: dict[str, str] | None = None,
    exclude_fields: list[str] | None = None,
    m2m: dict[str, Any] | None = None,
    update_fields: bool | list[str] = True,
    children: Mapping[str, ChildSpec] | None = None,
) -> ChangeResult[ModelT]

Async sibling of :func:update_from_input using asave()/aset().