Use Google-style docstrings

6 files changed, 86 insertions, 105 deletions

diff --git a/kombu/utils/__init__.py b/kombu/utils/__init__.py
index 2ddc4a80..4ecb7314 100644
--- a/kombu/utils/__init__.py
+++ b/kombu/utils/__init__.py
@@ -1,10 +1,4 @@
-"""
-kombu.utils
-===========
-
-Internal utilities.
-
-"""
+"""Internal utilities."""
 from __future__ import absolute_import, print_function, unicode_literals
 
 import importlib
@@ -38,11 +32,12 @@ except ImportError:  # pragma: no cover
     except ImportError:
         register_after_fork = None  # noqa
 
-
-__all__ = ['EqualityDict', 'uuid', 'maybe_list',
-           'fxrange', 'fxrangemax', 'retry_over_time',
-           'emergency_dump_state', 'cached_property', 'register_after_fork',
-           'reprkwargs', 'reprcall', 'nested', 'fileno', 'maybe_fileno']
+__all__ = [
+    'EqualityDict', 'uuid', 'maybe_list',
+    'fxrange', 'fxrangemax', 'retry_over_time',
+    'emergency_dump_state', 'cached_property', 'register_after_fork',
+    'reprkwargs', 'reprcall', 'nested', 'fileno', 'maybe_fileno',
+]
 
 
 def symbol_by_name(name, aliases={}, imp=None, package=None,
@@ -65,8 +60,7 @@ def symbol_by_name(name, aliases={}, imp=None, package=None,
     If `aliases` is provided, a dict containing short name/long name
     mappings, the name is looked up in the aliases first.
 
-    Examples::
-
+    Examples:
         >>> symbol_by_name('celery.concurrency.processes.TaskPool')
         <class 'celery.concurrency.processes.TaskPool'>
 
@@ -78,7 +72,6 @@ def symbol_by_name(name, aliases={}, imp=None, package=None,
         >>> from celery.concurrency.processes import TaskPool
         >>> symbol_by_name(TaskPool) is TaskPool
         True
-
     """
     if imp is None:
         imp = importlib.import_module
@@ -190,24 +183,28 @@ def retry_over_time(fun, catch, args=[], kwargs={}, errback=None,
     For each retry we sleep a for a while before we try again, this interval
     is increased for every retry until the max seconds is reached.
 
-    :param fun: The function to try
-    :param catch: Exceptions to catch, can be either tuple or a single
-        exception class.
-    :keyword args: Positional arguments passed on to the function.
-    :keyword kwargs: Keyword arguments passed on to the function.
-    :keyword errback: Callback for when an exception in ``catch`` is raised.
-        The callback must take three arguments: ``exc``, ``interval_range`` and
-        ``retries``, where ``exc`` is the exception instance, ``interval_range``
-        is an iterator which return the time in seconds to sleep next, and
-        ``retries`` is the number of previous retries.
-    :keyword max_retries: Maximum number of retries before we give up.
-        If this is not set, we will retry forever.
-    :keyword interval_start: How long (in seconds) we start sleeping between
-        retries.
-    :keyword interval_step: By how much the interval is increased for each
-        retry.
-    :keyword interval_max: Maximum number of seconds to sleep between retries.
-
+    Arguments:
+        fun (Callable): The function to try
+        catch (Tuple[BaseException]): Exceptions to catch, can be either
+            tuple or a single exception class.
+
+    Keyword Arguments:
+        args (Tuple): Positional arguments passed on to the function.
+        kwargs (Dict): Keyword arguments passed on to the function.
+        errback (Callable): Callback for when an exception in ``catch``
+            is raised.  The callback must take three arguments:
+            ``exc``, ``interval_range`` and ``retries``, where ``exc``
+            is the exception instance, ``interval_range`` is an iterator
+            which return the time in seconds to sleep next, and ``retries``
+            is the number of previous retries.
+        max_retries (int): Maximum number of retries before we give up.
+            If this is not set, we will retry forever.
+        interval_start (float): How long (in seconds) we start sleeping
+            between retries.
+        interval_step (float): By how much the interval is increased for
+            each retry.
+        interval_max (float): Maximum number of seconds to sleep
+            between retries.
     """
     retries = 0
     interval_range = fxrange(interval_start,
@@ -263,26 +260,24 @@ class cached_property(object):
     """Property descriptor that caches the return value
     of the get function.
 
-    *Examples*
-
-    .. code-block:: python
+    Examples:
+        .. code-block:: python
 
-        @cached_property
-        def connection(self):
-            return Connection()
-
-        @connection.setter  # Prepares stored value
-        def connection(self, value):
-            if value is None:
-                raise TypeError('Connection must be a connection')
-            return value
+            @cached_property
+            def connection(self):
+                return Connection()
 
-        @connection.deleter
-        def connection(self, value):
-            # Additional action to do at del(self.attr)
-            if value is not None:
-                print('Connection {0!r} deleted'.format(value)
+            @connection.setter  # Prepares stored value
+            def connection(self, value):
+                if value is None:
+                    raise TypeError('Connection must be a connection')
+                return value
 
+            @connection.deleter
+            def connection(self, value):
+                # Additional action to do at del(self.attr)
+                if value is not None:
+                    print('Connection {0!r} deleted'.format(value)
     """
 
     def __init__(self, fget=None, fset=None, fdel=None, doc=None):
diff --git a/kombu/utils/debug.py b/kombu/utils/debug.py
index 1df523f2..d5118a6f 100644
--- a/kombu/utils/debug.py
+++ b/kombu/utils/debug.py
@@ -1,10 +1,4 @@
-"""
-kombu.utils.debug
-=================
-
-Debugging support.
-
-"""
+"""Debugging support."""
 from __future__ import absolute_import, unicode_literals
 
 import logging
diff --git a/kombu/utils/encoding.py b/kombu/utils/encoding.py
index 722f79e3..7e1023fd 100644
--- a/kombu/utils/encoding.py
+++ b/kombu/utils/encoding.py
@@ -1,12 +1,9 @@
 # -*- coding: utf-8 -*-
-"""
-kombu.utils.encoding
-~~~~~~~~~~~~~~~~~~~~~
+"""Text encoding utilities.
 
 Utilities to encode text, and to safely emit text from running
-applications without crashing with the infamous :exc:`UnicodeDecodeError`
-exception.
-
+applications without crashing from the infamous
+:exc:`UnicodeDecodeError` exception.
 """
 from __future__ import absolute_import, unicode_literals
 
diff --git a/kombu/utils/functional.py b/kombu/utils/functional.py
index 4e3565cb..6ea7ba96 100644
--- a/kombu/utils/functional.py
+++ b/kombu/utils/functional.py
@@ -22,11 +22,11 @@ KEYWORD_MARK = object()
 class LRUCache(UserDict):
     """LRU Cache implementation using a doubly linked list to track access.
 
-    :keyword limit: The maximum number of keys to keep in the cache.
-        When a new key is inserted and the limit has been exceeded,
-        the *Least Recently Used* key will be discarded from the
-        cache.
-
+    Arguments:
+        limit (int): The maximum number of keys to keep in the cache.
+            When a new key is inserted and the limit has been exceeded,
+            the *Least Recently Used* key will be discarded from the
+            cache.
     """
 
     def __init__(self, limit=None):
@@ -166,7 +166,6 @@ class lazy(object):
 
     Overloaded operations that will evaluate the promise:
         :meth:`__str__`, :meth:`__repr__`, :meth:`__cmp__`.
-
     """
 
     def __init__(self, fun, *args, **kwargs):
diff --git a/kombu/utils/limits.py b/kombu/utils/limits.py
index 14a1fde2..13f52a12 100644
--- a/kombu/utils/limits.py
+++ b/kombu/utils/limits.py
@@ -1,10 +1,4 @@
-"""
-kombu.utils.limits
-==================
-
-Token bucket implementation for rate limiting.
-
-"""
+"""Token bucket implementation for rate limiting."""
 from __future__ import absolute_import, unicode_literals
 
 from collections import deque
@@ -17,16 +11,16 @@ __all__ = ['TokenBucket']
 class TokenBucket(object):
     """Token Bucket Algorithm.
 
-    See http://en.wikipedia.org/wiki/Token_Bucket
-    Most of this code was stolen from an entry in the ASPN Python Cookbook:
-    http://code.activestate.com/recipes/511490/
+    See Also:
+        http://en.wikipedia.org/wiki/Token_Bucket
 
-    .. admonition:: Thread safety
-
-        This implementation is not thread safe. Access to a `TokenBucket`
-        instance should occur within the critical section of any multithreaded
-        code.
+        Most of this code was stolen from an entry in the ASPN Python Cookbook:
+        http://code.activestate.com/recipes/511490/
 
+    Warning:
+        Thread Safety: This implementation is not thread safe.
+        Access to a `TokenBucket` instance should occur within the critical
+        section of any multithreaded code.
     """
 
     #: The rate in tokens/second that the bucket will be refilled.
@@ -55,19 +49,28 @@ class TokenBucket(object):
         self.contents.clear()
 
     def can_consume(self, tokens=1):
-        """Return :const:`True` if the number of tokens can be consumed
-        from the bucket.  If they can be consumed, a call will also consume the
-        requested number of tokens from the bucket. Calls will only consume
-        `tokens` (the number requested) or zero tokens -- it will never consume
-        a partial number of tokens."""
+        """Check if one or more tokens can be consumed.
+
+        Returns:
+            bool: true if the number of tokens can be consumed
+                from the bucket.  If they can be consumed, a call will also
+                consume the requested number of tokens from the bucket.
+                Calls will only consume `tokens` (the number requested)
+                or zero tokens -- it will never consume a partial number
+                of tokens.
+        """
         if tokens <= self._get_tokens():
             self._tokens -= tokens
             return True
         return False
 
     def expected_time(self, tokens=1):
-        """Return the time (in seconds) when a new token is expected
-        to be available. This will not consume any tokens from the bucket."""
+        """Get the current exepected time for when a new token is to be
+        available.
+
+        Returns:
+            float: the time in seconds.
+        """
         _tokens = self._get_tokens()
         tokens = max(tokens, _tokens)
         return (tokens - _tokens) / self.fill_rate
diff --git a/kombu/utils/scheduling.py b/kombu/utils/scheduling.py
index 0d40b767..d2ccf272 100644
--- a/kombu/utils/scheduling.py
+++ b/kombu/utils/scheduling.py
@@ -1,10 +1,4 @@
-"""
-    kombu.utils.scheduling
-    ~~~~~~~~~~~~~~~~~~~~~~
-
-    Consumer utilities.
-
-"""
+"""Consumer scheduling utilities."""
 from __future__ import absolute_import, unicode_literals
 
 from itertools import count
@@ -17,6 +11,12 @@ __all__ = [
     'FairCycle', 'priority_cycle', 'round_robin_cycle', 'sorted_cycle',
 ]
 
+CYCLE_ALIASES = {
+    'priority': 'kombu.utils.scheduling:priority_cycle',
+    'round_robin': 'kombu.utils.scheduling:round_robin_cycle',
+    'sorted': 'kombu.utils.scheduling:sorted_cycle',
+}
+
 
 @python_2_unicode_compatible
 class FairCycle(object):
@@ -91,12 +91,5 @@ class sorted_cycle(priority_cycle):
         return sorted(self.items[:n])
 
 
-CYCLE_ALIASES = {
-    'priority': 'kombu.utils.scheduling:priority_cycle',
-    'round_robin': 'kombu.utils.scheduling:round_robin_cycle',
-    'sorted': 'kombu.utils.scheduling:sorted_cycle',
-}
-
-
 def cycle_by_name(name):
     return symbol_by_name(name, CYCLE_ALIASES)