Merge pull request #240 from tseaver/docstrings-datastore

Add gcloud.* and gcloud.datastore.* docstrings to pacify pylint.

gcloud/__init__.py

@@ -1 +1,2 @@
+"""GCloud API access in idiomatic Python."""
 __version__ = '0.02.2'

gcloud/connection.py

@@ -1,3 +1,4 @@
+""" Shared implementation of connections to API servers."""
 from pkg_resources import get_distribution
 
 import httplib2
@@ -31,6 +32,10 @@ def __init__(self, credentials=None):
 
     @property
     def credentials(self):
+        """
+        :rtype: :class:`oauth2client.client.OAuth2Credentials`, or None
+        :returns: The credentials object associated with this connection.
+        """
         return self._credentials
 
     @property

gcloud/datastore/connection.py

@@ -1,3 +1,4 @@
+"""Connections to gcloud datastore API servers."""
 from gcloud import connection
 from gcloud.datastore import datastore_v1_pb2 as datastore_pb
 from gcloud.datastore import _helpers
@@ -59,6 +60,22 @@ def _request(self, dataset_id, method, data):
         return content
 
     def _rpc(self, dataset_id, method, request_pb, response_pb_cls):
+        """ Make a protobuf RPC request.
+
+        :type dataset_id: string
+        :param dataset_id: The ID of the dataset to connect to. This is
+                           usually your project name in the cloud console.
+
+        :type method: string
+        :param method: The name of the method to invoke.
+
+        :type request_pb: :class:`google.protobuf.message.Message` instance
+        :param method: the protobuf instance representing the request.
+
+        :type response_pb_cls: a :class:`google.protobuf.message.Message'
+                               subclass.
+        :param method: The class used to unmarshall the response protobuf.
+        """
         response = self._request(dataset_id=dataset_id, method=method,
                                  data=request_pb.SerializeToString())
         return response_pb_cls.FromString(response)
@@ -94,13 +111,29 @@ def build_api_url(cls, dataset_id, method, base_url=None,
             dataset_id=dataset_id, method=method)
 
     def transaction(self, transaction=connection.Connection._EMPTY):
+        """Getter/setter for the connection's transaction object.
+
+        :type transaction: :class:`gcloud.datastore.transaction.Transaction`,
+                           (setting), or omitted (getting).
+        :param transaction: The new transaction (if passed).
+
+        :rtype: :class:`gcloud.datastore.transaction.Transaction`, (getting)
+                or :class:`gcloud.datastore.connection.Connection' (setting)
+        :returns: the current transaction (getting) or self (setting).
+        """
         if transaction is self._EMPTY:
             return self._current_transaction
         else:
             self._current_transaction = transaction
             return self
 
     def mutation(self):
+        """Getter for mutation usable with current connection.
+
+        :rtype: :class:`gcloud.datastore.datastore_v1_pb2.Mutation`.
+        :returns: the mutation instance associated with the current transaction
+                  (if one exists) or or a new mutation instance.
+        """
         if self.transaction():
             return self.transaction().mutation()
         else:
@@ -278,6 +311,17 @@ def lookup(self, dataset_id, key_pbs):
         return results
 
     def commit(self, dataset_id, mutation_pb):
+        """Commit dataset mutations in context of current transation (if any).
+
+        :type dataset_id: string
+        :param dataset_id: The dataset in which to perform the changes.
+
+        :type mutation_pb: :class:`gcloud.datastore.datastore_v1_pb2.Mutation`.
+        :param mutation_pb: The protobuf for the mutations being saved.
+
+        :rtype: :class:`gcloud.datastore.datastore_v1_pb2.MutationResult`.
+        :returns': the result protobuf for the mutation.
+        """
         request = datastore_pb.CommitRequest()
 
         if self.transaction():
@@ -350,8 +394,11 @@ def delete_entities(self, dataset_id, key_pbs):
         :param dataset_id: The dataset from which to delete the keys.
 
         :type key_pbs: list of :class:`gcloud.datastore.datastore_v1_pb2.Key`
-                       (or a single Key)
-        :param key_pbs: The key (or keys) to delete from the datastore.
+        :param key_pbs: The keys to delete from the datastore.
+
+        :rtype: boolean (if in a transaction) or else
+                :class:`gcloud.datastore.datastore_v1_pb2.MutationResult`.
+        :returns: True (if in a transaction) or else a mutation result protobuf.
         """
         mutation = self.mutation()
 
@@ -365,4 +412,22 @@ def delete_entities(self, dataset_id, key_pbs):
             return self.commit(dataset_id, mutation)
 
     def delete_entity(self, dataset_id, key_pb):
+        """Delete a single key from a dataset in the Cloud Datastore.
+
+        This method deals only with
+        :class:`gcloud.datastore.datastore_v1_pb2.Key` protobufs
+        and not with any of the other abstractions.
+        For example, it's used under the hood in the
+        :func:`gcloud.datastore.entity.Entity.delete` method.
+
+        :type dataset_id: string
+        :param dataset_id: The dataset from which to delete the key.
+
+        :type key_pb: :class:`gcloud.datastore.datastore_v1_pb2.Key`
+        :param key_pb: The key to delete from the datastore.
+
+        :rtype: boolean (if in a transaction) or else
+                :class:`gcloud.datastore.datastore_v1_pb2.MutationResult`.
+        :returns: True (if in a transaction) or else a mutation result protobuf.
+        """
         return self.delete_entities(dataset_id, [key_pb])

gcloud/datastore/dataset.py

@@ -1,3 +1,5 @@
+"""Create / interact with gcloud datastore datasets."""
+
 class Dataset(object):
     """A dataset in the Cloud Datastore.
 
@@ -58,34 +60,67 @@ def id(self):
         return self._id
 
     def query(self, *args, **kwargs):
+        """Create a query bound to this dataset.
+
+        :param args: positional arguments, passed through to the Query
+
+        :param kw: keyword arguments, passed through to the Query
+
+        :rtype: :class:`gcloud.datastore.query.Query`
+        :returns: a new Query instance, bound to this dataset.
+        """
         from gcloud.datastore.query import Query
         kwargs['dataset'] = self
         return Query(*args, **kwargs)
 
     def entity(self, kind):
+        """Create an entity bound to this dataset.
+
+        :type kind: string
+        :param kind: the "kind" of the new entity.
+
+        :rtype: :class:`gcloud.datastore.entity.Entity`
+        :returns: a new Entity instance, bound to this dataset.
+        """
         from gcloud.datastore.entity import Entity
         return Entity(dataset=self, kind=kind)
 
     def transaction(self, *args, **kwargs):
+        """Create a transaction bound to this dataset.
+
+        :param args: positional arguments, passed through to the Transaction
+
+        :param kw: keyword arguments, passed through to the Transaction
+
+        :rtype: :class:`gcloud.datastore.transaction.Transaction`
+        :returns: a new Transaction instance, bound to this dataset.
+        """
         from gcloud.datastore.transaction import Transaction
         kwargs['dataset'] = self
         return Transaction(*args, **kwargs)
 
     def get_entity(self, key):
-        """Retrieves entity from the dataset, along with all of its attributes.
+        """Retrieves entity from the dataset, along with its attributes.
 
         :type key: :class:`gcloud.datastore.key.Key`
         :param item_name: The name of the item to retrieve.
 
         :rtype: :class:`gcloud.datastore.entity.Entity` or ``None``
         :return: The requested entity, or ``None`` if there was no match found.
-
         """
         entities = self.get_entities([key])
         if entities:
             return entities[0]
 
     def get_entities(self, keys):
+        """Retrieves entities from the dataset, along with their attributes.
+
+        :type key: list of :class:`gcloud.datastore.key.Key`
+        :param item_name: The name of the item to retrieve.
+
+        :rtype: list of :class:`gcloud.datastore.entity.Entity`
+        :return: The requested entities.
+        """
         # This import is here to avoid circular references.
         from gcloud.datastore.entity import Entity
 

gcloud/datastore/key.py

@@ -1,3 +1,5 @@
+"""Create / interact with gcloud datastore keys."""
+
 import copy
 from itertools import izip
 

gcloud/datastore/query.py

@@ -1,3 +1,5 @@
+"""Create / interact with gcloud datastore queries."""
+
 import base64
 import copy
 
@@ -60,6 +62,11 @@ def __init__(self, kind=None, dataset=None):
             self._pb.kind.add().name = kind
 
     def _clone(self):
+        """Create a new Query, copying self.
+
+        :rtype: :class:`gcloud.datastore.query.Query`
+        :returns: a copy of 'self'.
+        """
         clone = copy.deepcopy(self)
         clone._dataset = self._dataset  # Shallow copy the dataset.
         return clone

gcloud/datastore/transaction.py

@@ -1,3 +1,5 @@
+"""Create / interact with gcloud datastore transactions."""
+
 from gcloud.datastore import datastore_v1_pb2 as datastore_pb
 from gcloud.datastore.key import Key