API Reference

ProtoMapping

class mercator.ProtoMapping(data)[source]

Base class to define attribute mapping from dict or declarative_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)
to_dict()[source]
Returns:a dict with keyword-arguments to construct a new instance of protobuf message defined by __proto__.
to_protobuf()[source]
Returns:a new __proto__ instance with the data extracted with to_dict().

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 calling to_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 calling to_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

exception mercator.errors.ProtobufCastError[source]

raised when failed to create a Message instance

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception mercator.errors.TypeCastError[source]

Raised when trying to cast a value of the wrong type. Used primarily by mercator.ProtoList.cast() from ProtoList

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

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.
cast(value)[source]

coerces the given value into the target type. :param value: a python object that is compatible with the given target_type

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 given target_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 as target_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:

  1. Take the obj.__class__
  2. Take the __name__ of the class.
  3. Check that the name contains the string “FieldProperty”
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__.

mercator.meta.validate_proto_attribute(name, attributes)[source]

Invoked by MetaMapping during “import time” to validate the declaration of __proto__.