Transforms¶

class schematics.transforms.Role(function, fields)¶

A Role object can be used to filter specific fields against a sequence.

The Role is two things: a set of names and a function. The function describes how filter taking a field name as input and then returning either True or False, indicating that field should or should not be skipped.

A Role can be operated on as a Set object representing the fields is has an opinion on. When Roles are combined with other roles, the filtering behavior of the first role is used.

static blacklist(name, value, seq)¶

Implements the behavior of a blacklist by requesting a field be skipped whenever it’s name is found in the list of fields.

Parameters:	k – The field name to inspect. v – The field’s value. seq – The list of fields associated with the `Role`.

static whitelist(name, value, seq)¶

Implements the behavior of a whitelist by requesting a field be skipped whenever it’s name is not in the list of fields.

Parameters:	name – The field name to inspect. value – The field’s value. seq – The list of fields associated with the `Role`.

static wholelist(name, value, seq)¶

Accepts a field name, value, and a field list. This functions implements acceptance of all fields by never requesting a field be skipped, thus returns False for all input.

Parameters:	name – The field name to inspect. value – The field’s value. seq – The list of fields associated with the `Role`.

schematics.transforms.allow_none(cls, field)¶

This function inspects a model and a field for a setting either at the model or field level for the serialize_when_none setting.

The setting defaults to the value of the class. A field can override the class setting with it’s own serialize_when_none setting.

Parameters:	cls – The model definition. field – The field in question.

schematics.transforms.atoms(cls, instance_or_dict)¶

Iterator for the atomic components of a model definition and relevant data that creates a threeple of the field’s name, the instance of it’s type, and it’s value.

Parameters:	cls – The model definition. instance_or_dict – The structure where fields from cls are mapped to values. The only expectionation for this structure is that it implements a `dict` interface.

schematics.transforms.blacklist(*field_list)¶

Returns a function that operates as a blacklist for the provided list of fields.

A blacklist is a list of fields explicitly named that are not allowed.

schematics.transforms.expand(data, context=None)¶

Expands a flattened structure into it’s corresponding layers. Essentially, it is the counterpart to flatten_to_dict.

Parameters:	data – The data to expand. context – Existing expanded data that this function use for output

schematics.transforms.export_loop(cls, instance_or_dict, field_converter, role=None, raise_error_on_role=False, print_none=False)¶

The export_loop function is intended to be a general loop definition that can be used for any form of data shaping, such as application of roles or how a field is transformed.

Parameters:

cls – The model definition.
instance_or_dict – The structure where fields from cls are mapped to values. The only expectionation for this structure is that it implements a dict interface.
field_converter – This function is applied to every field found in instance_or_dict.
role – The role used to determine if fields should be left out of the transformation.
raise_error_on_role – This parameter enforces strict behavior which requires substructures to have the same role definition as their parent structures.
print_none – This function overrides serialize_when_none values found either on cls or an instance.

schematics.transforms.flatten(cls, instance_or_dict, role=None, raise_error_on_role=True, ignore_none=True, prefix=None, context=None)¶

Produces a flat dictionary representation of the model. Flat, in this context, means there is only one level to the dictionary. Multiple layers are represented by the structure of the key.

Example:

>>> class Foo(Model):
...    s = StringType()
...    l = ListType(StringType)

>>> f = Foo()
>>> f.s = 'string'
>>> f.l = ['jms', 'was here', 'and here']

>>> flatten(Foo, f)
{'s': 'string', u'l.1': 'jms', u'l.0': 'was here', u'l.2': 'and here'}

Parameters:

cls – The model definition.
instance_or_dict – The structure where fields from cls are mapped to values. The only expectionation for this structure is that it implements a dict interface.
role – The role used to determine if fields should be left out of the transformation.
raise_error_on_role – This parameter enforces strict behavior which requires substructures to have the same role definition as their parent structures.
ignore_none – This ignores any serialize_when_none settings and forces the empty fields to be printed as part of the flattening. Default: True
prefix – This puts a prefix in front of the field names during flattening. Default: None

schematics.transforms.flatten_to_dict(instance_or_dict, prefix=None, ignore_none=True)¶

Flattens an iterable structure into a single layer dictionary.

For example:

{

‘s’: ‘jms was hrrr’, ‘l’: [‘jms was here’, ‘here’, ‘and here’]

}

becomes

{

‘s’: ‘jms was hrrr’, u’l.1’: ‘here’, u’l.0’: ‘jms was here’, u’l.2’: ‘and here’

}

Parameters:

instance_or_dict – The structure where fields from cls are mapped to values. The only expectionation for this structure is that it implements a dict interface.
ignore_none – This ignores any serialize_when_none settings and forces the empty fields to be printed as part of the flattening. Default: True
prefix – This puts a prefix in front of the field names during flattening. Default: None

schematics.transforms.import_loop(cls, instance_or_dict, field_converter, context=None, partial=False, strict=False, mapping=None)¶

The import loop is designed to take untrusted data and convert it into the native types, as described in cls. It does this by calling field_converter on every field.

Errors are aggregated and returned by throwing a ModelConversionError.

Parameters:

cls – The class for the model.
instance_or_dict – A dict of data to be converted into types according to cls.
field_convert – This function is applied to every field found in instance_or_dict.
context – A dict-like structure that may contain already validated data.
partial – Allow partial data to validate; useful for PATCH requests. Essentially drops the required=True arguments from field definitions. Default: False
strict – Complain about unrecognized keys. Default: False

schematics.transforms.sort_dict(dct, based_on)¶

Sorts provided dictionary based on order of keys provided in based_on list.

Order is not guarantied in case if dct has keys that are not present in based_on

Parameters:	dct – Dictionary to be sorted. based_on – List of keys in order that resulting dictionary should have.
Returns:	OrderedDict with keys in the same order as provided `based_on`.

schematics.transforms.to_primitive(cls, instance_or_dict, role=None, raise_error_on_role=True, context=None)¶

Implements serialization as a mechanism to convert Model instances into dictionaries keyed by field_names with the converted data as the values.

The conversion is done by calling to_primitive on both model and field instances.

Parameters:

cls – The model definition.
instance_or_dict – The structure where fields from cls are mapped to values. The only expectionation for this structure is that it implements a dict interface.
role – The role used to determine if fields should be left out of the transformation.
raise_error_on_role – This parameter enforces strict behavior which requires substructures to have the same role definition as their parent structures.

schematics.transforms.whitelist(*field_list)¶

Returns a function that operates as a whitelist for the provided list of fields.

A whitelist is a list of fields explicitly named that are allowed.

schematics.transforms.wholelist(*field_list)¶: Returns a function that evicts nothing. Exists mainly to be an explicit allowance of all fields instead of a using an empty blacklist.

Usage¶

To learn more about how Transforms are used, visit Using Importing and Using Exporting