Base class#

class oblate.fields.Field(*, none=False, required=True, frozen=False, default=..., validators=..., extras=..., dump_key=..., load_key=..., data_key=...)#

The base class for all fields.

All fields provided by Oblate inherit from this class. If you intend to create a custom field, you must use this class to inherit the field from. Subclasses must implement the following methods:

value_load()
value_dump()

Tip

This class is a typing.Generic and takes two type arguments. The raw value type i.e the type of raw value which will be deserialized to final value and the type of deserialized value.

ERR_FIELD_REQUIRED#: Error code raised when a required field is not given in raw data.

ERR_NONE_DISALLOWED#: Error code raised when a field with none=False is given a value of None.

ERR_VALIDATION_FAILED#: Error code raised when a validator fails for a field without an explicit error message.

Parameters:

none (bool) – Whether this field allows None values to be set.
required (bool) – Whether this field is required.
frozen (bool) – Whether the field is frozen. Frozen fields are read only fields that cannot be updated once initialized.
default –
The default value for this field. If this is passed, the field is automatically marked as optional i.e required parameter gets ignored.

A callable can also be passed in this parameter that returns the default value. The callable takes two parameters, that is the current SchemaContext instance and the current Field instance.
validators (List[Union[callable, Validator]]) – The list of validators for this field.
extras (Dict[str, Any]) – A dictionary of extra data that can be attached to this field. This parameter is useful when you want to attach your own extra metadata to the field. Library does not perform any manipulation on the data.
load_key (str) – The key that points to value of this field in raw data. Defaults to the name of field.
dump_key (str) – The key that points to value of this field in serialized data returned by Schema.dump(). Defaults to the name of field.
data_key (str) – A shorthand parameter to control the value of both load_key and dump_key parameters.

property schema#

The schema that the field belongs to.

New in version 1.1.

Type:: Schema

property name#

The name of attribute that the field is assigned to.

New in version 1.1.

Type:: str

has_default()#: Indicates whether the field has a default value.

copy()#

Copies a field.

This method is useful when you want to reuse fields from other schemas. For example:

class User(oblate.Schema):
    id = fields.Integer(strict=False)
    username = fields.String()

class Game(oblate.Schema):
    id = User.id.copy()
    name = fields.String()

Returns:: The new field.
Return type:: Field

add_validator(validator, *, raw=False)#

Registers a validator for this field.

Parameters:

validator (Union[callable, validate.Validator]) – The validator to register. This can be a callable function or a validate.Validator instance.
raw (bool) – Whether a raw validator is being registered. This parameter is only taken into account when a callable is passed instead of a validate.Validator instance.

remove_validator(validator, *, raw=False)#

Removes a validator from this field.

No error is raised if the given validator is not already registered.

Parameters:

validator (Union[callable, validate.Validator]) – The validator to remove. This can be a callable function or a validate.Validator instance.
raw (bool) – Whether the validator being removed is raw. This parameter is only taken into account when a callable is passed instead of a validate.Validator instance.

clear_validators(*, raw=...)#

Removes all validator from this field.

Parameters:: raw (bool) – Whether to remove raw validators only. If this is not passed, all validators are removed. If this is True, only raw validators are removed and when False, only non-raw validators are removed.

walk_validators(*, raw=...)#

Iterates through the validator from this field.

Parameters:: raw (bool) – Whether to iterate through raw validators only. If this is not passed, all validators are iterated. If this is True, only raw validators are iterated and when False, only non-raw validators are iterated.

format_error(error_code, context, /)#

Formats the error.

This method can be overriden to add custom error messages for default errors. It should return a FieldError or str.

Changed in version 1.1: This method no longer requires super call. Default error messages are now automatically resolved.

Parameters:

error_code (str) – The error code indicating the error that was raised.
context (ErrorContext) – The context holding useful information about error.

Returns:

The formatted error.

Return type:

Optional[Union[FieldError, str]]

value_load(value, context, /)#

Deserializes a raw value.

This is an abstract method that must be implemented by subclasses. This method is called by the library when a field is being loaded.

The instances when this method is called are:

Initializing a Schema
Updating a field value on an existing Schema instance

The returned value is the value assigned to Schema field attribute.

Parameters:

value – The value to deserialize.
context (LoadContext) – The deserialization context.

Return type:

The serialized value.

value_dump(value, context, /)#

Serializes the value to raw form.

This is an abstract method that must be implemented by subclasses. This method is called by the library when a field is being dumped.

The only time this method is called when the Schema.dump() method is called. The returned value is the value included in serialized data.

Parameters:

value – The value to serialize.
context (DumpContext) – The serialization context.

Return type:

The serialized value.