def commit(self, project_id, mode, mutations, transaction=None, options=None): """ Commits a transaction, optionally creating, deleting or modifying some entities. Example: >>> from google.cloud.gapic.datastore.v1 import datastore_client >>> from google.cloud.gapic.datastore.v1 import enums >>> client = datastore_client.DatastoreClient() >>> project_id = '' >>> mode = enums.CommitRequest.Mode.MODE_UNSPECIFIED >>> mutations = [] >>> response = client.commit(project_id, mode, mutations) Args: project_id (string): The ID of the project against which to make the request. mode (enum :class:`google.cloud.gapic.datastore.v1.enums.CommitRequest.Mode`): The type of commit to perform. Defaults to ``TRANSACTIONAL``. mutations (list[:class:`google.cloud.proto.datastore.v1.datastore_pb2.Mutation`]): The mutations to perform. When mode is ``TRANSACTIONAL``, mutations affecting a single entity are applied in order. The following sequences of mutations affecting a single entity are not permitted in a single ``Commit`` request: - ``insert`` followed by ``insert`` - ``update`` followed by ``insert`` - ``upsert`` followed by ``insert`` - ``delete`` followed by ``update`` When mode is ``NON_TRANSACTIONAL``, no two mutations may affect a single entity. transaction (bytes): The identifier of the transaction associated with the commit. A transaction identifier is returned by a call to ``Datastore.BeginTransaction``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.datastore.v1.datastore_pb2.CommitResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Sanity check: We have some fields which are mutually exclusive; # raise ValueError if more than one is sent. oneof.check_oneof( transaction=transaction, ) # Create the request object. request = datastore_pb2.CommitRequest( project_id=project_id, mode=mode, mutations=mutations, transaction=transaction) return self._commit(request, options)
def get_document(self, name, mask=None, transaction=None, read_time=None, options=None): """ Gets a single document. Example: >>> from google.cloud import firestore_v1beta1 >>> >>> client = firestore_v1beta1.FirestoreClient() >>> >>> name = client.any_path_path('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]') >>> >>> response = client.get_document(name) Args: name (str): The resource name of the Document to get. In the format: ``projects/{project_id}/databases/{database_id}/documents/{document_path}``. mask (Union[dict, ~google.cloud.firestore_v1beta1.types.DocumentMask]): The fields to return. If not set, returns all fields. If the document has a field that is not present in this mask, that field will not be returned in the response. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.DocumentMask` transaction (bytes): Reads the document in a transaction. read_time (Union[dict, ~google.cloud.firestore_v1beta1.types.Timestamp]): Reads the version of the document at the given time. This may not be older than 60 seconds. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.Timestamp` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.firestore_v1beta1.types.Document` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Sanity check: We have some fields which are mutually exclusive; # raise ValueError if more than one is sent. oneof.check_oneof( transaction=transaction, read_time=read_time, ) request = firestore_pb2.GetDocumentRequest(name=name, mask=mask, transaction=transaction, read_time=read_time) return self._get_document(request, options)
def run_query(self, project_id, partition_id, read_options, query=None, gql_query=None, options=None): """ Queries for entities. Example: >>> from google.cloud.gapic.datastore.v1 import datastore_client >>> from google.cloud.proto.datastore.v1 import datastore_pb2 >>> from google.cloud.proto.datastore.v1 import entity_pb2 >>> api = datastore_client.DatastoreClient() >>> project_id = '' >>> partition_id = entity_pb2.PartitionId() >>> read_options = datastore_pb2.ReadOptions() >>> response = api.run_query(project_id, partition_id, read_options) Args: project_id (string): The ID of the project against which to make the request. partition_id (:class:`google.cloud.proto.datastore.v1.entity_pb2.PartitionId`): Entities are partitioned into subsets, identified by a partition ID. Queries are scoped to a single partition. This partition ID is normalized with the standard default context partition ID. read_options (:class:`google.cloud.proto.datastore.v1.datastore_pb2.ReadOptions`): The options for this query. query (:class:`google.cloud.proto.datastore.v1.query_pb2.Query`): The query to run. gql_query (:class:`google.cloud.proto.datastore.v1.query_pb2.GqlQuery`): The GQL query to run. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.datastore.v1.datastore_pb2.RunQueryResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Sanity check: We have some fields which are mutually exclusive; # raise ValueError if more than one is sent. oneof.check_oneof( query=query, gql_query=gql_query, ) # Create the request object. request = datastore_pb2.RunQueryRequest(project_id=project_id, partition_id=partition_id, read_options=read_options, query=query, gql_query=gql_query) return self._run_query(request, options)
def seek(self, subscription, time=None, snapshot=None, options=None): """ Seeks an existing subscription to a point in time or to a given snapshot, whichever is provided in the request. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_client >>> client = subscriber_client.SubscriberClient() >>> subscription = client.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> response = client.seek(subscription) Args: subscription (string): The subscription to affect. time (:class:`google.protobuf.timestamp_pb2.Timestamp`): The time to seek to. Messages retained in the subscription that were published before this time are marked as acknowledged, and messages retained in the subscription that were published after this time are marked as unacknowledged. Note that this operation affects only those messages retained in the subscription (configured by the combination of ``message_retention_duration`` and ``retain_acked_messages``). For example, if ``time`` corresponds to a point before the message retention window (or to a point before the system's notion of the subscription creation time), only retained messages will be marked as unacknowledged, and already-expunged messages will not be restored. snapshot (string): The snapshot to seek to. The snapshot's topic must be the same as that of the provided subscription. Format is ``projects/{project}/snapshots/{snap}``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.pubsub.v1.pubsub_pb2.SeekResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Sanity check: We have some fields which are mutually exclusive; # raise ValueError if more than one is sent. oneof.check_oneof( time=time, snapshot=snapshot, ) # Create the request object. request = pubsub_pb2.SeekRequest(subscription=subscription, time=time, snapshot=snapshot) return self._seek(request, options)
def seek(self, subscription, time=None, snapshot=None, options=None): """ Seeks an existing subscription to a point in time or to a given snapshot, whichever is provided in the request. Example: >>> from google.cloud.gapic.pubsub.v1 import subscriber_client >>> client = subscriber_client.SubscriberClient() >>> subscription = client.subscription_path('[PROJECT]', '[SUBSCRIPTION]') >>> response = client.seek(subscription) Args: subscription (string): The subscription to affect. time (:class:`google.protobuf.timestamp_pb2.Timestamp`): The time to seek to. Messages retained in the subscription that were published before this time are marked as acknowledged, and messages retained in the subscription that were published after this time are marked as unacknowledged. Note that this operation affects only those messages retained in the subscription (configured by the combination of ``message_retention_duration`` and ``retain_acked_messages``). For example, if ``time`` corresponds to a point before the message retention window (or to a point before the system's notion of the subscription creation time), only retained messages will be marked as unacknowledged, and already-expunged messages will not be restored. snapshot (string): The snapshot to seek to. The snapshot's topic must be the same as that of the provided subscription. Format is ``projects/{project}/snapshots/{snap}``. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.cloud.proto.pubsub.v1.pubsub_pb2.SeekResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Sanity check: We have some fields which are mutually exclusive; # raise ValueError if more than one is sent. oneof.check_oneof( time=time, snapshot=snapshot, ) # Create the request object. request = pubsub_pb2.SeekRequest( subscription=subscription, time=time, snapshot=snapshot) return self._seek(request, options)
def test_check_failures(self): with self.assertRaises(ValueError): oneof.check_oneof(foo='bar', spam='eggs') with self.assertRaises(ValueError): oneof.check_oneof(foo='bar', baz='bacon', spam='eggs') with self.assertRaises(ValueError): oneof.check_oneof(foo='bar', spam=0, eggs=None)
def run_query(self, parent, structured_query=None, transaction=None, new_transaction=None, read_time=None, options=None): """ Runs a query. Example: >>> from google.cloud import firestore_v1beta1 >>> >>> client = firestore_v1beta1.FirestoreClient() >>> >>> parent = client.any_path_path('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]') >>> >>> for element in client.run_query(parent): ... # process element ... pass Args: parent (str): The parent resource name. In the format: ``projects/{project_id}/databases/{database_id}/documents`` or ``projects/{project_id}/databases/{database_id}/documents/{document_path}``. For example: ``projects/my-project/databases/my-database/documents`` or ``projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`` structured_query (Union[dict, ~google.cloud.firestore_v1beta1.types.StructuredQuery]): A structured query. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.StructuredQuery` transaction (bytes): Reads documents in a transaction. new_transaction (Union[dict, ~google.cloud.firestore_v1beta1.types.TransactionOptions]): Starts a new transaction and reads the documents. Defaults to a read-only transaction. The new transaction ID will be returned as the first response in the stream. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.TransactionOptions` read_time (Union[dict, ~google.cloud.firestore_v1beta1.types.Timestamp]): Reads documents as they were at the given time. This may not be older than 60 seconds. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.Timestamp` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: Iterable[~google.cloud.firestore_v1beta1.types.RunQueryResponse]. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Sanity check: We have some fields which are mutually exclusive; # raise ValueError if more than one is sent. oneof.check_oneof(structured_query=structured_query, ) # Sanity check: We have some fields which are mutually exclusive; # raise ValueError if more than one is sent. oneof.check_oneof( transaction=transaction, new_transaction=new_transaction, read_time=read_time, ) request = firestore_pb2.RunQueryRequest( parent=parent, structured_query=structured_query, transaction=transaction, new_transaction=new_transaction, read_time=read_time) return self._run_query(request, options)
def batch_get_documents(self, database, documents, mask=None, transaction=None, new_transaction=None, read_time=None, options=None): """ Gets multiple documents. Documents returned by this method are not guaranteed to be returned in the same order that they were requested. Example: >>> from google.cloud import firestore_v1beta1 >>> >>> client = firestore_v1beta1.FirestoreClient() >>> >>> database = client.database_root_path('[PROJECT]', '[DATABASE]') >>> documents = [] >>> >>> for element in client.batch_get_documents(database, documents): ... # process element ... pass Args: database (str): The database name. In the format: ``projects/{project_id}/databases/{database_id}``. documents (list[str]): The names of the documents to retrieve. In the format: ``projects/{project_id}/databases/{database_id}/documents/{document_path}``. The request will fail if any of the document is not a child resource of the given ``database``. Duplicate names will be elided. mask (Union[dict, ~google.cloud.firestore_v1beta1.types.DocumentMask]): The fields to return. If not set, returns all fields. If a document has a field that is not present in this mask, that field will not be returned in the response. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.DocumentMask` transaction (bytes): Reads documents in a transaction. new_transaction (Union[dict, ~google.cloud.firestore_v1beta1.types.TransactionOptions]): Starts a new transaction and reads the documents. Defaults to a read-only transaction. The new transaction ID will be returned as the first response in the stream. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.TransactionOptions` read_time (Union[dict, ~google.cloud.firestore_v1beta1.types.Timestamp]): Reads documents as they were at the given time. This may not be older than 60 seconds. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.Timestamp` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: Iterable[~google.cloud.firestore_v1beta1.types.BatchGetDocumentsResponse]. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Sanity check: We have some fields which are mutually exclusive; # raise ValueError if more than one is sent. oneof.check_oneof( transaction=transaction, new_transaction=new_transaction, read_time=read_time, ) request = firestore_pb2.BatchGetDocumentsRequest( database=database, documents=documents, mask=mask, transaction=transaction, new_transaction=new_transaction, read_time=read_time) return self._batch_get_documents(request, options)
def list_documents(self, parent, collection_id, page_size=None, order_by=None, mask=None, transaction=None, read_time=None, show_missing=None, options=None): """ Lists documents. Example: >>> from google.cloud import firestore_v1beta1 >>> from google.gax import CallOptions, INITIAL_PAGE >>> >>> client = firestore_v1beta1.FirestoreClient() >>> >>> parent = client.any_path_path('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]') >>> collection_id = '' >>> >>> >>> # Iterate over all results >>> for element in client.list_documents(parent, collection_id): ... # process element ... pass >>> >>> # Or iterate over results one page at a time >>> for page in client.list_documents(parent, collection_id, options=CallOptions(page_token=INITIAL_PAGE)): ... for element in page: ... # process element ... pass Args: parent (str): The parent resource name. In the format: ``projects/{project_id}/databases/{database_id}/documents`` or ``projects/{project_id}/databases/{database_id}/documents/{document_path}``. For example: ``projects/my-project/databases/my-database/documents`` or ``projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`` collection_id (str): The collection ID, relative to ``parent``, to list. For example: ``chatrooms`` or ``messages``. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. order_by (str): The order to sort results by. For example: ``priority desc, name``. mask (Union[dict, ~google.cloud.firestore_v1beta1.types.DocumentMask]): The fields to return. If not set, returns all fields. If a document has a field that is not present in this mask, that field will not be returned in the response. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.DocumentMask` transaction (bytes): Reads documents in a transaction. read_time (Union[dict, ~google.cloud.firestore_v1beta1.types.Timestamp]): Reads documents as they were at the given time. This may not be older than 60 seconds. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.firestore_v1beta1.types.Timestamp` show_missing (bool): If the list should show missing documents. A missing document is a document that does not exist but has sub-documents. These documents will be returned with a key but will not have fields, ``Document.create_time``, or ``Document.update_time`` set. Requests with ``show_missing`` may not specify ``where`` or ``order_by``. options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.gax.PageIterator` instance. By default, this is an iterable of :class:`~google.cloud.firestore_v1beta1.types.Document` instances. This object can also be configured to iterate over the pages of the response through the `options` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Sanity check: We have some fields which are mutually exclusive; # raise ValueError if more than one is sent. oneof.check_oneof( transaction=transaction, read_time=read_time, ) request = firestore_pb2.ListDocumentsRequest( parent=parent, collection_id=collection_id, page_size=page_size, order_by=order_by, mask=mask, transaction=transaction, read_time=read_time, show_missing=show_missing) return self._list_documents(request, options)
def commit(self, session, mutations, transaction_id=None, single_use_transaction=None, options=None): """ Commits a transaction. The request includes the mutations to be applied to rows in the database. ``Commit`` might return an ``ABORTED`` error. This can occur at any time; commonly, the cause is conflicts with concurrent transactions. However, it can also happen for a variety of other reasons. If ``Commit`` returns ``ABORTED``, the caller should re-attempt the transaction from the beginning, re-using the same session. Example: >>> from google.cloud import spanner_v1 >>> >>> client = spanner_v1.SpannerClient() >>> >>> session = client.session_path('[PROJECT]', '[INSTANCE]', '[DATABASE]', '[SESSION]') >>> mutations = [] >>> >>> response = client.commit(session, mutations) Args: session (str): Required. The session in which the transaction to be committed is running. mutations (list[Union[dict, ~google.cloud.spanner_v1.types.Mutation]]): The mutations to be executed when this transaction commits. All mutations are applied atomically, in the order they appear in this list. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.Mutation` transaction_id (bytes): Commit a previously-started transaction. single_use_transaction (Union[dict, ~google.cloud.spanner_v1.types.TransactionOptions]): Execute mutations in a temporary transaction. Note that unlike commit of a previously-started transaction, commit with a temporary transaction is non-idempotent. That is, if the ``CommitRequest`` is sent to Cloud Spanner more than once (for instance, due to retries in the application, or in the transport library), it is possible that the mutations are executed more than once. If this is undesirable, use ``BeginTransaction`` and ``Commit`` instead. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.TransactionOptions` options (~google.gax.CallOptions): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`~google.cloud.spanner_v1.types.CommitResponse` instance. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Sanity check: We have some fields which are mutually exclusive; # raise ValueError if more than one is sent. oneof.check_oneof( transaction_id=transaction_id, single_use_transaction=single_use_transaction, ) request = spanner_pb2.CommitRequest( session=session, mutations=mutations, transaction_id=transaction_id, single_use_transaction=single_use_transaction) return self._commit(request, options)
def test_check_ok(self): self.assertIsNone(oneof.check_oneof()) self.assertIsNone(oneof.check_oneof(foo='bar')) self.assertIsNone(oneof.check_oneof(foo='bar', baz=None)) self.assertIsNone(oneof.check_oneof(foo=None, baz='bacon')) self.assertIsNone(oneof.check_oneof(foo='bar', spam=None, eggs=None))
def list_groups(self, name, children_of_group=None, ancestors_of_group=None, descendants_of_group=None, page_size=0, options=None): """ Lists the existing groups. Example: >>> from google.cloud.gapic.monitoring.v3 import group_service_client >>> from google.gax import CallOptions, INITIAL_PAGE >>> api = group_service_client.GroupServiceClient() >>> name = api.project_path('[PROJECT]') >>> >>> # Iterate over all results >>> for element in api.list_groups(name): >>> # process element >>> pass >>> >>> # Or iterate over results one page at a time >>> for page in api.list_groups(name, options=CallOptions(page_token=INITIAL_PAGE)): >>> for element in page: >>> # process element >>> pass Args: name (string): The project whose groups are to be listed. The format is ``\"projects/{project_id_or_number}\"``. children_of_group (string): A group name: ``\"projects/{project_id_or_number}/groups/{group_id}\"``. Returns groups whose ``parentName`` field contains the group name. If no groups have this parent, the results are empty. ancestors_of_group (string): A group name: ``\"projects/{project_id_or_number}/groups/{group_id}\"``. Returns groups that are ancestors of the specified group. The groups are returned in order, starting with the immediate parent and ending with the most distant ancestor. If the specified group has no immediate parent, the results are empty. descendants_of_group (string): A group name: ``\"projects/{project_id_or_number}/groups/{group_id}\"``. Returns the descendants of the specified group. This is a superset of the results returned by the ``childrenOfGroup`` filter, and includes children-of-children, and so forth. page_size (int): The maximum number of resources contained in the underlying API response. If page streaming is performed per- resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page. options (:class:`google.gax.CallOptions`): Overrides the default settings for this call, e.g, timeout, retries etc. Returns: A :class:`google.gax.PageIterator` instance. By default, this is an iterable of :class:`google.cloud.proto.monitoring.v3.group_pb2.Group` instances. This object can also be configured to iterate over the pages of the response through the `CallOptions` parameter. Raises: :exc:`google.gax.errors.GaxError` if the RPC is aborted. :exc:`ValueError` if the parameters are invalid. """ # Sanity check: We have some fields which are mutually exclusive; # raise ValueError if more than one is sent. oneof.check_oneof( children_of_group=children_of_group, ancestors_of_group=ancestors_of_group, descendants_of_group=descendants_of_group, ) # Create the request object. request = group_service_pb2.ListGroupsRequest( name=name, children_of_group=children_of_group, ancestors_of_group=ancestors_of_group, descendants_of_group=descendants_of_group, page_size=page_size) return self._list_groups(request, options)