From eadbc6a1e1ae5599a21cee5683c3b3813f1216b6 Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Mon, 13 Oct 2014 18:26:22 -0400
Subject: [PATCH 1/5] Add docstrings to pacify pylint.

See https://github.com/GoogleCloudPlatform/gcloud-python/pull/238#issuecomment-58954981.
---
 gcloud/__init__.py              |  2 +
 gcloud/connection.py            |  6 +++
 gcloud/datastore/connection.py  | 70 ++++++++++++++++++++++++++++++++-
 gcloud/datastore/dataset.py     | 40 ++++++++++++++++++-
 gcloud/datastore/key.py         |  3 ++
 gcloud/datastore/query.py       |  8 ++++
 gcloud/datastore/transaction.py |  3 ++
 7 files changed, 128 insertions(+), 4 deletions(-)

diff --git a/gcloud/__init__.py b/gcloud/__init__.py
index dd2d05294dcf..bf5194d67ee2 100644
--- a/gcloud/__init__.py
+++ b/gcloud/__init__.py
@@ -1 +1,3 @@
+"""GCloud API wrappers in idiomatic Python.
+"""
 __version__ = '0.02.2'
diff --git a/gcloud/connection.py b/gcloud/connection.py
index b25e9cf70d61..57590f4d7ba8 100644
--- a/gcloud/connection.py
+++ b/gcloud/connection.py
@@ -1,3 +1,5 @@
+""" Shared implementation of connections to API servers.
+"""
 from pkg_resources import get_distribution
 
 import httplib2
@@ -31,6 +33,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
diff --git a/gcloud/datastore/connection.py b/gcloud/datastore/connection.py
index 9916615a2781..f1c9420fd5a6 100644
--- a/gcloud/datastore/connection.py
+++ b/gcloud/datastore/connection.py
@@ -1,3 +1,5 @@
+"""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 +61,22 @@ def _request(self, dataset_id, method, data):
         return content
 
     def _rpc(self, dataset_id, method, request_pb, response_pb_cls):
+        """ Make an 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,6 +112,16 @@ 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:
@@ -101,6 +129,12 @@ def transaction(self, transaction=connection.Connection._EMPTY):
             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 +312,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 +395,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 +413,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])
diff --git a/gcloud/datastore/dataset.py b/gcloud/datastore/dataset.py
index a5e4bbb0f637..f64dbdd60009 100644
--- a/gcloud/datastore/dataset.py
+++ b/gcloud/datastore/dataset.py
@@ -1,3 +1,6 @@
+"""Wrapper for gcloud datastore datasets.
+"""
+
 class Dataset(object):
     """A dataset in the Cloud Datastore.
 
@@ -58,34 +61,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
 
diff --git a/gcloud/datastore/key.py b/gcloud/datastore/key.py
index 16e0c4ea1f66..57e091747728 100644
--- a/gcloud/datastore/key.py
+++ b/gcloud/datastore/key.py
@@ -1,3 +1,6 @@
+"""Wrapper for gcloud datastore keys.
+"""
+
 import copy
 from itertools import izip
 
diff --git a/gcloud/datastore/query.py b/gcloud/datastore/query.py
index aeeb6e540d8e..dc1abad21c2f 100644
--- a/gcloud/datastore/query.py
+++ b/gcloud/datastore/query.py
@@ -1,3 +1,6 @@
+"""Wrapper for gcloud datastore queries.
+"""
+
 import base64
 import copy
 
@@ -60,6 +63,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
diff --git a/gcloud/datastore/transaction.py b/gcloud/datastore/transaction.py
index 7eda4ecc8255..8ade730bc413 100644
--- a/gcloud/datastore/transaction.py
+++ b/gcloud/datastore/transaction.py
@@ -1,3 +1,6 @@
+"""Wrapper for gcloud datastore transactions.
+"""
+
 from gcloud.datastore import datastore_v1_pb2 as datastore_pb
 from gcloud.datastore.key import Key
 

From 204513e6794b9b4eb2d528d1e79e9e2415ce0c48 Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Mon, 13 Oct 2014 18:43:20 -0400
Subject: [PATCH 2/5] Typo.

Incorporate feedback from @dhermes.
---
 gcloud/datastore/connection.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/gcloud/datastore/connection.py b/gcloud/datastore/connection.py
index f1c9420fd5a6..e279b42dbbdb 100644
--- a/gcloud/datastore/connection.py
+++ b/gcloud/datastore/connection.py
@@ -61,7 +61,7 @@ def _request(self, dataset_id, method, data):
         return content
 
     def _rpc(self, dataset_id, method, request_pb, response_pb_cls):
-        """ Make an protobuf RPC request.
+        """ Make a protobuf RPC request.
 
         :type dataset_id: string
         :param dataset_id: The ID of the dataset to connect to. This is

From 2b51393e8819604ab7c411725d3bc0ffa6bd2d0f Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Mon, 13 Oct 2014 18:46:05 -0400
Subject: [PATCH 3/5] Avoid 'wrapper' in module docstrings.

Incorporate feedback from @dhermes.
---
 gcloud/__init__.py              | 2 +-
 gcloud/datastore/dataset.py     | 2 +-
 gcloud/datastore/key.py         | 2 +-
 gcloud/datastore/query.py       | 2 +-
 gcloud/datastore/transaction.py | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/gcloud/__init__.py b/gcloud/__init__.py
index bf5194d67ee2..5bb5b14b0111 100644
--- a/gcloud/__init__.py
+++ b/gcloud/__init__.py
@@ -1,3 +1,3 @@
-"""GCloud API wrappers in idiomatic Python.
+"""GCloud API access in idiomatic Python.
 """
 __version__ = '0.02.2'
diff --git a/gcloud/datastore/dataset.py b/gcloud/datastore/dataset.py
index f64dbdd60009..307d54f871b9 100644
--- a/gcloud/datastore/dataset.py
+++ b/gcloud/datastore/dataset.py
@@ -1,4 +1,4 @@
-"""Wrapper for gcloud datastore datasets.
+"""Create / interact with gcloud datastore datasets.
 """
 
 class Dataset(object):
diff --git a/gcloud/datastore/key.py b/gcloud/datastore/key.py
index 57e091747728..a3db2ed78ce6 100644
--- a/gcloud/datastore/key.py
+++ b/gcloud/datastore/key.py
@@ -1,4 +1,4 @@
-"""Wrapper for gcloud datastore keys.
+"""Create / interact with gcloud datastore keys.
 """
 
 import copy
diff --git a/gcloud/datastore/query.py b/gcloud/datastore/query.py
index dc1abad21c2f..2b49f370b3ea 100644
--- a/gcloud/datastore/query.py
+++ b/gcloud/datastore/query.py
@@ -1,4 +1,4 @@
-"""Wrapper for gcloud datastore queries.
+"""Create / interact with gcloud datastore queries.
 """
 
 import base64
diff --git a/gcloud/datastore/transaction.py b/gcloud/datastore/transaction.py
index 8ade730bc413..16496927831e 100644
--- a/gcloud/datastore/transaction.py
+++ b/gcloud/datastore/transaction.py
@@ -1,4 +1,4 @@
-"""Wrapper for gcloud datastore transactions.
+"""Create / interact with gcloud datastore transactions.
 """
 
 from gcloud.datastore import datastore_v1_pb2 as datastore_pb

From 60245f5a751b66314ae28f9995a8b9f043b107c7 Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Mon, 13 Oct 2014 18:48:01 -0400
Subject: [PATCH 4/5] PEP8:  single-line docstrings.

Incorporate feedback from @dhermes.
---
 gcloud/__init__.py              | 3 +--
 gcloud/datastore/connection.py  | 3 +--
 gcloud/datastore/dataset.py     | 3 +--
 gcloud/datastore/key.py         | 3 +--
 gcloud/datastore/query.py       | 3 +--
 gcloud/datastore/transaction.py | 3 +--
 6 files changed, 6 insertions(+), 12 deletions(-)

diff --git a/gcloud/__init__.py b/gcloud/__init__.py
index 5bb5b14b0111..aaece64626ac 100644
--- a/gcloud/__init__.py
+++ b/gcloud/__init__.py
@@ -1,3 +1,2 @@
-"""GCloud API access in idiomatic Python.
-"""
+"""GCloud API access in idiomatic Python."""
 __version__ = '0.02.2'
diff --git a/gcloud/datastore/connection.py b/gcloud/datastore/connection.py
index e279b42dbbdb..8faabad0352f 100644
--- a/gcloud/datastore/connection.py
+++ b/gcloud/datastore/connection.py
@@ -1,5 +1,4 @@
-"""Connections to gcloud datastore API servers.
-"""
+"""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
diff --git a/gcloud/datastore/dataset.py b/gcloud/datastore/dataset.py
index 307d54f871b9..314dfba94ec9 100644
--- a/gcloud/datastore/dataset.py
+++ b/gcloud/datastore/dataset.py
@@ -1,5 +1,4 @@
-"""Create / interact with gcloud datastore datasets.
-"""
+"""Create / interact with gcloud datastore datasets."""
 
 class Dataset(object):
     """A dataset in the Cloud Datastore.
diff --git a/gcloud/datastore/key.py b/gcloud/datastore/key.py
index a3db2ed78ce6..0ba282735cf0 100644
--- a/gcloud/datastore/key.py
+++ b/gcloud/datastore/key.py
@@ -1,5 +1,4 @@
-"""Create / interact with gcloud datastore keys.
-"""
+"""Create / interact with gcloud datastore keys."""
 
 import copy
 from itertools import izip
diff --git a/gcloud/datastore/query.py b/gcloud/datastore/query.py
index 2b49f370b3ea..46b2dedb780f 100644
--- a/gcloud/datastore/query.py
+++ b/gcloud/datastore/query.py
@@ -1,5 +1,4 @@
-"""Create / interact with gcloud datastore queries.
-"""
+"""Create / interact with gcloud datastore queries."""
 
 import base64
 import copy
diff --git a/gcloud/datastore/transaction.py b/gcloud/datastore/transaction.py
index 16496927831e..d20f35a686d4 100644
--- a/gcloud/datastore/transaction.py
+++ b/gcloud/datastore/transaction.py
@@ -1,5 +1,4 @@
-"""Create / interact with gcloud datastore transactions.
-"""
+"""Create / interact with gcloud datastore transactions."""
 
 from gcloud.datastore import datastore_v1_pb2 as datastore_pb
 from gcloud.datastore.key import Key

From 56458c24619205aec1bc4f76b8f490ae1c58889c Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Mon, 13 Oct 2014 22:02:47 -0400
Subject: [PATCH 5/5] PEP8:  this time for sure, Rocky

---
 gcloud/connection.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/gcloud/connection.py b/gcloud/connection.py
index 57590f4d7ba8..10d84e321bed 100644
--- a/gcloud/connection.py
+++ b/gcloud/connection.py
@@ -1,5 +1,4 @@
-""" Shared implementation of connections to API servers.
-"""
+""" Shared implementation of connections to API servers."""
 from pkg_resources import get_distribution
 
 import httplib2