From 24418259483afab8bb9c1996d7bd5d28ab085773 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Wed, 22 May 2019 13:44:13 -0400 Subject: [PATCH] Revert "Replace relative class refs with fully-qualifed names. (#8039)" (#8095) This reverts commit 76e877dd74c44dcc593dc6a5e28dc7463e6206c1. --- google/cloud/firestore_v1/_helpers.py | 18 ++-- google/cloud/firestore_v1/batch.py | 24 +++--- google/cloud/firestore_v1/client.py | 42 ++++----- google/cloud/firestore_v1/collection.py | 62 ++++++------- google/cloud/firestore_v1/document.py | 38 ++++---- google/cloud/firestore_v1/field_path.py | 2 +- .../firestore_v1/gapic/firestore_client.py | 4 +- .../transports/firestore_grpc_transport.py | 2 +- google/cloud/firestore_v1/query.py | 86 +++++++++---------- google/cloud/firestore_v1/transaction.py | 20 ++--- google/cloud/firestore_v1beta1/_helpers.py | 18 ++-- google/cloud/firestore_v1beta1/batch.py | 24 +++--- google/cloud/firestore_v1beta1/client.py | 42 ++++----- google/cloud/firestore_v1beta1/collection.py | 62 ++++++------- google/cloud/firestore_v1beta1/document.py | 38 ++++---- google/cloud/firestore_v1beta1/field_path.py | 2 +- .../gapic/firestore_client.py | 4 +- .../transports/firestore_grpc_transport.py | 2 +- google/cloud/firestore_v1beta1/query.py | 82 +++++++++--------- google/cloud/firestore_v1beta1/transaction.py | 20 ++--- 20 files changed, 296 insertions(+), 296 deletions(-) diff --git a/google/cloud/firestore_v1/_helpers.py b/google/cloud/firestore_v1/_helpers.py index 5d21d6574..4d3e27cbb 100644 --- a/google/cloud/firestore_v1/_helpers.py +++ b/google/cloud/firestore_v1/_helpers.py @@ -220,11 +220,11 @@ def reference_value_to_document(reference_value, client): Args: reference_value (str): A document reference value. - client (~google.cloud.firestore_v1.client.Client): A client that has + client (~.firestore_v1.client.Client): A client that has a document factory. Returns: - ~google.cloud.firestore_v1.document.DocumentReference: The document + ~.firestore_v1.document.DocumentReference: The document corresponding to ``reference_value``. Raises: @@ -255,7 +255,7 @@ def decode_value(value, client): Args: value (google.cloud.firestore_v1.types.Value): A Firestore protobuf to be decoded / parsed / converted. - client (~google.cloud.firestore_v1.client.Client): A client that has + client (~.firestore_v1.client.Client): A client that has a document factory. Returns: @@ -301,7 +301,7 @@ def decode_dict(value_fields, client): Args: value_fields (google.protobuf.pyext._message.MessageMapContainer): A protobuf map of Firestore ``Value``-s. - client (~google.cloud.firestore_v1.client.Client): A client that has + client (~.firestore_v1.client.Client): A client that has a document factory. Returns: @@ -851,7 +851,7 @@ def pbs_for_update(document_path, field_updates, option): document_path (str): A fully-qualified document path. field_updates (dict): Field names or paths to update and values to update with. - option (optional[~google.cloud.firestore_v1.client.WriteOption]): A + option (optional[~.firestore_v1.client.WriteOption]): A write option to make assertions / preconditions on the server state of the document before applying changes. @@ -890,7 +890,7 @@ def pb_for_delete(document_path, option): Args: document_path (str): A fully-qualified document path. - option (optional[~google.cloud.firestore_v1.client.WriteOption]): A + option (optional[~.firestore_v1.client.WriteOption]): A write option to make assertions / preconditions on the server state of the document before applying changes. @@ -916,7 +916,7 @@ def get_transaction_id(transaction, read_operation=True): """Get the transaction ID from a ``Transaction`` object. Args: - transaction (Optional[~google.cloud.firestore_v1.transaction.\ + transaction (Optional[~.firestore_v1.transaction.\ Transaction]): An existing transaction that this query will run in. read_operation (Optional[bool]): Indicates if the transaction ID @@ -979,7 +979,7 @@ class LastUpdateOption(WriteOption): """Option used to assert a "last update" condition on a write operation. This will typically be created by - :meth:`~google.cloud.firestore_v1.client.Client.write_option`. + :meth:`~.firestore_v1.client.Client.write_option`. Args: last_update_time (google.protobuf.timestamp_pb2.Timestamp): A @@ -1019,7 +1019,7 @@ class ExistsOption(WriteOption): """Option used to assert existence on a write operation. This will typically be created by - :meth:`~google.cloud.firestore_v1.client.Client.write_option`. + :meth:`~.firestore_v1.client.Client.write_option`. Args: exists (bool): Indicates if the document being modified diff --git a/google/cloud/firestore_v1/batch.py b/google/cloud/firestore_v1/batch.py index 7b0c3f11b..1bcbe22aa 100644 --- a/google/cloud/firestore_v1/batch.py +++ b/google/cloud/firestore_v1/batch.py @@ -22,11 +22,11 @@ class WriteBatch(object): """Accumulate write operations to be sent in a batch. This has the same set of methods for write operations that - :class:`~google.cloud.firestore_v1.document.DocumentReference` does, - e.g. :meth:`~google.cloud.firestore_v1.document.DocumentReference.create`. + :class:`~.firestore_v1.document.DocumentReference` does, + e.g. :meth:`~.firestore_v1.document.DocumentReference.create`. Args: - client (~google.cloud.firestore_v1.client.Client): The client that + client (~.firestore_v1.client.Client): The client that created this batch. """ @@ -54,7 +54,7 @@ def create(self, reference, document_data): batch will fail when :meth:`commit`-ed. Args: - reference (~google.cloud.firestore_v1.document.DocumentReference): A + reference (~.firestore_v1.document.DocumentReference): A document reference to be created in this batch. document_data (dict): Property names and values to use for creating a document. @@ -66,12 +66,12 @@ def set(self, reference, document_data, merge=False): """Add a "change" to replace a document. See - :meth:`~google.cloud.firestore_v1.document.DocumentReference.set` for + :meth:`~.firestore_v1.document.DocumentReference.set` for more information on how ``option`` determines how the change is applied. Args: - reference (~google.cloud.firestore_v1.document.DocumentReference): + reference (~.firestore_v1.document.DocumentReference): A document reference that will have values set in this batch. document_data (dict): Property names and values to use for replacing a document. @@ -94,15 +94,15 @@ def update(self, reference, field_updates, option=None): """Add a "change" to update a document. See - :meth:`~google.cloud.firestore_v1.document.DocumentReference.update` for + :meth:`~.firestore_v1.document.DocumentReference.update` for more information on ``field_updates`` and ``option``. Args: - reference (~google.cloud.firestore_v1.document.DocumentReference): A + reference (~.firestore_v1.document.DocumentReference): A document reference that will be deleted in this batch. field_updates (dict): Field names or paths to update and values to update with. - option (Optional[~google.cloud.firestore_v1.client.WriteOption]): A + option (Optional[~.firestore_v1.client.WriteOption]): A write option to make assertions / preconditions on the server state of the document before applying changes. """ @@ -117,14 +117,14 @@ def delete(self, reference, option=None): """Add a "change" to delete a document. See - :meth:`~google.cloud.firestore_v1.document.DocumentReference.delete` for + :meth:`~.firestore_v1.document.DocumentReference.delete` for more information on how ``option`` determines how the change is applied. Args: - reference (~google.cloud.firestore_v1.document.DocumentReference): A + reference (~.firestore_v1.document.DocumentReference): A document reference that will be deleted in this batch. - option (Optional[~google.cloud.firestore_v1.client.WriteOption]): A + option (Optional[~.firestore_v1.client.WriteOption]): A write option to make assertions / preconditions on the server state of the document before applying changes. """ diff --git a/google/cloud/firestore_v1/client.py b/google/cloud/firestore_v1/client.py index 036f56898..a1c631eae 100644 --- a/google/cloud/firestore_v1/client.py +++ b/google/cloud/firestore_v1/client.py @@ -18,10 +18,10 @@ In the hierarchy of API concepts -* a :class:`~google.cloud.firestore_v1.client.Client` owns a - :class:`~google.cloud.firestore_v1.collection.CollectionReference` -* a :class:`~google.cloud.firestore_v1.client.Client` owns a - :class:`~google.cloud.firestore_v1.document.DocumentReference` +* a :class:`~.firestore_v1.client.Client` owns a + :class:`~.firestore_v1.collection.CollectionReference` +* a :class:`~.firestore_v1.client.Client` owns a + :class:`~.firestore_v1.document.DocumentReference` """ from google.api_core.gapic_v1 import client_info from google.cloud.client import ClientWithProject @@ -40,7 +40,7 @@ DEFAULT_DATABASE = "(default)" -"""str: The default database used in a :class:`~google.cloud.firestore.client.Client`.""" +"""str: The default database used in a :class:`~.firestore.client.Client`.""" _BAD_OPTION_ERR = ( "Exactly one of ``last_update_time`` or ``exists`` " "must be provided." ) @@ -108,7 +108,7 @@ def _firestore_api(self): """Lazy-loading getter GAPIC Firestore API. Returns: - ~google.cloud.gapic.firestore.v1.firestore_client.FirestoreClient: The + ~.gapic.firestore.v1.firestore_client.FirestoreClient: The GAPIC client with the credentials of the current client. """ if self._firestore_api_internal is None: @@ -185,7 +185,7 @@ def collection(self, *collection_path): * A tuple of collection path segments Returns: - ~google.cloud.firestore_v1.collection.CollectionReference: A reference + ~.firestore_v1.collection.CollectionReference: A reference to a collection in the Firestore database. """ if len(collection_path) == 1: @@ -248,7 +248,7 @@ def document(self, *document_path): * A tuple of document path segments Returns: - ~google.cloud.firestore_v1.document.DocumentReference: A reference + ~.firestore_v1.document.DocumentReference: A reference to a document in a collection. """ if len(document_path) == 1: @@ -298,9 +298,9 @@ def field_path(*field_names): def write_option(**kwargs): """Create a write option for write operations. - Write operations include :meth:`~google.cloud.DocumentReference.set`, - :meth:`~google.cloud.DocumentReference.update` and - :meth:`~google.cloud.DocumentReference.delete`. + Write operations include :meth:`~.DocumentReference.set`, + :meth:`~.DocumentReference.update` and + :meth:`~.DocumentReference.delete`. One of the following keyword arguments must be provided: @@ -352,7 +352,7 @@ def get_all(self, references, field_paths=None, transaction=None): If multiple ``references`` refer to the same document, the server will only return one result. - See :meth:`~google.cloud.firestore_v1.client.Client.field_path` for + See :meth:`~.firestore_v1.client.Client.field_path` for more information on **field paths**. If a ``transaction`` is used and it already has write operations @@ -366,7 +366,7 @@ def get_all(self, references, field_paths=None, transaction=None): paths (``.``-delimited list of field names) to use as a projection of document fields in the returned results. If no value is provided, all fields will be returned. - transaction (Optional[~google.cloud.firestore_v1.transaction.\ + transaction (Optional[~.firestore_v1.transaction.\ Transaction]): An existing transaction that these ``references`` will be retrieved in. @@ -391,7 +391,7 @@ def collections(self): """List top-level collections of the client's database. Returns: - Sequence[~google.cloud.firestore_v1.collection.CollectionReference]: + Sequence[~.firestore_v1.collection.CollectionReference]: iterator of subcollections of the current document. """ iterator = self._firestore_api.list_collection_ids( @@ -405,7 +405,7 @@ def batch(self): """Get a batch instance from this client. Returns: - ~google.cloud.firestore_v1.batch.WriteBatch: A "write" batch to be + ~.firestore_v1.batch.WriteBatch: A "write" batch to be used for accumulating document changes and sending the changes all at once. """ @@ -414,17 +414,17 @@ def batch(self): def transaction(self, **kwargs): """Get a transaction that uses this client. - See :class:`~google.cloud.firestore_v1.transaction.Transaction` for + See :class:`~.firestore_v1.transaction.Transaction` for more information on transactions and the constructor arguments. Args: kwargs (Dict[str, Any]): The keyword arguments (other than ``client``) to pass along to the - :class:`~google.cloud.firestore_v1.transaction.Transaction` + :class:`~.firestore_v1.transaction.Transaction` constructor. Returns: - ~google.cloud.firestore_v1.transaction.Transaction: A transaction + ~.firestore_v1.transaction.Transaction: A transaction attached to this client. """ return Transaction(self, **kwargs) @@ -433,7 +433,7 @@ def transaction(self, **kwargs): def _reference_info(references): """Get information about document references. - Helper for :meth:`~google.cloud.firestore_v1.client.Client.get_all`. + Helper for :meth:`~.firestore_v1.client.Client.get_all`. Args: references (List[.DocumentReference, ...]): Iterable of document @@ -461,7 +461,7 @@ def _get_reference(document_path, reference_map): """Get a document reference from a dictionary. This just wraps a simple dictionary look-up with a helpful error that is - specific to :meth:`~google.cloud.firestore.client.Client.get_all`, the + specific to :meth:`~.firestore.client.Client.get_all`, the **public** caller of this function. Args: @@ -493,7 +493,7 @@ def _parse_batch_get(get_doc_response, reference_map, client): reference_map (Dict[str, .DocumentReference]): A mapping (produced by :func:`_reference_info`) of fully-qualified document paths to document references. - client (~google.cloud.firestore_v1.client.Client): A client that has + client (~.firestore_v1.client.Client): A client that has a document factory. Returns: diff --git a/google/cloud/firestore_v1/collection.py b/google/cloud/firestore_v1/collection.py index d1bda1729..e7b999448 100644 --- a/google/cloud/firestore_v1/collection.py +++ b/google/cloud/firestore_v1/collection.py @@ -40,7 +40,7 @@ class CollectionReference(object): that contain a sub-collection. kwargs (dict): The keyword arguments for the constructor. The only supported keyword is ``client`` and it must be a - :class:`~google.cloud.firestore_v1.client.Client` if provided. It + :class:`~.firestore_v1.client.Client` if provided. It represents the client that created this collection reference. Raises: @@ -81,7 +81,7 @@ def parent(self): """Document that owns the current collection. Returns: - Optional[~google.cloud.firestore_v1.document.DocumentReference]: The + Optional[~.firestore_v1.document.DocumentReference]: The parent document, if the current collection is not a top-level collection. """ @@ -101,7 +101,7 @@ def document(self, document_id=None): uppercase and lowercase and letters. Returns: - ~google.cloud.firestore_v1.document.DocumentReference: The child + ~.firestore_v1.document.DocumentReference: The child document. """ if document_id is None: @@ -146,7 +146,7 @@ def add(self, document_data, document_id=None): Returns: Tuple[google.protobuf.timestamp_pb2.Timestamp, \ - ~google.cloud.firestore_v1.document.DocumentReference]: Pair of + ~.firestore_v1.document.DocumentReference]: Pair of * The ``update_time`` when the document was created (or overwritten). @@ -188,7 +188,7 @@ def list_documents(self, page_size=None): are ignored. Defaults to a sensible value set by the API. Returns: - Sequence[~google.cloud.firestore_v1.collection.DocumentReference]: + Sequence[~.firestore_v1.collection.DocumentReference]: iterator of subdocuments of the current collection. If the collection does not exist at the time of `snapshot`, the iterator will be empty @@ -210,7 +210,7 @@ def select(self, field_paths): """Create a "select" query with this collection as parent. See - :meth:`~google.cloud.firestore_v1.query.Query.select` for + :meth:`~.firestore_v1.query.Query.select` for more information on this method. Args: @@ -219,7 +219,7 @@ def select(self, field_paths): of document fields in the query results. Returns: - ~google.cloud.firestore_v1.query.Query: A "projected" query. + ~.firestore_v1.query.Query: A "projected" query. """ query = query_mod.Query(self) return query.select(field_paths) @@ -228,7 +228,7 @@ def where(self, field_path, op_string, value): """Create a "where" query with this collection as parent. See - :meth:`~google.cloud.firestore_v1.query.Query.where` for + :meth:`~.firestore_v1.query.Query.where` for more information on this method. Args: @@ -242,7 +242,7 @@ def where(self, field_path, op_string, value): allowed operation. Returns: - ~google.cloud.firestore_v1.query.Query: A filtered query. + ~.firestore_v1.query.Query: A filtered query. """ query = query_mod.Query(self) return query.where(field_path, op_string, value) @@ -251,7 +251,7 @@ def order_by(self, field_path, **kwargs): """Create an "order by" query with this collection as parent. See - :meth:`~google.cloud.firestore_v1.query.Query.order_by` for + :meth:`~.firestore_v1.query.Query.order_by` for more information on this method. Args: @@ -259,11 +259,11 @@ def order_by(self, field_path, **kwargs): field names) on which to order the query results. kwargs (Dict[str, Any]): The keyword arguments to pass along to the query. The only supported keyword is ``direction``, - see :meth:`~google.cloud.firestore_v1.query.Query.order_by` for + see :meth:`~.firestore_v1.query.Query.order_by` for more information. Returns: - ~google.cloud.firestore_v1.query.Query: An "order by" query. + ~.firestore_v1.query.Query: An "order by" query. """ query = query_mod.Query(self) return query.order_by(field_path, **kwargs) @@ -272,7 +272,7 @@ def limit(self, count): """Create a limited query with this collection as parent. See - :meth:`~google.cloud.firestore_v1.query.Query.limit` for + :meth:`~.firestore_v1.query.Query.limit` for more information on this method. Args: @@ -280,7 +280,7 @@ def limit(self, count): the query. Returns: - ~google.cloud.firestore_v1.query.Query: A limited query. + ~.firestore_v1.query.Query: A limited query. """ query = query_mod.Query(self) return query.limit(count) @@ -289,7 +289,7 @@ def offset(self, num_to_skip): """Skip to an offset in a query with this collection as parent. See - :meth:`~google.cloud.firestore_v1.query.Query.offset` for + :meth:`~.firestore_v1.query.Query.offset` for more information on this method. Args: @@ -297,7 +297,7 @@ def offset(self, num_to_skip): of query results. (Must be non-negative.) Returns: - ~google.cloud.firestore_v1.query.Query: An offset query. + ~.firestore_v1.query.Query: An offset query. """ query = query_mod.Query(self) return query.offset(num_to_skip) @@ -306,18 +306,18 @@ def start_at(self, document_fields): """Start query at a cursor with this collection as parent. See - :meth:`~google.cloud.firestore_v1.query.Query.start_at` for + :meth:`~.firestore_v1.query.Query.start_at` for more information on this method. Args: - document_fields (Union[~google.cloud.firestore_v1.\ + document_fields (Union[~.firestore_v1.\ document.DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: - ~google.cloud.firestore_v1.query.Query: A query with cursor. + ~.firestore_v1.query.Query: A query with cursor. """ query = query_mod.Query(self) return query.start_at(document_fields) @@ -326,18 +326,18 @@ def start_after(self, document_fields): """Start query after a cursor with this collection as parent. See - :meth:`~google.cloud.firestore_v1.query.Query.start_after` for + :meth:`~.firestore_v1.query.Query.start_after` for more information on this method. Args: - document_fields (Union[~google.cloud.firestore_v1.\ + document_fields (Union[~.firestore_v1.\ document.DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: - ~google.cloud.firestore_v1.query.Query: A query with cursor. + ~.firestore_v1.query.Query: A query with cursor. """ query = query_mod.Query(self) return query.start_after(document_fields) @@ -346,18 +346,18 @@ def end_before(self, document_fields): """End query before a cursor with this collection as parent. See - :meth:`~google.cloud.firestore_v1.query.Query.end_before` for + :meth:`~.firestore_v1.query.Query.end_before` for more information on this method. Args: - document_fields (Union[~google.cloud.firestore_v1.\ + document_fields (Union[~.firestore_v1.\ document.DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: - ~google.cloud.firestore_v1.query.Query: A query with cursor. + ~.firestore_v1.query.Query: A query with cursor. """ query = query_mod.Query(self) return query.end_before(document_fields) @@ -366,18 +366,18 @@ def end_at(self, document_fields): """End query at a cursor with this collection as parent. See - :meth:`~google.cloud.firestore_v1.query.Query.end_at` for + :meth:`~.firestore_v1.query.Query.end_at` for more information on this method. Args: - document_fields (Union[~google.cloud.firestore_v1.\ + document_fields (Union[~.firestore_v1.\ document.DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: - ~google.cloud.firestore_v1.query.Query: A query with cursor. + ~.firestore_v1.query.Query: A query with cursor. """ query = query_mod.Query(self) return query.end_at(document_fields) @@ -410,12 +410,12 @@ def stream(self, transaction=None): allowed). Args: - transaction (Optional[~google.cloud.firestore_v1.transaction.\ + transaction (Optional[~.firestore_v1.transaction.\ Transaction]): An existing transaction that the query will run in. Yields: - ~google.cloud.firestore_v1.document.DocumentSnapshot: The next + ~.firestore_v1.document.DocumentSnapshot: The next document that fulfills the query. """ query = query_mod.Query(self) @@ -428,7 +428,7 @@ def on_snapshot(self, callback): provided callback is run on the snapshot of the documents. Args: - callback(~google.cloud.firestore.collection.CollectionSnapshot): a callback + callback(~.firestore.collection.CollectionSnapshot): a callback to run when a change occurs. Example: diff --git a/google/cloud/firestore_v1/document.py b/google/cloud/firestore_v1/document.py index e4ebaa398..6843aefa1 100644 --- a/google/cloud/firestore_v1/document.py +++ b/google/cloud/firestore_v1/document.py @@ -37,7 +37,7 @@ class DocumentReference(object): that contain a sub-collection (as well as the base document). kwargs (dict): The keyword arguments for the constructor. The only supported keyword is ``client`` and it must be a - :class:`~google.cloud.firestore_v1.client.Client`. It represents + :class:`~.firestore_v1.client.Client`. It represents the client that created this document reference. Raises: @@ -162,7 +162,7 @@ def parent(self): """Collection that owns the current document. Returns: - ~google.cloud.firestore_v1.collection.CollectionReference: The + ~.firestore_v1.collection.CollectionReference: The parent collection. """ parent_path = self._path[:-1] @@ -176,7 +176,7 @@ def collection(self, collection_id): referred to as the "kind"). Returns: - ~google.cloud.firestore_v1.collection.CollectionReference: The + ~.firestore_v1.collection.CollectionReference: The child collection. """ child_path = self._path + (collection_id,) @@ -242,7 +242,7 @@ def update(self, field_updates, option=None): Each key in ``field_updates`` can either be a field name or a **field path** (For more information on **field paths**, see - :meth:`~google.cloud.firestore_v1.client.Client.field_path`.) To + :meth:`~.firestore_v1.client.Client.field_path`.) To illustrate this, consider a document with .. code-block:: python @@ -312,7 +312,7 @@ def update(self, field_updates, option=None): ``field_updates``. To delete / remove a field from an existing document, use the - :attr:`~google.cloud.firestore_v1.transforms.DELETE_FIELD` sentinel. So + :attr:`~.firestore_v1.transforms.DELETE_FIELD` sentinel. So with the example above, sending .. code-block:: python @@ -336,7 +336,7 @@ def update(self, field_updates, option=None): To set a field to the current time on the server when the update is received, use the - :attr:`~google.cloud.firestore_v1.transforms.SERVER_TIMESTAMP` sentinel. + :attr:`~.firestore_v1.transforms.SERVER_TIMESTAMP` sentinel. Sending .. code-block:: python @@ -363,7 +363,7 @@ def update(self, field_updates, option=None): Args: field_updates (dict): Field names or paths to update and values to update with. - option (Optional[~google.cloud.firestore_v1.client.WriteOption]): A + option (Optional[~.firestore_v1.client.WriteOption]): A write option to make assertions / preconditions on the server state of the document before applying changes. @@ -384,7 +384,7 @@ def delete(self, option=None): """Delete the current document in the Firestore database. Args: - option (Optional[~google.cloud.firestore_v1.client.WriteOption]): A + option (Optional[~.firestore_v1.client.WriteOption]): A write option to make assertions / preconditions on the server state of the document before applying changes. @@ -408,7 +408,7 @@ def delete(self, option=None): def get(self, field_paths=None, transaction=None): """Retrieve a snapshot of the current document. - See :meth:`~google.cloud.firestore_v1.client.Client.field_path` for + See :meth:`~.firestore_v1.client.Client.field_path` for more information on **field paths**. If a ``transaction`` is used and it already has write operations @@ -420,12 +420,12 @@ def get(self, field_paths=None, transaction=None): paths (``.``-delimited list of field names) to use as a projection of document fields in the returned results. If no value is provided, all fields will be returned. - transaction (Optional[~google.cloud.firestore_v1.transaction.\ + transaction (Optional[~.firestore_v1.transaction.\ Transaction]): An existing transaction that this reference will be retrieved in. Returns: - ~google.cloud.firestore_v1.document.DocumentSnapshot: A snapshot of + ~.firestore_v1.document.DocumentSnapshot: A snapshot of the current document. If the document does not exist at the time of `snapshot`, the snapshot `reference`, `data`, `update_time`, and `create_time` attributes will all be @@ -476,7 +476,7 @@ def collections(self, page_size=None): are ignored. Defaults to a sensible value set by the API. Returns: - Sequence[~google.cloud.firestore_v1.collection.CollectionReference]: + Sequence[~.firestore_v1.collection.CollectionReference]: iterator of subcollections of the current document. If the document does not exist at the time of `snapshot`, the iterator will be empty @@ -497,7 +497,7 @@ def on_snapshot(self, callback): provided callback is run on the snapshot. Args: - callback(~google.cloud.firestore.document.DocumentSnapshot):a callback to run + callback(~.firestore.document.DocumentSnapshot):a callback to run when a change occurs Example: @@ -531,10 +531,10 @@ class DocumentSnapshot(object): Instances of this class are not intended to be constructed by hand, rather they'll be returned as responses to various methods, such as - :meth:`~google.cloud.DocumentReference.get`. + :meth:`~.DocumentReference.get`. Args: - reference (~google.cloud.firestore_v1.document.DocumentReference): A + reference (~.firestore_v1.document.DocumentReference): A document reference corresponding to the document that contains the data in this snapshot. data (Dict[str, Any]): The data retrieved in the snapshot. @@ -576,7 +576,7 @@ def _client(self): """The client that owns the document reference for this snapshot. Returns: - ~google.cloud.firestore_v1.client.Client: The client that owns this + ~.firestore_v1.client.Client: The client that owns this document. """ return self._reference._client @@ -607,7 +607,7 @@ def reference(self): """Document reference corresponding to document that owns this data. Returns: - ~google.cloud.firestore_v1.document.DocumentReference: A document + ~.firestore_v1.document.DocumentReference: A document reference corresponding to this document. """ return self._reference @@ -652,7 +652,7 @@ def get(self, field_path): >>> snapshot.get('top1.middle2.bottom3') 20 - See :meth:`~google.cloud.firestore_v1.client.Client.field_path` for + See :meth:`~.firestore_v1.client.Client.field_path` for more information on **field paths**. A copy is returned since the data may contain mutable values, @@ -701,7 +701,7 @@ def _get_document_path(client, path): documents/{document_path}`` Args: - client (~google.cloud.firestore_v1.client.Client): The client that holds + client (~.firestore_v1.client.Client): The client that holds configuration details and a GAPIC client object. path (Tuple[str, ...]): The components in a document path. diff --git a/google/cloud/firestore_v1/field_path.py b/google/cloud/firestore_v1/field_path.py index 7552f2ec1..bba237ee2 100644 --- a/google/cloud/firestore_v1/field_path.py +++ b/google/cloud/firestore_v1/field_path.py @@ -216,7 +216,7 @@ def get_nested_value(field_path, data): >>> get_nested_value('top1.middle2.bottom3', data) 20 - See :meth:`~google.cloud.firestore_v1.client.Client.field_path` for + See :meth:`~.firestore_v1.client.Client.field_path` for more information on **field paths**. Args: diff --git a/google/cloud/firestore_v1/gapic/firestore_client.py b/google/cloud/firestore_v1/gapic/firestore_client.py index f76159d76..fc97baa11 100644 --- a/google/cloud/firestore_v1/gapic/firestore_client.py +++ b/google/cloud/firestore_v1/gapic/firestore_client.py @@ -147,8 +147,8 @@ def __init__( """Constructor. Args: - transport (Union[~google.cloud.FirestoreGrpcTransport, - Callable[[~google.cloud.Credentials, type], ~.FirestoreGrpcTransport]): A transport + transport (Union[~.FirestoreGrpcTransport, + Callable[[~.Credentials, type], ~.FirestoreGrpcTransport]): A transport instance, responsible for actually making the API calls. The default transport uses the gRPC protocol. This argument may also be a callable which returns a diff --git a/google/cloud/firestore_v1/gapic/transports/firestore_grpc_transport.py b/google/cloud/firestore_v1/gapic/transports/firestore_grpc_transport.py index 9fa9ab9a2..22bbdbe31 100644 --- a/google/cloud/firestore_v1/gapic/transports/firestore_grpc_transport.py +++ b/google/cloud/firestore_v1/gapic/transports/firestore_grpc_transport.py @@ -75,7 +75,7 @@ def create_channel(cls, address="firestore.googleapis.com:443", credentials=None Args: address (str): The host for the channel to use. - credentials (~google.cloud.Credentials): The + credentials (~.Credentials): The authorization credentials to attach to requests. These credentials identify this application to the service. If none are specified, the client will attempt to ascertain diff --git a/google/cloud/firestore_v1/query.py b/google/cloud/firestore_v1/query.py index 70b46d874..12141cc80 100644 --- a/google/cloud/firestore_v1/query.py +++ b/google/cloud/firestore_v1/query.py @@ -14,8 +14,8 @@ """Classes for representing queries for the Google Cloud Firestore API. -A :class:`~google.cloud.firestore_v1.query.Query` can be created directly from -a :class:`~google.cloud.firestore_v1.collection.Collection` and that can be +A :class:`~.firestore_v1.query.Query` can be created directly from +a :class:`~.firestore_v1.collection.Collection` and that can be a more common way to create a query than direct usage of the constructor. """ import copy @@ -71,7 +71,7 @@ class Query(object): would modify an instance instead return a new instance. Args: - parent (~google.cloud.firestore_v1.collection.Collection): The collection + parent (~.firestore_v1.collection.Collection): The collection that this query applies to. projection (Optional[google.cloud.proto.firestore.v1.\ query_pb2.StructuredQuery.Projection]): A projection of document @@ -164,7 +164,7 @@ def _client(self): """The client of the parent collection. Returns: - ~google.cloud.firestore_v1.client.Client: The client that owns + ~.firestore_v1.client.Client: The client that owns this query. """ return self._parent._client @@ -172,11 +172,11 @@ def _client(self): def select(self, field_paths): """Project documents matching query to a limited set of fields. - See :meth:`~google.cloud.firestore_v1.client.Client.field_path` for + See :meth:`~.firestore_v1.client.Client.field_path` for more information on **field paths**. If the current query already has a projection set (i.e. has already - called :meth:`~google.cloud.firestore_v1.query.Query.select`), this + called :meth:`~.firestore_v1.query.Query.select`), this will overwrite it. Args: @@ -185,7 +185,7 @@ def select(self, field_paths): of document fields in the query results. Returns: - ~google.cloud.firestore_v1.query.Query: A "projected" query. Acts as + ~.firestore_v1.query.Query: A "projected" query. Acts as a copy of the current query, modified with the newly added projection. Raises: @@ -216,10 +216,10 @@ def select(self, field_paths): def where(self, field_path, op_string, value): """Filter the query on a field. - See :meth:`~google.cloud.firestore_v1.client.Client.field_path` for + See :meth:`~.firestore_v1.client.Client.field_path` for more information on **field paths**. - Returns a new :class:`~google.cloud.firestore_v1.query.Query` that + Returns a new :class:`~.firestore_v1.query.Query` that filters on a specific field path, according to an operation (e.g. ``==`` or "equals") and a particular value to be paired with that operation. @@ -235,7 +235,7 @@ def where(self, field_path, op_string, value): allowed operation. Returns: - ~google.cloud.firestore_v1.query.Query: A filtered query. Acts as a + ~.firestore_v1.query.Query: A filtered query. Acts as a copy of the current query, modified with the newly added filter. Raises: @@ -292,10 +292,10 @@ def _make_order(field_path, direction): def order_by(self, field_path, direction=ASCENDING): """Modify the query to add an order clause on a specific field. - See :meth:`~google.cloud.firestore_v1.client.Client.field_path` for + See :meth:`~.firestore_v1.client.Client.field_path` for more information on **field paths**. - Successive :meth:`~google.cloud.firestore_v1.query.Query.order_by` calls + Successive :meth:`~.firestore_v1.query.Query.order_by` calls will further refine the ordering of results returned by the query (i.e. the new "order by" fields will be added to existing ones). @@ -307,7 +307,7 @@ def order_by(self, field_path, direction=ASCENDING): :attr:`ASCENDING`. Returns: - ~google.cloud.firestore_v1.query.Query: An ordered query. Acts as a + ~.firestore_v1.query.Query: An ordered query. Acts as a copy of the current query, modified with the newly added "order by" constraint. @@ -343,7 +343,7 @@ def limit(self, count): the query. Returns: - ~google.cloud.firestore_v1.query.Query: A limited query. Acts as a + ~.firestore_v1.query.Query: A limited query. Acts as a copy of the current query, modified with the newly added "limit" filter. """ @@ -370,7 +370,7 @@ def offset(self, num_to_skip): of query results. (Must be non-negative.) Returns: - ~google.cloud.firestore_v1.query.Query: An offset query. Acts as a + ~.firestore_v1.query.Query: An offset query. Acts as a copy of the current query, modified with the newly added "offset" field. """ @@ -393,10 +393,10 @@ def _cursor_helper(self, document_fields, before, start): When the query is sent to the server, the ``document_fields`` will be used in the order given by fields set by - :meth:`~google.cloud.firestore_v1.query.Query.order_by`. + :meth:`~.firestore_v1.query.Query.order_by`. Args: - document_fields (Union[~google.cloud.firestore_v1.\ + document_fields (Union[~.firestore_v1.\ document.DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that @@ -408,7 +408,7 @@ def _cursor_helper(self, document_fields, before, start): cursor (:data:`True`) or an ``end_at`` cursor (:data:`False`). Returns: - ~google.cloud.firestore_v1.query.Query: A query with cursor. Acts as + ~.firestore_v1.query.Query: A query with cursor. Acts as a copy of the current query, modified with the newly added "start at" cursor. """ @@ -449,22 +449,22 @@ def start_at(self, document_fields): If the current query already has specified a start cursor -- either via this method or - :meth:`~google.cloud.firestore_v1.query.Query.start_after` -- this will + :meth:`~.firestore_v1.query.Query.start_after` -- this will overwrite it. When the query is sent to the server, the ``document_fields`` will be used in the order given by fields set by - :meth:`~google.cloud.firestore_v1.query.Query.order_by`. + :meth:`~.firestore_v1.query.Query.order_by`. Args: - document_fields (Union[~google.cloud.firestore_v1.\ + document_fields (Union[~.firestore_v1.\ document.DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: - ~google.cloud.firestore_v1.query.Query: A query with cursor. Acts as + ~.firestore_v1.query.Query: A query with cursor. Acts as a copy of the current query, modified with the newly added "start at" cursor. """ @@ -478,22 +478,22 @@ def start_after(self, document_fields): If the current query already has specified a start cursor -- either via this method or - :meth:`~google.cloud.firestore_v1.query.Query.start_at` -- this will + :meth:`~.firestore_v1.query.Query.start_at` -- this will overwrite it. When the query is sent to the server, the ``document_fields`` will be used in the order given by fields set by - :meth:`~google.cloud.firestore_v1.query.Query.order_by`. + :meth:`~.firestore_v1.query.Query.order_by`. Args: - document_fields (Union[~google.cloud.firestore_v1.\ + document_fields (Union[~.firestore_v1.\ document.DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: - ~google.cloud.firestore_v1.query.Query: A query with cursor. Acts as + ~.firestore_v1.query.Query: A query with cursor. Acts as a copy of the current query, modified with the newly added "start after" cursor. """ @@ -507,22 +507,22 @@ def end_before(self, document_fields): If the current query already has specified an end cursor -- either via this method or - :meth:`~google.cloud.firestore_v1.query.Query.end_at` -- this will + :meth:`~.firestore_v1.query.Query.end_at` -- this will overwrite it. When the query is sent to the server, the ``document_fields`` will be used in the order given by fields set by - :meth:`~google.cloud.firestore_v1.query.Query.order_by`. + :meth:`~.firestore_v1.query.Query.order_by`. Args: - document_fields (Union[~google.cloud.firestore_v1.\ + document_fields (Union[~.firestore_v1.\ document.DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: - ~google.cloud.firestore_v1.query.Query: A query with cursor. Acts as + ~.firestore_v1.query.Query: A query with cursor. Acts as a copy of the current query, modified with the newly added "end before" cursor. """ @@ -536,22 +536,22 @@ def end_at(self, document_fields): If the current query already has specified an end cursor -- either via this method or - :meth:`~google.cloud.firestore_v1.query.Query.end_before` -- this will + :meth:`~.firestore_v1.query.Query.end_before` -- this will overwrite it. When the query is sent to the server, the ``document_fields`` will be used in the order given by fields set by - :meth:`~google.cloud.firestore_v1.query.Query.order_by`. + :meth:`~.firestore_v1.query.Query.order_by`. Args: - document_fields (Union[~google.cloud.firestore_v1.\ + document_fields (Union[~.firestore_v1.\ document.DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: - ~google.cloud.firestore_v1.query.Query: A query with cursor. Acts as + ~.firestore_v1.query.Query: A query with cursor. Acts as a copy of the current query, modified with the newly added "end at" cursor. """ @@ -735,12 +735,12 @@ def stream(self, transaction=None): allowed). Args: - transaction (Optional[~google.cloud.firestore_v1.transaction.\ + transaction (Optional[~.firestore_v1.transaction.\ Transaction]): An existing transaction that this query will run in. Yields: - ~google.cloud.firestore_v1.document.DocumentSnapshot: The next + ~.firestore_v1.document.DocumentSnapshot: The next document that fulfills the query. """ parent_path, expected_prefix = self._parent._parent_info() @@ -770,7 +770,7 @@ def on_snapshot(self, callback): provided callback is run on the snapshot of the documents. Args: - callback(~google.cloud.firestore.query.QuerySnapshot): a callback to run when + callback(~.firestore.query.QuerySnapshot): a callback to run when a change occurs. Example: @@ -888,8 +888,8 @@ def _enum_from_direction(direction): Args: direction (str): A direction to order by. Must be one of - :attr:`~google.cloud.firestore.Query.ASCENDING` or - :attr:`~google.cloud.firestore.Query.DESCENDING`. + :attr:`~.firestore.Query.ASCENDING` or + :attr:`~.firestore.Query.DESCENDING`. Returns: int: The enum corresponding to ``direction``. @@ -960,14 +960,14 @@ def _query_response_to_snapshot(response_pb, collection, expected_prefix): Args: response_pb (google.cloud.proto.firestore.v1.\ firestore_pb2.RunQueryResponse): A - collection (~google.cloud.firestore_v1.collection.CollectionReference): A + collection (~.firestore_v1.collection.CollectionReference): A reference to the collection that initiated the query. expected_prefix (str): The expected prefix for fully-qualified document names returned in the query results. This can be computed directly from ``collection`` via :meth:`_parent_info`. Returns: - Optional[~google.cloud.firestore.document.DocumentSnapshot]: A + Optional[~.firestore.document.DocumentSnapshot]: A snapshot of the data returned in the query. If ``response_pb.document`` is not set, the snapshot will be :data:`None`. """ @@ -994,11 +994,11 @@ def _collection_group_query_response_to_snapshot(response_pb, collection): Args: response_pb (google.cloud.proto.firestore.v1.\ firestore_pb2.RunQueryResponse): A - collection (~google.cloud.firestore_v1.collection.CollectionReference): A + collection (~.firestore_v1.collection.CollectionReference): A reference to the collection that initiated the query. Returns: - Optional[~google.cloud.firestore.document.DocumentSnapshot]: A + Optional[~.firestore.document.DocumentSnapshot]: A snapshot of the data returned in the query. If ``response_pb.document`` is not set, the snapshot will be :data:`None`. """ diff --git a/google/cloud/firestore_v1/transaction.py b/google/cloud/firestore_v1/transaction.py index fad17b3fe..5570e38b8 100644 --- a/google/cloud/firestore_v1/transaction.py +++ b/google/cloud/firestore_v1/transaction.py @@ -46,11 +46,11 @@ class Transaction(batch.WriteBatch): """Accumulate read-and-write operations to be sent in a transaction. Args: - client (~google.cloud.firestore_v1.client.Client): The client that + client (~.firestore_v1.client.Client): The client that created this transaction. max_attempts (Optional[int]): The maximum number of attempts for the transaction (i.e. allowing retries). Defaults to - :attr:`~google.cloud.firestore_v1.transaction.MAX_ATTEMPTS`. + :attr:`~.firestore_v1.transaction.MAX_ATTEMPTS`. read_only (Optional[bool]): Flag indicating if the transaction should be read-only or should allow writes. Defaults to :data:`False`. @@ -206,10 +206,10 @@ class _Transactional(object): """Provide a callable object to use as a transactional decorater. This is surfaced via - :func:`~google.cloud.firestore_v1.transaction.transactional`. + :func:`~.firestore_v1.transaction.transactional`. Args: - to_wrap (Callable[~google.cloud.firestore_v1.transaction.Transaction, \ + to_wrap (Callable[~.firestore_v1.transaction.Transaction, \ Any]): A callable that should be run (and retried) in a transaction. """ @@ -234,7 +234,7 @@ def _pre_commit(self, transaction, *args, **kwargs): it will have staged writes). Args: - transaction (~google.cloud.firestore_v1.transaction.Transaction): A + transaction (~.firestore_v1.transaction.Transaction): A transaction to execute the callable within. args (Tuple[Any, ...]): The extra positional arguments to pass along to the wrapped callable. @@ -271,7 +271,7 @@ def _maybe_commit(self, transaction): not be caught. Args: - transaction (~google.cloud.firestore_v1.transaction.Transaction): The + transaction (~.firestore_v1.transaction.Transaction): The transaction to be ``Commit``-ed. Returns: @@ -294,7 +294,7 @@ def __call__(self, transaction, *args, **kwargs): """Execute the wrapped callable within a transaction. Args: - transaction (~google.cloud.firestore_v1.transaction.Transaction): A + transaction (~.firestore_v1.transaction.Transaction): A transaction to execute the callable within. args (Tuple[Any, ...]): The extra positional arguments to pass along to the wrapped callable. @@ -331,12 +331,12 @@ def transactional(to_wrap): """Decorate a callable so that it runs in a transaction. Args: - to_wrap (Callable[~google.cloud.firestore_v1.transaction.Transaction, \ + to_wrap (Callable[~.firestore_v1.transaction.Transaction, \ Any]): A callable that should be run (and retried) in a transaction. Returns: - Callable[~google.cloud.firestore_v1.transaction.Transaction, Any]: the + Callable[~.firestore_v1.transaction.Transaction, Any]: the wrapped callable. """ return _Transactional(to_wrap) @@ -352,7 +352,7 @@ def _commit_with_retry(client, write_pbs, transaction_id): our own retry to special-case the ``INVALID_ARGUMENT`` error. Args: - client (~google.cloud.firestore_v1.client.Client): A client with + client (~.firestore_v1.client.Client): A client with GAPIC client and configuration details. write_pbs (List[google.cloud.proto.firestore.v1.\ write_pb2.Write, ...]): A ``Write`` protobuf instance to diff --git a/google/cloud/firestore_v1beta1/_helpers.py b/google/cloud/firestore_v1beta1/_helpers.py index d2805fa32..8707d9113 100644 --- a/google/cloud/firestore_v1beta1/_helpers.py +++ b/google/cloud/firestore_v1beta1/_helpers.py @@ -220,11 +220,11 @@ def reference_value_to_document(reference_value, client): Args: reference_value (str): A document reference value. - client (~google.cloud.firestore_v1beta1.client.Client): A client that has + client (~.firestore_v1beta1.client.Client): A client that has a document factory. Returns: - ~google.cloud.firestore_v1beta1.document.DocumentReference: The document + ~.firestore_v1beta1.document.DocumentReference: The document corresponding to ``reference_value``. Raises: @@ -255,7 +255,7 @@ def decode_value(value, client): Args: value (google.cloud.firestore_v1beta1.types.Value): A Firestore protobuf to be decoded / parsed / converted. - client (~google.cloud.firestore_v1beta1.client.Client): A client that has + client (~.firestore_v1beta1.client.Client): A client that has a document factory. Returns: @@ -301,7 +301,7 @@ def decode_dict(value_fields, client): Args: value_fields (google.protobuf.pyext._message.MessageMapContainer): A protobuf map of Firestore ``Value``-s. - client (~google.cloud.firestore_v1beta1.client.Client): A client that has + client (~.firestore_v1beta1.client.Client): A client that has a document factory. Returns: @@ -800,7 +800,7 @@ def pbs_for_update(document_path, field_updates, option): document_path (str): A fully-qualified document path. field_updates (dict): Field names or paths to update and values to update with. - option (optional[~google.cloud.firestore_v1beta1.client.WriteOption]): A + option (optional[~.firestore_v1beta1.client.WriteOption]): A write option to make assertions / preconditions on the server state of the document before applying changes. @@ -839,7 +839,7 @@ def pb_for_delete(document_path, option): Args: document_path (str): A fully-qualified document path. - option (optional[~google.cloud.firestore_v1beta1.client.WriteOption]): A + option (optional[~.firestore_v1beta1.client.WriteOption]): A write option to make assertions / preconditions on the server state of the document before applying changes. @@ -865,7 +865,7 @@ def get_transaction_id(transaction, read_operation=True): """Get the transaction ID from a ``Transaction`` object. Args: - transaction (Optional[~google.cloud.firestore_v1beta1.transaction.\ + transaction (Optional[~.firestore_v1beta1.transaction.\ Transaction]): An existing transaction that this query will run in. read_operation (Optional[bool]): Indicates if the transaction ID @@ -928,7 +928,7 @@ class LastUpdateOption(WriteOption): """Option used to assert a "last update" condition on a write operation. This will typically be created by - :meth:`~google.cloud.firestore_v1beta1.client.Client.write_option`. + :meth:`~.firestore_v1beta1.client.Client.write_option`. Args: last_update_time (google.protobuf.timestamp_pb2.Timestamp): A @@ -968,7 +968,7 @@ class ExistsOption(WriteOption): """Option used to assert existence on a write operation. This will typically be created by - :meth:`~google.cloud.firestore_v1beta1.client.Client.write_option`. + :meth:`~.firestore_v1beta1.client.Client.write_option`. Args: exists (bool): Indicates if the document being modified diff --git a/google/cloud/firestore_v1beta1/batch.py b/google/cloud/firestore_v1beta1/batch.py index 0b79d9cdc..310127ee7 100644 --- a/google/cloud/firestore_v1beta1/batch.py +++ b/google/cloud/firestore_v1beta1/batch.py @@ -22,11 +22,11 @@ class WriteBatch(object): """Accumulate write operations to be sent in a batch. This has the same set of methods for write operations that - :class:`~google.cloud.firestore_v1beta1.document.DocumentReference` does, - e.g. :meth:`~google.cloud.firestore_v1beta1.document.DocumentReference.create`. + :class:`~.firestore_v1beta1.document.DocumentReference` does, + e.g. :meth:`~.firestore_v1beta1.document.DocumentReference.create`. Args: - client (~google.cloud.firestore_v1beta1.client.Client): The client that + client (~.firestore_v1beta1.client.Client): The client that created this batch. """ @@ -54,7 +54,7 @@ def create(self, reference, document_data): batch will fail when :meth:`commit`-ed. Args: - reference (~google.cloud.firestore_v1beta1.document.DocumentReference): A + reference (~.firestore_v1beta1.document.DocumentReference): A document reference to be created in this batch. document_data (dict): Property names and values to use for creating a document. @@ -66,12 +66,12 @@ def set(self, reference, document_data, merge=False): """Add a "change" to replace a document. See - :meth:`~google.cloud.firestore_v1beta1.document.DocumentReference.set` for + :meth:`~.firestore_v1beta1.document.DocumentReference.set` for more information on how ``option`` determines how the change is applied. Args: - reference (~google.cloud.firestore_v1beta1.document.DocumentReference): + reference (~.firestore_v1beta1.document.DocumentReference): A document reference that will have values set in this batch. document_data (dict): Property names and values to use for replacing a document. @@ -94,15 +94,15 @@ def update(self, reference, field_updates, option=None): """Add a "change" to update a document. See - :meth:`~google.cloud.firestore_v1beta1.document.DocumentReference.update` for + :meth:`~.firestore_v1beta1.document.DocumentReference.update` for more information on ``field_updates`` and ``option``. Args: - reference (~google.cloud.firestore_v1beta1.document.DocumentReference): A + reference (~.firestore_v1beta1.document.DocumentReference): A document reference that will be deleted in this batch. field_updates (dict): Field names or paths to update and values to update with. - option (Optional[~google.cloud.firestore_v1beta1.client.WriteOption]): A + option (Optional[~.firestore_v1beta1.client.WriteOption]): A write option to make assertions / preconditions on the server state of the document before applying changes. """ @@ -117,14 +117,14 @@ def delete(self, reference, option=None): """Add a "change" to delete a document. See - :meth:`~google.cloud.firestore_v1beta1.document.DocumentReference.delete` for + :meth:`~.firestore_v1beta1.document.DocumentReference.delete` for more information on how ``option`` determines how the change is applied. Args: - reference (~google.cloud.firestore_v1beta1.document.DocumentReference): A + reference (~.firestore_v1beta1.document.DocumentReference): A document reference that will be deleted in this batch. - option (Optional[~google.cloud.firestore_v1beta1.client.WriteOption]): A + option (Optional[~.firestore_v1beta1.client.WriteOption]): A write option to make assertions / preconditions on the server state of the document before applying changes. """ diff --git a/google/cloud/firestore_v1beta1/client.py b/google/cloud/firestore_v1beta1/client.py index 04101882b..02adaeb9a 100644 --- a/google/cloud/firestore_v1beta1/client.py +++ b/google/cloud/firestore_v1beta1/client.py @@ -18,10 +18,10 @@ In the hierarchy of API concepts -* a :class:`~google.cloud.firestore_v1beta1.client.Client` owns a - :class:`~google.cloud.firestore_v1beta1.collection.CollectionReference` -* a :class:`~google.cloud.firestore_v1beta1.client.Client` owns a - :class:`~google.cloud.firestore_v1beta1.document.DocumentReference` +* a :class:`~.firestore_v1beta1.client.Client` owns a + :class:`~.firestore_v1beta1.collection.CollectionReference` +* a :class:`~.firestore_v1beta1.client.Client` owns a + :class:`~.firestore_v1beta1.document.DocumentReference` """ from google.cloud.client import ClientWithProject @@ -37,7 +37,7 @@ DEFAULT_DATABASE = "(default)" -"""str: The default database used in a :class:`~google.cloud.firestore.client.Client`.""" +"""str: The default database used in a :class:`~.firestore.client.Client`.""" _BAD_OPTION_ERR = ( "Exactly one of ``last_update_time`` or ``exists`` " "must be provided." ) @@ -92,7 +92,7 @@ def _firestore_api(self): """Lazy-loading getter GAPIC Firestore API. Returns: - ~google.cloud.gapic.firestore.v1beta1.firestore_client.FirestoreClient: The + ~.gapic.firestore.v1beta1.firestore_client.FirestoreClient: The GAPIC client with the credentials of the current client. """ if self._firestore_api_internal is None: @@ -169,7 +169,7 @@ def collection(self, *collection_path): * A tuple of collection path segments Returns: - ~google.cloud.firestore_v1beta1.collection.CollectionReference: A reference + ~.firestore_v1beta1.collection.CollectionReference: A reference to a collection in the Firestore database. """ if len(collection_path) == 1: @@ -207,7 +207,7 @@ def document(self, *document_path): * A tuple of document path segments Returns: - ~google.cloud.firestore_v1beta1.document.DocumentReference: A reference + ~.firestore_v1beta1.document.DocumentReference: A reference to a document in a collection. """ if len(document_path) == 1: @@ -250,9 +250,9 @@ def field_path(*field_names): def write_option(**kwargs): """Create a write option for write operations. - Write operations include :meth:`~google.cloud.DocumentReference.set`, - :meth:`~google.cloud.DocumentReference.update` and - :meth:`~google.cloud.DocumentReference.delete`. + Write operations include :meth:`~.DocumentReference.set`, + :meth:`~.DocumentReference.update` and + :meth:`~.DocumentReference.delete`. One of the following keyword arguments must be provided: @@ -304,7 +304,7 @@ def get_all(self, references, field_paths=None, transaction=None): If multiple ``references`` refer to the same document, the server will only return one result. - See :meth:`~google.cloud.firestore_v1beta1.client.Client.field_path` for + See :meth:`~.firestore_v1beta1.client.Client.field_path` for more information on **field paths**. If a ``transaction`` is used and it already has write operations @@ -318,7 +318,7 @@ def get_all(self, references, field_paths=None, transaction=None): paths (``.``-delimited list of field names) to use as a projection of document fields in the returned results. If no value is provided, all fields will be returned. - transaction (Optional[~google.cloud.firestore_v1beta1.transaction.\ + transaction (Optional[~.firestore_v1beta1.transaction.\ Transaction]): An existing transaction that these ``references`` will be retrieved in. @@ -343,7 +343,7 @@ def collections(self): """List top-level collections of the client's database. Returns: - Sequence[~google.cloud.firestore_v1beta1.collection.CollectionReference]: + Sequence[~.firestore_v1beta1.collection.CollectionReference]: iterator of subcollections of the current document. """ iterator = self._firestore_api.list_collection_ids( @@ -357,7 +357,7 @@ def batch(self): """Get a batch instance from this client. Returns: - ~google.cloud.firestore_v1beta1.batch.WriteBatch: A "write" batch to be + ~.firestore_v1beta1.batch.WriteBatch: A "write" batch to be used for accumulating document changes and sending the changes all at once. """ @@ -366,17 +366,17 @@ def batch(self): def transaction(self, **kwargs): """Get a transaction that uses this client. - See :class:`~google.cloud.firestore_v1beta1.transaction.Transaction` for + See :class:`~.firestore_v1beta1.transaction.Transaction` for more information on transactions and the constructor arguments. Args: kwargs (Dict[str, Any]): The keyword arguments (other than ``client``) to pass along to the - :class:`~google.cloud.firestore_v1beta1.transaction.Transaction` + :class:`~.firestore_v1beta1.transaction.Transaction` constructor. Returns: - ~google.cloud.firestore_v1beta1.transaction.Transaction: A transaction + ~.firestore_v1beta1.transaction.Transaction: A transaction attached to this client. """ return Transaction(self, **kwargs) @@ -385,7 +385,7 @@ def transaction(self, **kwargs): def _reference_info(references): """Get information about document references. - Helper for :meth:`~google.cloud.firestore_v1beta1.client.Client.get_all`. + Helper for :meth:`~.firestore_v1beta1.client.Client.get_all`. Args: references (List[.DocumentReference, ...]): Iterable of document @@ -413,7 +413,7 @@ def _get_reference(document_path, reference_map): """Get a document reference from a dictionary. This just wraps a simple dictionary look-up with a helpful error that is - specific to :meth:`~google.cloud.firestore.client.Client.get_all`, the + specific to :meth:`~.firestore.client.Client.get_all`, the **public** caller of this function. Args: @@ -445,7 +445,7 @@ def _parse_batch_get(get_doc_response, reference_map, client): reference_map (Dict[str, .DocumentReference]): A mapping (produced by :func:`_reference_info`) of fully-qualified document paths to document references. - client (~google.cloud.firestore_v1beta1.client.Client): A client that has + client (~.firestore_v1beta1.client.Client): A client that has a document factory. Returns: diff --git a/google/cloud/firestore_v1beta1/collection.py b/google/cloud/firestore_v1beta1/collection.py index 1038640c3..9afd96866 100644 --- a/google/cloud/firestore_v1beta1/collection.py +++ b/google/cloud/firestore_v1beta1/collection.py @@ -40,7 +40,7 @@ class CollectionReference(object): that contain a sub-collection. kwargs (dict): The keyword arguments for the constructor. The only supported keyword is ``client`` and it must be a - :class:`~google.cloud.firestore_v1beta1.client.Client` if provided. It + :class:`~.firestore_v1beta1.client.Client` if provided. It represents the client that created this collection reference. Raises: @@ -81,7 +81,7 @@ def parent(self): """Document that owns the current collection. Returns: - Optional[~google.cloud.firestore_v1beta1.document.DocumentReference]: The + Optional[~.firestore_v1beta1.document.DocumentReference]: The parent document, if the current collection is not a top-level collection. """ @@ -101,7 +101,7 @@ def document(self, document_id=None): uppercase and lowercase and letters. Returns: - ~google.cloud.firestore_v1beta1.document.DocumentReference: The child + ~.firestore_v1beta1.document.DocumentReference: The child document. """ if document_id is None: @@ -146,7 +146,7 @@ def add(self, document_data, document_id=None): Returns: Tuple[google.protobuf.timestamp_pb2.Timestamp, \ - ~google.cloud.firestore_v1beta1.document.DocumentReference]: Pair of + ~.firestore_v1beta1.document.DocumentReference]: Pair of * The ``update_time`` when the document was created (or overwritten). @@ -188,7 +188,7 @@ def list_documents(self, page_size=None): are ignored. Defaults to a sensible value set by the API. Returns: - Sequence[~google.cloud.firestore_v1beta1.collection.DocumentReference]: + Sequence[~.firestore_v1beta1.collection.DocumentReference]: iterator of subdocuments of the current collection. If the collection does not exist at the time of `snapshot`, the iterator will be empty @@ -210,7 +210,7 @@ def select(self, field_paths): """Create a "select" query with this collection as parent. See - :meth:`~google.cloud.firestore_v1beta1.query.Query.select` for + :meth:`~.firestore_v1beta1.query.Query.select` for more information on this method. Args: @@ -219,7 +219,7 @@ def select(self, field_paths): of document fields in the query results. Returns: - ~google.cloud.firestore_v1beta1.query.Query: A "projected" query. + ~.firestore_v1beta1.query.Query: A "projected" query. """ query = query_mod.Query(self) return query.select(field_paths) @@ -228,7 +228,7 @@ def where(self, field_path, op_string, value): """Create a "where" query with this collection as parent. See - :meth:`~google.cloud.firestore_v1beta1.query.Query.where` for + :meth:`~.firestore_v1beta1.query.Query.where` for more information on this method. Args: @@ -242,7 +242,7 @@ def where(self, field_path, op_string, value): allowed operation. Returns: - ~google.cloud.firestore_v1beta1.query.Query: A filtered query. + ~.firestore_v1beta1.query.Query: A filtered query. """ query = query_mod.Query(self) return query.where(field_path, op_string, value) @@ -251,7 +251,7 @@ def order_by(self, field_path, **kwargs): """Create an "order by" query with this collection as parent. See - :meth:`~google.cloud.firestore_v1beta1.query.Query.order_by` for + :meth:`~.firestore_v1beta1.query.Query.order_by` for more information on this method. Args: @@ -259,11 +259,11 @@ def order_by(self, field_path, **kwargs): field names) on which to order the query results. kwargs (Dict[str, Any]): The keyword arguments to pass along to the query. The only supported keyword is ``direction``, - see :meth:`~google.cloud.firestore_v1beta1.query.Query.order_by` for + see :meth:`~.firestore_v1beta1.query.Query.order_by` for more information. Returns: - ~google.cloud.firestore_v1beta1.query.Query: An "order by" query. + ~.firestore_v1beta1.query.Query: An "order by" query. """ query = query_mod.Query(self) return query.order_by(field_path, **kwargs) @@ -272,7 +272,7 @@ def limit(self, count): """Create a limited query with this collection as parent. See - :meth:`~google.cloud.firestore_v1beta1.query.Query.limit` for + :meth:`~.firestore_v1beta1.query.Query.limit` for more information on this method. Args: @@ -280,7 +280,7 @@ def limit(self, count): the query. Returns: - ~google.cloud.firestore_v1beta1.query.Query: A limited query. + ~.firestore_v1beta1.query.Query: A limited query. """ query = query_mod.Query(self) return query.limit(count) @@ -289,7 +289,7 @@ def offset(self, num_to_skip): """Skip to an offset in a query with this collection as parent. See - :meth:`~google.cloud.firestore_v1beta1.query.Query.offset` for + :meth:`~.firestore_v1beta1.query.Query.offset` for more information on this method. Args: @@ -297,7 +297,7 @@ def offset(self, num_to_skip): of query results. (Must be non-negative.) Returns: - ~google.cloud.firestore_v1beta1.query.Query: An offset query. + ~.firestore_v1beta1.query.Query: An offset query. """ query = query_mod.Query(self) return query.offset(num_to_skip) @@ -306,18 +306,18 @@ def start_at(self, document_fields): """Start query at a cursor with this collection as parent. See - :meth:`~google.cloud.firestore_v1beta1.query.Query.start_at` for + :meth:`~.firestore_v1beta1.query.Query.start_at` for more information on this method. Args: - document_fields (Union[~google.cloud.firestore_v1beta1.\ + document_fields (Union[~.firestore_v1beta1.\ document.DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: - ~google.cloud.firestore_v1beta1.query.Query: A query with cursor. + ~.firestore_v1beta1.query.Query: A query with cursor. """ query = query_mod.Query(self) return query.start_at(document_fields) @@ -326,18 +326,18 @@ def start_after(self, document_fields): """Start query after a cursor with this collection as parent. See - :meth:`~google.cloud.firestore_v1beta1.query.Query.start_after` for + :meth:`~.firestore_v1beta1.query.Query.start_after` for more information on this method. Args: - document_fields (Union[~google.cloud.firestore_v1beta1.\ + document_fields (Union[~.firestore_v1beta1.\ document.DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: - ~google.cloud.firestore_v1beta1.query.Query: A query with cursor. + ~.firestore_v1beta1.query.Query: A query with cursor. """ query = query_mod.Query(self) return query.start_after(document_fields) @@ -346,18 +346,18 @@ def end_before(self, document_fields): """End query before a cursor with this collection as parent. See - :meth:`~google.cloud.firestore_v1beta1.query.Query.end_before` for + :meth:`~.firestore_v1beta1.query.Query.end_before` for more information on this method. Args: - document_fields (Union[~google.cloud.firestore_v1beta1.\ + document_fields (Union[~.firestore_v1beta1.\ document.DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: - ~google.cloud.firestore_v1beta1.query.Query: A query with cursor. + ~.firestore_v1beta1.query.Query: A query with cursor. """ query = query_mod.Query(self) return query.end_before(document_fields) @@ -366,18 +366,18 @@ def end_at(self, document_fields): """End query at a cursor with this collection as parent. See - :meth:`~google.cloud.firestore_v1beta1.query.Query.end_at` for + :meth:`~.firestore_v1beta1.query.Query.end_at` for more information on this method. Args: - document_fields (Union[~google.cloud.firestore_v1beta1.\ + document_fields (Union[~.firestore_v1beta1.\ document.DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: - ~google.cloud.firestore_v1beta1.query.Query: A query with cursor. + ~.firestore_v1beta1.query.Query: A query with cursor. """ query = query_mod.Query(self) return query.end_at(document_fields) @@ -410,12 +410,12 @@ def stream(self, transaction=None): allowed). Args: - transaction (Optional[~google.cloud.firestore_v1beta1.transaction.\ + transaction (Optional[~.firestore_v1beta1.transaction.\ Transaction]): An existing transaction that the query will run in. Yields: - ~google.cloud.firestore_v1beta1.document.DocumentSnapshot: The next + ~.firestore_v1beta1.document.DocumentSnapshot: The next document that fulfills the query. """ query = query_mod.Query(self) @@ -428,7 +428,7 @@ def on_snapshot(self, callback): provided callback is run on the snapshot of the documents. Args: - callback(~google.cloud.firestore.collection.CollectionSnapshot): a callback + callback(~.firestore.collection.CollectionSnapshot): a callback to run when a change occurs. Example: diff --git a/google/cloud/firestore_v1beta1/document.py b/google/cloud/firestore_v1beta1/document.py index 04dfbcda6..17238af0d 100644 --- a/google/cloud/firestore_v1beta1/document.py +++ b/google/cloud/firestore_v1beta1/document.py @@ -37,7 +37,7 @@ class DocumentReference(object): that contain a sub-collection (as well as the base document). kwargs (dict): The keyword arguments for the constructor. The only supported keyword is ``client`` and it must be a - :class:`~google.cloud.firestore_v1beta1.client.Client`. It represents + :class:`~.firestore_v1beta1.client.Client`. It represents the client that created this document reference. Raises: @@ -162,7 +162,7 @@ def parent(self): """Collection that owns the current document. Returns: - ~google.cloud.firestore_v1beta1.collection.CollectionReference: The + ~.firestore_v1beta1.collection.CollectionReference: The parent collection. """ parent_path = self._path[:-1] @@ -176,7 +176,7 @@ def collection(self, collection_id): referred to as the "kind"). Returns: - ~google.cloud.firestore_v1beta1.collection.CollectionReference: The + ~.firestore_v1beta1.collection.CollectionReference: The child collection. """ child_path = self._path + (collection_id,) @@ -242,7 +242,7 @@ def update(self, field_updates, option=None): Each key in ``field_updates`` can either be a field name or a **field path** (For more information on **field paths**, see - :meth:`~google.cloud.firestore_v1beta1.client.Client.field_path`.) To + :meth:`~.firestore_v1beta1.client.Client.field_path`.) To illustrate this, consider a document with .. code-block:: python @@ -312,7 +312,7 @@ def update(self, field_updates, option=None): ``field_updates``. To delete / remove a field from an existing document, use the - :attr:`~google.cloud.firestore_v1beta1.transforms.DELETE_FIELD` sentinel. So + :attr:`~.firestore_v1beta1.transforms.DELETE_FIELD` sentinel. So with the example above, sending .. code-block:: python @@ -336,7 +336,7 @@ def update(self, field_updates, option=None): To set a field to the current time on the server when the update is received, use the - :attr:`~google.cloud.firestore_v1beta1.transforms.SERVER_TIMESTAMP` sentinel. + :attr:`~.firestore_v1beta1.transforms.SERVER_TIMESTAMP` sentinel. Sending .. code-block:: python @@ -363,7 +363,7 @@ def update(self, field_updates, option=None): Args: field_updates (dict): Field names or paths to update and values to update with. - option (Optional[~google.cloud.firestore_v1beta1.client.WriteOption]): A + option (Optional[~.firestore_v1beta1.client.WriteOption]): A write option to make assertions / preconditions on the server state of the document before applying changes. @@ -384,7 +384,7 @@ def delete(self, option=None): """Delete the current document in the Firestore database. Args: - option (Optional[~google.cloud.firestore_v1beta1.client.WriteOption]): A + option (Optional[~.firestore_v1beta1.client.WriteOption]): A write option to make assertions / preconditions on the server state of the document before applying changes. @@ -408,7 +408,7 @@ def delete(self, option=None): def get(self, field_paths=None, transaction=None): """Retrieve a snapshot of the current document. - See :meth:`~google.cloud.firestore_v1beta1.client.Client.field_path` for + See :meth:`~.firestore_v1beta1.client.Client.field_path` for more information on **field paths**. If a ``transaction`` is used and it already has write operations @@ -420,12 +420,12 @@ def get(self, field_paths=None, transaction=None): paths (``.``-delimited list of field names) to use as a projection of document fields in the returned results. If no value is provided, all fields will be returned. - transaction (Optional[~google.cloud.firestore_v1beta1.transaction.\ + transaction (Optional[~.firestore_v1beta1.transaction.\ Transaction]): An existing transaction that this reference will be retrieved in. Returns: - ~google.cloud.firestore_v1beta1.document.DocumentSnapshot: A snapshot of + ~.firestore_v1beta1.document.DocumentSnapshot: A snapshot of the current document. If the document does not exist at the time of `snapshot`, the snapshot `reference`, `data`, `update_time`, and `create_time` attributes will all be @@ -476,7 +476,7 @@ def collections(self, page_size=None): are ignored. Defaults to a sensible value set by the API. Returns: - Sequence[~google.cloud.firestore_v1beta1.collection.CollectionReference]: + Sequence[~.firestore_v1beta1.collection.CollectionReference]: iterator of subcollections of the current document. If the document does not exist at the time of `snapshot`, the iterator will be empty @@ -497,7 +497,7 @@ def on_snapshot(self, callback): provided callback is run on the snapshot. Args: - callback(~google.cloud.firestore.document.DocumentSnapshot):a callback to run + callback(~.firestore.document.DocumentSnapshot):a callback to run when a change occurs Example: @@ -531,10 +531,10 @@ class DocumentSnapshot(object): Instances of this class are not intended to be constructed by hand, rather they'll be returned as responses to various methods, such as - :meth:`~google.cloud.DocumentReference.get`. + :meth:`~.DocumentReference.get`. Args: - reference (~google.cloud.firestore_v1beta1.document.DocumentReference): A + reference (~.firestore_v1beta1.document.DocumentReference): A document reference corresponding to the document that contains the data in this snapshot. data (Dict[str, Any]): The data retrieved in the snapshot. @@ -576,7 +576,7 @@ def _client(self): """The client that owns the document reference for this snapshot. Returns: - ~google.cloud.firestore_v1beta1.client.Client: The client that owns this + ~.firestore_v1beta1.client.Client: The client that owns this document. """ return self._reference._client @@ -607,7 +607,7 @@ def reference(self): """Document reference corresponding to document that owns this data. Returns: - ~google.cloud.firestore_v1beta1.document.DocumentReference: A document + ~.firestore_v1beta1.document.DocumentReference: A document reference corresponding to this document. """ return self._reference @@ -652,7 +652,7 @@ def get(self, field_path): >>> snapshot.get('top1.middle2.bottom3') 20 - See :meth:`~google.cloud.firestore_v1beta1.client.Client.field_path` for + See :meth:`~.firestore_v1beta1.client.Client.field_path` for more information on **field paths**. A copy is returned since the data may contain mutable values, @@ -701,7 +701,7 @@ def _get_document_path(client, path): documents/{document_path}`` Args: - client (~google.cloud.firestore_v1beta1.client.Client): The client that holds + client (~.firestore_v1beta1.client.Client): The client that holds configuration details and a GAPIC client object. path (Tuple[str, ...]): The components in a document path. diff --git a/google/cloud/firestore_v1beta1/field_path.py b/google/cloud/firestore_v1beta1/field_path.py index 1570aefb5..87e9b211c 100644 --- a/google/cloud/firestore_v1beta1/field_path.py +++ b/google/cloud/firestore_v1beta1/field_path.py @@ -216,7 +216,7 @@ def get_nested_value(field_path, data): >>> get_nested_value('top1.middle2.bottom3', data) 20 - See :meth:`~google.cloud.firestore_v1beta1.client.Client.field_path` for + See :meth:`~.firestore_v1beta1.client.Client.field_path` for more information on **field paths**. Args: diff --git a/google/cloud/firestore_v1beta1/gapic/firestore_client.py b/google/cloud/firestore_v1beta1/gapic/firestore_client.py index 773f16f5e..fd9404f10 100644 --- a/google/cloud/firestore_v1beta1/gapic/firestore_client.py +++ b/google/cloud/firestore_v1beta1/gapic/firestore_client.py @@ -147,8 +147,8 @@ def __init__( """Constructor. Args: - transport (Union[~google.cloud.FirestoreGrpcTransport, - Callable[[~google.cloud.Credentials, type], ~.FirestoreGrpcTransport]): A transport + transport (Union[~.FirestoreGrpcTransport, + Callable[[~.Credentials, type], ~.FirestoreGrpcTransport]): A transport instance, responsible for actually making the API calls. The default transport uses the gRPC protocol. This argument may also be a callable which returns a diff --git a/google/cloud/firestore_v1beta1/gapic/transports/firestore_grpc_transport.py b/google/cloud/firestore_v1beta1/gapic/transports/firestore_grpc_transport.py index 2d37b69f3..ff54b9e3e 100644 --- a/google/cloud/firestore_v1beta1/gapic/transports/firestore_grpc_transport.py +++ b/google/cloud/firestore_v1beta1/gapic/transports/firestore_grpc_transport.py @@ -75,7 +75,7 @@ def create_channel(cls, address="firestore.googleapis.com:443", credentials=None Args: address (str): The host for the channel to use. - credentials (~google.cloud.Credentials): The + credentials (~.Credentials): The authorization credentials to attach to requests. These credentials identify this application to the service. If none are specified, the client will attempt to ascertain diff --git a/google/cloud/firestore_v1beta1/query.py b/google/cloud/firestore_v1beta1/query.py index d52edac23..1191f75af 100644 --- a/google/cloud/firestore_v1beta1/query.py +++ b/google/cloud/firestore_v1beta1/query.py @@ -14,8 +14,8 @@ """Classes for representing queries for the Google Cloud Firestore API. -A :class:`~google.cloud.firestore_v1beta1.query.Query` can be created directly from -a :class:`~google.cloud.firestore_v1beta1.collection.Collection` and that can be +A :class:`~.firestore_v1beta1.query.Query` can be created directly from +a :class:`~.firestore_v1beta1.collection.Collection` and that can be a more common way to create a query than direct usage of the constructor. """ import copy @@ -71,7 +71,7 @@ class Query(object): would modify an instance instead return a new instance. Args: - parent (~google.cloud.firestore_v1beta1.collection.Collection): The collection + parent (~.firestore_v1beta1.collection.Collection): The collection that this query applies to. projection (Optional[google.cloud.proto.firestore.v1beta1.\ query_pb2.StructuredQuery.Projection]): A projection of document @@ -157,7 +157,7 @@ def _client(self): """The client of the parent collection. Returns: - ~google.cloud.firestore_v1beta1.client.Client: The client that owns + ~.firestore_v1beta1.client.Client: The client that owns this query. """ return self._parent._client @@ -165,11 +165,11 @@ def _client(self): def select(self, field_paths): """Project documents matching query to a limited set of fields. - See :meth:`~google.cloud.firestore_v1beta1.client.Client.field_path` for + See :meth:`~.firestore_v1beta1.client.Client.field_path` for more information on **field paths**. If the current query already has a projection set (i.e. has already - called :meth:`~google.cloud.firestore_v1beta1.query.Query.select`), this + called :meth:`~.firestore_v1beta1.query.Query.select`), this will overwrite it. Args: @@ -178,7 +178,7 @@ def select(self, field_paths): of document fields in the query results. Returns: - ~google.cloud.firestore_v1beta1.query.Query: A "projected" query. Acts as + ~.firestore_v1beta1.query.Query: A "projected" query. Acts as a copy of the current query, modified with the newly added projection. Raises: @@ -208,10 +208,10 @@ def select(self, field_paths): def where(self, field_path, op_string, value): """Filter the query on a field. - See :meth:`~google.cloud.firestore_v1beta1.client.Client.field_path` for + See :meth:`~.firestore_v1beta1.client.Client.field_path` for more information on **field paths**. - Returns a new :class:`~google.cloud.firestore_v1beta1.query.Query` that + Returns a new :class:`~.firestore_v1beta1.query.Query` that filters on a specific field path, according to an operation (e.g. ``==`` or "equals") and a particular value to be paired with that operation. @@ -227,7 +227,7 @@ def where(self, field_path, op_string, value): allowed operation. Returns: - ~google.cloud.firestore_v1beta1.query.Query: A filtered query. Acts as a + ~.firestore_v1beta1.query.Query: A filtered query. Acts as a copy of the current query, modified with the newly added filter. Raises: @@ -283,10 +283,10 @@ def _make_order(field_path, direction): def order_by(self, field_path, direction=ASCENDING): """Modify the query to add an order clause on a specific field. - See :meth:`~google.cloud.firestore_v1beta1.client.Client.field_path` for + See :meth:`~.firestore_v1beta1.client.Client.field_path` for more information on **field paths**. - Successive :meth:`~google.cloud.firestore_v1beta1.query.Query.order_by` calls + Successive :meth:`~.firestore_v1beta1.query.Query.order_by` calls will further refine the ordering of results returned by the query (i.e. the new "order by" fields will be added to existing ones). @@ -298,7 +298,7 @@ def order_by(self, field_path, direction=ASCENDING): :attr:`ASCENDING`. Returns: - ~google.cloud.firestore_v1beta1.query.Query: An ordered query. Acts as a + ~.firestore_v1beta1.query.Query: An ordered query. Acts as a copy of the current query, modified with the newly added "order by" constraint. @@ -333,7 +333,7 @@ def limit(self, count): the query. Returns: - ~google.cloud.firestore_v1beta1.query.Query: A limited query. Acts as a + ~.firestore_v1beta1.query.Query: A limited query. Acts as a copy of the current query, modified with the newly added "limit" filter. """ @@ -359,7 +359,7 @@ def offset(self, num_to_skip): of query results. (Must be non-negative.) Returns: - ~google.cloud.firestore_v1beta1.query.Query: An offset query. Acts as a + ~.firestore_v1beta1.query.Query: An offset query. Acts as a copy of the current query, modified with the newly added "offset" field. """ @@ -381,10 +381,10 @@ def _cursor_helper(self, document_fields, before, start): When the query is sent to the server, the ``document_fields`` will be used in the order given by fields set by - :meth:`~google.cloud.firestore_v1beta1.query.Query.order_by`. + :meth:`~.firestore_v1beta1.query.Query.order_by`. Args: - document_fields (Union[~google.cloud.firestore_v1beta1.\ + document_fields (Union[~.firestore_v1beta1.\ document.DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that @@ -396,7 +396,7 @@ def _cursor_helper(self, document_fields, before, start): cursor (:data:`True`) or an ``end_at`` cursor (:data:`False`). Returns: - ~google.cloud.firestore_v1beta1.query.Query: A query with cursor. Acts as + ~.firestore_v1beta1.query.Query: A query with cursor. Acts as a copy of the current query, modified with the newly added "start at" cursor. """ @@ -436,22 +436,22 @@ def start_at(self, document_fields): If the current query already has specified a start cursor -- either via this method or - :meth:`~google.cloud.firestore_v1beta1.query.Query.start_after` -- this will + :meth:`~.firestore_v1beta1.query.Query.start_after` -- this will overwrite it. When the query is sent to the server, the ``document_fields`` will be used in the order given by fields set by - :meth:`~google.cloud.firestore_v1beta1.query.Query.order_by`. + :meth:`~.firestore_v1beta1.query.Query.order_by`. Args: - document_fields (Union[~google.cloud.firestore_v1beta1.\ + document_fields (Union[~.firestore_v1beta1.\ document.DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: - ~google.cloud.firestore_v1beta1.query.Query: A query with cursor. Acts as + ~.firestore_v1beta1.query.Query: A query with cursor. Acts as a copy of the current query, modified with the newly added "start at" cursor. """ @@ -465,22 +465,22 @@ def start_after(self, document_fields): If the current query already has specified a start cursor -- either via this method or - :meth:`~google.cloud.firestore_v1beta1.query.Query.start_at` -- this will + :meth:`~.firestore_v1beta1.query.Query.start_at` -- this will overwrite it. When the query is sent to the server, the ``document_fields`` will be used in the order given by fields set by - :meth:`~google.cloud.firestore_v1beta1.query.Query.order_by`. + :meth:`~.firestore_v1beta1.query.Query.order_by`. Args: - document_fields (Union[~google.cloud.firestore_v1beta1.\ + document_fields (Union[~.firestore_v1beta1.\ document.DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: - ~google.cloud.firestore_v1beta1.query.Query: A query with cursor. Acts as + ~.firestore_v1beta1.query.Query: A query with cursor. Acts as a copy of the current query, modified with the newly added "start after" cursor. """ @@ -494,22 +494,22 @@ def end_before(self, document_fields): If the current query already has specified an end cursor -- either via this method or - :meth:`~google.cloud.firestore_v1beta1.query.Query.end_at` -- this will + :meth:`~.firestore_v1beta1.query.Query.end_at` -- this will overwrite it. When the query is sent to the server, the ``document_fields`` will be used in the order given by fields set by - :meth:`~google.cloud.firestore_v1beta1.query.Query.order_by`. + :meth:`~.firestore_v1beta1.query.Query.order_by`. Args: - document_fields (Union[~google.cloud.firestore_v1beta1.\ + document_fields (Union[~.firestore_v1beta1.\ document.DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: - ~google.cloud.firestore_v1beta1.query.Query: A query with cursor. Acts as + ~.firestore_v1beta1.query.Query: A query with cursor. Acts as a copy of the current query, modified with the newly added "end before" cursor. """ @@ -523,22 +523,22 @@ def end_at(self, document_fields): If the current query already has specified an end cursor -- either via this method or - :meth:`~google.cloud.firestore_v1beta1.query.Query.end_before` -- this will + :meth:`~.firestore_v1beta1.query.Query.end_before` -- this will overwrite it. When the query is sent to the server, the ``document_fields`` will be used in the order given by fields set by - :meth:`~google.cloud.firestore_v1beta1.query.Query.order_by`. + :meth:`~.firestore_v1beta1.query.Query.order_by`. Args: - document_fields (Union[~google.cloud.firestore_v1beta1.\ + document_fields (Union[~.firestore_v1beta1.\ document.DocumentSnapshot, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: - ~google.cloud.firestore_v1beta1.query.Query: A query with cursor. Acts as + ~.firestore_v1beta1.query.Query: A query with cursor. Acts as a copy of the current query, modified with the newly added "end at" cursor. """ @@ -722,12 +722,12 @@ def stream(self, transaction=None): allowed). Args: - transaction (Optional[~google.cloud.firestore_v1beta1.transaction.\ + transaction (Optional[~.firestore_v1beta1.transaction.\ Transaction]): An existing transaction that this query will run in. Yields: - ~google.cloud.firestore_v1beta1.document.DocumentSnapshot: The next + ~.firestore_v1beta1.document.DocumentSnapshot: The next document that fulfills the query. """ parent_path, expected_prefix = self._parent._parent_info() @@ -752,7 +752,7 @@ def on_snapshot(self, callback): provided callback is run on the snapshot of the documents. Args: - callback(~google.cloud.firestore.query.QuerySnapshot): a callback to run when + callback(~.firestore.query.QuerySnapshot): a callback to run when a change occurs. Example: @@ -870,8 +870,8 @@ def _enum_from_direction(direction): Args: direction (str): A direction to order by. Must be one of - :attr:`~google.cloud.firestore.Query.ASCENDING` or - :attr:`~google.cloud.firestore.Query.DESCENDING`. + :attr:`~.firestore.Query.ASCENDING` or + :attr:`~.firestore.Query.DESCENDING`. Returns: int: The enum corresponding to ``direction``. @@ -942,14 +942,14 @@ def _query_response_to_snapshot(response_pb, collection, expected_prefix): Args: response_pb (google.cloud.proto.firestore.v1beta1.\ firestore_pb2.RunQueryResponse): A - collection (~google.cloud.firestore_v1beta1.collection.CollectionReference): A + collection (~.firestore_v1beta1.collection.CollectionReference): A reference to the collection that initiated the query. expected_prefix (str): The expected prefix for fully-qualified document names returned in the query results. This can be computed directly from ``collection`` via :meth:`_parent_info`. Returns: - Optional[~google.cloud.firestore.document.DocumentSnapshot]: A + Optional[~.firestore.document.DocumentSnapshot]: A snapshot of the data returned in the query. If ``response_pb.document`` is not set, the snapshot will be :data:`None`. """ diff --git a/google/cloud/firestore_v1beta1/transaction.py b/google/cloud/firestore_v1beta1/transaction.py index e928f57ff..d7c01523b 100644 --- a/google/cloud/firestore_v1beta1/transaction.py +++ b/google/cloud/firestore_v1beta1/transaction.py @@ -46,11 +46,11 @@ class Transaction(batch.WriteBatch): """Accumulate read-and-write operations to be sent in a transaction. Args: - client (~google.cloud.firestore_v1beta1.client.Client): The client that + client (~.firestore_v1beta1.client.Client): The client that created this transaction. max_attempts (Optional[int]): The maximum number of attempts for the transaction (i.e. allowing retries). Defaults to - :attr:`~google.cloud.firestore_v1beta1.transaction.MAX_ATTEMPTS`. + :attr:`~.firestore_v1beta1.transaction.MAX_ATTEMPTS`. read_only (Optional[bool]): Flag indicating if the transaction should be read-only or should allow writes. Defaults to :data:`False`. @@ -206,10 +206,10 @@ class _Transactional(object): """Provide a callable object to use as a transactional decorater. This is surfaced via - :func:`~google.cloud.firestore_v1beta1.transaction.transactional`. + :func:`~.firestore_v1beta1.transaction.transactional`. Args: - to_wrap (Callable[~google.cloud.firestore_v1beta1.transaction.Transaction, \ + to_wrap (Callable[~.firestore_v1beta1.transaction.Transaction, \ Any]): A callable that should be run (and retried) in a transaction. """ @@ -234,7 +234,7 @@ def _pre_commit(self, transaction, *args, **kwargs): it will have staged writes). Args: - transaction (~google.cloud.firestore_v1beta1.transaction.Transaction): A + transaction (~.firestore_v1beta1.transaction.Transaction): A transaction to execute the callable within. args (Tuple[Any, ...]): The extra positional arguments to pass along to the wrapped callable. @@ -271,7 +271,7 @@ def _maybe_commit(self, transaction): not be caught. Args: - transaction (~google.cloud.firestore_v1beta1.transaction.Transaction): The + transaction (~.firestore_v1beta1.transaction.Transaction): The transaction to be ``Commit``-ed. Returns: @@ -294,7 +294,7 @@ def __call__(self, transaction, *args, **kwargs): """Execute the wrapped callable within a transaction. Args: - transaction (~google.cloud.firestore_v1beta1.transaction.Transaction): A + transaction (~.firestore_v1beta1.transaction.Transaction): A transaction to execute the callable within. args (Tuple[Any, ...]): The extra positional arguments to pass along to the wrapped callable. @@ -331,12 +331,12 @@ def transactional(to_wrap): """Decorate a callable so that it runs in a transaction. Args: - to_wrap (Callable[~google.cloud.firestore_v1beta1.transaction.Transaction, \ + to_wrap (Callable[~.firestore_v1beta1.transaction.Transaction, \ Any]): A callable that should be run (and retried) in a transaction. Returns: - Callable[~google.cloud.firestore_v1beta1.transaction.Transaction, Any]: the + Callable[~.firestore_v1beta1.transaction.Transaction, Any]: the wrapped callable. """ return _Transactional(to_wrap) @@ -352,7 +352,7 @@ def _commit_with_retry(client, write_pbs, transaction_id): our own retry to special-case the ``INVALID_ARGUMENT`` error. Args: - client (~google.cloud.firestore_v1beta1.client.Client): A client with + client (~.firestore_v1beta1.client.Client): A client with GAPIC client and configuration details. write_pbs (List[google.cloud.proto.firestore.v1beta1.\ write_pb2.Write, ...]): A ``Write`` protobuf instance to