diff --git a/gcloud/datastore/key.py b/gcloud/datastore/key.py index 7f06daa0a416..7257ee2879a2 100644 --- a/gcloud/datastore/key.py +++ b/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