Schema¶
A collection of fields is represented by:
- class resource_api.schema.Schema(validate_required_constraint=True, with_errors=True)¶
Base class for containers that would hold one or many fields.
it has one class attribute that may be used to alter shcema’s validation flow
- has_additional_fields (bool = False)
- If True it shall be possible to have extra fields inside input data that will not be validated
NOTE: when defining schemas do not use any of the following reserved keywords:
- find_fields
- deserialize
- get_schema
- serialize
- has_additional_fields
Schema example¶
A schema for a page with title, text, creation timestamp and a 5 star rating would look the following way:
class PageSchema(Schema):
title = StringField(max_length=70)
text = StringField()
creation_time = DateTimeField()
rating = IntegerField(min_value=1, max_value=5)
General field API¶
All fields inherit from BaseField and thus have its attributes in common.
- class resource_api.schema.BaseField(description=None, required=True, **kwargs)¶
Superclass for all fields
- description (None|string = None)
- help text to be shown in schema. This should include the reasons why this field actually needs to exist.
- required (bool = False)
- flag that specifes if the field has to be present
- **kwargs
- extra parameters that are not programmatically supported
There are two extra parameters supported by Resource API:
- readonly (bool=False)
- if True field cannot be set nor changed but is a logical part of the resource. Resource creation time would be a good example.
- changeable (bool=False)
- if True field can be set during creation but cannot be change later on. User’s birth date is a valid example.
Primitive fields¶
There are two types of digit fields supported by schema. Integers and floats. Fields that represent them have a common base class:
- class resource_api.schema.DigitField(min_val=None, max_val=None, **kwargs)¶
Base class for fields that represent numbers
- min_val (int|long|float = None)
- Minumum threshold for incoming value
- max_val (int|long|float = None)
- Maximum threshold for imcoming value
The fields representing integers and floats respecively are:
- class resource_api.schema.IntegerField(min_val=None, max_val=None, **kwargs)¶
Transforms input data that could be any number or a string value with that number into long
- class resource_api.schema.FloatField(min_val=None, max_val=None, **kwargs)¶
Transforms input data that could be any number or a string value with that number into float
Time related fields are represented by:
- class resource_api.schema.DateTimeField(description=None, required=True, **kwargs)¶
datetime object serialized into YYYY-MM-DDThh:mm:ss.sTZD.
E.g.: 2013-09-30T11:32:39.984847
- class resource_api.schema.DateField(description=None, required=True, **kwargs)¶
date object serialized into YYYY-MM-DD.
E.g.: 2013-09-30
- class resource_api.schema.TimeField(description=None, required=True, **kwargs)¶
time object serialized into hh:mm:ssTZD.
E.g.: 11:32:39.984847
- class resource_api.schema.DurationField(description=None, required=True, **kwargs)¶
timedelta object serialized into PnYnMnDTnHnMnS.
E.g.: P105DT9H52M49.448422S
Strings are represented by:
- class resource_api.schema.StringField(regex=None, min_length=None, max_length=None, **kwargs)¶
Represents any arbitrary text
- regex (string = None)
- Python regular expression used to validate the string.
- min_length (int = None)
- Minimum size of string value
- max_length (int = None)
- Maximum size of string value
Various boolean flags exist in the schape of:
- class resource_api.schema.BooleanField(default=None, **kwargs)¶
Expects only a boolean value as incoming data
Composite fields¶
- class resource_api.schema.ListField(item_type, **kwargs)¶
Represents a collection of primitives. Serialized into a list.
- item_type (python primitve|Field instance)
- value is used by list field to validate individual items python primitive are internally mapped to Field instances according to PRIMITIVE_TYPES_MAP
PRIMITIVE_TYPES_MAP = {
int: IntegerField,
float: FloatField,
str: StringField,
unicode: StringField,
basestring: StringField,
bool: BooleanField
}
- class resource_api.schema.ObjectField(schema, **kwargs)¶
Represents a nested document/mapping of primitives. Serialized into a dict.
- schema (class):
- schema to be used for validation of the nested document, it does not have to be Schema subclass - just a collection of fields
ObjectField can be declared via two different ways.
First, if there is a reusable schema defined elsewhere:
>>> class Sample(Schema): >>> object_field = ObjectField(ExternalSchema, required=False, description="Zen")
Second, if the field is supposed to have a unique custom schema:
>>> class Sample(Schema): >>> object_field = ObjectField(required=False, description="Zen", schema=dict( >>> "foo": StringField() >>> ))