Module fl_server_api.serializers.training

View Source

# SPDX-FileCopyrightText: 2024 Benedikt Franke <benedikt.franke@dlr.de>
# SPDX-FileCopyrightText: 2024 Florian Heinrich <florian.heinrich@dlr.de>
#
# SPDX-License-Identifier: Apache-2.0

from dataclasses import dataclass, field
from marshmallow import fields, post_load, Schema
from typing import Any, Dict, List
from uuid import UUID

from fl_server_core.models.training import AggregationMethod, UncertaintyMethod


class CreateTrainingRequestSchema(Schema):
    """
    A schema for serializing and deserializing `CreateTrainingRequest` instances.
    """

    model_id = fields.UUID()
    """ID of the model to be trained."""
    target_num_updates = fields.Integer()
    """Target number of updates for the training process."""
    metric_names = fields.List(fields.Str())
    """Names of the metrics to be used in the training process."""
    aggregation_method = fields.Enum(
        AggregationMethod,
        required=True,
        dump_default=AggregationMethod.FED_AVG,
        by_value=True
    )
    """Method to be used for aggregating updates. Defaults to `FED_AVG`."""
    uncertainty_method = fields.Enum(
        UncertaintyMethod,
        required=False,
        dump_default=UncertaintyMethod.NONE,
        by_value=True
    )
    """Method to be used for handling uncertainty. Defaults to `NONE`."""
    options = fields.Dict(required=False, dump_default={})
    """Additional options for the training process. Defaults to an empty dictionary."""
    clients = fields.List(fields.UUID(), dump_default=[])
    """Clients participating in the training process. Defaults to an empty list."""

    @post_load
    def _make_create_training_request(self, data: Dict[str, Any], **kwargs):
        """
        Create a `CreateTrainingRequest` instance from the loaded data.

        This method is called after the data has been loaded and validated.

        Args:
            data (Dict[str, Any]): The loaded data.
            **kwargs: Additional keyword arguments.

        Returns:
            CreateTrainingRequest: The created `CreateTrainingRequest` instance.
        """
        return CreateTrainingRequest(**data)


@dataclass
class CreateTrainingRequest:
    """
    A data class representing a request to create a training process.

    Attributes:
        model_id (UUID): The ID of the model to be trained.
        target_num_updates (int): The target number of updates for the training process.
        metric_names (list[str]): The names of the metrics to be used in the training process.
        aggregation_method (AggregationMethod): The method to be used for aggregating updates. Defaults to FED_AVG.
        uncertainty_method (UncertaintyMethod): The method to be used for handling uncertainty. Defaults to NONE.
        options (Dict[str, Any]): Additional options for the training process. Defaults to an empty dictionary.
        clients (List[UUID]): The clients participating in the training process. Defaults to an empty list.
    """
    model_id: UUID
    """ID of the model to be trained."""
    target_num_updates: int
    """Target number of updates for the training process."""
    metric_names: list[str]
    """Names of the metrics to be used in the training process."""
    aggregation_method: AggregationMethod = field(default=AggregationMethod.FED_AVG)  # type: ignore[assignment]
    """Method to be used for aggregating updates. Defaults to `FED_AVG`."""
    uncertainty_method: UncertaintyMethod = field(default=UncertaintyMethod.NONE)  # type: ignore[assignment]
    """Method to be used for handling uncertainty. Defaults to `NONE`."""
    options: Dict[str, Any] = field(default_factory=lambda: {})
    """Additional options for the training process. Defaults to an empty dictionary."""
    clients: List[UUID] = field(default_factory=lambda: [])
    """Clients participating in the training process. Defaults to an empty list."""


class ClientAdministrationBodySchema(Schema):
    """
    A schema for serializing and deserializing `ClientAdministrationBody` instances.
    """

    clients = fields.List(fields.UUID, required=True)
    """A list of UUIDs representing the clients to be administered."""

    @post_load
    def _make_client_administration_body(self, data: Dict[str, Any], **kwargs):
        """
        Create a `ClientAdministrationBody` instance from the loaded data.

        This method is called after the data has been loaded and validated.

        Args:
            data (Dict[str, Any]): The loaded data.
            **kwargs: Additional keyword arguments.

        Returns:
            ClientAdministrationBody: The created `ClientAdministrationBody` instance.
        """
        return ClientAdministrationBody(**data)


@dataclass
class ClientAdministrationBody:
    """
    A data class representing the body of a client administration request.
    """

    clients: List[UUID]
    """A list of UUIDs representing the clients to be administered."""

Classes

ClientAdministrationBody

class ClientAdministrationBody(
    clients: List[uuid.UUID]
)

A data class representing the body of a client administration request.

View Source

@dataclass
class ClientAdministrationBody:
    """
    A data class representing the body of a client administration request.
    """

    clients: List[UUID]
    """A list of UUIDs representing the clients to be administered."""

---

ClientAdministrationBodySchema

class ClientAdministrationBodySchema(
    *,
    only: 'types.StrSequenceOrSet | None' = None,
    exclude: 'types.StrSequenceOrSet' = (),
    many: 'bool' = False,
    context: 'dict | None' = None,
    load_only: 'types.StrSequenceOrSet' = (),
    dump_only: 'types.StrSequenceOrSet' = (),
    partial: 'bool | types.StrSequenceOrSet' = False,
    unknown: 'str | None' = None
)

A schema for serializing and deserializing ClientAdministrationBody instances.

View Source

class ClientAdministrationBodySchema(Schema):
    """
    A schema for serializing and deserializing `ClientAdministrationBody` instances.
    """

    clients = fields.List(fields.UUID, required=True)
    """A list of UUIDs representing the clients to be administered."""

    @post_load
    def _make_client_administration_body(self, data: Dict[str, Any], **kwargs):
        """
        Create a `ClientAdministrationBody` instance from the loaded data.

        This method is called after the data has been loaded and validated.

        Args:
            data (Dict[str, Any]): The loaded data.
            **kwargs: Additional keyword arguments.

        Returns:
            ClientAdministrationBody: The created `ClientAdministrationBody` instance.
        """
        return ClientAdministrationBody(**data)

---

Ancestors (in MRO)

• marshmallow.schema.Schema
• marshmallow.base.SchemaABC

Class variables

Meta

OPTIONS_CLASS

TYPE_MAPPING

clients

A list of UUIDs representing the clients to be administered.

error_messages

opts

Static methods

from_dict

def from_dict(
    fields: 'dict[str, ma_fields.Field | type]',
    *,
    name: 'str' = 'GeneratedSchema'
) -> 'type'

Generate a Schema class given a dictionary of fields.

.. code-block:: python

from marshmallow import Schema, fields

PersonSchema = Schema.from_dict({"name": fields.Str()})
print(PersonSchema().load({"name": "David"}))  # => {'name': 'David'}

Generated schemas are not added to the class registry and therefore cannot be referred to by name in Nested fields.

Parameters:

Name	Type	Description	Default
fields	dict	Dictionary mapping field names to field instances.	None
name	str	Optional name for the class, which will appear in the repr for the class. .. versionadded:: 3.0.0	None

View Source

    @classmethod
    def from_dict(
        cls,
        fields: dict[str, ma_fields.Field | type],
        *,
        name: str = "GeneratedSchema",
    ) -> type:
        """Generate a `Schema` class given a dictionary of fields.

        .. code-block:: python

            from marshmallow import Schema, fields

            PersonSchema = Schema.from_dict({"name": fields.Str()})
            print(PersonSchema().load({"name": "David"}))  # => {'name': 'David'}

        Generated schemas are not added to the class registry and therefore cannot
        be referred to by name in `Nested` fields.

        :param dict fields: Dictionary mapping field names to field instances.
        :param str name: Optional name for the class, which will appear in
            the ``repr`` for the class.

        .. versionadded:: 3.0.0
        """
        attrs = fields.copy()
        attrs["Meta"] = type(
            "GeneratedMeta", (getattr(cls, "Meta", object),), {"register": False}
        )
        schema_cls = type(name, (cls,), attrs)
        return schema_cls

Instance variables

dict_class

set_class

Methods

dump

def dump(
    self,
    obj: 'typing.Any',
    *,
    many: 'bool | None' = None
)

Serialize an object to native Python data types according to this

Schema's fields.

Parameters:

Name	Type	Description	Default
obj	None	The object to serialize.	None
many	None	Whether to serialize obj as a collection. If None, the value for self.many is used.	None

Returns:

Type	Description
None	Serialized data .. versionadded:: 1.0.0 .. versionchanged:: 3.0.0b7 This method returns the serialized data rather than a (data, errors) duple. A :exc:ValidationError <marshmallow.exceptions.ValidationError> is raised if obj is invalid. .. versionchanged:: 3.0.0rc9 Validation no longer occurs upon serialization.

View Source

    def dump(self, obj: typing.Any, *, many: bool | None = None):
        """Serialize an object to native Python data types according to this
        Schema's fields.

        :param obj: The object to serialize.
        :param many: Whether to serialize `obj` as a collection. If `None`, the value
            for `self.many` is used.
        :return: Serialized data

        .. versionadded:: 1.0.0
        .. versionchanged:: 3.0.0b7
            This method returns the serialized data rather than a ``(data, errors)`` duple.
            A :exc:`ValidationError <marshmallow.exceptions.ValidationError>` is raised
            if ``obj`` is invalid.
        .. versionchanged:: 3.0.0rc9
            Validation no longer occurs upon serialization.
        """
        many = self.many if many is None else bool(many)
        if self._has_processors(PRE_DUMP):
            processed_obj = self._invoke_dump_processors(
                PRE_DUMP, obj, many=many, original_data=obj
            )
        else:
            processed_obj = obj

        result = self._serialize(processed_obj, many=many)

        if self._has_processors(POST_DUMP):
            result = self._invoke_dump_processors(
                POST_DUMP, result, many=many, original_data=obj
            )

        return result

dumps

def dumps(
    self,
    obj: 'typing.Any',
    *args,
    many: 'bool | None' = None,
    **kwargs
)

Same as :meth:dump, except return a JSON-encoded string.

Parameters:

Name	Type	Description	Default
obj	None	The object to serialize.	None
many	None	Whether to serialize obj as a collection. If None, the value for self.many is used.	None

Returns:

Type	Description
None	A json string .. versionadded:: 1.0.0 .. versionchanged:: 3.0.0b7 This method returns the serialized data rather than a (data, errors) duple. A :exc:ValidationError <marshmallow.exceptions.ValidationError> is raised if obj is invalid.

View Source

    def dumps(self, obj: typing.Any, *args, many: bool | None = None, **kwargs):
        """Same as :meth:`dump`, except return a JSON-encoded string.

        :param obj: The object to serialize.
        :param many: Whether to serialize `obj` as a collection. If `None`, the value
            for `self.many` is used.
        :return: A ``json`` string

        .. versionadded:: 1.0.0
        .. versionchanged:: 3.0.0b7
            This method returns the serialized data rather than a ``(data, errors)`` duple.
            A :exc:`ValidationError <marshmallow.exceptions.ValidationError>` is raised
            if ``obj`` is invalid.
        """
        serialized = self.dump(obj, many=many)
        return self.opts.render_module.dumps(serialized, *args, **kwargs)

get_attribute

def get_attribute(
    self,
    obj: 'typing.Any',
    attr: 'str',
    default: 'typing.Any'
)

Defines how to pull values from an object to serialize.

.. versionadded:: 2.0.0

.. versionchanged:: 3.0.0a1 Changed position of obj and attr.

View Source

    def get_attribute(self, obj: typing.Any, attr: str, default: typing.Any):
        """Defines how to pull values from an object to serialize.

        .. versionadded:: 2.0.0

        .. versionchanged:: 3.0.0a1
            Changed position of ``obj`` and ``attr``.
        """
        return get_value(obj, attr, default)

handle_error

def handle_error(
    self,
    error: 'ValidationError',
    data: 'typing.Any',
    *,
    many: 'bool',
    **kwargs
)

Custom error handler function for the schema.

Parameters:

Name	Type	Description	Default
error	None	The ValidationError raised during (de)serialization.	None
data	None	The original input data.	None
many	None	Value of many on dump or load.	None
partial	None	Value of partial on load. .. versionadded:: 2.0.0 .. versionchanged:: 3.0.0rc9 Receives many and partial (on deserialization) as keyword arguments.	None

View Source

    def handle_error(
        self, error: ValidationError, data: typing.Any, *, many: bool, **kwargs
    ):
        """Custom error handler function for the schema.

        :param error: The `ValidationError` raised during (de)serialization.
        :param data: The original input data.
        :param many: Value of ``many`` on dump or load.
        :param partial: Value of ``partial`` on load.

        .. versionadded:: 2.0.0

        .. versionchanged:: 3.0.0rc9
            Receives `many` and `partial` (on deserialization) as keyword arguments.
        """
        pass

load

def load(
    self,
    data: 'typing.Mapping[str, typing.Any] | typing.Iterable[typing.Mapping[str, typing.Any]]',
    *,
    many: 'bool | None' = None,
    partial: 'bool | types.StrSequenceOrSet | None' = None,
    unknown: 'str | None' = None
)

Deserialize a data structure to an object defined by this Schema's fields.

Parameters:

Name	Type	Description	Default
data	None	The data to deserialize.	None
many	None	Whether to deserialize data as a collection. If None, the value for self.many is used.	None
partial	None	Whether to ignore missing fields and not require any fields declared. Propagates down to Nested fields as well. If its value is an iterable, only missing fields listed in that iterable will be ignored. Use dot delimiters to specify nested fields.	None
unknown	None	Whether to exclude, include, or raise an error for unknown fields in the data. Use EXCLUDE, INCLUDE or RAISE. If None, the value for self.unknown is used.	None

Returns:

Type	Description
None	Deserialized data .. versionadded:: 1.0.0 .. versionchanged:: 3.0.0b7 This method returns the deserialized data rather than a (data, errors) duple. A :exc:ValidationError <marshmallow.exceptions.ValidationError> is raised if invalid data are passed.

View Source

    def load(
        self,
        data: (
            typing.Mapping[str, typing.Any]
            | typing.Iterable[typing.Mapping[str, typing.Any]]
        ),
        *,
        many: bool | None = None,
        partial: bool | types.StrSequenceOrSet | None = None,
        unknown: str | None = None,
    ):
        """Deserialize a data structure to an object defined by this Schema's fields.

        :param data: The data to deserialize.
        :param many: Whether to deserialize `data` as a collection. If `None`, the
            value for `self.many` is used.
        :param partial: Whether to ignore missing fields and not require
            any fields declared. Propagates down to ``Nested`` fields as well. If
            its value is an iterable, only missing fields listed in that iterable
            will be ignored. Use dot delimiters to specify nested fields.
        :param unknown: Whether to exclude, include, or raise an error for unknown
            fields in the data. Use `EXCLUDE`, `INCLUDE` or `RAISE`.
            If `None`, the value for `self.unknown` is used.
        :return: Deserialized data

        .. versionadded:: 1.0.0
        .. versionchanged:: 3.0.0b7
            This method returns the deserialized data rather than a ``(data, errors)`` duple.
            A :exc:`ValidationError <marshmallow.exceptions.ValidationError>` is raised
            if invalid data are passed.
        """
        return self._do_load(
            data, many=many, partial=partial, unknown=unknown, postprocess=True
        )

loads

def loads(
    self,
    json_data: 'str',
    *,
    many: 'bool | None' = None,
    partial: 'bool | types.StrSequenceOrSet | None' = None,
    unknown: 'str | None' = None,
    **kwargs
)

Same as :meth:load, except it takes a JSON string as input.

Parameters:

Name	Type	Description	Default
json_data	None	A JSON string of the data to deserialize.	None
many	None	Whether to deserialize obj as a collection. If None, the value for self.many is used.	None
partial	None	Whether to ignore missing fields and not require any fields declared. Propagates down to Nested fields as well. If its value is an iterable, only missing fields listed in that iterable will be ignored. Use dot delimiters to specify nested fields.	None
unknown	None	Whether to exclude, include, or raise an error for unknown fields in the data. Use EXCLUDE, INCLUDE or RAISE. If None, the value for self.unknown is used.	None

Returns:

Type	Description
None	Deserialized data .. versionadded:: 1.0.0 .. versionchanged:: 3.0.0b7 This method returns the deserialized data rather than a (data, errors) duple. A :exc:ValidationError <marshmallow.exceptions.ValidationError> is raised if invalid data are passed.

View Source

    def loads(
        self,
        json_data: str,
        *,
        many: bool | None = None,
        partial: bool | types.StrSequenceOrSet | None = None,
        unknown: str | None = None,
        **kwargs,
    ):
        """Same as :meth:`load`, except it takes a JSON string as input.

        :param json_data: A JSON string of the data to deserialize.
        :param many: Whether to deserialize `obj` as a collection. If `None`, the
            value for `self.many` is used.
        :param partial: Whether to ignore missing fields and not require
            any fields declared. Propagates down to ``Nested`` fields as well. If
            its value is an iterable, only missing fields listed in that iterable
            will be ignored. Use dot delimiters to specify nested fields.
        :param unknown: Whether to exclude, include, or raise an error for unknown
            fields in the data. Use `EXCLUDE`, `INCLUDE` or `RAISE`.
            If `None`, the value for `self.unknown` is used.
        :return: Deserialized data

        .. versionadded:: 1.0.0
        .. versionchanged:: 3.0.0b7
            This method returns the deserialized data rather than a ``(data, errors)`` duple.
            A :exc:`ValidationError <marshmallow.exceptions.ValidationError>` is raised
            if invalid data are passed.
        """
        data = self.opts.render_module.loads(json_data, **kwargs)
        return self.load(data, many=many, partial=partial, unknown=unknown)

on_bind_field

def on_bind_field(
    self,
    field_name: 'str',
    field_obj: 'ma_fields.Field'
) -> 'None'

Hook to modify a field when it is bound to the Schema.

No-op by default.

View Source

    def on_bind_field(self, field_name: str, field_obj: ma_fields.Field) -> None:
        """Hook to modify a field when it is bound to the `Schema`.

        No-op by default.
        """
        return None

validate

def validate(
    self,
    data: 'typing.Mapping[str, typing.Any] | typing.Iterable[typing.Mapping[str, typing.Any]]',
    *,
    many: 'bool | None' = None,
    partial: 'bool | types.StrSequenceOrSet | None' = None
) -> 'dict[str, list[str]]'

Validate data against the schema, returning a dictionary of

validation errors.

Parameters:

Name	Type	Description	Default
data	None	The data to validate.	None
many	None	Whether to validate data as a collection. If None, the value for self.many is used.	None
partial	None	Whether to ignore missing fields and not require any fields declared. Propagates down to Nested fields as well. If its value is an iterable, only missing fields listed in that iterable will be ignored. Use dot delimiters to specify nested fields.	None

Returns:

Type	Description
None	A dictionary of validation errors. .. versionadded:: 1.1.0

View Source

    def validate(
        self,
        data: (
            typing.Mapping[str, typing.Any]
            | typing.Iterable[typing.Mapping[str, typing.Any]]
        ),
        *,
        many: bool | None = None,
        partial: bool | types.StrSequenceOrSet | None = None,
    ) -> dict[str, list[str]]:
        """Validate `data` against the schema, returning a dictionary of
        validation errors.

        :param data: The data to validate.
        :param many: Whether to validate `data` as a collection. If `None`, the
            value for `self.many` is used.
        :param partial: Whether to ignore missing fields and not require
            any fields declared. Propagates down to ``Nested`` fields as well. If
            its value is an iterable, only missing fields listed in that iterable
            will be ignored. Use dot delimiters to specify nested fields.
        :return: A dictionary of validation errors.

        .. versionadded:: 1.1.0
        """
        try:
            self._do_load(data, many=many, partial=partial, postprocess=False)
        except ValidationError as exc:
            return typing.cast(typing.Dict[str, typing.List[str]], exc.messages)
        return {}

CreateTrainingRequest

class CreateTrainingRequest(
    model_id: uuid.UUID,
    target_num_updates: int,
    metric_names: list[str],
    aggregation_method: fl_server_core.models.training.AggregationMethod = AggregationMethod.FED_AVG,
    uncertainty_method: fl_server_core.models.training.UncertaintyMethod = UncertaintyMethod.NONE,
    options: Dict[str, Any] = <factory>,
    clients: List[uuid.UUID] = <factory>
)

A data class representing a request to create a training process.

Attributes

Name	Type	Description	Default
model_id	UUID	The ID of the model to be trained.	None
target_num_updates	int	The target number of updates for the training process.	None
metric_names	list[str]	The names of the metrics to be used in the training process.	None
aggregation_method	AggregationMethod	The method to be used for aggregating updates. Defaults to FED_AVG.	FED_AVG
uncertainty_method	UncertaintyMethod	The method to be used for handling uncertainty. Defaults to NONE.	NONE
options	Dict[str, Any]	Additional options for the training process. Defaults to an empty dictionary.	an empty dictionary
clients	List[UUID]	The clients participating in the training process. Defaults to an empty list.	an empty list

View Source

@dataclass
class CreateTrainingRequest:
    """
    A data class representing a request to create a training process.

    Attributes:
        model_id (UUID): The ID of the model to be trained.
        target_num_updates (int): The target number of updates for the training process.
        metric_names (list[str]): The names of the metrics to be used in the training process.
        aggregation_method (AggregationMethod): The method to be used for aggregating updates. Defaults to FED_AVG.
        uncertainty_method (UncertaintyMethod): The method to be used for handling uncertainty. Defaults to NONE.
        options (Dict[str, Any]): Additional options for the training process. Defaults to an empty dictionary.
        clients (List[UUID]): The clients participating in the training process. Defaults to an empty list.
    """
    model_id: UUID
    """ID of the model to be trained."""
    target_num_updates: int
    """Target number of updates for the training process."""
    metric_names: list[str]
    """Names of the metrics to be used in the training process."""
    aggregation_method: AggregationMethod = field(default=AggregationMethod.FED_AVG)  # type: ignore[assignment]
    """Method to be used for aggregating updates. Defaults to `FED_AVG`."""
    uncertainty_method: UncertaintyMethod = field(default=UncertaintyMethod.NONE)  # type: ignore[assignment]
    """Method to be used for handling uncertainty. Defaults to `NONE`."""
    options: Dict[str, Any] = field(default_factory=lambda: {})
    """Additional options for the training process. Defaults to an empty dictionary."""
    clients: List[UUID] = field(default_factory=lambda: [])
    """Clients participating in the training process. Defaults to an empty list."""

---

Class variables

aggregation_method

uncertainty_method

CreateTrainingRequestSchema

class CreateTrainingRequestSchema(
    *,
    only: 'types.StrSequenceOrSet | None' = None,
    exclude: 'types.StrSequenceOrSet' = (),
    many: 'bool' = False,
    context: 'dict | None' = None,
    load_only: 'types.StrSequenceOrSet' = (),
    dump_only: 'types.StrSequenceOrSet' = (),
    partial: 'bool | types.StrSequenceOrSet' = False,
    unknown: 'str | None' = None
)

A schema for serializing and deserializing CreateTrainingRequest instances.

View Source

class CreateTrainingRequestSchema(Schema):
    """
    A schema for serializing and deserializing `CreateTrainingRequest` instances.
    """

    model_id = fields.UUID()
    """ID of the model to be trained."""
    target_num_updates = fields.Integer()
    """Target number of updates for the training process."""
    metric_names = fields.List(fields.Str())
    """Names of the metrics to be used in the training process."""
    aggregation_method = fields.Enum(
        AggregationMethod,
        required=True,
        dump_default=AggregationMethod.FED_AVG,
        by_value=True
    )
    """Method to be used for aggregating updates. Defaults to `FED_AVG`."""
    uncertainty_method = fields.Enum(
        UncertaintyMethod,
        required=False,
        dump_default=UncertaintyMethod.NONE,
        by_value=True
    )
    """Method to be used for handling uncertainty. Defaults to `NONE`."""
    options = fields.Dict(required=False, dump_default={})
    """Additional options for the training process. Defaults to an empty dictionary."""
    clients = fields.List(fields.UUID(), dump_default=[])
    """Clients participating in the training process. Defaults to an empty list."""

    @post_load
    def _make_create_training_request(self, data: Dict[str, Any], **kwargs):
        """
        Create a `CreateTrainingRequest` instance from the loaded data.

        This method is called after the data has been loaded and validated.

        Args:
            data (Dict[str, Any]): The loaded data.
            **kwargs: Additional keyword arguments.

        Returns:
            CreateTrainingRequest: The created `CreateTrainingRequest` instance.
        """
        return CreateTrainingRequest(**data)

---

Ancestors (in MRO)

• marshmallow.schema.Schema
• marshmallow.base.SchemaABC

Class variables

Meta

OPTIONS_CLASS

TYPE_MAPPING

aggregation_method

Method to be used for aggregating updates. Defaults to FED_AVG.

clients

Clients participating in the training process. Defaults to an empty list.

error_messages

metric_names

Names of the metrics to be used in the training process.

model_id

ID of the model to be trained.

options

Additional options for the training process. Defaults to an empty dictionary.

opts

target_num_updates

Target number of updates for the training process.

uncertainty_method

Method to be used for handling uncertainty. Defaults to NONE.

Static methods

from_dict

def from_dict(
    fields: 'dict[str, ma_fields.Field | type]',
    *,
    name: 'str' = 'GeneratedSchema'
) -> 'type'

Generate a Schema class given a dictionary of fields.

.. code-block:: python

from marshmallow import Schema, fields

PersonSchema = Schema.from_dict({"name": fields.Str()})
print(PersonSchema().load({"name": "David"}))  # => {'name': 'David'}

Generated schemas are not added to the class registry and therefore cannot be referred to by name in Nested fields.

Parameters:

Name	Type	Description	Default
fields	dict	Dictionary mapping field names to field instances.	None
name	str	Optional name for the class, which will appear in the repr for the class. .. versionadded:: 3.0.0	None

View Source

    @classmethod
    def from_dict(
        cls,
        fields: dict[str, ma_fields.Field | type],
        *,
        name: str = "GeneratedSchema",
    ) -> type:
        """Generate a `Schema` class given a dictionary of fields.

        .. code-block:: python

            from marshmallow import Schema, fields

            PersonSchema = Schema.from_dict({"name": fields.Str()})
            print(PersonSchema().load({"name": "David"}))  # => {'name': 'David'}

        Generated schemas are not added to the class registry and therefore cannot
        be referred to by name in `Nested` fields.

        :param dict fields: Dictionary mapping field names to field instances.
        :param str name: Optional name for the class, which will appear in
            the ``repr`` for the class.

        .. versionadded:: 3.0.0
        """
        attrs = fields.copy()
        attrs["Meta"] = type(
            "GeneratedMeta", (getattr(cls, "Meta", object),), {"register": False}
        )
        schema_cls = type(name, (cls,), attrs)
        return schema_cls

Instance variables

dict_class

set_class

Methods

dump

def dump(
    self,
    obj: 'typing.Any',
    *,
    many: 'bool | None' = None
)

Serialize an object to native Python data types according to this

Schema's fields.

Parameters:

Name	Type	Description	Default
obj	None	The object to serialize.	None
many	None	Whether to serialize obj as a collection. If None, the value for self.many is used.	None

Returns:

Type	Description
None	Serialized data .. versionadded:: 1.0.0 .. versionchanged:: 3.0.0b7 This method returns the serialized data rather than a (data, errors) duple. A :exc:ValidationError <marshmallow.exceptions.ValidationError> is raised if obj is invalid. .. versionchanged:: 3.0.0rc9 Validation no longer occurs upon serialization.

View Source

    def dump(self, obj: typing.Any, *, many: bool | None = None):
        """Serialize an object to native Python data types according to this
        Schema's fields.

        :param obj: The object to serialize.
        :param many: Whether to serialize `obj` as a collection. If `None`, the value
            for `self.many` is used.
        :return: Serialized data

        .. versionadded:: 1.0.0
        .. versionchanged:: 3.0.0b7
            This method returns the serialized data rather than a ``(data, errors)`` duple.
            A :exc:`ValidationError <marshmallow.exceptions.ValidationError>` is raised
            if ``obj`` is invalid.
        .. versionchanged:: 3.0.0rc9
            Validation no longer occurs upon serialization.
        """
        many = self.many if many is None else bool(many)
        if self._has_processors(PRE_DUMP):
            processed_obj = self._invoke_dump_processors(
                PRE_DUMP, obj, many=many, original_data=obj
            )
        else:
            processed_obj = obj

        result = self._serialize(processed_obj, many=many)

        if self._has_processors(POST_DUMP):
            result = self._invoke_dump_processors(
                POST_DUMP, result, many=many, original_data=obj
            )

        return result

dumps

def dumps(
    self,
    obj: 'typing.Any',
    *args,
    many: 'bool | None' = None,
    **kwargs
)

Same as :meth:dump, except return a JSON-encoded string.

Parameters:

Name	Type	Description	Default
obj	None	The object to serialize.	None
many	None	Whether to serialize obj as a collection. If None, the value for self.many is used.	None

Returns:

Type	Description
None	A json string .. versionadded:: 1.0.0 .. versionchanged:: 3.0.0b7 This method returns the serialized data rather than a (data, errors) duple. A :exc:ValidationError <marshmallow.exceptions.ValidationError> is raised if obj is invalid.

View Source

    def dumps(self, obj: typing.Any, *args, many: bool | None = None, **kwargs):
        """Same as :meth:`dump`, except return a JSON-encoded string.

        :param obj: The object to serialize.
        :param many: Whether to serialize `obj` as a collection. If `None`, the value
            for `self.many` is used.
        :return: A ``json`` string

        .. versionadded:: 1.0.0
        .. versionchanged:: 3.0.0b7
            This method returns the serialized data rather than a ``(data, errors)`` duple.
            A :exc:`ValidationError <marshmallow.exceptions.ValidationError>` is raised
            if ``obj`` is invalid.
        """
        serialized = self.dump(obj, many=many)
        return self.opts.render_module.dumps(serialized, *args, **kwargs)

get_attribute

def get_attribute(
    self,
    obj: 'typing.Any',
    attr: 'str',
    default: 'typing.Any'
)

Defines how to pull values from an object to serialize.

.. versionadded:: 2.0.0

.. versionchanged:: 3.0.0a1 Changed position of obj and attr.

View Source

    def get_attribute(self, obj: typing.Any, attr: str, default: typing.Any):
        """Defines how to pull values from an object to serialize.

        .. versionadded:: 2.0.0

        .. versionchanged:: 3.0.0a1
            Changed position of ``obj`` and ``attr``.
        """
        return get_value(obj, attr, default)

handle_error

def handle_error(
    self,
    error: 'ValidationError',
    data: 'typing.Any',
    *,
    many: 'bool',
    **kwargs
)

Custom error handler function for the schema.

Parameters:

Name	Type	Description	Default
error	None	The ValidationError raised during (de)serialization.	None
data	None	The original input data.	None
many	None	Value of many on dump or load.	None
partial	None	Value of partial on load. .. versionadded:: 2.0.0 .. versionchanged:: 3.0.0rc9 Receives many and partial (on deserialization) as keyword arguments.	None

View Source

    def handle_error(
        self, error: ValidationError, data: typing.Any, *, many: bool, **kwargs
    ):
        """Custom error handler function for the schema.

        :param error: The `ValidationError` raised during (de)serialization.
        :param data: The original input data.
        :param many: Value of ``many`` on dump or load.
        :param partial: Value of ``partial`` on load.

        .. versionadded:: 2.0.0

        .. versionchanged:: 3.0.0rc9
            Receives `many` and `partial` (on deserialization) as keyword arguments.
        """
        pass

load

def load(
    self,
    data: 'typing.Mapping[str, typing.Any] | typing.Iterable[typing.Mapping[str, typing.Any]]',
    *,
    many: 'bool | None' = None,
    partial: 'bool | types.StrSequenceOrSet | None' = None,
    unknown: 'str | None' = None
)

Deserialize a data structure to an object defined by this Schema's fields.

Parameters:

Name	Type	Description	Default
data	None	The data to deserialize.	None
many	None	Whether to deserialize data as a collection. If None, the value for self.many is used.	None
partial	None	Whether to ignore missing fields and not require any fields declared. Propagates down to Nested fields as well. If its value is an iterable, only missing fields listed in that iterable will be ignored. Use dot delimiters to specify nested fields.	None
unknown	None	Whether to exclude, include, or raise an error for unknown fields in the data. Use EXCLUDE, INCLUDE or RAISE. If None, the value for self.unknown is used.	None

Returns:

Type	Description
None	Deserialized data .. versionadded:: 1.0.0 .. versionchanged:: 3.0.0b7 This method returns the deserialized data rather than a (data, errors) duple. A :exc:ValidationError <marshmallow.exceptions.ValidationError> is raised if invalid data are passed.

View Source

    def load(
        self,
        data: (
            typing.Mapping[str, typing.Any]
            | typing.Iterable[typing.Mapping[str, typing.Any]]
        ),
        *,
        many: bool | None = None,
        partial: bool | types.StrSequenceOrSet | None = None,
        unknown: str | None = None,
    ):
        """Deserialize a data structure to an object defined by this Schema's fields.

        :param data: The data to deserialize.
        :param many: Whether to deserialize `data` as a collection. If `None`, the
            value for `self.many` is used.
        :param partial: Whether to ignore missing fields and not require
            any fields declared. Propagates down to ``Nested`` fields as well. If
            its value is an iterable, only missing fields listed in that iterable
            will be ignored. Use dot delimiters to specify nested fields.
        :param unknown: Whether to exclude, include, or raise an error for unknown
            fields in the data. Use `EXCLUDE`, `INCLUDE` or `RAISE`.
            If `None`, the value for `self.unknown` is used.
        :return: Deserialized data

        .. versionadded:: 1.0.0
        .. versionchanged:: 3.0.0b7
            This method returns the deserialized data rather than a ``(data, errors)`` duple.
            A :exc:`ValidationError <marshmallow.exceptions.ValidationError>` is raised
            if invalid data are passed.
        """
        return self._do_load(
            data, many=many, partial=partial, unknown=unknown, postprocess=True
        )

loads

def loads(
    self,
    json_data: 'str',
    *,
    many: 'bool | None' = None,
    partial: 'bool | types.StrSequenceOrSet | None' = None,
    unknown: 'str | None' = None,
    **kwargs
)

Same as :meth:load, except it takes a JSON string as input.

Parameters:

Name	Type	Description	Default
json_data	None	A JSON string of the data to deserialize.	None
many	None	Whether to deserialize obj as a collection. If None, the value for self.many is used.	None
partial	None	Whether to ignore missing fields and not require any fields declared. Propagates down to Nested fields as well. If its value is an iterable, only missing fields listed in that iterable will be ignored. Use dot delimiters to specify nested fields.	None
unknown	None	Whether to exclude, include, or raise an error for unknown fields in the data. Use EXCLUDE, INCLUDE or RAISE. If None, the value for self.unknown is used.	None

Returns:

Type	Description
None	Deserialized data .. versionadded:: 1.0.0 .. versionchanged:: 3.0.0b7 This method returns the deserialized data rather than a (data, errors) duple. A :exc:ValidationError <marshmallow.exceptions.ValidationError> is raised if invalid data are passed.

View Source

    def loads(
        self,
        json_data: str,
        *,
        many: bool | None = None,
        partial: bool | types.StrSequenceOrSet | None = None,
        unknown: str | None = None,
        **kwargs,
    ):
        """Same as :meth:`load`, except it takes a JSON string as input.

        :param json_data: A JSON string of the data to deserialize.
        :param many: Whether to deserialize `obj` as a collection. If `None`, the
            value for `self.many` is used.
        :param partial: Whether to ignore missing fields and not require
            any fields declared. Propagates down to ``Nested`` fields as well. If
            its value is an iterable, only missing fields listed in that iterable
            will be ignored. Use dot delimiters to specify nested fields.
        :param unknown: Whether to exclude, include, or raise an error for unknown
            fields in the data. Use `EXCLUDE`, `INCLUDE` or `RAISE`.
            If `None`, the value for `self.unknown` is used.
        :return: Deserialized data

        .. versionadded:: 1.0.0
        .. versionchanged:: 3.0.0b7
            This method returns the deserialized data rather than a ``(data, errors)`` duple.
            A :exc:`ValidationError <marshmallow.exceptions.ValidationError>` is raised
            if invalid data are passed.
        """
        data = self.opts.render_module.loads(json_data, **kwargs)
        return self.load(data, many=many, partial=partial, unknown=unknown)

on_bind_field

def on_bind_field(
    self,
    field_name: 'str',
    field_obj: 'ma_fields.Field'
) -> 'None'

Hook to modify a field when it is bound to the Schema.

No-op by default.

View Source

    def on_bind_field(self, field_name: str, field_obj: ma_fields.Field) -> None:
        """Hook to modify a field when it is bound to the `Schema`.

        No-op by default.
        """
        return None

validate

def validate(
    self,
    data: 'typing.Mapping[str, typing.Any] | typing.Iterable[typing.Mapping[str, typing.Any]]',
    *,
    many: 'bool | None' = None,
    partial: 'bool | types.StrSequenceOrSet | None' = None
) -> 'dict[str, list[str]]'

Validate data against the schema, returning a dictionary of

validation errors.

Parameters:

Name	Type	Description	Default
data	None	The data to validate.	None
many	None	Whether to validate data as a collection. If None, the value for self.many is used.	None
partial	None	Whether to ignore missing fields and not require any fields declared. Propagates down to Nested fields as well. If its value is an iterable, only missing fields listed in that iterable will be ignored. Use dot delimiters to specify nested fields.	None

Returns:

Type	Description
None	A dictionary of validation errors. .. versionadded:: 1.1.0

View Source

    def validate(
        self,
        data: (
            typing.Mapping[str, typing.Any]
            | typing.Iterable[typing.Mapping[str, typing.Any]]
        ),
        *,
        many: bool | None = None,
        partial: bool | types.StrSequenceOrSet | None = None,
    ) -> dict[str, list[str]]:
        """Validate `data` against the schema, returning a dictionary of
        validation errors.

        :param data: The data to validate.
        :param many: Whether to validate `data` as a collection. If `None`, the
            value for `self.many` is used.
        :param partial: Whether to ignore missing fields and not require
            any fields declared. Propagates down to ``Nested`` fields as well. If
            its value is an iterable, only missing fields listed in that iterable
            will be ignored. Use dot delimiters to specify nested fields.
        :return: A dictionary of validation errors.

        .. versionadded:: 1.1.0
        """
        try:
            self._do_load(data, many=many, partial=partial, postprocess=False)
        except ValidationError as exc:
            return typing.cast(typing.Dict[str, typing.List[str]], exc.messages)
        return {}