Association service

service.py

# -*- coding: utf-8 -*-

# apptools RPC
from apptools import rpc


## TrackerException - abstract parent for all exceptions related to :py:class:`Tracker`.
class TrackerException(rpc.remote.ApplicationError): pass


## AssociationFailed - raised when an attempt to associate a :py:class:`Tracker` or ``ASID`` with an ``adgroup`` fails.
class AssociationFailed(TrackerException): ''' Raised when an `associate` call fails. '''


## Association - expresses an association between an ``adgroup`` and :py:class:`Tracker` or ``ASID``.
class Association(rpc.messages.Message):

    ''' Expresses an association between an ``adgroup``
        and either a :py:class:`Tracker` or ``ASID``. '''

    adgroup = rpc.messages.StringField(1)
    asid = rpc.messages.StringField(2)
    tracker = rpc.messages.StringField(3)


@rpc.service
class TrackerService(rpc.Service):

    ''' Tracker service sample with `associate` method. '''

    exceptions = datastructures.DictProxy(**{
      'generic': TrackerServiceException,
      'association_failed': AssociationFailed
    })

    @rpc.method(Association)
    def associate(self, request):

        ''' Associate a :py:class:`Tracker` with a given
            ``adgroup_id``, or add an ``ASID``-type legacy
            association to an ``adgroup_id``, via the special
            adgroup/tracker mappings.

            :param request:
            :raises:
            :returns: '''

        try:

            # call low-level association method
            self.tracker.associate(request.adgroup, request.tracker, request.asid)

        except Exception as e:

            # raise client-valid exception
            context = (e.__class__.__name__, str(e))
            raise self.exceptions.association_failed('Association failed with exception "%s": %s.' % context)

        return messages.Association(**{
            'adgroup': request.adgroup,
            'asid': request.asid,
            'tracker': request.tracker
        })