Developer Interface¶
This part of the documentation covers all the interfaces of Kim.
Mappers¶
-
class
kim.mapper.
Mapper
(obj=None, data=None, partial=False, raw=False, parent=None)[source]¶ Mappers are the building blocks of Kim - they define how JSON output should look and how input JSON should be expected to look.
Mappers consist of Fields. Fields define the shape and nature of the data both when being serialised(output) and marshaled(input).
Mappers must define a
__type__
. This is the type that will be instantiated if a new object is marshaled through the mapper.__type__
may be be any object that supportsgetattr
andsetattr
, or any dict like object.Usage:
from kim import Mapper, field class UserMapper(Mapper): __type__ = User id = field.Integer(read_only=True) name = field.String(required=True) company = field.Nested('myapp.mappers.CompanyMapper')
Initialise a Mapper with the object and/or the data to be serialzed/marshaled. Mappers must be instantiated once per object/data. At least one of obj or data must be passed.
Parameters: - obj -- the object to be serialized, or updated by marshaling
- data -- input data to be used for marshaling
- raw -- the mapper will instruct fields to populate themselves using __dunder__ field names where required.
- partial -- allow pipelines to pull data from an existing source or fall back to standard checks.
- parent -- The parent of this Mapper. Set internally when a Mapper is being used as a nested field.
Raises: MapperError
Returns: None
Return type: None
-
_get_mapper_type
()[source]¶ Return the specified type for this Mapper. If no
__type__
is defined aMapperError
is raisedRaises: MapperError
Returns: The specified __type__
for the mapper.
-
_get_obj
()[source]¶ Return
self.obj
or create a new instance ofself.__type__
Returns: self.obj
or new instance ofself.__type__
-
_get_role
(name_or_role, deferred_role=None)[source]¶ Resolve a string to a role and check it exists, or check a directly passed role is a Role instance and return it.
You may also affect the fields returned from a role at read time using
deferred_role
. deferred_role is used to provide the intersection between the role specified atname_or_role
and thedeferred_role
.Usage:
class FooMapper(Mapper): __type__ = dict name = field.String() id = field.String() secret = field.String() __roles__ = { 'overview': whitelist('id', 'name'), } mapper._get_role('overview', deferred_role=whitelist('id'))
Deferred roles can be used for things like allowing end users to provide a list of fields they want back from your API but only if they appear in a role you've specified.
Parameters: - deferred_role -- provide a role containing fields to dynamically change the
permitted fields for the role specified in
name_or_role
- name_or_role -- role name as a string or a Role instance
Raises: MapperError
Returns: Role instance
Return type: Role
- deferred_role -- provide a role containing fields to dynamically change the
permitted fields for the role specified in
-
_get_fields
(name_or_role, deferred_role=None, for_marshal=False)[source]¶ Returns a list of
Field
instances providing they are registered in the specifiedRole
.If the provided name_or_role is not found in the Mappers role list an error will be raised.
Parameters: - deferred_role -- an instance of role used to dynamically a new role.
- name_or_role -- the name of a role as a string or a
Role
instance. - for_marshal -- Indicate that the mapper is marshaling data.
Raises: MapperError
Returns: list of
Field
instancesReturn type: list
-
get_mapper_session
(data, output)[source]¶ Populate and return a new instance of
MapperSession
Parameters: - data -- data being Mapped
- output -- obj mapper is mapping too
Returns: MapperSession
objectReturn type: MapperSession
object
-
classmethod
many
(**mapper_params)[source]¶ Provide access to a
MapperIterator
to allow multiple items to be mapped by a mapper.Parameters: mapper_params -- dict of params passed to each new instance of the mapper. Returns: MapperIterator
objectReturn type: MapperIterator
Usage:
>>> mapper = Mapper.many(data=data).marshal()
-
marshal
(role='__default__')[source]¶ Marshal
self.data
intoself.obj
according to the fields defined on this Mapper.Returns: Object of __type__
populated with data
-
serialize
(role='__default__', raw=False, deferred_role=None)[source]¶ Serialize
self.obj
into a dict according to the fields defined on this Mapper.Parameters: - role -- specify the role to use when serializing this mapper
- raw -- instruct the mapper to transform the data before serializing. This option overrides the Mapper.raw setting.
Raises: FieldInvalid
MapperError
Returns: dict containing serialized object
Return type: mixed
- Usage::
>>> mapper = UserMapper(obj=user) >>> mapper.serialize(role='public')
See also
transform_data
-
transform_data
(data)[source]¶ Transform a flat list of key names into a nested data structure by inflating dunder_score key name into objects.
Parameters: data -- The object or data being transformed Returns: transformed data Return type: dict Usage:
>>> data = ['id', 'name', 'contact_details__phone', 'contact_details__address__postcode'] >>> mapper.transform_data(data) { 'id': x, 'name': x, 'contact_details': { 'phone': x, 'address': { 'postcode': x } } }
-
class
kim.mapper.
PolymorphicMapper
(obj=None, data=None, partial=False, raw=False, parent=None)[source]¶ PolymorphicMappers build on the normal Mapper system to provide functionality for serializing and marshaling collections of different objects with different data structures.
Usage:
from kim import Mapper, field class ActivityMapper(PolymorphicMapper): __type__ = Activity id = field.String() name = field.String() object_type = field.String(choices=['event', 'task']) created_at = field.DateTime(read_only=True) __mapper_args__ = { 'polymorphic_on': object_type, } class TaskMapper(ActivityMapper): __type__ = Task status = field.String(read_only=True) is_complete = field.Boolean() __mapper_args__ = { 'polymorphic_name': 'task' } class EventMapper(ActivityMapper): __type__ = Event location = field.String(read_only=True) __mapper_args__ = { 'polymorphic_name': 'event' }
Initialise a Mapper with the object and/or the data to be serialzed/marshaled. Mappers must be instantiated once per object/data. At least one of obj or data must be passed.
Parameters: - obj -- the object to be serialized, or updated by marshaling
- data -- input data to be used for marshaling
- raw -- the mapper will instruct fields to populate themselves using __dunder__ field names where required.
- partial -- allow pipelines to pull data from an existing source or fall back to standard checks.
- parent -- The parent of this Mapper. Set internally when a Mapper is being used as a nested field.
Raises: MapperError
Returns: None
Return type: None
-
get_mapper_session
(data, output)¶ Populate and return a new instance of
MapperSession
Parameters: - data -- data being Mapped
- output -- obj mapper is mapping too
Returns: MapperSession
objectReturn type: MapperSession
object
-
classmethod
get_polymorphic_identity
(key)[source]¶ Return the polymorphic mapper stored at
key
.Parameters: key -- The name of a polymoprhic indentity Raises: kim.exception.MapperError
Return type: kim.mapper.Mapper
Returns: the Mapper stored against key
-
classmethod
get_polymorphic_key
(obj=None, data=None)[source]¶ Return the value from obj when serializing or from data when marshaling for the polymorphic_on key.
Parameters: - data -- datum being marshaled by the Mapper
- obj -- obj being serialized by the Mapper
Returns: the polymorphic type name
Return type: str
Raises:
-
classmethod
is_polymorphic_base
()[source]¶ Return a boolean indicating if this cls is the base type in the class hierarchy
Returns: True if the class is the base type, otherwise False Return type: boolean
-
many
(**mapper_params)¶ Provide access to a
MapperIterator
to allow multiple items to be mapped by a mapper.Parameters: mapper_params -- dict of params passed to each new instance of the mapper. Returns: MapperIterator
objectReturn type: MapperIterator
Usage:
>>> mapper = Mapper.many(data=data).marshal()
-
marshal
(role='__default__')¶ Marshal
self.data
intoself.obj
according to the fields defined on this Mapper.Returns: Object of __type__
populated with data
-
serialize
(role='__default__', raw=False, deferred_role=None)¶ Serialize
self.obj
into a dict according to the fields defined on this Mapper.Parameters: - role -- specify the role to use when serializing this mapper
- raw -- instruct the mapper to transform the data before serializing. This option overrides the Mapper.raw setting.
Raises: FieldInvalid
MapperError
Returns: dict containing serialized object
Return type: mixed
- Usage::
>>> mapper = UserMapper(obj=user) >>> mapper.serialize(role='public')
See also
transform_data
-
transform_data
(data)¶ Transform a flat list of key names into a nested data structure by inflating dunder_score key name into objects.
Parameters: data -- The object or data being transformed Returns: transformed data Return type: dict Usage:
>>> data = ['id', 'name', 'contact_details__phone', 'contact_details__address__postcode'] >>> mapper.transform_data(data) { 'id': x, 'name': x, 'contact_details': { 'phone': x, 'address': { 'postcode': x } } }
-
validate
(output)¶ Mappers may subclass this method to perform top-level validation on multiple related fields, raising FieldInvalid or MappingInvalid if any problems are found.
Raises: FieldInvalid Raises: MappingInvalid
-
class
kim.mapper.
MapperIterator
(mapper, **mapper_params)[source]¶ Provides a symmetric interface for Mapping many objects in one batch.
A simple example would be seriaizing a list of User objects from a database query or other source.
Usage:
from kim import Mapper, field class UserMapper(Mapper): __type__ = User id = field.Integer(read_only=True) name = field.String(required=True) company = field.Nested('myapp.mappers.CompanyMapper') objs = User.query.all() results = UserMapper.many().serialize(objs)
Constructs a new instance of a MapperIterator.
Parameters: - mapper -- a
Mapper
to map each item too. - mapper_params -- a dict of kwargs passed to each mapper
-
get_mapper
(data=None, obj=None)[source]¶ Return a new instance of the provided mapper.
Parameters: - data -- provide the new mapper with data when marshaling
- obj -- provide the new mapper with data when serializing
Return type: Returns: a new
Mapper
- mapper -- a
-
class
kim.mapper.
MapperSession
(mapper, data, output, partial=None)[source]¶ Object that represents the state of a
Mapper
during the execution of marshaling and serializationPipeline
.Instantiate a new instance of
MapperSession
Parameters: - mapper --
Mapper
instance. - data -- The data marshaled by the
Mapper
- output -- The object the
Mapper
is outputting to.
Returns: None
Return type: None
See also
get_mapper_session method
get_mapper_session
- mapper --
Fields¶
-
class
kim.field.
Field
(*args, **field_opts)[source]¶ Field, as it's name suggests, represents a single key or 'field' inside of your mappings. Much like columns in a database or a csv, they provide a way to represent different data types when pushing data into and out of your Mappers.
A core concept of Kims architecture is that of Pipelines. Every Field makes use of both an Input and Output pipeline which affords users a great level of flexibility when it comes to handling data.
Kim provides a collection of default Field implementations, for more complex cases extending Field to create new field types couldn't be easier.
Usage:
from kim import Mapper from kim import field class UserMapper(Mapper): id = field.Integer(required=True, read_only=True) name = field.String(required=True)
Constructs a new instance of Field. Each Field accepts a set of kwargs that will be passed directly to the fields defined
FieldOpts
.Parameters: - args -- list of arguments passed to the field
- kwargs -- keyword arguments typically passed to the FieldOpts class attached to this Field.
Raises: FieldOptsError
Returns: None
See also
FieldOpts
-
opts_class
= <class 'kim.field.FieldOpts'>¶ The
FieldOpts
field config class to use for the Field.
-
marshal_pipeline
= <class 'kim.pipelines.marshaling.MarshalPipeline'>¶ The Fields marshaling pipeline
-
serialize_pipeline
= <class 'kim.pipelines.serialization.SerializePipeline'>¶ The Fields serialization pipeline
-
get_error
(error_type)[source]¶ Return the error message for
error_type
from the error messages defined on the fields opts class.Parameters: error_type -- the key of the error found in self.error_msgs Returns: Error message Return type: string
-
invalid
(error_type)[source]¶ Raise an Exception using the provided error_type for the error message. This method is typically used by pipes to allow
Field
to control how its errors are handled.Usage:
@pipe() def validate_name(session): if session.data and session.data != 'Mike Waites': raise session.fied.invalid('not_mike')
Parameters: error_type -- The key of the error being raised. Raises: FieldInvalid
See also
FieldOpts
for an explanation on defining error messags
-
marshal
(mapper_session, **opts)[source]¶ Run the marshal
Pipeline
for this field for the givendata
and update the output for this field inside of the mapper_session.Parameters: mapper_session -- The Mappers marshaling session this field is being run inside of. Opts: kwargs passed to the marshal pipelines run method. Returns: None See also
-
marshal_pipeline
¶ The Fields marshaling pipeline
alias of
MarshalPipeline
-
name
¶ Proxy access to the
FieldOpts
defined for this field.Return type: str Returns: The value of get_name from FieldOpts Raises: FieldError
See also
-
opts_class
¶ The
FieldOpts
field config class to use for the Field.alias of
FieldOpts
-
serialize
(mapper_session, **opts)[source]¶ Run the serialize
Pipeline
for this field for the given data and update output in for this field inside of the mapper_session.Parameters: mapper_session -- The Mappers marshaling session this field is being run inside of. Opts: kwargs passed to the marshal pipelines run method. Returns: None See also
-
serialize_pipeline
¶ The Fields serialization pipeline
alias of
SerializePipeline
-
class
kim.field.
FieldOpts
(**opts)[source]¶ FieldOpts are used to provide configuration options to
Field
. They are designed to allow users to easily provide custom configuration options toField
classes.Custom
FieldOpts
classes are set onField
using theopts_class
property.class MyFieldOpts(FieldOpts): def __init__(self, **opts): self.some_property = opts.get('some_property', None) super(MyFieldOpts, self).__init__(**opts)
See also
Construct a new instance of
FieldOpts
and set config optionsParameters: - name -- Specify the name of the field for data output
- required -- This field must be present when marshaling
- attribute_name -- Specify internal name for this field, set on mapper.fields dict
- source -- Specify the name of the attribute on the object to use
when getting/setting data. May be
__self__
to use entire mapper object as data - default -- Specify a default value for this field to apply when serializing or marshaling
- allow_none -- This option only takes affect if required=False. If
allow_none=False and required=False, then Kim will accept either
the field being missing completely from the data, or the field
being passed with a non-None value. That is, either
{}
or{'field': 'value'}
but never{'field': None}
. Default True. - read_only -- Specify if this field should be ignored when marshaling
- error_msgs -- A dict of error_type: error messages.
- null_default -- Specify the default type to return when a field is null IE None or {} or ''
- choices -- Specify a list of valid values
- extra_serialize_pipes -- dict of lists containing extra Pipe functions
to be run at the end of each stage when serializing.
eg
{'output': [my_pipe, my_other_pipe]}`
- extra_marshal_pipes -- dict of lists containing extra Pipe functions
to be run at the end of each stage when marshaling.
eg
{'validate': [my_pipe, my_other_pipe]}`
Raises: Returns: None
-
get_name
()[source]¶ Return the name property set by
set_name
Return type: str Returns: the name of the field to be used in input/output
-
set_name
(name=None, attribute_name=None, source=None)[source]¶ Programmatically set the name properties for a field.
Names cascade from each other unless they are explicitly overridden.
Example 1: class MyMapper(Mapper):
foo = field.String()attribute_name = foo name = foo source = foo
Example 2: class MyMapper(Mapper):
foo = field.String(name='bar', source='baz')attribute_name = foo name = bar source = baz
Parameters: - name -- value of name property
- attribute_name -- value of attribute_name property
- source -- value of source property
Returns: None
-
validate
()[source]¶ Allow users to perform checks for required config options. Concrete classes should raise
FieldError
when invalid configuration is encountered.A slightly contrived example is requiring all fields to be
read_only=True
Usage:
from kim.field import FieldOpts class MyOpts(FieldOpts): def validate(self): if self.read_only is True: raise FieldOptsError('Field cannot be read only')
Raises: .FieldOptsError Returns: None
-
class
kim.field.
String
(*args, **field_opts)[source]¶ String
represents a value that must be valid when passed to str()Usage:
from kim import Mapper from kim import field class UserMapper(Mapper): __type__ = User name = field.String(required=True)
Constructs a new instance of Field. Each Field accepts a set of kwargs that will be passed directly to the fields defined
FieldOpts
.Parameters: - args -- list of arguments passed to the field
- kwargs -- keyword arguments typically passed to the FieldOpts class attached to this Field.
Raises: FieldOptsError
Returns: None
See also
FieldOpts
-
marshal_pipeline
¶ alias of
StringMarshalPipeline
-
opts_class
¶ alias of
StringFieldOpts
-
serialize_pipeline
¶ alias of
StringSerializePipeline
-
class
kim.field.
Integer
(*args, **field_opts)[source]¶ Integer
represents a value that must be valid when passed to int()Usage:
from kim import Mapper from kim import field class UserMapper(Mapper): __type__ = User id = field.Integer(required=True, min=1, max=10)
Constructs a new instance of Field. Each Field accepts a set of kwargs that will be passed directly to the fields defined
FieldOpts
.Parameters: - args -- list of arguments passed to the field
- kwargs -- keyword arguments typically passed to the FieldOpts class attached to this Field.
Raises: FieldOptsError
Returns: None
See also
FieldOpts
-
marshal_pipeline
¶ alias of
IntegerMarshalPipeline
-
opts_class
¶ alias of
IntegerFieldOpts
-
serialize_pipeline
¶ alias of
IntegerSerializePipeline
-
class
kim.field.
IntegerFieldOpts
(**kwargs)[source]¶ Custom FieldOpts class that provides additional config options for
Integer
.Construct a new instance of
IntegerFieldOpts
and set config optionsParameters: - max -- Specify the maximum permitted value
- min -- Specify the minimum permitted value
Raises: FieldOptsError
Returns: None
-
class
kim.field.
Decimal
(*args, **field_opts)[source]¶ Decimal
represents a value that must be valid when passed to decimal.Decimal()Usage:
from kim import Mapper from kim import field class UserMapper(Mapper): __type__ = User score = field.Decimal(precision=4, min=0, max=1.5)
Constructs a new instance of Field. Each Field accepts a set of kwargs that will be passed directly to the fields defined
FieldOpts
.Parameters: - args -- list of arguments passed to the field
- kwargs -- keyword arguments typically passed to the FieldOpts class attached to this Field.
Raises: FieldOptsError
Returns: None
See also
FieldOpts
-
marshal_pipeline
¶ alias of
DecimalMarshalPipeline
-
opts_class
¶ alias of
FloatFieldOpts
-
serialize_pipeline
¶ alias of
DecimalSerializePipeline
-
class
kim.field.
Boolean
(*args, **field_opts)[source]¶ Boolean
represents a value that must be valid boolean type.Usage:
from kim import Mapper from kim import field class UserMapper(Mapper): __type__ = User active = field.Boolean( required=True, true_boolean_values=[True, 'true', 1], false_boolean_values=[False, 'false', 0])
Constructs a new instance of Field. Each Field accepts a set of kwargs that will be passed directly to the fields defined
FieldOpts
.Parameters: - args -- list of arguments passed to the field
- kwargs -- keyword arguments typically passed to the FieldOpts class attached to this Field.
Raises: FieldOptsError
Returns: None
See also
FieldOpts
-
marshal_pipeline
¶ alias of
BooleanMarshalPipeline
-
opts_class
¶ alias of
BooleanFieldOpts
-
serialize_pipeline
¶ alias of
BooleanSerializePipeline
-
class
kim.field.
BooleanFieldOpts
(**kwargs)[source]¶ Custom FieldOpts class that provides additional config options for
Boolean
.Construct a new instance of
BooleanFieldOpts
and set config optionsParameters: - true_boolean_values -- Specify an array of values that will validate as being 'true' when the field is marshaled.
- false_boolean_values -- Specify an array of values that will validate as being 'false' when the field is marshaled.
Raises: FieldOptsError
Returns: None
-
class
kim.field.
Nested
(*args, **kwargs)[source]¶ Nested
represents an object that is represented by another mapper.Usage:
from kim import Mapper from kim import field class PostMapper(Mapper): __type__ = User id = field.String() name= field.String() content = field.String() user = field.Nested( 'UserMapper', role='public', getter=user_getter, allow_upadtes=False, allow_partial_updates=False, allow_updates_in_place=False, allow_create=False, required=True)
See also
NestedFieldOpts
-
get_mapper
(as_class=False, **mapper_params)[source]¶ Retrieve the specified mapper from the Mapper registry.
Parameters: - as_class -- Return the Mapper class object without calling the constructor. This is typically used when nested is mapping many objects.
- mapper_params -- A dict of kwarg's to pass to the specified mappers constructor
Return type: Mapper
Returns: a new instance of the specified mapper
-
marshal_pipeline
¶ alias of
NestedMarshalPipeline
-
opts_class
¶ alias of
NestedFieldOpts
-
serialize_pipeline
¶ alias of
NestedSerializePipeline
-
-
class
kim.field.
NestedFieldOpts
(mapper_or_mapper_name, **kwargs)[source]¶ Custom FieldOpts class that provides additional config options for
Nested
.Construct a new instance of
NestedFieldOpts
Parameters: - mapper_or_mapper_name -- a required instance of a
Mapper
or a valid mapper name - role -- specify the name of a role to use on the Nested mapper
- collection_class -- provide a custom type to be used when mapping many nested objects
- getter -- provide a function taking a pipeline session which returns the object to be set on this field, or None if it can't find one. This is useful where your API accepts simply {'id': 2} but you want a full object to be set
- allow_updates -- Allow existing objects returned by the
getter
function to be updated. - allow_updates_in_place -- Whereas allow_updates requires the getter to return an existing object which it will then update, allow_updates_in_place will make updates to any existing object it finds at the specified key.
- allow_create -- If the
getter
returns None, allow the Nested field to create a new instance. - allow_partial_updates -- Allow existing object to be updated using a subset of the fields defined on the Nested field.
- mapper_or_mapper_name -- a required instance of a
-
class
kim.field.
Collection
(*args, **field_opts)[source]¶ Collection
represents collection of other field types, typically stored in a list.Usage:
from kim import Mapper from kim import field class UserMapper(Mapper): __type__ = User id = field.String() friends = field.Collection(field.Nested('UserMapper', required=True)) user_ids = field.Collection(field.String())
See also
CollectionFieldOpts
Constructs a new instance of Field. Each Field accepts a set of kwargs that will be passed directly to the fields defined
FieldOpts
.Parameters: - args -- list of arguments passed to the field
- kwargs -- keyword arguments typically passed to the FieldOpts class attached to this Field.
Raises: FieldOptsError
Returns: None
See also
FieldOpts
-
marshal_pipeline
¶ alias of
CollectionMarshalPipeline
-
opts_class
¶ alias of
CollectionFieldOpts
-
serialize_pipeline
¶ alias of
CollectionSerializePipeline
-
class
kim.field.
CollectionFieldOpts
(field, **kwargs)[source]¶ Custom FieldOpts class that provides additional config options for
Collection
.Construct a new instance of
CollectionFieldOpts
Parameters: - field -- Specify the field type mpapped inside of this collection. This
may be any
Field
type. - unique_on -- Specify a key that is used to check the collection for duplicates.
-
get_name
()[source]¶ Proxy access to the
FieldOpts
defined for this collections field.Return type: str Returns: The value of get_name from the collections Field.
- field -- Specify the field type mpapped inside of this collection. This
may be any
-
class
kim.field.
Static
(*args, **field_opts)[source]¶ Static
represents a field that outputs a constant value.This field is implicitly read_only and therefore is typically only used during serialization flows.
Usage:
from kim import Mapper from kim import field class UserMapper(Mapper): __type__ = User id = field.String() object_type = field.Static(value='user')
Constructs a new instance of Field. Each Field accepts a set of kwargs that will be passed directly to the fields defined
FieldOpts
.Parameters: - args -- list of arguments passed to the field
- kwargs -- keyword arguments typically passed to the FieldOpts class attached to this Field.
Raises: FieldOptsError
Returns: None
See also
FieldOpts
-
opts_class
¶ alias of
StaticFieldOpts
-
serialize_pipeline
¶ alias of
StaticSerializePipeline
-
class
kim.field.
StaticFieldOpts
(value, **kwargs)[source]¶ Custom FieldOpts class that provides additional config options for
Static
.Construct a new instance of
StaticFieldOpts
Parameters: value -- specify the static value to return when this field is serialized.
-
class
kim.field.
DateTime
(*args, **field_opts)[source]¶ DateTime
represents an iso8601 encoded date timefrom kim import Mapper from kim import field class UserMapper(Mapper): __type__ = User created_at = field.DateTime(required=True)
Constructs a new instance of Field. Each Field accepts a set of kwargs that will be passed directly to the fields defined
FieldOpts
.Parameters: - args -- list of arguments passed to the field
- kwargs -- keyword arguments typically passed to the FieldOpts class attached to this Field.
Raises: FieldOptsError
Returns: None
See also
FieldOpts
-
marshal_pipeline
¶ alias of
DateTimeMarshalPipeline
-
opts_class
¶ alias of
DateTimeFieldOpts
-
serialize_pipeline
¶ alias of
DateTimeSerializePipeline
-
class
kim.field.
Date
(*args, **field_opts)[source]¶ Date
represents a date objectfrom kim import Mapper from kim import field class UserMapper(Mapper): __type__ = User signup_date = field.Date(required=True)
Constructs a new instance of Field. Each Field accepts a set of kwargs that will be passed directly to the fields defined
FieldOpts
.Parameters: - args -- list of arguments passed to the field
- kwargs -- keyword arguments typically passed to the FieldOpts class attached to this Field.
Raises: FieldOptsError
Returns: None
See also
FieldOpts
-
marshal_pipeline
¶ alias of
DateMarshalPipeline
-
opts_class
¶ alias of
DateFieldOpts
Roles¶
-
class
kim.role.
Role
(*args, **kwargs)[source]¶ Roles are a fundamental feature of Kim. It's very common to need to provide a different view of your data or to only require a selection of fields when marshaling data.
Roles
in Kim allow users to shape their data at runtime in a simple yet flexible manner.Roles
are added to yourMapper
declarations using the__roles__
attribute.Usage:
from kim import Mapper, whitelist, field class UserMapper(Mapper): __type__ = User id = field.Integer(read_only=True) name = field.String(required=True) company = field.Nested('myapp.mappers.CompanyMapper') __roles__ = { 'id_only': whitelist('id') }
initialise a new
Role
.Parameters: whitelist -- pass a boolean indicating whether this role is a whitelist -
__contains__
(field_name)[source]¶ overloaded membership test that inverts the check depending on wether the role is a whitelist or blacklist.
If the role is defined as whitelist=True the normal membership test is applied ie:
>>> 'name' in whitelist('name') True
For blacklist the test is flipped as we are aiming to ensure the field name is not present in the role:
>>> 'other_name' in blacklist('name') True >>> 'name' in blacklist('name') False
Parameters: field_name -- name of a field to test for membership Return type: boolean Returns: boolean indicating wether field_name is found in the role
-
__or__
(other)[source]¶ Override handling of producing the union of two Roles to provide native support for merging whitelist and blacklist roles correctly.
This overloading allows users to produce the union of two roles that may, on one side, want to allow fields and on the other exclude them.
Usage:
>>> from kim.role import whitelist, blacklist >>> my_role = whitelist('foo', 'bar') | blacklist('foo', 'baz') >>> my_role Role('bar')
Parameters: other -- another instance of kim.role.Role
Raises: kim.exception.RoleError
Return type: kim.role.Role
Returns: a new kim.role.Role
containng the set of field names
-
fields
¶ return an iterable containing all the field names defined in this role.
Return type: list Returns: iterable of field names
-
-
class
kim.role.
whitelist
(*args, **kwargs)[source]¶ Whitelists are roles that define a list of fields that are permitted for inclusion when marhsaling or serializing. For example, a whitelist role called
id_only
that contains the field nameid
instructs kim that whenever theid_only
role is used only theid
field should be considered in the input/output data.Usage:
from kim import whitelist id_only_role = whitelist('id') class IdMixin(object): id = fields.Integer(read_only=True) __roles__ = { 'id_only': id_only }
-
class
kim.role.
blacklist
(*args, **kwargs)[source]¶ Blacklists are role that act in the opposite manner to whitelists. They define a list of fields that should not be used when marshaling and serializing data. A blacklist role named
id_less
that contained the field nameid
would instruct kim that every field defined on the mapper should be considered exceptid
.Usage:
from kim import whitelist class UserMapper(Mapper): id_less_role = blacklist('id') __roles__ = { 'id_less': blacklist('id') }
Pipelines¶
-
kim.pipelines.base.
pipe
(**pipe_kwargs)[source]¶ Pipe decorator is provided as a convenience to avoid duplicating logic like not running pipes when session.data is null.
Parameters: run_if_none -- Specify wether the pipe function should be called if session.data is None. Usage:
from kim.pipelines.base import pipe @pipe(run_if_none=True) def my_pipe(session): do_stuff(session)
-
class
kim.pipelines.base.
Pipeline
[source]¶ Pipelines provide a simple, extensible way of processing data for a
kim.field.Field
. Each pipeline provides 4 input groups,input_pipes
,validation_pipes
,process_pipes
andoutput_pipes
. Each containing pipe functions that are called in order passing data from one pipe to another.Kim pipes are similar to unix pipes, where each pipe in the chain has a single role in handling data before passing it on to the next pipe in the chain.
Pipelines are typically ignorant to whether they are marhsaling data or serializing data, they simply take data in one end, this may be a deserialized dict of JSON or an object that's been populated from the database, and produce an output at the other.
Usage:
from kim.pipelines.base import Pipeline class StringIntPipeline(Pipeline): input_pipes = [get_data_from_json] validation_pipes = [is_numeric_string] process_pipes [cast_to_int] output_pipes = [update_output]
-
class
kim.pipelines.collection.
CollectionMarshalPipeline
[source]¶ See also
kim.pipelines.collection.check_duplicates
kim.pipelines.collection.marshal_collection
kim.pipelines.marshaling.MarshalPipeline
Pipes¶
Base¶
-
kim.pipelines.base.
get_data_from_name
(session, *args, **kwargs)[source]¶ Extracts a specific key from data using
field.name
. This pipe is typically used as the entry point to a chain of input pipes.Parameters: session -- Kim pipeline session instance Return type: mixed Returns: the key found in data using field.name
-
kim.pipelines.base.
get_data_from_source
(session, *args, **kwargs)[source]¶ Extracts a specific key from data using
field.source
. This pipe is typically used as the entry point to a chain of output pipes.Parameters: session -- Kim pipeline session instance Return type: mixed Returns: the key found in data using field.source
-
kim.pipelines.base.
read_only
(session, *args, **kwargs)[source]¶ End processing of a pipeline if a Field is marked as read_only.
Parameters: session -- Kim pipeline session instance Raises StopPipelineExecution:
-
kim.pipelines.base.
is_valid_choice
(session, *args, **kwargs)[source]¶ End processing of a pipeline if a Field is marked as read_only.
Parameters: session -- Kim pipeline session instance Raises StopPipelineExecution:
String¶
-
kim.pipelines.string.
is_valid_string
(session, *args, **kwargs)[source]¶ Pipe used to determine if a value can be coerced to a string
Parameters: session -- Kim pipeline session instance
Integer¶
String¶
-
kim.pipelines.numeric.
is_valid_decimal
(session, *args, **kwargs)[source]¶ Pipe used to determine if a value can be coerced to a Decimal
Parameters: session -- Kim pipeline session instance
Boolean¶
Nested¶
-
kim.pipelines.nested.
marshal_nested
(session, *args, **kwargs)[source]¶ Marshal data using the nested mapper defined on this field.
There are 6 possible scenarios, depending on the security setters and presence of a getter function
- Getter function returns an object and no updates are allowed - Return the object immediately
- Getter function returns an object and updates are allowed - Call the nested mapper with the object to update it
- Object already exists, getter function returns None/does not exist and in place updates are allowed - Call the nested mapper with the existing object to update it
- Getter function returns None/does not exist and creation of new objects is allowed - Call the nested mapper to create a new object
- Getter function returns None/does not exist and creation of new objects is not allowed, nor are in place updates - Raise an exception.
- Object already exists, getter function returns None/does not exist and partial updates are allowed - Call the nested mapper with the existing object to update it
Parameters: session -- Kim pipeline session instance
Collection¶
-
kim.pipelines.collection.
marshall_collection
(session, *args, **kwargs)[source]¶ iterate over each item in
data
and marshal the item through the wrapped field defined for this collectionParameters: session -- Kim pipeline session instance TODO(mike) this should be called marshal_collection