PEP257 Clean-up of docstrings.

Fixes all Pylint failures of
- missing-returns-doc
- redundant-returns-doc
- ungrouped-imports

Also makes a little headway on missing-raises-doc though it's
unclear if this error should be fixed.

Towards #1968.

gcloud/_helpers.py

@@ -26,18 +26,17 @@
 from threading import local as Local
 
 from google.protobuf import timestamp_pb2
+try:
+    from google.appengine.api import app_identity
+except ImportError:
+    app_identity = None
 import six
 from six.moves.http_client import HTTPConnection
 from six.moves import configparser
 
 from gcloud.environment_vars import PROJECT
 from gcloud.environment_vars import CREDENTIALS
 
-try:
-    from google.appengine.api import app_identity
-except ImportError:
-    app_identity = None
-
 
 _NOW = datetime.datetime.utcnow  # To be replaced by tests.
 _RFC3339_MICROS = '%Y-%m-%dT%H:%M:%S.%fZ'
@@ -77,15 +76,17 @@ def push(self, resource):
     def pop(self):
         """Pop a resource from our stack.
 
-        :raises: IndexError if the stack is empty.
+        :rtype: object
         :returns: the top-most resource, after removing it.
+        :raises IndexError: if the stack is empty.
         """
         return self._stack.pop()
 
     @property
     def top(self):
         """Get the top-most resource
 
+        :rtype: object
         :returns: the top-most item, or None if the stack is empty.
         """
         if len(self._stack) > 0:
@@ -141,8 +142,7 @@ def _ensure_tuple_or_list(arg_name, tuple_or_list):
 
     :rtype: list of str
     :returns: The ``tuple_or_list`` passed in cast to a ``list``.
-    :raises: class:`TypeError` if the ``tuple_or_list`` is not a tuple or
-             list.
+    :raises TypeError: if the ``tuple_or_list`` is not a tuple or list.
     """
     if not isinstance(tuple_or_list, (tuple, list)):
         raise TypeError('Expected %s to be a tuple or list. '
@@ -392,6 +392,8 @@ def _rfc3339_nanos_to_datetime(dt_str):
 
     :rtype: :class:`datetime.datetime`
     :returns: The datetime object created from the string.
+    :raises ValueError: If the timestamp does not match the RFC 3339
+                        regular expression.
     """
     with_nanos = _RFC3339_NANOS.match(dt_str)
     if with_nanos is None:
@@ -439,8 +441,7 @@ def _to_bytes(value, encoding='ascii'):
     :rtype: str / bytes
     :returns: The original value converted to bytes (if unicode) or as passed
               in if it started out as bytes.
-    :raises: :class:`TypeError <exceptions.TypeError>` if the value
-             could not be converted to bytes.
+    :raises TypeError: if the value could not be converted to bytes.
     """
     result = (value.encode(encoding)
               if isinstance(value, six.text_type) else value)
@@ -460,8 +461,7 @@ def _bytes_to_unicode(value):
     :returns: The original value converted to unicode (if bytes) or as passed
               in if it started out as unicode.
 
-    :raises: :class:`ValueError` if the value could not be converted to
-             unicode.
+    :raises ValueError: if the value could not be converted to unicode.
     """
     result = (value.decode('utf-8')
               if isinstance(value, six.binary_type) else value)
@@ -522,9 +522,9 @@ def _name_from_project_path(path, project, template):
 
     :rtype: str
     :returns: Name parsed from ``path``.
-    :raises: :class:`ValueError` if the ``path`` is ill-formed or if
-             the project from the ``path`` does not agree with the
-             ``project`` passed in.
+    :raises ValueError: if the ``path`` is ill-formed or if the project from
+                        the ``path`` does not agree with the ``project``
+                        passed in.
     """
     if isinstance(template, str):
         template = re.compile(template)

gcloud/bigquery/dataset.py

@@ -432,6 +432,9 @@ def exists(self, client=None):
         :type client: :class:`gcloud.bigquery.client.Client` or ``NoneType``
         :param client: the client to use.  If not passed, falls back to the
                        ``client`` stored on the current dataset.
+
+        :rtype: bool
+        :returns: Boolean indicating existence of the dataset.
         """
         client = self._require_client(client)
 

gcloud/bigquery/job.py

@@ -319,6 +319,9 @@ def exists(self, client=None):
         :type client: :class:`gcloud.bigquery.client.Client` or ``NoneType``
         :param client: the client to use.  If not passed, falls back to the
                        ``client`` stored on the current dataset.
+
+        :rtype: bool
+        :returns: Boolean indicating existence of the job.
         """
         client = self._require_client(client)
 

gcloud/bigquery/table.py

@@ -461,6 +461,9 @@ def exists(self, client=None):
         :type client: :class:`gcloud.bigquery.client.Client` or ``NoneType``
         :param client: the client to use.  If not passed, falls back to the
                        ``client`` stored on the current dataset.
+
+        :rtype: bool
+        :returns: Boolean indicating existence of the table.
         """
         client = self._require_client(client)
 

gcloud/bigtable/happybase/connection.py

@@ -71,8 +71,8 @@ def _get_instance(timeout=None):
     :rtype: :class:`gcloud.bigtable.instance.Instance`
     :returns: The unique instance owned by the project inferred from
               the environment.
-    :raises: :class:`ValueError <exceptions.ValueError>` if there is a failed
-             location or any number of instances other than one.
+    :raises ValueError: if there is a failed location or any number of
+                        instances other than one.
     """
     client_kwargs = {'admin': True}
     if timeout is not None:
@@ -182,9 +182,8 @@ def _handle_legacy_args(arguments_dict):
         :type arguments_dict: dict
         :param arguments_dict: Unused keyword arguments.
 
-        :raises: :class:`TypeError <exceptions.TypeError>` if a keyword other
-                 than ``host``, ``port``, ``compat``, ``transport`` or
-                 ``protocol`` is used.
+        :raises TypeError: if a keyword other than ``host``, ``port``,
+                           ``compat``, ``transport`` or ``protocol`` is used.
         """
         common_args = _LEGACY_ARGS.intersection(six.iterkeys(arguments_dict))
         if common_args:
@@ -322,10 +321,12 @@ def create_table(self, name, families):
                          * :class:`dict`
                          * :class:`.GarbageCollectionRule`
 
-        :raises: :class:`TypeError <exceptions.TypeError>` if ``families`` is
-                 not a dictionary,
-                 :class:`ValueError <exceptions.ValueError>` if ``families``
-                 has no entries
+        :raises TypeError: If ``families`` is not a dictionary.
+        :raises ValueError: If ``families`` has no entries.
+        :raises AlreadyExists: If creation fails due to an already
+                               existing table.
+        :raises NetworkError: If creation fails for a reason other than
+                              table exists.
         """
         if not isinstance(families, dict):
             raise TypeError('families arg must be a dictionary')

gcloud/bigtable/happybase/pool.py

@@ -113,12 +113,13 @@ def connection(self, timeout=None):
         If ``timeout`` is omitted, this method waits forever for a connection
         to become available from the local queue.
 
+        Yields an active :class:`Connection <.happybase.connection.Connection>`
+        from the pool.
+
         :type timeout: int
         :param timeout: (Optional) Time (in seconds) to wait for a connection
                         to open.
 
-        :rtype: :class:`Connection <.happybase.connection.Connection>`
-        :returns: An active connection from the pool.
         :raises: :class:`NoConnectionsAvailable` if no connection can be
                  retrieved from the pool before the ``timeout`` (only if
                  a timeout is specified).

gcloud/connection.py

@@ -324,6 +324,9 @@ def api_request(self, method, path, query_params=None,
                                initialization of the object at a later time.
 
         :raises: Exception if the response code is not 200 OK.
+        :rtype: dict or str
+        :returns: The API response payload, either as a raw string or
+                  a dictionary if the response is valid JSON.
         """
         url = self.build_api_url(path=path, query_params=query_params,
                                  api_base_url=api_base_url,

gcloud/datastore/client.py

@@ -366,7 +366,7 @@ def delete(self, key):
         :type key: :class:`gcloud.datastore.key.Key`
         :param key: The key to be deleted from the datastore.
         """
-        return self.delete_multi(keys=[key])
+        self.delete_multi(keys=[key])
 
     def delete_multi(self, keys):
         """Delete keys from the Cloud Datastore.

gcloud/datastore/connection.py

@@ -112,10 +112,13 @@ def _rpc(self, project, method, request_pb, response_pb_cls):
         :type request_pb: :class:`google.protobuf.message.Message` instance
         :param request_pb: the protobuf instance representing the request.
 
-        :type response_pb_cls: A :class:`google.protobuf.message.Message'
+        :type response_pb_cls: A :class:`google.protobuf.message.Message`
                                subclass.
         :param response_pb_cls: The class used to unmarshall the response
                                 protobuf.
+
+        :rtype: :class:`google.protobuf.message.Message`
+        :returns: The RPC message parsed from the response.
         """
         response = self._request(project=project, method=method,
                                  data=request_pb.SerializeToString())
@@ -142,6 +145,9 @@ def build_api_url(self, project, method, base_url=None,
         :type api_version: string
         :param api_version: The version of the API to connect to.
                             You shouldn't have to provide this.
+
+        :rtype: str
+        :returns: The API URL created.
         """
         return self.API_URL_TEMPLATE.format(
             api_base=(base_url or self.api_base_url),
@@ -322,9 +328,9 @@ def commit(self, project, request, transaction_id):
             This method will mutate ``request`` before using it.
 
         :rtype: tuple
-        :returns': The pair of the number of index updates and a list of
-                   :class:`._generated.entity_pb2.Key` for each incomplete key
-                   that was completed in the commit.
+        :returns: The pair of the number of index updates and a list of
+                  :class:`._generated.entity_pb2.Key` for each incomplete key
+                  that was completed in the commit.
         """
         if transaction_id:
             request.mode = _datastore_pb2.CommitRequest.TRANSACTIONAL
@@ -415,9 +421,9 @@ def _parse_commit_response(commit_response_pb):
     :param commit_response_pb: The protobuf response from a commit request.
 
     :rtype: tuple
-    :returns': The pair of the number of index updates and a list of
-               :class:`._generated.entity_pb2.Key` for each incomplete key
-               that was completed in the commit.
+    :returns: The pair of the number of index updates and a list of
+              :class:`._generated.entity_pb2.Key` for each incomplete key
+              that was completed in the commit.
     """
     mut_results = commit_response_pb.mutation_results
     index_updates = commit_response_pb.index_updates

gcloud/datastore/entity.py

@@ -131,6 +131,7 @@ def exclude_from_indexes(self):
         """Names of fields which are *not* to be indexed for this entity.
 
         :rtype: sequence of field names
+        :returns: The set of fields excluded from indexes.
         """
         return frozenset(self._exclude_from_indexes)
 

gcloud/datastore/helpers.py

@@ -296,6 +296,7 @@ def _pb_attr_value(val):
                bool, float, integer, string
     :param val: The value to be scrutinized.
 
+    :rtype: tuple
     :returns: A tuple of the attribute name and proper value type.
     """
 
@@ -341,6 +342,7 @@ def _get_value_from_value_pb(value_pb):
     :type value_pb: :class:`gcloud.datastore._generated.entity_pb2.Value`
     :param value_pb: The Value Protobuf.
 
+    :rtype: object
     :returns: The value provided by the Protobuf.
     :raises: :class:`ValueError <exceptions.ValueError>` if no value type
              has been set.

gcloud/datastore/query.py

@@ -101,6 +101,7 @@ def project(self):
         """Get the project for this Query.
 
         :rtype: str
+        :returns: The project for the query.
         """
         return self._project or self._client.project
 
@@ -128,6 +129,7 @@ def kind(self):
         """Get the Kind of the Query.
 
         :rtype: string
+        :returns: The kind for the query.
         """
         return self._kind
 
@@ -155,6 +157,7 @@ def ancestor(self):
         """The ancestor key for the query.
 
         :rtype: Key or None
+        :returns: The ancestor for the query.
         """
         return self._ancestor
 
@@ -179,6 +182,7 @@ def filters(self):
         """Filters set on the query.
 
         :rtype: sequence of (property_name, operator, value) tuples.
+        :returns: The filters set on the query.
         """
         return self._filters[:]
 
@@ -267,6 +271,7 @@ def order(self):
         """Names of fields used to sort query results.
 
         :rtype: sequence of string
+        :returns: The order(s) set on the query.
         """
         return self._order[:]
 
@@ -291,6 +296,7 @@ def distinct_on(self):
         """Names of fields used to group query results.
 
         :rtype: sequence of string
+        :returns: The "distinct on" fields set on the query.
         """
         return self._distinct_on[:]
 
@@ -338,6 +344,7 @@ def fetch(self, limit=None, offset=0, start_cursor=None, end_cursor=None,
                        If not supplied, uses the query's value.
 
         :rtype: :class:`Iterator`
+        :returns: The iterator for the query.
         :raises: ValueError if ``connection`` is not passed and no implicit
                  default has been set.
         """
@@ -400,6 +407,7 @@ def next_page(self):
         to iterate on the current Iterator.
 
         :rtype: tuple, (entities, more_results, cursor)
+        :returns: The next page of results.
         """
         pb = _pb_from_query(self._query)
 

gcloud/datastore/transaction.py

@@ -112,6 +112,7 @@ def current(self):
             returns None.
 
         :rtype: :class:`gcloud.datastore.transaction.Transaction` or None
+        :returns: The current transaction (if any are active).
         """
         top = super(Transaction, self).current()
         if isinstance(top, Transaction):

gcloud/dns/changes.py

@@ -229,6 +229,9 @@ def exists(self, client=None):
         :type client: :class:`gcloud.dns.client.Client` or ``NoneType``
         :param client: the client to use.  If not passed, falls back to the
                        ``client`` stored on the current zone.
+
+        :rtype: bool
+        :returns: Boolean indicating existence of the changes.
         """
         client = self._require_client(client)
         try:

gcloud/dns/zone.py

@@ -267,6 +267,9 @@ def exists(self, client=None):
         :type client: :class:`gcloud.dns.client.Client` or ``NoneType``
         :param client: the client to use.  If not passed, falls back to the
                        ``client`` stored on the current zone.
+
+        :rtype: bool
+        :returns: Boolean indicating existence of the managed zone.
         """
         client = self._require_client(client)
 

gcloud/iterator.py

@@ -136,9 +136,6 @@ def get_items_from_response(self, response):
 
         :type response: dict
         :param response: The response of asking for the next page of items.
-
-        :rtype: iterable
-        :returns: Items that the iterator should yield.
         """
         raise NotImplementedError