diff --git a/gcloud/__init__.py b/gcloud/__init__.py index dd2d05294dcf..aaece64626ac 100644 --- a/gcloud/__init__.py +++ b/gcloud/__init__.py @@ -1 +1,2 @@ +"""GCloud API access in idiomatic Python.""" __version__ = '0.02.2' diff --git a/gcloud/connection.py b/gcloud/connection.py index b25e9cf70d61..10d84e321bed 100644 --- a/gcloud/connection.py +++ b/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 diff --git a/gcloud/datastore/connection.py b/gcloud/datastore/connection.py index 9916615a2781..8faabad0352f 100644 --- a/gcloud/datastore/connection.py +++ b/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,6 +111,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 +128,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 +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]) diff --git a/gcloud/datastore/dataset.py b/gcloud/datastore/dataset.py index a5e4bbb0f637..314dfba94ec9 100644 --- a/gcloud/datastore/dataset.py +++ b/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 diff --git a/gcloud/datastore/key.py b/gcloud/datastore/key.py index 16e0c4ea1f66..0ba282735cf0 100644 --- a/gcloud/datastore/key.py +++ b/gcloud/datastore/key.py @@ -1,3 +1,5 @@ +"""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 aeeb6e540d8e..46b2dedb780f 100644 --- a/gcloud/datastore/query.py +++ b/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 diff --git a/gcloud/datastore/transaction.py b/gcloud/datastore/transaction.py index 7eda4ecc8255..d20f35a686d4 100644 --- a/gcloud/datastore/transaction.py +++ b/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