Transforms

import_loop(cls, instance_or_dict, field_converter=None, trusted_data=None, mapping=None, partial=False, strict=False, init_values=False, apply_defaults=False, convert=True, validate=False, new=False, recursive=False, app_data=None, context=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_converter – This function is applied to every field found in instance_or_dict.
  • trusted_data – 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
  • apply_defaults – Whether to set fields to their default values when not present in input data.
  • app_data – An arbitrary container for application-specific data that needs to be available during the conversion.
  • context – A Context object that encapsulates configuration options and app_data. The context object is created upon the initial invocation of import_loop and is then propagated through the entire process.
class 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.
flatten(cls, instance_or_dict, role=None, raise_error_on_role=True, ignore_none=True, prefix=None, app_data=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', 'l.1': 'jms', 'l.0': 'was here', 'l.2': 'and here'}
Parameters:
  • cls – The model definition.
  • instance_or_dict – The structure where fields from cls are mapped to values. The only expectation for this structure is that it implements a Mapping 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
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’, ‘l.1’: ‘here’, ‘l.0’: ‘jms was here’, ‘l.2’: ‘and here’

}

Parameters:
  • instance_or_dict – The structure where fields from cls are mapped to values. The only expectation for this structure is that it implements a Mapping 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
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.

expand(data, expanded_data=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.
  • expanded_data – Existing expanded data that this function use for output
atoms(cls, instance_or_dict)

Iterator for the atomic components of a model definition and relevant data that creates a 3-tuple of the field’s name, its type instance and its value.

Parameters:
  • cls – The model definition.
  • instance_or_dict – The structure where fields from cls are mapped to values. The only expectation for this structure is that it implements a Mapping interface.
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.

export_loop(cls, instance_or_dict, field_converter=None, role=None, raise_error_on_role=True, export_level=None, app_data=None, context=None)

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.
  • app_data – An arbitrary container for application-specific data that needs to be available during the conversion.
  • context – A Context object that encapsulates configuration options and app_data. The context object is created upon the initial invocation of import_loop and is then propagated through the entire process.
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.

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.

Usage

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