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 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