Merge pull request #184 from tseaver/add_key_docstrings

Add docstrings for API method of g.datastore.key.Key.

gcloud/datastore/key.py

@@ -11,6 +11,18 @@ class Key(object):
   """
 
   def __init__(self, dataset=None, namespace=None, path=None):
+    """Constructor / initializer for a key.
+
+    :type dataset: :class:`gcloud.datastore.dataset.Dataset`
+    :param dataset: A dataset instance for the key.
+
+    :type namespace: :class:`str`
+    :param namespace: A namespace identifier for the key.
+
+    :type path: sequence of dicts
+    :param path: Each dict must have keys 'kind' (a string) and optionally
+    'name' (a string) or 'id' (an integer).
+    """
     self._dataset = dataset
     self._namespace = namespace
     self._path = path or [{'kind': ''}]
@@ -28,6 +40,20 @@ def _clone(self):
 
   @classmethod
   def from_protobuf(cls, pb, dataset=None):
+    """Factory method for creating a key based on a protobuf.
+
+    The protobuf should be one returned from the Cloud Datastore Protobuf API.
+
+    :type pb: :class:`gcloud.datastore.datastore_v1_pb2.Key`
+    :param pb: The Protobuf representing the key.
+
+    :type dataset: :class:`gcloud.datastore.dataset.Dataset`
+    :param dataset: A dataset instance.  If not passed, defaults to an
+    instance whose ID is derived from pb.
+
+    :rtype: :class:`gcloud.datastore.key.Key`
+    :returns: a new `Key` instance
+    """
     path = []
     for element in pb.path_element:
       element_dict = {'kind': element.kind}
@@ -46,6 +72,11 @@ def from_protobuf(cls, pb, dataset=None):
     return cls(path=path, dataset=dataset)
 
   def to_protobuf(self):
+    """Return a protobuf corresponding to the key.
+
+    :rtype: :class:`gcloud.datastore.datastore_v1_pb2.Key`
+    :returns: The Protobuf representing the key.
+    """
     key = datastore_pb.Key()
 
     # Technically a dataset is required to do anything with the key,
@@ -77,6 +108,20 @@ def to_protobuf(self):
 
   @classmethod
   def from_path(cls, *args, **kwargs):
+    """Factory method for creating a key based on a path.
+
+    :type args: :class:`tuple
+    :param args: sequence of even length, where the first of each
+    pair is a string representing the 'kind' of the path element, and the
+    second of the pair is either a string (for the path element's name)
+    or an integer (for its id).
+
+    :type kwargs: :class:`dict`
+    :param kwargs: Other named parameters which can be passed to `__init__()`.
+
+    :rtype: :class:`gcloud.datastore.key.Key`
+    :returns: a new `Key` instance
+    """
     path = []
     items = iter(args)
 
@@ -92,9 +137,25 @@ def from_path(cls, *args, **kwargs):
     return cls(**kwargs)
 
   def is_partial(self):
+    """Boolean test: is the key fully mapped onto a backend entity?
+
+    :rtype: :class:`bool`
+    :returns: True if the last element of the key's path does not have an 'id'
+    or a 'name'.
+    """
     return (self.id_or_name() is None)
 
   def dataset(self, dataset=None):
+    """Setter / getter.
+
+    :type dataset: :class:`gcloud.datastore.dataset.Dataset`
+    :param dataset: A dataset instance for the key.
+
+    :rtype: :class:`Key` (for setter); or
+            :class:`gcloud.datastore.dataset.Dataset` (for getter)
+    :returns: a new key, cloned from self., with the given dataset (setter);
+             or self's dataset (getter).
+    """
     if dataset:
       clone = self._clone()
       clone._dataset = dataset
@@ -103,6 +164,15 @@ def dataset(self, dataset=None):
       return self._dataset
 
   def namespace(self, namespace=None):
+    """Setter / getter.
+
+    :type namespace: :class:`str`
+    :param namespace: A namespace identifier for the key.
+
+    :rtype: :class:`Key` (for setter); or :class:`str` (for getter)
+    :returns: a new key, cloned from self., with the given namespace (setter);
+             or self's namespace (getter).
+    """
     if namespace:
       clone = self._clone()
       clone._namespace = namespace
@@ -111,6 +181,16 @@ def namespace(self, namespace=None):
       return self._namespace
 
   def path(self, path=None):
+    """Setter / getter.
+
+    :type path: sequence of dicts
+    :param path: Each dict must have keys 'kind' (a string) and optionally
+    'name' (a string) or 'id' (an integer).
+
+    :rtype: :class:`Key` (for setter); or :class:`str` (for getter)
+    :returns: a new key, cloned from self., with the given path (setter);
+             or self's path (getter).
+    """
     if path:
       clone = self._clone()
       clone._path = path
@@ -119,6 +199,15 @@ def path(self, path=None):
       return self._path
 
   def kind(self, kind=None):
+    """Setter / getter.  Based on the last element of path.
+
+    :type kind: :class:`str`
+    :param kind: The new kind for the key.
+
+    :rtype: :class:`Key` (for setter); or :class:`str` (for getter)
+    :returns: a new key, cloned from self., with the given kind (setter);
+             or self's kind (getter).
+    """
     if kind:
       clone = self._clone()
       clone._path[-1]['kind'] = kind
@@ -127,6 +216,15 @@ def kind(self, kind=None):
       return self._path[-1]['kind']
 
   def id(self, id=None):
+    """Setter / getter.  Based on the last element of path.
+
+    :type kind: :class:`str`
+    :param kind: The new kind for the key.
+
+    :rtype: :class:`Key` (for setter); or :class:`int` (for getter)
+    :returns: a new key, cloned from self., with the given id (setter);
+             or self's id (getter).
+    """
     if id:
       clone = self._clone()
       clone._path[-1]['id'] = id
@@ -135,6 +233,15 @@ def id(self, id=None):
       return self._path[-1].get('id')
 
   def name(self, name=None):
+    """Setter / getter.  Based on the last element of path.
+
+    :type kind: :class:`str`
+    :param kind: The new name for the key.
+
+    :rtype: :class:`Key` (for setter); or :class:`str` (for getter)
+    :returns: a new key, cloned from self., with the given name (setter);
+             or self's name (getter).
+    """
     if name:
       clone = self._clone()
       clone._path[-1]['name'] = name
@@ -143,6 +250,12 @@ def name(self, name=None):
       return self._path[-1].get('name')
 
   def id_or_name(self):
+    """Getter.  Based on the last element of path.
+
+    :rtype: :class:`int` (if 'id' is set); or :class:`str` (the 'name')
+    :returns: True if the last element of the key's path has either an 'id'
+    or a 'name'.
+    """
     return self.id() or self.name()
 
   def parent(self):#pragma NO COVER