Fix client_info bug, update docstrings. (#6412)

Author: dpebot

packages/google-cloud-firestore/google/cloud/firestore_v1beta1/gapic/enums.py

@@ -20,10 +20,10 @@
 
 class NullValue(enum.IntEnum):
     """
-    ``NullValue`` is a singleton enumeration to represent the null value for the
-    ``Value`` type union.
+    ``NullValue`` is a singleton enumeration to represent the null value for
+    the ``Value`` type union.
 
-     The JSON representation for ``NullValue`` is JSON ``null``.
+    The JSON representation for ``NullValue`` is JSON ``null``.
 
     Attributes:
       NULL_VALUE (int): Null value.
@@ -125,8 +125,8 @@ class TargetChangeType(enum.IntEnum):
           This will be sent after or with a ``read_time`` that is greater than or
           equal to the time at which the targets were added.
 
-          Listeners can wait for this change if read-after-write semantics
-          are desired.
+          Listeners can wait for this change if read-after-write semantics are
+          desired.
           RESET (int): The targets have been reset, and a new initial state for the targets
           will be returned in subsequent changes.
 

packages/google-cloud-firestore/google/cloud/firestore_v1beta1/gapic/firestore_client.py

@@ -51,26 +51,19 @@ class FirestoreClient(object):
 
     This service exposes several types of comparable timestamps:
 
-    *    ``create_time`` - The time at which a document was created. Changes only
-    ::
-
-         when a document is deleted, then re-created. Increases in a strict
-          monotonic fashion.
-    *    ``update_time`` - The time at which a document was last updated. Changes
-    ::
-
-         every time a document is modified. Does not change when a write results
-         in no modifications. Increases in a strict monotonic fashion.
-    *    ``read_time`` - The time at which a particular state was observed. Used
-    ::
-
-         to denote a consistent snapshot of the database or the time at which a
-         Document was observed to not exist.
-    *    ``commit_time`` - The time at which the writes in a transaction were
-    ::
-
-         committed. Any read with an equal or greater `read_time` is guaranteed
-         to see the effects of the transaction.
+    -  ``create_time`` - The time at which a document was created. Changes
+       only when a document is deleted, then re-created. Increases in a
+       strict monotonic fashion.
+    -  ``update_time`` - The time at which a document was last updated.
+       Changes every time a document is modified. Does not change when a
+       write results in no modifications. Increases in a strict monotonic
+       fashion.
+    -  ``read_time`` - The time at which a particular state was observed.
+       Used to denote a consistent snapshot of the database or the time at
+       which a Document was observed to not exist.
+    -  ``commit_time`` - The time at which the writes in a transaction were
+       committed. Any read with an equal or greater ``read_time`` is
+       guaranteed to see the effects of the transaction.
     """
 
     SERVICE_ADDRESS = 'firestore.googleapis.com:443'
@@ -209,9 +202,10 @@ def __init__(self,
             )
 
         if client_info is None:
-            client_info = (
-                google.api_core.gapic_v1.client_info.DEFAULT_CLIENT_INFO)
-        client_info.gapic_version = _GAPIC_LIBRARY_VERSION
+            client_info = google.api_core.gapic_v1.client_info.ClientInfo(
+                gapic_version=_GAPIC_LIBRARY_VERSION, )
+        else:
+            client_info.gapic_version = _GAPIC_LIBRARY_VERSION
         self._client_info = client_info
 
         # Parse out the default settings for retry and timeout for each RPC
@@ -255,11 +249,13 @@ def get_document(self,
 
                 If the document has a field that is not present in this mask, that field
                 will not be returned in the response.
+
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_v1beta1.types.DocumentMask`
             transaction (bytes): Reads the document in a transaction.
             read_time (Union[dict, ~google.cloud.firestore_v1beta1.types.Timestamp]): Reads the version of the document at the given time.
                 This may not be older than 60 seconds.
+
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_v1beta1.types.Timestamp`
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
@@ -330,7 +326,7 @@ def list_documents(self,
             >>>
             >>> parent = client.any_path_path('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]')
             >>>
-            >>> # TODO: Initialize ``collection_id``:
+            >>> # TODO: Initialize `collection_id`:
             >>> collection_id = ''
             >>>
             >>> # Iterate over all results
@@ -342,7 +338,7 @@ def list_documents(self,
             >>> # Alternatively:
             >>>
             >>> # Iterate over results one page at a time
-            >>> for page in client.list_documents(parent, collection_id, options=CallOptions(page_token=INITIAL_PAGE)):
+            >>> for page in client.list_documents(parent, collection_id).pages:
             ...     for element in page:
             ...         # process element
             ...         pass
@@ -351,11 +347,10 @@ def list_documents(self,
             parent (str): The parent resource name. In the format:
                 ``projects/{project_id}/databases/{database_id}/documents`` or
                 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
-                For example:
-                ``projects/my-project/databases/my-database/documents`` or
+                For example: ``projects/my-project/databases/my-database/documents`` or
                 ``projects/my-project/databases/my-database/documents/chatrooms/my-chatroom``
-            collection_id (str): The collection ID, relative to ``parent``, to list. For example: ``chatrooms``
-                or ``messages``.
+            collection_id (str): The collection ID, relative to ``parent``, to list. For example:
+                ``chatrooms`` or ``messages``.
             page_size (int): The maximum number of resources contained in the
                 underlying API response. If page streaming is performed per-
                 resource, this parameter does not affect the return value. If page
@@ -366,17 +361,19 @@ def list_documents(self,
 
                 If a document has a field that is not present in this mask, that field
                 will not be returned in the response.
+
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_v1beta1.types.DocumentMask`
             transaction (bytes): Reads documents in a transaction.
             read_time (Union[dict, ~google.cloud.firestore_v1beta1.types.Timestamp]): Reads documents as they were at the given time.
                 This may not be older than 60 seconds.
+
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_v1beta1.types.Timestamp`
             show_missing (bool): If the list should show missing documents. A missing document is a
                 document that does not exist but has sub-documents. These documents will
-                be returned with a key but will not have fields, ``Document.create_time``,
-                or ``Document.update_time`` set.
+                be returned with a key but will not have fields,
+                ``Document.create_time``, or ``Document.update_time`` set.
 
                 Requests with ``show_missing`` may not specify ``where`` or
                 ``order_by``.
@@ -463,13 +460,13 @@ def create_document(self,
             >>>
             >>> parent = client.any_path_path('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]')
             >>>
-            >>> # TODO: Initialize ``collection_id``:
+            >>> # TODO: Initialize `collection_id`:
             >>> collection_id = ''
             >>>
-            >>> # TODO: Initialize ``document_id``:
+            >>> # TODO: Initialize `document_id`:
             >>> document_id = ''
             >>>
-            >>> # TODO: Initialize ``document``:
+            >>> # TODO: Initialize `document`:
             >>> document = {}
             >>>
             >>> response = client.create_document(parent, collection_id, document_id, document)
@@ -478,17 +475,20 @@ def create_document(self,
             parent (str): The parent resource. For example:
                 ``projects/{project_id}/databases/{database_id}/documents`` or
                 ``projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id}``
-            collection_id (str): The collection ID, relative to ``parent``, to list. For example: ``chatrooms``.
+            collection_id (str): The collection ID, relative to ``parent``, to list. For example:
+                ``chatrooms``.
             document_id (str): The client-assigned document ID to use for this document.
 
                 Optional. If not specified, an ID will be assigned by the service.
             document (Union[dict, ~google.cloud.firestore_v1beta1.types.Document]): The document to create. ``name`` must not be set.
+
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_v1beta1.types.Document`
             mask (Union[dict, ~google.cloud.firestore_v1beta1.types.DocumentMask]): The fields to return. If not set, returns all fields.
 
                 If the document has a field that is not present in this mask, that field
                 will not be returned in the response.
+
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_v1beta1.types.DocumentMask`
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
@@ -547,17 +547,18 @@ def update_document(self,
             >>>
             >>> client = firestore_v1beta1.FirestoreClient()
             >>>
-            >>> # TODO: Initialize ``document``:
+            >>> # TODO: Initialize `document`:
             >>> document = {}
             >>>
-            >>> # TODO: Initialize ``update_mask``:
+            >>> # TODO: Initialize `update_mask`:
             >>> update_mask = {}
             >>>
             >>> response = client.update_document(document, update_mask)
 
         Args:
             document (Union[dict, ~google.cloud.firestore_v1beta1.types.Document]): The updated document.
                 Creates the document if it does not already exist.
+
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_v1beta1.types.Document`
             update_mask (Union[dict, ~google.cloud.firestore_v1beta1.types.DocumentMask]): The fields to update.
@@ -567,16 +568,19 @@ def update_document(self,
                 mask, they are left unchanged.
                 Fields referenced in the mask, but not present in the input document, are
                 deleted from the document on the server.
+
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_v1beta1.types.DocumentMask`
             mask (Union[dict, ~google.cloud.firestore_v1beta1.types.DocumentMask]): The fields to return. If not set, returns all fields.
 
                 If the document has a field that is not present in this mask, that field
                 will not be returned in the response.
+
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_v1beta1.types.DocumentMask`
             current_document (Union[dict, ~google.cloud.firestore_v1beta1.types.Precondition]): An optional precondition on the document.
                 The request will fail if this is set and not met by the target document.
+
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_v1beta1.types.Precondition`
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
@@ -641,6 +645,7 @@ def delete_document(self,
                 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
             current_document (Union[dict, ~google.cloud.firestore_v1beta1.types.Precondition]): An optional precondition on the document.
                 The request will fail if this is set and not met by the target document.
+
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_v1beta1.types.Precondition`
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
@@ -700,7 +705,7 @@ def batch_get_documents(self,
             >>>
             >>> database = client.database_root_path('[PROJECT]', '[DATABASE]')
             >>>
-            >>> # TODO: Initialize ``documents``:
+            >>> # TODO: Initialize `documents`:
             >>> documents = []
             >>>
             >>> for element in client.batch_get_documents(database, documents):
@@ -712,23 +717,26 @@ def batch_get_documents(self,
                 ``projects/{project_id}/databases/{database_id}``.
             documents (list[str]): The names of the documents to retrieve. In the format:
                 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
-                The request will fail if any of the document is not a child resource of the
-                given ``database``. Duplicate names will be elided.
+                The request will fail if any of the document is not a child resource of
+                the given ``database``. Duplicate names will be elided.
             mask (Union[dict, ~google.cloud.firestore_v1beta1.types.DocumentMask]): The fields to return. If not set, returns all fields.
 
                 If a document has a field that is not present in this mask, that field will
                 not be returned in the response.
+
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_v1beta1.types.DocumentMask`
             transaction (bytes): Reads documents in a transaction.
             new_transaction (Union[dict, ~google.cloud.firestore_v1beta1.types.TransactionOptions]): Starts a new transaction and reads the documents.
                 Defaults to a read-only transaction.
                 The new transaction ID will be returned as the first response in the
                 stream.
+
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_v1beta1.types.TransactionOptions`
             read_time (Union[dict, ~google.cloud.firestore_v1beta1.types.Timestamp]): Reads documents as they were at the given time.
                 This may not be older than 60 seconds.
+
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_v1beta1.types.Timestamp`
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
@@ -804,6 +812,7 @@ def begin_transaction(self,
                 ``projects/{project_id}/databases/{database_id}``.
             options_ (Union[dict, ~google.cloud.firestore_v1beta1.types.TransactionOptions]): The options for the transaction.
                 Defaults to a read-write transaction.
+
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_v1beta1.types.TransactionOptions`
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
@@ -861,7 +870,7 @@ def commit(self,
             >>>
             >>> database = client.database_root_path('[PROJECT]', '[DATABASE]')
             >>>
-            >>> # TODO: Initialize ``writes``:
+            >>> # TODO: Initialize `writes`:
             >>> writes = []
             >>>
             >>> response = client.commit(database, writes)
@@ -872,6 +881,7 @@ def commit(self,
             writes (list[Union[dict, ~google.cloud.firestore_v1beta1.types.Write]]): The writes to apply.
 
                 Always executed atomically and in order.
+
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_v1beta1.types.Write`
             transaction (bytes): If set, applies all writes in this transaction, and commits it.
@@ -928,7 +938,7 @@ def rollback(self,
             >>>
             >>> database = client.database_root_path('[PROJECT]', '[DATABASE]')
             >>>
-            >>> # TODO: Initialize ``transaction``:
+            >>> # TODO: Initialize `transaction`:
             >>> transaction = b''
             >>>
             >>> client.rollback(database, transaction)
@@ -997,21 +1007,23 @@ def run_query(self,
             parent (str): The parent resource name. In the format:
                 ``projects/{project_id}/databases/{database_id}/documents`` or
                 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
-                For example:
-                ``projects/my-project/databases/my-database/documents`` or
+                For example: ``projects/my-project/databases/my-database/documents`` or
                 ``projects/my-project/databases/my-database/documents/chatrooms/my-chatroom``
             structured_query (Union[dict, ~google.cloud.firestore_v1beta1.types.StructuredQuery]): A structured query.
+
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_v1beta1.types.StructuredQuery`
             transaction (bytes): Reads documents in a transaction.
             new_transaction (Union[dict, ~google.cloud.firestore_v1beta1.types.TransactionOptions]): Starts a new transaction and reads the documents.
                 Defaults to a read-only transaction.
                 The new transaction ID will be returned as the first response in the
                 stream.
+
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_v1beta1.types.TransactionOptions`
             read_time (Union[dict, ~google.cloud.firestore_v1beta1.types.Timestamp]): Reads documents as they were at the given time.
                 This may not be older than 60 seconds.
+
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_v1beta1.types.Timestamp`
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
@@ -1207,7 +1219,7 @@ def list_collection_ids(self,
             >>> # Alternatively:
             >>>
             >>> # Iterate over results one page at a time
-            >>> for page in client.list_collection_ids(parent, options=CallOptions(page_token=INITIAL_PAGE)):
+            >>> for page in client.list_collection_ids(parent).pages:
             ...     for element in page:
             ...         # process element
             ...         pass