def lookup(self, dataset_id, key_pbs,
eventual=False, transaction_id=None):
"""Lookup keys from a dataset in the Cloud Datastore.
Maps the ``DatastoreService.Lookup`` protobuf RPC.
This method deals only with protobufs
(:class:`gcloud.datastore._datastore_v1_pb2.Key` and
:class:`gcloud.datastore._datastore_v1_pb2.Entity`) and is used
under the hood in :func:`gcloud.datastore.get`:
>>> from gcloud import datastore
>>> datastore.set_defaults()
>>> key = datastore.Key('MyKind', 1234, dataset_id='dataset-id')
>>> datastore.get([key])
[<Entity object>]
Using the ``connection`` class directly:
>>> connection.lookup('dataset-id', [key.to_protobuf()])
[<Entity protobuf>]
:type dataset_id: string
:param dataset_id: The ID of the dataset to look up the keys.
:type key_pbs: list of :class:`gcloud.datastore._datastore_v1_pb2.Key`
:param key_pbs: The keys to retrieve from the datastore.
:type eventual: boolean
:param eventual: If False (the default), request ``STRONG`` read
consistency. If True, request ``EVENTUAL`` read
consistency.
:type transaction_id: string
:param transaction_id: If passed, make the request in the scope of
the given transaction. Incompatible with
``eventual==True``.
:rtype: tuple
:returns: A triple of (``results``, ``missing``, ``deferred``) where
both ``results`` and ``missing`` are lists of
:class:`gcloud.datastore._datastore_v1_pb2.Entity` and
``deferred`` is a list of
:class:`gcloud.datastore._datastore_v1_pb2.Key`.
"""
lookup_request = datastore_pb.LookupRequest()
_set_read_options(lookup_request, eventual, transaction_id)
helpers._add_keys_to_request(lookup_request.key, key_pbs)
lookup_response = self._rpc(dataset_id, 'lookup', lookup_request,
datastore_pb.LookupResponse)
results = [result.entity for result in lookup_response.found]
missing = [result.entity for result in lookup_response.missing]
return results, missing, list(lookup_response.deferred)
def delete(self, key):
"""Remember a key to be deleted durring ``commit``.
:type key: :class:`gcloud.datastore.key.Key`
:param key: the key to be deleted.
:raises: ValueError if key is not complete.
"""
if key.is_partial:
raise ValueError("Key must be complete")
key_pb = key.to_protobuf()
helpers._add_keys_to_request(self.mutation.delete, [key_pb])
def delete(self, key):
"""Remember a key to be deleted durring ``commit``.
:type key: :class:`gcloud.datastore.key.Key`
:param key: the key to be deleted.
:raises: ValueError if key is not complete, or if the key's
``dataset_id`` does not match ours.
"""
if key.is_partial:
raise ValueError("Key must be complete")
if not _dataset_ids_equal(self._dataset_id, key.dataset_id):
raise ValueError("Key must be from same dataset as batch")
key_pb = key.to_protobuf()
helpers._add_keys_to_request(self.mutation.delete, [key_pb])
def delete(self, key):
"""Remember a key to be deleted durring ``commit``.
:type key: :class:`gcloud.datastore.key.Key`
:param key: the key to be deleted.
:raises: ValueError if key is not complete, or if the key's
``dataset_id`` does not match ours.
"""
if key.is_partial:
raise ValueError("Key must be complete")
if not _dataset_ids_equal(self._dataset_id, key.dataset_id):
raise ValueError("Key must be from same dataset as batch")
key_pb = key.to_protobuf()
helpers._add_keys_to_request(self.mutation.delete, [key_pb])
def allocate_ids(self, dataset_id, key_pbs):
"""Obtain backend-generated IDs for a set of keys.
Maps the ``DatastoreService.AllocateIds`` protobuf RPC.
:type dataset_id: string
:param dataset_id: The ID of the dataset to which the transaction
belongs.
:type key_pbs: list of :class:`gcloud.datastore._datastore_v1_pb2.Key`
:param key_pbs: The keys for which the backend should allocate IDs.
:rtype: list of :class:`gcloud.datastore._datastore_v1_pb2.Key`
:returns: An equal number of keys, with IDs filled in by the backend.
"""
request = datastore_pb.AllocateIdsRequest()
helpers._add_keys_to_request(request.key, key_pbs)
# Nothing to do with this response, so just execute the method.
response = self._rpc(dataset_id, 'allocateIds', request,
datastore_pb.AllocateIdsResponse)
return list(response.key)
def lookup(self,
dataset_id,
key_pbs,
missing=None,
deferred=None,
eventual=False,
transaction_id=None):
"""Lookup keys from a dataset in the Cloud Datastore.
Maps the ``DatastoreService.Lookup`` protobuf RPC.
This method deals only with protobufs
(:class:`gcloud.datastore._datastore_v1_pb2.Key` and
:class:`gcloud.datastore._datastore_v1_pb2.Entity`) and is used
under the hood in :func:`gcloud.datastore.get`:
>>> from gcloud import datastore
>>> datastore.set_defaults()
>>> key = datastore.Key('MyKind', 1234, dataset_id='dataset-id')
>>> datastore.get(key)
<Entity object>
Using the ``connection`` class directly:
>>> connection.lookup('dataset-id', key.to_protobuf())
<Entity protobuf>
:type dataset_id: string
:param dataset_id: The ID of the dataset to look up 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 retrieve from the datastore.
:type missing: an empty list or None.
:param missing: If a list is passed, the key-only entity protobufs
returned by the backend as "missing" will be copied
into it. Use only as a keyword param.
:type deferred: an empty list or None.
:param deferred: If a list is passed, the key protobufs returned
by the backend as "deferred" will be copied into it.
Use only as a keyword param.
:type eventual: boolean
:param eventual: If False (the default), request ``STRONG`` read
consistency. If True, request ``EVENTUAL`` read
consistency.
:type transaction_id: string
:param transaction_id: If passed, make the request in the scope of
the given transaction. Incompatible with
``eventual==True``.
:rtype: list of :class:`gcloud.datastore._datastore_v1_pb2.Entity`
(or a single Entity)
:returns: The entities corresponding to the keys provided.
If a single key was provided and no results matched,
this will return None.
If multiple keys were provided and no results matched,
this will return an empty list.
:raises: ValueError if ``eventual`` is True
"""
if missing is not None and missing != []:
raise ValueError('missing must be None or an empty list')
if deferred is not None and deferred != []:
raise ValueError('deferred must be None or an empty list')
lookup_request = datastore_pb.LookupRequest()
_set_read_options(lookup_request, eventual, transaction_id)
single_key = isinstance(key_pbs, datastore_pb.Key)
if single_key:
key_pbs = [key_pbs]
helpers._add_keys_to_request(lookup_request.key, key_pbs)
results, missing_found, deferred_found = self._lookup(
lookup_request, dataset_id, deferred is not None)
if missing is not None:
missing.extend(missing_found)
if deferred is not None:
deferred.extend(deferred_found)
if single_key:
if results:
return results[0]
else:
return None
return results
