docs: Add documentation for enums (#886)

* docs: Add documentation for enums

fix: Add context manager return types

chore: Update gapic-generator-python to v1.8.1
PiperOrigin-RevId: 503210727

Source-Link: googleapis/googleapis@a391fd1

Source-Link: googleapis/googleapis-gen@0080f83
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiMDA4MGY4MzBkZWMzN2MzMzg0MTU3MDgyYmNlMjc5ZTM3MDc5ZWE1OCJ9

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
Co-authored-by: Astha Mohta <35952883+asthamohta@users.noreply.github.com>

google/cloud/spanner_admin_database_v1/services/database_admin/client.py

@@ -3064,7 +3064,7 @@ def sample_list_database_roles():
         # Done; return the response.
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> "DatabaseAdminClient":
         return self
 
     def __exit__(self, type, value, traceback):

google/cloud/spanner_admin_database_v1/types/backup.py

@@ -132,7 +132,17 @@ class Backup(proto.Message):
     """
 
     class State(proto.Enum):
-        r"""Indicates the current state of the backup."""
+        r"""Indicates the current state of the backup.
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                Not specified.
+            CREATING (1):
+                The pending backup is still being created. Operations on the
+                backup may fail with ``FAILED_PRECONDITION`` in this state.
+            READY (2):
+                The backup is complete and ready for use.
+        """
         STATE_UNSPECIFIED = 0
         CREATING = 1
         READY = 2
@@ -810,7 +820,24 @@ class CreateBackupEncryptionConfig(proto.Message):
     """
 
     class EncryptionType(proto.Enum):
-        r"""Encryption types for the backup."""
+        r"""Encryption types for the backup.
+
+        Values:
+            ENCRYPTION_TYPE_UNSPECIFIED (0):
+                Unspecified. Do not use.
+            USE_DATABASE_ENCRYPTION (1):
+                Use the same encryption configuration as the database. This
+                is the default option when
+                [encryption_config][google.spanner.admin.database.v1.CreateBackupEncryptionConfig]
+                is empty. For example, if the database is using
+                ``Customer_Managed_Encryption``, the backup will be using
+                the same Cloud KMS key as the database.
+            GOOGLE_DEFAULT_ENCRYPTION (2):
+                Use Google default encryption.
+            CUSTOMER_MANAGED_ENCRYPTION (3):
+                Use customer managed encryption. If specified,
+                ``kms_key_name`` must contain a valid Cloud KMS key.
+        """
         ENCRYPTION_TYPE_UNSPECIFIED = 0
         USE_DATABASE_ENCRYPTION = 1
         GOOGLE_DEFAULT_ENCRYPTION = 2
@@ -842,7 +869,25 @@ class CopyBackupEncryptionConfig(proto.Message):
     """
 
     class EncryptionType(proto.Enum):
-        r"""Encryption types for the backup."""
+        r"""Encryption types for the backup.
+
+        Values:
+            ENCRYPTION_TYPE_UNSPECIFIED (0):
+                Unspecified. Do not use.
+            USE_CONFIG_DEFAULT_OR_BACKUP_ENCRYPTION (1):
+                This is the default option for
+                [CopyBackup][google.spanner.admin.database.v1.DatabaseAdmin.CopyBackup]
+                when
+                [encryption_config][google.spanner.admin.database.v1.CopyBackupEncryptionConfig]
+                is not specified. For example, if the source backup is using
+                ``Customer_Managed_Encryption``, the backup will be using
+                the same Cloud KMS key as the source backup.
+            GOOGLE_DEFAULT_ENCRYPTION (2):
+                Use Google default encryption.
+            CUSTOMER_MANAGED_ENCRYPTION (3):
+                Use customer managed encryption. If specified,
+                ``kms_key_name`` must contain a valid Cloud KMS key.
+        """
         ENCRYPTION_TYPE_UNSPECIFIED = 0
         USE_CONFIG_DEFAULT_OR_BACKUP_ENCRYPTION = 1
         GOOGLE_DEFAULT_ENCRYPTION = 2

google/cloud/spanner_admin_database_v1/types/common.py

@@ -33,7 +33,17 @@
 
 
 class DatabaseDialect(proto.Enum):
-    r"""Indicates the dialect type of a database."""
+    r"""Indicates the dialect type of a database.
+
+    Values:
+        DATABASE_DIALECT_UNSPECIFIED (0):
+            Default value. This value will create a database with the
+            GOOGLE_STANDARD_SQL dialect.
+        GOOGLE_STANDARD_SQL (1):
+            Google standard SQL.
+        POSTGRESQL (2):
+            PostgreSQL supported SQL.
+    """
     DATABASE_DIALECT_UNSPECIFIED = 0
     GOOGLE_STANDARD_SQL = 1
     POSTGRESQL = 2
@@ -104,7 +114,23 @@ class EncryptionInfo(proto.Message):
     """
 
     class Type(proto.Enum):
-        r"""Possible encryption types."""
+        r"""Possible encryption types.
+
+        Values:
+            TYPE_UNSPECIFIED (0):
+                Encryption type was not specified, though
+                data at rest remains encrypted.
+            GOOGLE_DEFAULT_ENCRYPTION (1):
+                The data is encrypted at rest with a key that
+                is fully managed by Google. No key version or
+                status will be populated. This is the default
+                state.
+            CUSTOMER_MANAGED_ENCRYPTION (2):
+                The data is encrypted at rest with a key that is managed by
+                the customer. The active version of the key.
+                ``kms_key_version`` will be populated, and
+                ``encryption_status`` may be populated.
+        """
         TYPE_UNSPECIFIED = 0
         GOOGLE_DEFAULT_ENCRYPTION = 1
         CUSTOMER_MANAGED_ENCRYPTION = 2

google/cloud/spanner_admin_database_v1/types/spanner_database_admin.py

@@ -53,7 +53,15 @@
 
 
 class RestoreSourceType(proto.Enum):
-    r"""Indicates the type of the restore source."""
+    r"""Indicates the type of the restore source.
+
+    Values:
+        TYPE_UNSPECIFIED (0):
+            No restore associated.
+        BACKUP (1):
+            A backup was used as the source of the
+            restore.
+    """
     TYPE_UNSPECIFIED = 0
     BACKUP = 1
 
@@ -153,7 +161,29 @@ class Database(proto.Message):
     """
 
     class State(proto.Enum):
-        r"""Indicates the current state of the database."""
+        r"""Indicates the current state of the database.
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                Not specified.
+            CREATING (1):
+                The database is still being created. Operations on the
+                database may fail with ``FAILED_PRECONDITION`` in this
+                state.
+            READY (2):
+                The database is fully created and ready for
+                use.
+            READY_OPTIMIZING (3):
+                The database is fully created and ready for use, but is
+                still being optimized for performance and cannot handle full
+                load.
+
+                In this state, the database still references the backup it
+                was restore from, preventing the backup from being deleted.
+                When optimizations are complete, the full performance of the
+                database will be restored, and the database will transition
+                to ``READY`` state.
+        """
         STATE_UNSPECIFIED = 0
         CREATING = 1
         READY = 2
@@ -723,7 +753,21 @@ class RestoreDatabaseEncryptionConfig(proto.Message):
     """
 
     class EncryptionType(proto.Enum):
-        r"""Encryption types for the database to be restored."""
+        r"""Encryption types for the database to be restored.
+
+        Values:
+            ENCRYPTION_TYPE_UNSPECIFIED (0):
+                Unspecified. Do not use.
+            USE_CONFIG_DEFAULT_OR_BACKUP_ENCRYPTION (1):
+                This is the default option when
+                [encryption_config][google.spanner.admin.database.v1.RestoreDatabaseEncryptionConfig]
+                is not specified.
+            GOOGLE_DEFAULT_ENCRYPTION (2):
+                Use Google default encryption.
+            CUSTOMER_MANAGED_ENCRYPTION (3):
+                Use customer managed encryption. If specified,
+                ``kms_key_name`` must must contain a valid Cloud KMS key.
+        """
         ENCRYPTION_TYPE_UNSPECIFIED = 0
         USE_CONFIG_DEFAULT_OR_BACKUP_ENCRYPTION = 1
         GOOGLE_DEFAULT_ENCRYPTION = 2

google/cloud/spanner_admin_instance_v1/services/instance_admin/client.py

@@ -2480,7 +2480,7 @@ def sample_test_iam_permissions():
         # Done; return the response.
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> "InstanceAdminClient":
         return self
 
     def __exit__(self, type, value, traceback):

google/cloud/spanner_admin_instance_v1/types/spanner_instance_admin.py

@@ -72,6 +72,36 @@ class ReplicaType(proto.Enum):
         r"""Indicates the type of replica. See the `replica types
         documentation <https://cloud.google.com/spanner/docs/replication#replica_types>`__
         for more details.
+
+        Values:
+            TYPE_UNSPECIFIED (0):
+                Not specified.
+            READ_WRITE (1):
+                Read-write replicas support both reads and writes. These
+                replicas:
+
+                -  Maintain a full copy of your data.
+                -  Serve reads.
+                -  Can vote whether to commit a write.
+                -  Participate in leadership election.
+                -  Are eligible to become a leader.
+            READ_ONLY (2):
+                Read-only replicas only support reads (not writes).
+                Read-only replicas:
+
+                -  Maintain a full copy of your data.
+                -  Serve reads.
+                -  Do not participate in voting to commit writes.
+                -  Are not eligible to become a leader.
+            WITNESS (3):
+                Witness replicas don't support reads but do participate in
+                voting to commit writes. Witness replicas:
+
+                -  Do not maintain a full copy of data.
+                -  Do not serve reads.
+                -  Vote whether to commit writes.
+                -  Participate in leader election but are not eligible to
+                   become leader.
         """
         TYPE_UNSPECIFIED = 0
         READ_WRITE = 1
@@ -184,13 +214,32 @@ class InstanceConfig(proto.Message):
     """
 
     class Type(proto.Enum):
-        r"""The type of this configuration."""
+        r"""The type of this configuration.
+
+        Values:
+            TYPE_UNSPECIFIED (0):
+                Unspecified.
+            GOOGLE_MANAGED (1):
+                Google managed configuration.
+            USER_MANAGED (2):
+                User managed configuration.
+        """
         TYPE_UNSPECIFIED = 0
         GOOGLE_MANAGED = 1
         USER_MANAGED = 2
 
     class State(proto.Enum):
-        r"""Indicates the current state of the instance config."""
+        r"""Indicates the current state of the instance config.
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                Not specified.
+            CREATING (1):
+                The instance config is still being created.
+            READY (2):
+                The instance config is fully created and
+                ready to be used to create instances.
+        """
         STATE_UNSPECIFIED = 0
         CREATING = 1
         READY = 2
@@ -335,7 +384,20 @@ class Instance(proto.Message):
     """
 
     class State(proto.Enum):
-        r"""Indicates the current state of the instance."""
+        r"""Indicates the current state of the instance.
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                Not specified.
+            CREATING (1):
+                The instance is still being created.
+                Resources may not be available yet, and
+                operations such as database creation may not
+                work.
+            READY (2):
+                The instance is fully created and ready to do
+                work such as creating databases.
+        """
         STATE_UNSPECIFIED = 0
         CREATING = 1
         READY = 2

google/cloud/spanner_v1/services/spanner/client.py

@@ -2115,7 +2115,7 @@ def sample_partition_read():
         # Done; return the response.
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> "SpannerClient":
         return self
 
     def __exit__(self, type, value, traceback):

google/cloud/spanner_v1/types/query_plan.py

@@ -76,6 +76,21 @@ class Kind(proto.Enum):
         r"""The kind of [PlanNode][google.spanner.v1.PlanNode]. Distinguishes
         between the two different kinds of nodes that can appear in a query
         plan.
+
+        Values:
+            KIND_UNSPECIFIED (0):
+                Not specified.
+            RELATIONAL (1):
+                Denotes a Relational operator node in the expression tree.
+                Relational operators represent iterative processing of rows
+                during query execution. For example, a ``TableScan``
+                operation that reads rows from a table.
+            SCALAR (2):
+                Denotes a Scalar node in the expression tree.
+                Scalar nodes represent non-iterable entities in
+                the query plan. For example, constants or
+                arithmetic operators appearing inside predicate
+                expressions or references to column names.
         """
         KIND_UNSPECIFIED = 0
         RELATIONAL = 1

google/cloud/spanner_v1/types/spanner.py

@@ -343,6 +343,19 @@ class Priority(proto.Enum):
            priorities, Cloud Spanner does not guarantee to process the
            higher priority operations first. There may be other constraints
            to satisfy, such as order of operations.
+
+        Values:
+            PRIORITY_UNSPECIFIED (0):
+                ``PRIORITY_UNSPECIFIED`` is equivalent to ``PRIORITY_HIGH``.
+            PRIORITY_LOW (1):
+                This specifies that the request is low
+                priority.
+            PRIORITY_MEDIUM (2):
+                This specifies that the request is medium
+                priority.
+            PRIORITY_HIGH (3):
+                This specifies that the request is high
+                priority.
         """
         PRIORITY_UNSPECIFIED = 0
         PRIORITY_LOW = 1
@@ -464,7 +477,20 @@ class ExecuteSqlRequest(proto.Message):
     """
 
     class QueryMode(proto.Enum):
-        r"""Mode in which the statement must be processed."""
+        r"""Mode in which the statement must be processed.
+
+        Values:
+            NORMAL (0):
+                The default mode. Only the statement results
+                are returned.
+            PLAN (1):
+                This mode returns only the query plan,
+                without any results or execution statistics
+                information.
+            PROFILE (2):
+                This mode returns both the query plan and the
+                execution statistics along with the results.
+        """
         NORMAL = 0
         PLAN = 1
         PROFILE = 2

google/cloud/spanner_v1/types/transaction.py

@@ -411,6 +411,21 @@ class ReadWrite(proto.Message):
         class ReadLockMode(proto.Enum):
             r"""``ReadLockMode`` is used to set the read lock mode for read-write
             transactions.
+
+            Values:
+                READ_LOCK_MODE_UNSPECIFIED (0):
+                    Default value.
+                    If the value is not specified, the pessimistic
+                    read lock is used.
+                PESSIMISTIC (1):
+                    Pessimistic lock mode.
+                    Read locks are acquired immediately on read.
+                OPTIMISTIC (2):
+                    Optimistic lock mode.
+                    Locks for reads within the transaction are not
+                    acquired on read. Instead the locks are acquired
+                    on a commit to validate that read/queried data
+                    has not changed since the transaction started.
             """
             READ_LOCK_MODE_UNSPECIFIED = 0
             PESSIMISTIC = 1