docs: Add documentation for enums (#725)

* 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>

google/cloud/bigtable_admin_v2/services/bigtable_instance_admin/client.py

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

google/cloud/bigtable_admin_v2/services/bigtable_table_admin/client.py

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

google/cloud/bigtable_admin_v2/types/bigtable_instance_admin.py

@@ -444,7 +444,26 @@ class TableProgress(proto.Message):
         """
 
         class State(proto.Enum):
-            r""""""
+            r"""
+
+            Values:
+                STATE_UNSPECIFIED (0):
+
+                PENDING (1):
+                    The table has not yet begun copying to the
+                    new cluster.
+                COPYING (2):
+                    The table is actively being copied to the new
+                    cluster.
+                COMPLETED (3):
+                    The table has been fully copied to the new
+                    cluster.
+                CANCELLED (4):
+                    The table was deleted before it finished
+                    copying to the new cluster. Note that tables
+                    deleted after completion will stay marked as
+                    COMPLETED, not CANCELLED.
+            """
             STATE_UNSPECIFIED = 0
             PENDING = 1
             COPYING = 2

google/cloud/bigtable_admin_v2/types/common.py

@@ -30,7 +30,16 @@
 
 
 class StorageType(proto.Enum):
-    r"""Storage media types for persisting Bigtable data."""
+    r"""Storage media types for persisting Bigtable data.
+
+    Values:
+        STORAGE_TYPE_UNSPECIFIED (0):
+            The user did not specify a storage type.
+        SSD (1):
+            Flash (SSD) storage should be used.
+        HDD (2):
+            Magnetic drive (HDD) storage should be used.
+    """
     STORAGE_TYPE_UNSPECIFIED = 0
     SSD = 1
     HDD = 2

google/cloud/bigtable_admin_v2/types/instance.py

@@ -83,13 +83,41 @@ class Instance(proto.Message):
     """
 
     class State(proto.Enum):
-        r"""Possible states of an instance."""
+        r"""Possible states of an instance.
+
+        Values:
+            STATE_NOT_KNOWN (0):
+                The state of the instance could not be
+                determined.
+            READY (1):
+                The instance has been successfully created
+                and can serve requests to its tables.
+            CREATING (2):
+                The instance is currently being created, and
+                may be destroyed if the creation process
+                encounters an error.
+        """
         STATE_NOT_KNOWN = 0
         READY = 1
         CREATING = 2
 
     class Type(proto.Enum):
-        r"""The type of the instance."""
+        r"""The type of the instance.
+
+        Values:
+            TYPE_UNSPECIFIED (0):
+                The type of the instance is unspecified. If set when
+                creating an instance, a ``PRODUCTION`` instance will be
+                created. If set when updating an instance, the type will be
+                left unchanged.
+            PRODUCTION (1):
+                An instance meant for production use. ``serve_nodes`` must
+                be set on the cluster.
+            DEVELOPMENT (2):
+                DEPRECATED: Prefer PRODUCTION for all use
+                cases, as it no longer enforces a higher minimum
+                node count than DEVELOPMENT.
+        """
         TYPE_UNSPECIFIED = 0
         PRODUCTION = 1
         DEVELOPMENT = 2
@@ -221,7 +249,33 @@ class Cluster(proto.Message):
     """
 
     class State(proto.Enum):
-        r"""Possible states of a cluster."""
+        r"""Possible states of a cluster.
+
+        Values:
+            STATE_NOT_KNOWN (0):
+                The state of the cluster could not be
+                determined.
+            READY (1):
+                The cluster has been successfully created and
+                is ready to serve requests.
+            CREATING (2):
+                The cluster is currently being created, and
+                may be destroyed if the creation process
+                encounters an error. A cluster may not be able
+                to serve requests while being created.
+            RESIZING (3):
+                The cluster is currently being resized, and
+                may revert to its previous node count if the
+                process encounters an error. A cluster is still
+                capable of serving requests while being resized,
+                but may exhibit performance as if its number of
+                allocated nodes is between the starting and
+                requested states.
+            DISABLED (4):
+                The cluster has no backing nodes. The data
+                (tables) still exist, but no operations can be
+                performed on the cluster.
+        """
         STATE_NOT_KNOWN = 0
         READY = 1
         CREATING = 2

google/cloud/bigtable_admin_v2/types/table.py

@@ -39,7 +39,15 @@
 
 
 class RestoreSourceType(proto.Enum):
-    r"""Indicates the type of the restore source."""
+    r"""Indicates the type of the restore source.
+
+    Values:
+        RESTORE_SOURCE_TYPE_UNSPECIFIED (0):
+            No restore associated.
+        BACKUP (1):
+            A backup was used as the source of the
+            restore.
+    """
     RESTORE_SOURCE_TYPE_UNSPECIFIED = 0
     BACKUP = 1
 
@@ -118,12 +126,40 @@ class Table(proto.Message):
     class TimestampGranularity(proto.Enum):
         r"""Possible timestamp granularities to use when keeping multiple
         versions of data in a table.
+
+        Values:
+            TIMESTAMP_GRANULARITY_UNSPECIFIED (0):
+                The user did not specify a granularity.
+                Should not be returned. When specified during
+                table creation, MILLIS will be used.
+            MILLIS (1):
+                The table keeps data versioned at a
+                granularity of 1ms.
         """
         TIMESTAMP_GRANULARITY_UNSPECIFIED = 0
         MILLIS = 1
 
     class View(proto.Enum):
-        r"""Defines a view over a table's fields."""
+        r"""Defines a view over a table's fields.
+
+        Values:
+            VIEW_UNSPECIFIED (0):
+                Uses the default view for each method as
+                documented in its request.
+            NAME_ONLY (1):
+                Only populates ``name``.
+            SCHEMA_VIEW (2):
+                Only populates ``name`` and fields related to the table's
+                schema.
+            REPLICATION_VIEW (3):
+                Only populates ``name`` and fields related to the table's
+                replication state.
+            ENCRYPTION_VIEW (5):
+                Only populates ``name`` and fields related to the table's
+                encryption state.
+            FULL (4):
+                Populates all fields.
+        """
         VIEW_UNSPECIFIED = 0
         NAME_ONLY = 1
         SCHEMA_VIEW = 2
@@ -150,7 +186,37 @@ class ClusterState(proto.Message):
         """
 
         class ReplicationState(proto.Enum):
-            r"""Table replication states."""
+            r"""Table replication states.
+
+            Values:
+                STATE_NOT_KNOWN (0):
+                    The replication state of the table is unknown
+                    in this cluster.
+                INITIALIZING (1):
+                    The cluster was recently created, and the
+                    table must finish copying over pre-existing data
+                    from other clusters before it can begin
+                    receiving live replication updates and serving
+                    Data API requests.
+                PLANNED_MAINTENANCE (2):
+                    The table is temporarily unable to serve Data
+                    API requests from this cluster due to planned
+                    internal maintenance.
+                UNPLANNED_MAINTENANCE (3):
+                    The table is temporarily unable to serve Data
+                    API requests from this cluster due to unplanned
+                    or emergency maintenance.
+                READY (4):
+                    The table can serve Data API requests from
+                    this cluster. Depending on replication delay,
+                    reads may not immediately reflect the state of
+                    the table in other clusters.
+                READY_OPTIMIZING (5):
+                    The table is fully created and ready for use after a
+                    restore, and is being optimized for performance. When
+                    optimizations are complete, the table will transition to
+                    ``READY`` state.
+            """
             STATE_NOT_KNOWN = 0
             INITIALIZING = 1
             PLANNED_MAINTENANCE = 2
@@ -335,7 +401,26 @@ class EncryptionInfo(proto.Message):
     """
 
     class EncryptionType(proto.Enum):
-        r"""Possible encryption types for a resource."""
+        r"""Possible encryption types for a resource.
+
+        Values:
+            ENCRYPTION_TYPE_UNSPECIFIED (0):
+                Encryption type was not specified, though
+                data at rest remains encrypted.
+            GOOGLE_DEFAULT_ENCRYPTION (1):
+                The data backing this resource 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 backing this resource is encrypted at rest with a
+                key that is managed by the customer. The in-use version of
+                the key and its status are populated for CMEK-protected
+                tables. CMEK-protected backups are pinned to the key version
+                that was in use at the time the backup was taken. This key
+                version is populated but its status is not tracked and is
+                reported as ``UNKNOWN``.
+        """
         ENCRYPTION_TYPE_UNSPECIFIED = 0
         GOOGLE_DEFAULT_ENCRYPTION = 1
         CUSTOMER_MANAGED_ENCRYPTION = 2
@@ -397,7 +482,21 @@ class Snapshot(proto.Message):
     """
 
     class State(proto.Enum):
-        r"""Possible states of a snapshot."""
+        r"""Possible states of a snapshot.
+
+        Values:
+            STATE_NOT_KNOWN (0):
+                The state of the snapshot could not be
+                determined.
+            READY (1):
+                The snapshot has been successfully created
+                and can serve all requests.
+            CREATING (2):
+                The snapshot is currently being created, and
+                may be destroyed if the creation process
+                encounters an error. A snapshot may not be
+                restored to a table while it is being created.
+        """
         STATE_NOT_KNOWN = 0
         READY = 1
         CREATING = 2
@@ -481,7 +580,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

google/cloud/bigtable_v2/services/bigtable/client.py

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

google/cloud/bigtable_v2/types/bigtable.py

@@ -76,6 +76,19 @@ class RequestStatsView(proto.Enum):
         r"""The desired view into RequestStats that should be returned in
         the response.
         See also: RequestStats message.
+
+        Values:
+            REQUEST_STATS_VIEW_UNSPECIFIED (0):
+                The default / unset value. The API will
+                default to the NONE option below.
+            REQUEST_STATS_NONE (1):
+                Do not include any RequestStats in the
+                response. This will leave the RequestStats
+                embedded message unset in the response.
+            REQUEST_STATS_FULL (2):
+                Include the full set of available
+                RequestStats in the response, applicable to this
+                read.
         """
         REQUEST_STATS_VIEW_UNSPECIFIED = 0
         REQUEST_STATS_NONE = 1