Convert sphinx-style docstrings to Google-style across src/

Author: ndevenish

src/workflows/contrib/start_service.py

@@ -60,9 +60,11 @@ def run(
         **kwargs,
     ):
         """Example command line interface to start services.
-        :param cmdline_args: List of command line arguments to pass to parser
-        :param program_name: Name of the command line tool to display in help
-        :param version: Version number to print when run with '--version'
+
+        Args:
+            cmdline_args: List of command line arguments to pass to parser
+            program_name: Name of the command line tool to display in help
+            version: Version number to print when run with '--version'
         """
 
         # Enumerate all known services

src/workflows/frontend/__init__.py

@@ -44,22 +44,24 @@ def __init__(
         """Create a frontend instance. Connect to the transport layer, start any
         requested service, begin broadcasting status information and listen
         for control commands.
-        :param restart_service:
-            If the service process dies unexpectedly the frontend should start
-            a new instance.
-        :param service:
-            A class or name of the class to be instantiated in a subprocess as
-            service.
-        :param transport:
-            Either the name of a transport class, a transport class, or a
-            transport class object.
-        :param transport_command_channel:
-            An optional channel of a transport subscription to be listened to for
-            commands.
-        :param verbose_service:
-            If set, run services with increased logging level (DEBUG).
-        :param environment:
-            An optional dictionary that is passed to started services.
+
+        Args:
+            restart_service:
+                If the service process dies unexpectedly the frontend should start
+                a new instance.
+            service:
+                A class or name of the class to be instantiated in a subprocess as
+                service.
+            transport:
+                Either the name of a transport class, a transport class, or a
+                transport class object.
+            transport_command_channel:
+                An optional channel of a transport subscription to be listened to
+                for commands.
+            verbose_service:
+                If set, run services with increased logging level (DEBUG).
+            environment:
+                An optional dictionary that is passed to started services.
         """
         self.__lock = threading.RLock()
         self.__hostid = workflows.util.generate_unique_host_id()
@@ -148,9 +150,12 @@ def update_status(self, status_code=None):
         broadcast if it is held for over 0.5 seconds.
         When the status does not change it is still broadcast every
         _status_interval seconds.
-        :param status_code: Either an integer describing the service status
-                            (see workflows.services.common_service), or None
-                            if the status is unchanged.
+
+        Args:
+            status_code:
+                Either an integer describing the service status (see
+                workflows.services.common_service), or None if the status is
+                unchanged.
         """
         if status_code is not None:
             self._service_status = status_code
@@ -399,9 +404,13 @@ def exponential_backoff(self):
 
     def switch_service(self, new_service=None):
         """Start a new service in a subprocess.
-        :param new_service: Either a service name or a service class. If not set,
-                            start up a new instance of the previous class
-        :return: True on success, False on failure.
+
+        Args:
+            new_service: Either a service name or a service class. If not set,
+                start up a new instance of the previous class.
+
+        Returns:
+            True on success, False on failure.
         """
         if new_service:
             self._service_factory = new_service

src/workflows/recipe/__init__.py

@@ -35,38 +35,44 @@ def _wrap_subscription(
     """Internal method to create an intercepting function for incoming messages
     to interpret recipes. This function is then used to subscribe to a channel
     on the transport layer.
-      :param transport_layer: Reference to underlying transport object.
-      :param subscription_call: Reference to the subscribing function of the
-                                transport layer.
-      :param channel:  Channel name to subscribe to.
-      :param callback: Real function to be called when messages are received.
-                       The callback will pass three arguments,
-                       a RecipeWrapper object (details below), the header as
-                       a dictionary structure, and the message.
-
-      :param allow_non_recipe_messages: Pass on incoming messages that do not
-                       include recipe information. In this case the first
-                       argument to the callback function will be 'None'.
-      :param log_extender: If the recipe contains useful contextual information
-                       for log messages, such as a unique ID which can be used
-                       to connect all messages originating from the same
-                       recipe, then the information will be passed to this
-                       function, which must be a context manager factory.
-      :return:         Return value of call to subscription_call.
+
+    Args:
+        transport_layer: Reference to underlying transport object.
+        subscription_call: Reference to the subscribing function of the transport layer.
+        channel: Channel name to subscribe to.
+        callback:
+            Real function to be called when messages are received.
+            The callback will pass three arguments: a RecipeWrapper object,
+            the header as a dictionary structure, and the message.
+        allow_non_recipe_messages:
+            Pass on incoming messages that do not include recipe information.
+            In this case the first argument to the callback function will be None.
+        log_extender:
+            If the recipe contains useful contextual information for log messages,
+            such as a unique ID which can be used to connect all messages
+            originating from the same recipe, then the information will be passed
+            to this function, which must be a context manager factory.
+
+    Returns:
+        Return value of call to subscription_call.
     """
 
     allow_non_recipe_messages = kwargs.pop("allow_non_recipe_messages", False)
     log_extender = kwargs.pop("log_extender", None)
 
     @functools.wraps(callback)
     def unwrap_recipe(header, message):
-        """This is a helper function unpacking incoming messages when they are
-        in a recipe format. Other messages are passed through unmodified.
-        :param header:  A dictionary of message headers. If the header contains
-                        an entry 'workflows-recipe' then the message is parsed
-                        and the embedded recipe information is passed on in a
-                        RecipeWrapper object to the target function.
-        :param message: Incoming deserialized message object.
+        """Unpack incoming messages when they are in a recipe format.
+
+        Other messages are passed through unmodified.
+
+        Args:
+            header:
+                A dictionary of message headers. If the header contains an entry
+                'workflows-recipe' then the message is parsed and the embedded
+                recipe information is passed on in a RecipeWrapper object to the
+                target function.
+            message: Incoming deserialized message object.
         """
         if mangle_for_receiving:
             message = mangle_for_receiving(message)
@@ -125,13 +131,17 @@ def wrap_subscribe(
     transport/common_transport.py. Intercept all incoming messages and parse
     for recipe information.
     See common_transport.subscribe for possible additional keyword arguments.
-      :param transport_layer: Reference to underlying transport object.
-      :param channel:  Queue name to subscribe to.
-      :param callback: Function to be called when messages are received.
-                       The callback will pass three arguments,
-                       a RecipeWrapper object (details below), the header as
-                       a dictionary structure, and the message.
-      :return: A unique subscription ID
+
+    Args:
+        transport_layer: Reference to underlying transport object.
+        channel: Queue name to subscribe to.
+        callback:
+            Function to be called when messages are received. The callback will
+            pass three arguments: a RecipeWrapper object, the header as a
+            dictionary structure, and the message.
+
+    Returns:
+        A unique subscription ID
     """
 
     return _wrap_subscription(
@@ -157,13 +167,17 @@ def wrap_subscribe_broadcast(
     subscribe_broadcast call in transport/common_transport.py. Intercept all
     incoming messages and parse for recipe information.
     See common_transport.subscribe_broadcast for possible arguments.
-      :param transport_layer: Reference to underlying transport object.
-      :param channel:  Topic name to subscribe to.
-      :param callback: Function to be called when messages are received.
-                       The callback will pass three arguments,
-                       a RecipeWrapper object (details below), the header as
-                       a dictionary structure, and the message.
-      :return: A unique subscription ID
+
+    Args:
+        transport_layer: Reference to underlying transport object.
+        channel: Topic name to subscribe to.
+        callback:
+            Function to be called when messages are received. The callback will
+            pass three arguments: a RecipeWrapper object, the header as a
+            dictionary structure, and the message.
+
+    Returns:
+        A unique subscription ID
     """
 
     return _wrap_subscription(

src/workflows/recipe/recipe.py

@@ -275,9 +275,12 @@ def merge(self, other):
         """Merge two recipes together, returning a single recipe containing all
         nodes.
         Note: This does NOT yet return a minimal recipe.
-        :param other: A Recipe object that should be merged with the current
-                      Recipe object.
-        :return: A new Recipe object containing information from both recipes.
+
+        Args:
+            other: A Recipe object that should be merged with the current Recipe object.
+
+        Returns:
+            A new Recipe object containing information from both recipes.
         """
 
         # Merging empty values returns a copy of the original

src/workflows/recipe/wrapper.py

@@ -143,7 +143,9 @@ def start(self, header=None, **kwargs):
     def checkpoint(self, message, header=None, delay=0, **kwargs):
         """Send a message to the current recipe destination. This can be used to
         keep a state for longer processing tasks.
-        :param delay: Delay transport of message by this many seconds
+
+        Args:
+            delay: Delay transport of message by this many seconds
         """
         if not self.transport:
             raise ValueError(

src/workflows/services/__init__.py

@@ -5,8 +5,12 @@
 
 def lookup(service: str):
     """Find a service class based on a name.
-    :param service: Name of the service
-    :return: A service class
+
+    Args:
+        service: Name of the service
+
+    Returns:
+        A service class
     """
     service_factory = get_known_services().get(service)
     if service_factory:
@@ -17,9 +21,11 @@ def lookup(service: str):
 
 def get_known_services():
     """Return a dictionary of all known services.
-    :return: A dictionary containing entries { service name : service class factory }
-             A factory is a function that takes no arguments and returns an
-             uninstantiated service class.
+
+    Returns:
+        A dictionary containing entries { service name : service class factory }
+        where a factory is a function that takes no arguments and returns an
+        uninstantiated service class.
     """
     if not hasattr(get_known_services, "cache"):
         setattr(