docs(firestore): standardize use of 'required' and 'optional' in docstrings; add py2 deprecation warning; add 3.8 unit tests (via synth) (#10068)

Author: yoshi-automation

firestore/google/cloud/firestore_admin_v1/__init__.py

@@ -16,12 +16,23 @@
 
 
 from __future__ import absolute_import
+import sys
+import warnings
 
 from google.cloud.firestore_admin_v1 import types
 from google.cloud.firestore_admin_v1.gapic import enums
 from google.cloud.firestore_admin_v1.gapic import firestore_admin_client
 
 
+if sys.version_info[:2] == (2, 7):
+    message = (
+        "A future version of this library will drop support for Python 2.7."
+        "More details about Python 2 support for Google Cloud Client Libraries"
+        "can be found at https://cloud.google.com/python/docs/python2-sunset/"
+    )
+    warnings.warn(message, DeprecationWarning)
+
+
 class FirestoreAdminClient(firestore_admin_client.FirestoreAdminClient):
     __doc__ = firestore_admin_client.FirestoreAdminClient.__doc__
     enums = enums

firestore/google/cloud/firestore_admin_v1/gapic/firestore_admin_client.py

@@ -264,9 +264,9 @@ def create_index(
             >>> response = client.create_index(parent, index)
 
         Args:
-            parent (str): A parent name of the form
+            parent (str): Required. A parent name of the form
                 ``projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}``
-            index (Union[dict, ~google.cloud.firestore_admin_v1.types.Index]): The composite index to create.
+            index (Union[dict, ~google.cloud.firestore_admin_v1.types.Index]): Required. The composite index to create.
 
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_admin_v1.types.Index`
@@ -352,7 +352,7 @@ def list_indexes(
             ...         pass
 
         Args:
-            parent (str): A parent name of the form
+            parent (str): Required. A parent name of the form
                 ``projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}``
             filter_ (str): The filter to apply to list results.
             page_size (int): The maximum number of resources contained in the
@@ -444,7 +444,7 @@ def get_index(
             >>> response = client.get_index(name)
 
         Args:
-            name (str): A name of the form
+            name (str): Required. A name of the form
                 ``projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}/indexes/{index_id}``
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
@@ -514,7 +514,7 @@ def delete_index(
             >>> client.delete_index(name)
 
         Args:
-            name (str): A name of the form
+            name (str): Required. A name of the form
                 ``projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}/indexes/{index_id}``
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
@@ -587,7 +587,7 @@ def import_documents(
             >>> response = client.import_documents(name)
 
         Args:
-            name (str): Database to import into. Should be of the form:
+            name (str): Required. Database to import into. Should be of the form:
                 ``projects/{project_id}/databases/{database_id}``.
             collection_ids (list[str]): Which collection ids to import. Unspecified means all collections included
                 in the import.
@@ -674,7 +674,7 @@ def export_documents(
             >>> response = client.export_documents(name)
 
         Args:
-            name (str): Database to export. Should be of the form:
+            name (str): Required. Database to export. Should be of the form:
                 ``projects/{project_id}/databases/{database_id}``.
             collection_ids (list[str]): Which collection ids to export. Unspecified means all collections.
             output_uri_prefix (str): The output URI. Currently only supports Google Cloud Storage URIs of the
@@ -757,7 +757,7 @@ def get_field(
             >>> response = client.get_field(name)
 
         Args:
-            name (str): A name of the form
+            name (str): Required. A name of the form
                 ``projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}/fields/{field_id}``
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
@@ -846,7 +846,7 @@ def list_fields(
             ...         pass
 
         Args:
-            parent (str): A parent name of the form
+            parent (str): Required. A parent name of the form
                 ``projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}``
             filter_ (str): The filter to apply to list results. Currently,
                 ``FirestoreAdmin.ListFields`` only supports listing fields that have
@@ -956,7 +956,7 @@ def update_field(
             >>> response = client.update_field(field)
 
         Args:
-            field (Union[dict, ~google.cloud.firestore_admin_v1.types.Field]): The field to be updated.
+            field (Union[dict, ~google.cloud.firestore_admin_v1.types.Field]): Required. The field to be updated.
 
                 If a dict is provided, it must be of the same form as the protobuf
                 message :class:`~google.cloud.firestore_admin_v1.types.Field`

firestore/google/cloud/firestore_admin_v1/proto/field.proto

@@ -17,6 +17,7 @@ syntax = "proto3";
 
 package google.firestore.admin.v1;
 
+import "google/api/resource.proto";
 import "google/firestore/admin/v1/index.proto";
 import "google/api/annotations.proto";
 
@@ -33,6 +34,11 @@ option php_namespace = "Google\\Cloud\\Firestore\\Admin\\V1";
 // Fields are grouped by their "Collection Group", which represent all
 // collections in the database with the same id.
 message Field {
+  option (google.api.resource) = {
+    type: "firestore.googleapis.com/Field"
+    pattern: "projects/{project}/databases/{database}/collectionGroups/{collection}/fields/{field}"
+  };
+
   // The index configuration for this field.
   message IndexConfig {
     // The indexes supported for this field.