From b87f96f042602a03d8d473547073043a35d31a32 Mon Sep 17 00:00:00 2001 From: Heith Seewald Date: Sun, 9 Sep 2018 23:03:46 -0500 Subject: [PATCH] [Docstring] Add docstrings and type info to create service tasks * Add docstrings to taskflow tasks. * Add type info for execute/revert methods. * Add new glossary definition for Responder. --- doc/source/glossary.rst | 3 + .../taskflow/task/create_service_tasks.py | 96 +++++++++++++++++++ 2 files changed, 99 insertions(+) diff --git a/doc/source/glossary.rst b/doc/source/glossary.rst index 8a39d4b0..f31431dc 100644 --- a/doc/source/glossary.rst +++ b/doc/source/glossary.rst @@ -50,6 +50,9 @@ Poppy is an OpenStack-related project to provide a generic and modular vendor-ne Purge Purging removes content from the edge servers, so it can be refreshed from your origin servers. + Responder + Provides a consistent way of formatting responses from various third-party APIs. + Restriction A restriction enables the user to define rules about who can or cannot access content from the cache. Examples of a restriction are allowing requests only from certain domains, geographies, or IP addresses. diff --git a/poppy/distributed_task/taskflow/task/create_service_tasks.py b/poppy/distributed_task/taskflow/task/create_service_tasks.py index e3c126ff..1db3553d 100644 --- a/poppy/distributed_task/taskflow/task/create_service_tasks.py +++ b/poppy/distributed_task/taskflow/task/create_service_tasks.py @@ -43,9 +43,35 @@ class CreateProviderServicesTask(task.Task): + """Create external services on CDN providers.""" default_provides = "responders" def execute(self, providers_list_json, project_id, service_id): + """Attempts to create services for each :term:`provider` in ``providers_list_json``. + + Example return: + + .. code-block:: python + + [{ + 'Akamai': { + 'domains_certificate_status': {u'test.hsrax.com': 'create_in_progress'}, + 'id': '[{"protocol": "https", "certificate": "sni", "policy_name": "test.hsrax.com"}]', + 'links': []} + }] + + + :param providers_list_json: A serialized list of providers. i.e. ``u'["akamai"]'`` + :type providers_list_json: unicode + :param service_id: A generated :py:func:`uuid.uuid4` that represents a service + :type service_id: unicode + :param project_id: A project/tenant id + :type service_id: unicode + + :return: List of results from :py:meth:`poppy.provider.base.responder.Responder.created` + :rtype: list[dict] + :raises ValueError: If no service exists with the given ``project_id``. + """ service_controller, self.storage_controller = \ memoized_controllers.task_controllers('poppy', 'storage') @@ -91,6 +117,7 @@ def execute(self, providers_list_json, project_id, service_id): return responders def revert(self, *args, **kwargs): + """Close any Cassandra connections left open on the session.""" try: if getattr(self, 'storage_controller') \ and self.storage_controller._driver.session: @@ -104,6 +131,40 @@ class CreateServiceDNSMappingTask(task.Task): default_provides = "dns_responder" def execute(self, responders, retry_sleep_time, project_id, service_id): + """Creates the mapping between dns service and provider url. + + The goal here is to get or create the (dns provider) domain that + a customer can then cname their vanity domain. + + **dns-provider-domain <-> cdn-provider-domain** + + + Example of ``responders`` *(input parameter)*: + + .. code-block:: python + + [{'Akamai': { + 'domains_certificate_status': {u'test.hsrax.com': 'create_in_progress'}, + 'id': '[{"protocol": "https", "certificate": "sni", "policy_name": "test.hsrax.com"}]', + 'links': []}}] + + + Example return: + + .. code-block:: python + + {'Akamai': {'access_urls': []}} + + + :param list[dict] responders: list of responders (from DNS Providers) + :param int retry_sleep_time: The number of seconds between each retry attempt + :param unicode project_id: A project/tenant id + :param unicode service_id: A generated :py:func:`uuid.uuid4` that represents a service + + :return: dict of dns_responder: :py:meth:`poppy.dns.base.responder.Responder.created` + (also see: :py:meth:`poppy.dns.rackspace.services.ServicesController#create`) + :rtype: dict + """ service_controller, dns = \ memoized_controllers.task_controllers('poppy', 'dns') @@ -134,6 +195,13 @@ def execute(self, responders, retry_sleep_time, project_id, service_id): def revert(self, responders, retry_sleep_time, project_id, service_id, **kwargs): + """Reverts the create dns mapping task if failed. + + :param list responders: list of responder + :param int retry_sleep_time: The number of seconds between each retry attempt + :param unicode project_id: A project/tenant id + :param unicode service_id: A generated :py:func:`uuid.uuid4` that represents a service + """ if self.name in kwargs['flow_failures'].keys(): retries = conf[DNS_GROUP].retries @@ -208,6 +276,14 @@ class CreateLogDeliveryContainerTask(task.Task): default_provides = "log_responders" def execute(self, project_id, auth_token, service_id): + """Create an object storage container for logs (if enabled). + + :param unicode project_id: A project/tenant id + :param unicode auth_token: auth_token from keystone used for container access + :param unicode service_id: A generated :py:func:`uuid.uuid4` that represents a service + :return: Log responders: :py:meth:`~poppy.distributed_task.taskflow.task.common.create_log_delivery_container` + :rtype: list or list[dict] + """ service_controller, self.storage_controller = \ memoized_controllers.task_controllers('poppy', 'storage') @@ -233,6 +309,7 @@ def execute(self, project_id, auth_token, service_id): return log_responders def revert(self, *args, **kwargs): + """Close any Cassandra connections left open on the session.""" try: if getattr(self, 'storage_controller') \ and self.storage_controller._driver.session: @@ -246,6 +323,25 @@ class GatherProviderDetailsTask(task.Task): default_provides = "provider_details_dict" def execute(self, responders, dns_responder, log_responders): + """Gathers the status of create service, create dns and log delivery. + + Example return: + + .. code-block:: python + + {'Akamai': OrderedDict( + [('id', '[{"protocol": "https", "certificate": "sni", "policy_name": "test.hsrax.com"}]'), + ('access_urls', []), ('status', 'deployed'), ('name', None), + ('domains_certificate_status', {u'test.hsrax.com': 'create_in_progress'}), ('error_info', None), + ('error_message', None), ('error_class', None)])} + + + :param list[dict] responders: List of results from :py:meth:`poppy.provider.base.responder.Responder.created` + :param dict dns_responder: DNS provider details (see: :py:meth:poppy.dns.base.responder.Responder.created`) + :param list[dict] log_responders: list of log_responder (see :term:`Responder`) + :return: Details from providers, dns, and log :term:`responders` stored in a single dict + :rtype: dict[str, collections.OrderedDict] + """ provider_details_dict = {} for responder in responders: for provider_name in responder: