API Reference

class serpyco.AbstractValidator(schema_builder)

Abstract class for schema validators. Implementation shall raise serpyco.ValidationError().

json_schema(many=False)

Returns the schema that this validator uses to validate.

Return type

Dict[str, Any]

abstract validate(data, many=False)

Validates the given data against this object’s schema.

Return type

None

abstract validate_json(json_string, many=False)

Validates a JSON string against this object’s schema.

Return type

None

validate_user(data, many=False)

Validates the given data with the user-defined validators. See serpyco.field(). :type data: Union[Dict[str, Any], List[Dict[str, Any]]] :param data: data to validate, either a dict or a list of dicts (with many=True) :type many: bool :param many: if true, data will be considered as a list

Return type

None

exception serpyco.BaseSerpycoError
class serpyco.FieldEncoder

Base class for encoding fields to and from JSON encodable values

dump()

Convert the given value to a JSON encodable value

json_schema()

Return the JSON schema of the handled value type.

load()

Convert the given JSON value to its python counterpart

class serpyco.FieldHints(dict_key=None, ignore=False, getter=None, validator=None, description=None, examples=<factory>, format_=None, pattern=None, min_length=None, max_length=None, minimum=None, maximum=None, only=<factory>, exclude=<factory>, cast_on_load=False, allowed_values=<factory>, type_encoders=<factory>, load_as_type=None)
exception serpyco.NoEncoderError
exception serpyco.NotADataClassError
class serpyco.SchemaBuilder(dataclass, only=None, exclude=None, type_encoders=None, get_definition_name=<function default_get_definition_name>, strict=False)

Creates a JSON schema by inspecting a dataclass

json_schema(many=False)

Returns the json schema built from this SchemaBuilder’s dataclass.

Return type

Dict[str, Any]

nested_builders()

Returns a the list of nested builders this builder has created. Values are (definition name, builder) tuples.

Return type

List[Tuple[str, SchemaBuilder]]

classmethod register_global_type(type_, encoder)

Can be used to register a custom encoder for the given type.

Return type

None

classmethod unregister_global_type(type_)

Removes a previously registered encoder for the given type.

Return type

None

exception serpyco.SchemaError
class serpyco.Serializer

Serializer class for dataclasses instances.

dataclass(self) type

Returns the dataclass used to construct this serializer.

dump(self, obj: typing.Union[object, typing.Iterable[object]], bool validate: bool = False, bool many: bool = False)

Dumps the object(s) in the form of a dict/list only composed of builtin python types.

Parameters

validate – if True, the dumped data will be validated.

dump_json(self, obj: typing.Union[object, typing.Iterable[object]], bool validate: bool = False, bool many: bool = False) unicode

Dumps the object(s) in the form of a JSON string.

Parameters

validate – if True, the dumped data will be validated

f

alias of UUID

get_dict_path(self, obj_path: Sequence[str]) List[str]

Returns the path of a field in dumped dictionaries. :param obj_path: list of field names, for example [“foo”, “bar”] to get the dict path of foo.bar

get_object_path(self, dict_path: Sequence[str]) List[str]

Returns the path of a field in loaded objects. :param dict_path: list of dictionary keys, for example [“foo”, “bar”] to get the object path of {“foo”: {“bar”: 42}}

json_schema(self, many: bool = False) JsonDict

Returns the JSON schema of the underlying validator.

load(self, data: typing.Union[dict, typing.Iterable[dict]], bool validate: bool = True, bool many: bool = False)

Loads the given data and returns object(s) of this serializer’s dataclass.

Parameters

validate – if True, the data will be validated before creating objects

load_json(self, unicode js, bool validate: bool = True, bool many: bool = False)

Loads the given JSON string and returns object(s) of this serializer’s dataclass.

Parameters

validate – if True, the JSON will be validated before creating objects

register_global_type(type cls, field_type: typing.Any, FieldEncoder encoder: FieldEncoder) None

Registers a encoder/decoder for the given type.

unregister_global_type(type cls, field_type: typing.Any) None

Removes a previously registered encoder for the given type.

class serpyco.SerializerMixin

Base class that provides load/dump, load_json/dump_json methods.

dump(validate=False)

Dump the object to a dict.

Return type

Dict[str, Any]

dump_json(validate=False)

Dump the object to a JSON string.

Return type

str

classmethod load(data, validate=True)

Load the given dict an return a new object.

Return type

TypeVar(T, bound= SerializerMixin)

classmethod load_json(json_string, validate=True)

Load the given JSON string an return a new object.

Return type

TypeVar(T, bound= SerializerMixin)

classmethod serializer()

Serializer instance for this class.

Return type

Serializer

class serpyco.StringFormat(value)

Possible formats for a string field

exception serpyco.ValidationError(msg, errors=None)

Raised when an error is found during validation of data.

Parameters
  • msg (str) – formatted exception message(s).

  • errors (Optional[Dict[str, str]]) – dictionary of error message(s) where the key

is the JSON path to the invalid data.

serpyco.field(dict_key=None, ignore=False, getter=None, validator=None, cast_on_load=False, description=None, examples=None, allowed_values=None, **kwargs)

Convenience function to setup Serializer hints on dataclass fields. Call it at field declaration as you would do with dataclasses.field(). Additional parameters will be passed verbatim to dataclasses.field().

Parameters
  • dict_key (Optional[str]) – key of the field in the dumped dictionary.

  • ignore (bool) – if True, the field won’t be considered by Serpyco.

  • getter (Optional[Callable[[object], Any]]) – callable used to get values of this field when dumping. Must take one object argument.

  • validator (Optional[Callable[[Any], None]]) – callable used to perform custom validation of this field. Will be called with values of the field, shall raise ValidationError() if the value is not valid.

  • cast_on_load (bool) – when true, dict values for this field are constructed from the field’s type.

  • description (Optional[str]) – a description for the field. Will be included in the generated JSON schema.

  • examples (Optional[List[str]]) – a list of example usages for the field. Will be included in the generated JSON schema.

  • allowed_values (Optional[List[Any]]) – if given only values in this list will be considered valid during validation.

Return type

Any

serpyco.nested_field(only=None, exclude=None, type_encoders=None, load_as_type=None, dict_key=None, ignore=False, getter=None, validator=None, description=None, examples=None, **kwargs)

Convenience function to setup Serializer hints on nested dataclass fields. Call it at field declaration as you would do with dataclasses.field(). Additional parameters will be passed verbatim to dataclasses.field().

Parameters
  • only (Optional[List[str]]) – if present, only fields in this list will be serialized.

  • exclude (Optional[List[str]]) – if present, fields in this list will not be serialized.

  • dict_key (Optional[str]) – key of the field in the dumped dictionary.

  • ignore (bool) – if True, the field won’t be considered by Serpyco.

  • getter (Optional[Callable[[object], Any]]) – callable used to get values of this field. Must take one object argument.

  • validator (Optional[Callable[[Any], None]]) – callable used to perform custom validation of this field. Will be called with values of the field, shall raise ValidationError() if the value is not valid.

  • description (Optional[str]) – a description for the field. Will be included in the generated JSON schema.

  • examples (Optional[List[str]]) – a list of example usages for the field. Will be included in the generated JSON schema.

Return type

Any

serpyco.number_field(dict_key=None, ignore=False, getter=None, validator=None, cast_on_load=False, description=None, examples=None, allowed_values=None, minimum=None, maximum=None, **kwargs)

Convenience function to setup Serializer hints for a number (int/float) dataclass field. Call it at field declaration as you would do with dataclasses.field(). Additional parameters will be passed verbatim to dataclasses.field().

Parameters
  • dict_key (Optional[str]) – key of the field in the dumped dictionary.

  • ignore (bool) – if True, this field won’t be considered by Serpyco.

  • getter (Optional[Callable[[object], Any]]) – callable used to get values of this field when dumping. Must take one object argument.

  • validator (Optional[Callable[[Any], None]]) – callable used to perform custom validation of this field. Will be called with values of the field, shall raise ValidationError() if the value is not valid.

  • cast_on_load (bool) – when true, dict values for this field are constructed from the field’s type.

  • description (Optional[str]) – a description for the field. Will be included in the generated JSON schema.

  • examples (Optional[List[str]]) – a list of example usages for the field. Will be included in the generated JSON schema.

  • minimum (Optional[int]) – minimum allowed value (inclusive).

  • maximum (Optional[int]) – maximum allowed value (inclusive).

Return type

Any

serpyco.post_dump(method)

This decorator can be applied to a callable taking one dictionary and should return another dictionary. The method will then be called with each dictionary output by Serializer.dump or Serializer.dump_json after dumping them. :param: method method to call after dumping

Return type

Callable[[Dict[str, Any]], Dict[str, Any]]

serpyco.post_load(method)

This decorator can be applied to a callable taking one data class object and should return an object. The method will then be called with each object output by Serializer.load or Serializer.load_json before returning them. :param: method method to call after loading.

Return type

Callable[[object], object]

serpyco.pre_dump(method)

This decorator can be applied to a callable taking one object and should return an object of the dataclass it is declared in. The method will then be called with each object given to Serializer.dump or Serializer.dump_json before dumping them. :param: method method to call before dumping

Return type

Callable[[object], object]

serpyco.pre_load(method)

This decorator can be applied to a callable taking one dictionary and should return another dictionary. The method will then be called with each dictionary given to Serializer.load or Serializer.load before loading them in dataclass objects. :param: method method to call before loading

Return type

Callable[[Dict[str, Any]], Dict[str, Any]]

serpyco.string_field(dict_key=None, ignore=False, getter=None, validator=None, cast_on_load=False, description=None, examples=None, allowed_values=None, format_=None, pattern=None, min_length=None, max_length=None, **kwargs)

Convenience function to setup Serializer hints for a str dataclass field. Call it at field declaration as you would do with dataclasses.field(). Additional parameters will be passed verbatim to dataclasses.field().

Parameters
  • dict_key (Optional[str]) – key of the field in the dumped dictionary.

  • ignore (bool) – if True, this field won’t be considered by Serpyco.

  • getter (Optional[Callable[[object], Any]]) – callable used to get values of this field when dumping. Must take one object argument.

  • validator (Optional[Callable[[Any], None]]) – callable used to perform custom validation of this field. Will be called with values of the field, shall raise ValidationError() if the value is not valid.

  • cast_on_load (bool) – when true, dict values for this field are constructed from the field’s type.

  • description (Optional[str]) – a description for the field. Will be included in the generated JSON schema.

  • examples (Optional[List[str]]) – a list of example usages for the field. Will be included in the generated JSON schema.

  • format – additional semantic validation for strings. Currently only used to better document the JSON schema, if you need special validation for a string, use a validator callable.

  • pattern (Optional[str]) – restricts the strings of this field to the given regular expression.

  • min_length (Optional[int]) – minimum string length.

  • max_length (Optional[int]) – maximum string length.

Return type

Any

Indices and tables