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>

Author: gcf-owl-bot[bot]

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