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.