API Reference¶
ProtoMapping¶
-
class
mercator.
ProtoMapping
(data)[source]¶ Base class to define attribute mapping from
dict
ordeclarative_base()
subclasses’ instances into pre-filled protobuf messages.Example:
from mercator import ( ProtoMapping, ProtoKey, ProtoList, SinglePropertyMapping, ) from google.protobuf.timestamp_pb2 import Timestamp ProtobufTimestamp = SinglePropertyMapping(int, Timestamp, 'seconds') class AuthRequestMapping(ProtoMapping): __proto__ = domain_pb2.AuthRequest username = ProtoKey('username', str) password = ProtoKey('password', str) class UserAuthTokenMapping(ProtoMapping): __proto__ = domain_pb2.User.AuthToken value = ProtoKey('data', str) created_at = ProtoKey('created_at', ProtobufTimestamp) expires_at = ProtoKey('expires_at', ProtobufTimestamp) class UserMapping(ProtoMapping): __proto__ = domain_pb2.User uuid = ProtoKey('id', str) email = ProtoKey('email', str) username = ProtoKey('login', str) tokens = ProtoList('tokens', UserAuthTokenMapping) metadata = ProtoKey('extra_info', dict) class MediaMapping(ProtoMapping): __proto__ = domain_pb2.Media author = ProtoKey('author', UserMapping) download_url = ProtoKey('link', str) blob = ProtoKey('blob', bytes) content_type = ProtoKey('content_type', bytes) class AuthResponseMapping(ProtoMapping): __proto__ = domain_pb2.AuthResponse token = ProtoKey('token', UserAuthTokenMapping)
ProtoKey¶
-
class
mercator.
ProtoKey
(name_at_source: str, target_type: type = None)[source]¶ Represents the intent to translate a object property or dictionary key into a protobuf message.
Use this to map specific values into a protobuf object.
Example:
class UserMapping(ProtoMapping): __proto__ = domain_pb2.User username = ProtoKey('login', str)
Parameters: - name_at_source – a string with the name of key or property to be extracted in an input object before casting into the target type.
- target_type – an optional
ProtoMapping
subclass or native python type. Check target_type for more details.
-
cast
(value)[source]¶ Parameters: value – a python object that is compatible with the given target_type
Returns: value
coerced into the target type. Supports ProtoMappings by automatically callingto_protobuf()
.
ProtoList¶
-
class
mercator.
ProtoList
(name_at_source: str, target_type: type = None)[source]¶ Represents the intent to translate a several object properties or dictionary keys into a list in a protobuf message.
Example:
class UserMapping(ProtoMapping): __proto__ = domain_pb2.User tokens = ProtoList('tokens', UserAuthTokenMapping)
Parameters: - name_at_source – a string with the name of key or property to be extracted in an input object before casting into the target type.
- target_type – an optional
ProtoMapping
subclass or native python type. Check target_type for more details.
-
cast
(value)[source]¶ Parameters: value – a python object that is compatible with the given target_type
Returns: list of items target type coerced into the target_type
. Supports ProtoMappings by automatically callingto_protobuf()
.
SinglePropertyMapping¶
-
class
mercator.
SinglePropertyMapping
(to_python, pb2_type, argname)[source]¶ creates a new instance of the given protobuf type populated with a single property preprocessing the input value with the given callable.
Example:
from mercator import ( ProtoMapping, ProtoKey, SinglePropertyMapping, ) from google.protobuf.timestamp_pb2 import Timestamp ProtobufTimestamp = SinglePropertyMapping(int, Timestamp, 'seconds') class UserAuthTokenMapping(ProtoMapping): __proto__ = domain_pb2.User.AuthToken value = ProtoKey('data', str) created_at = ProtoKey('created_at', ProtobufTimestamp) expires_at = ProtoKey('expires_at', ProtobufTimestamp) auth_token = UserAuthTokenMapping({'created_at': 12345}).to_protobuf() assert isinstance(auth_token.created_at, Timestamp) assert auth_token.created_at.seconds == 12345
mercator.errors¶
mercator.meta¶
-
class
mercator.meta.
FieldMapping
(name_at_source: str, target_type: type = None)[source]¶ Base-class for field mapping declaration in
ProtoMapping
that is:This base-class resides in
mercator.meta
so the metaclass can capture the field mapping declarations during import-time.Parameters: - name_at_source – a string with the name of key or property to be extracted in an input object before casting into the target type.
- target_type – an optional
ProtoMapping
subclass or native python type. Check target_type for more details.
-
class
mercator.meta.
ImplicitField
(name_at_source: str, target_type: type = None)[source]¶ Like
ProtoKey
but works is declared automagically by the metaclass.-
cast
(value)¶ coerces the given
value
into the target type. :param value: a python object that is compatible with the giventarget_type
-
-
class
mercator.meta.
MercatorDomainClass
[source]¶ The existence of this class is a trick to avoid redundant imports.
Any subclasses of this are automatically supported by
FieldMapping
astarget_type
.This was introduced to support
SinglePropertyMapping
but can be used in the future in any new types that leverage type casting.
-
class
mercator.meta.
MetaMapping
[source]¶ Metaclass to leverage and enforce correct syntax sugar when declaring protomappings.
Check the source code for comments explaining how everything works.
-
mro
()¶ Return a type’s method resolution order.
-
-
mercator.meta.
field_properties_from_proto_class
(proto_class)[source]¶ inspects all members of the given proto_class and returns a list of those who seem to be a message field (determined by
is_field_property()
)
-
mercator.meta.
is_field_property
(obj)[source]¶ utility function to check if the give object is a field from a protobuf message.
For now there is not much metadata when inspecting a protobuf class compiled by protoc, so the current strategy is:
- Take the
obj.__class__
- Take the
__name__
of the class. - Check that the name contains the string “FieldProperty”
- Take the
-
mercator.meta.
validate_and_register_base_model_class
(cls, name, attributes)[source]¶ Invoked by
MetaMapping
during “import time” to validate the declaration of __source_input_type__.