diff --git a/docs/batch.rst b/docs/batch.rst index d130d0379..db732c549 100644 --- a/docs/batch.rst +++ b/docs/batch.rst @@ -1,6 +1,14 @@ Batches ~~~~~~~ +.. automodule:: google.cloud.firestore_v1.base_batch + :members: + :show-inheritance: + .. automodule:: google.cloud.firestore_v1.batch :members: :show-inheritance: + +.. automodule:: google.cloud.firestore_v1.async_batch + :members: + :show-inheritance: diff --git a/docs/client.rst b/docs/client.rst index c42eb4347..79811483a 100644 --- a/docs/client.rst +++ b/docs/client.rst @@ -1,6 +1,14 @@ Client ~~~~~~ +.. automodule:: google.cloud.firestore_v1.base_client + :members: + :show-inheritance: + .. automodule:: google.cloud.firestore_v1.client :members: :show-inheritance: + +.. automodule:: google.cloud.firestore_v1.async_client + :members: + :show-inheritance: diff --git a/docs/collection.rst b/docs/collection.rst index 22d4d8243..1bc227f9f 100644 --- a/docs/collection.rst +++ b/docs/collection.rst @@ -1,6 +1,14 @@ Collections ~~~~~~~~~~~ +.. automodule:: google.cloud.firestore_v1.base_collection + :members: + :show-inheritance: + .. automodule:: google.cloud.firestore_v1.collection :members: :show-inheritance: + +.. automodule:: google.cloud.firestore_v1.async_collection + :members: + :show-inheritance: diff --git a/docs/document.rst b/docs/document.rst index bc04dd444..163a9819d 100644 --- a/docs/document.rst +++ b/docs/document.rst @@ -1,6 +1,14 @@ Documents ~~~~~~~~~ +.. automodule:: google.cloud.firestore_v1.base_document + :members: + :show-inheritance: + .. automodule:: google.cloud.firestore_v1.document :members: :show-inheritance: + +.. automodule:: google.cloud.firestore_v1.async_document + :members: + :show-inheritance: diff --git a/docs/query.rst b/docs/query.rst index 8f4117671..3590112b6 100644 --- a/docs/query.rst +++ b/docs/query.rst @@ -1,6 +1,14 @@ Queries ~~~~~~~ +.. automodule:: google.cloud.firestore_v1.base_query + :members: + :show-inheritance: + .. automodule:: google.cloud.firestore_v1.query :members: :show-inheritance: + +.. automodule:: google.cloud.firestore_v1.async_query + :members: + :show-inheritance: diff --git a/docs/transaction.rst b/docs/transaction.rst index 97e670a34..ef3d77f5d 100644 --- a/docs/transaction.rst +++ b/docs/transaction.rst @@ -1,7 +1,17 @@ Transactions ~~~~~~~~~~~~ +.. automodule:: google.cloud.firestore_v1.base_transaction + :inherited-members: + :members: + :show-inheritance: + .. automodule:: google.cloud.firestore_v1.transaction :inherited-members: :members: :show-inheritance: + +.. automodule:: google.cloud.firestore_v1.async_transaction + :inherited-members: + :members: + :show-inheritance: diff --git a/google/cloud/firestore_v1/base_collection.py b/google/cloud/firestore_v1/base_collection.py index 155705702..a022e96ba 100644 --- a/google/cloud/firestore_v1/base_collection.py +++ b/google/cloud/firestore_v1/base_collection.py @@ -288,12 +288,15 @@ def limit(self, count: int) -> BaseQuery: def limit_to_last(self, count: int): """Create a limited to last query with this collection as parent. + .. note:: `limit` and `limit_to_last` are mutually exclusive. Setting `limit_to_last` will drop previously set `limit`. + See :meth:`~google.cloud.firestore_v1.query.Query.limit_to_last` for more information on this method. + Args: count (int): Maximum number of documents to return that match the query. diff --git a/google/cloud/firestore_v1/base_query.py b/google/cloud/firestore_v1/base_query.py index 6e0671907..27897ee23 100644 --- a/google/cloud/firestore_v1/base_query.py +++ b/google/cloud/firestore_v1/base_query.py @@ -370,9 +370,11 @@ def limit(self, count: int) -> "BaseQuery": """Limit a query to return at most `count` matching results. If the current query already has a `limit` set, this will override it. + .. note:: `limit` and `limit_to_last` are mutually exclusive. Setting `limit` will drop previously set `limit_to_last`. + Args: count (int): Maximum number of documents to return that match the query. @@ -398,9 +400,11 @@ def limit_to_last(self, count: int) -> "BaseQuery": """Limit a query to return the last `count` matching results. If the current query already has a `limit_to_last` set, this will override it. + .. note:: `limit` and `limit_to_last` are mutually exclusive. Setting `limit_to_last` will drop previously set `limit`. + Args: count (int): Maximum number of documents to return that match the query. diff --git a/google/cloud/firestore_v1/document.py b/google/cloud/firestore_v1/document.py index bdb5c7943..2b1c304a8 100644 --- a/google/cloud/firestore_v1/document.py +++ b/google/cloud/firestore_v1/document.py @@ -65,7 +65,14 @@ def create( retry: retries.Retry = gapic_v1.method.DEFAULT, timeout: float = None, ) -> write.WriteResult: - """Create the current document in the Firestore database. + """Create a document in the Firestore database. + + >>> document_data = {"a": 1, "b": {"c": "Two"}} + >>> document.get().to_dict() is None # does not exist + True + >>> document.create(document_data) + >>> document.get().to_dict() == document_data # exists + True Args: document_data (dict): Property names and values to use for @@ -95,23 +102,51 @@ def set( retry: retries.Retry = gapic_v1.method.DEFAULT, timeout: float = None, ) -> write.WriteResult: - """Replace the current document in the Firestore database. + """Create / replace / merge a document in the Firestore database. + + - To "upsert" a document (create if it doesn't exist, replace completely + if it does), leave the ``merge`` argument at its default: + + >>> document_data = {"a": 1, "b": {"c": "Two"}} + >>> document.get().to_dict() is None # document exists + False + >>> document.set(document_data) + >>> document.get().to_dict() == document_data # exists + True + + - To "merge" ``document_data`` with an existing document (creating if + the document does not exist), pass ``merge`` as True``: + + >>> document_data = {"a": 1, "b": {"c": "Two"}} + >>> document.get().to_dict() == {"d": "Three", "b": {}} # exists + >>> document.set(document_data, merge=True) + >>> document.get().to_dict() == {"a": 1, "d": "Three", "b": {"c": "Two"}} + True + + In this case, existing documents with top-level keys which are + not present in ``document_data`` (``"d"``) will preserve the values + of those keys. + + + - To merge only specific fields of ``document_data`` with existing + documents (creating if the document does not exist), pass ``merge`` + as a list of field paths: + - A write ``option`` can be specified to indicate preconditions of - the "set" operation. If no ``option`` is specified and this document - doesn't exist yet, this method will create it. + >>> document_data = {"a": 1, "b": {"c": "Two"}} + >>> document.get().to_dict() == {"b": {"c": "One", "d": "Four" }} # exists + True + >>> document.set(document_data, merge=["b.c"]) + >>> document.get().to_dict() == {"b": {"c": "Two", "d": "Four" }} + True - Overwrites all content for the document with the fields in - ``document_data``. This method performs almost the same functionality - as :meth:`create`. The only difference is that this method doesn't - make any requirements on the existence of the document (unless - ``option`` is used), whereas as :meth:`create` will fail if the - document already exists. + For more information on field paths, see + :meth:`~google.cloud.firestore_v1.base_client.BaseClient.field_path`. Args: document_data (dict): Property names and values to use for replacing a document. - merge (Optional[bool] or Optional[List]): + merge (Optional[bool] or Optional[List]): If True, apply merging instead of overwriting the state of the document. retry (google.api_core.retry.Retry): Designation of what errors, if any, @@ -142,9 +177,9 @@ def update( override these preconditions. 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 - illustrate this, consider a document with + **field path** (For more information on field paths, see + :meth:`~google.cloud.firestore_v1.base_client.BaseClient.field_path`.) + To illustrate this, consider a document with .. code-block:: python