docs: Add documentation for enums (#47)

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

packages/google-cloud-gke-backup/google/cloud/gke_backup_v1/services/backup_for_gke/client.py

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

packages/google-cloud-gke-backup/google/cloud/gke_backup_v1/types/backup.py

@@ -170,7 +170,28 @@ class Backup(proto.Message):
     """
 
     class State(proto.Enum):
-        r"""State"""
+        r"""State
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                The Backup resource is in the process of
+                being created.
+            CREATING (1):
+                The Backup resource has been created and the
+                associated BackupJob Kubernetes resource has
+                been injected into the source cluster.
+            IN_PROGRESS (2):
+                The gkebackup agent in the cluster has begun
+                executing the backup operation.
+            SUCCEEDED (3):
+                The backup operation has completed
+                successfully.
+            FAILED (4):
+                The backup operation has failed.
+            DELETING (5):
+                This Backup resource (and its associated
+                artifacts) is in the process of being deleted.
+        """
         STATE_UNSPECIFIED = 0
         CREATING = 1
         IN_PROGRESS = 2

packages/google-cloud-gke-backup/google/cloud/gke_backup_v1/types/restore.py

@@ -109,7 +109,29 @@ class Restore(proto.Message):
     """
 
     class State(proto.Enum):
-        r"""Possible values for state of the Restore."""
+        r"""Possible values for state of the Restore.
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                The Restore resource is in the process of
+                being created.
+            CREATING (1):
+                The Restore resource has been created and the
+                associated RestoreJob Kubernetes resource has
+                been injected into target cluster.
+            IN_PROGRESS (2):
+                The gkebackup agent in the cluster has begun
+                executing the restore operation.
+            SUCCEEDED (3):
+                The restore operation has completed
+                successfully. Restored workloads may not yet be
+                operational.
+            FAILED (4):
+                The restore operation has failed.
+            DELETING (5):
+                This Restore resource is in the process of
+                being deleted.
+        """
         STATE_UNSPECIFIED = 0
         CREATING = 1
         IN_PROGRESS = 2
@@ -255,7 +277,31 @@ class RestoreConfig(proto.Message):
     """
 
     class VolumeDataRestorePolicy(proto.Enum):
-        r"""Defines how volume data should be restored"""
+        r"""Defines how volume data should be restored
+
+        Values:
+            VOLUME_DATA_RESTORE_POLICY_UNSPECIFIED (0):
+                Unspecified (illegal).
+            RESTORE_VOLUME_DATA_FROM_BACKUP (1):
+                For each PVC to be restored, will create a
+                new underlying volume (and PV) from the
+                corresponding VolumeBackup contained within the
+                Backup.
+            REUSE_VOLUME_HANDLE_FROM_BACKUP (2):
+                For each PVC to be restored, attempt to reuse
+                the original PV contained in the Backup (with
+                its original underlying volume).  Note that
+                option is likely only usable when restoring a
+                workload to its original cluster.
+            NO_VOLUME_DATA_RESTORATION (3):
+                For each PVC to be restored, PVCs will be
+                created without any particular action to restore
+                data.  In this case, the normal Kubernetes
+                provisioning logic would kick in, and this would
+                likely result in either dynamically provisioning
+                blank PVs or binding to statically provisioned
+                PVs.
+        """
         VOLUME_DATA_RESTORE_POLICY_UNSPECIFIED = 0
         RESTORE_VOLUME_DATA_FROM_BACKUP = 1
         REUSE_VOLUME_HANDLE_FROM_BACKUP = 2
@@ -265,6 +311,21 @@ class ClusterResourceConflictPolicy(proto.Enum):
         r"""Defines the behavior for handling the situation where
         cluster-scoped resources being restored already exist in the
         target cluster.
+
+        Values:
+            CLUSTER_RESOURCE_CONFLICT_POLICY_UNSPECIFIED (0):
+                Unspecified. Only allowed if no
+                cluster-scoped resources will be restored.
+            USE_EXISTING_VERSION (1):
+                Do not attempt to restore the conflicting
+                resource.
+            USE_BACKUP_VERSION (2):
+                Delete the existing version before
+                re-creating it from the Backup. Note that this
+                is a dangerous option which could cause
+                unintentional data loss if used inappropriately
+                - for example, deleting a CRD will cause
+                Kubernetes to delete all CRs of that type.
         """
         CLUSTER_RESOURCE_CONFLICT_POLICY_UNSPECIFIED = 0
         USE_EXISTING_VERSION = 1
@@ -274,6 +335,31 @@ class NamespacedResourceRestoreMode(proto.Enum):
         r"""Defines the behavior for handling the situation where sets of
         namespaced resources being restored already exist in the target
         cluster.
+
+        Values:
+            NAMESPACED_RESOURCE_RESTORE_MODE_UNSPECIFIED (0):
+                Unspecified (invalid).
+            DELETE_AND_RESTORE (1):
+                When conflicting top-level resources (either
+                Namespaces or ProtectedApplications, depending
+                upon the scope) are encountered, this will first
+                trigger a delete of the conflicting resource AND
+                ALL OF ITS REFERENCED RESOURCES (e.g., all
+                resources in the Namespace or all resources
+                referenced by the ProtectedApplication) before
+                restoring the resources from the Backup. This
+                mode should only be used when you are intending
+                to revert some portion of a cluster to an
+                earlier state.
+            FAIL_ON_CONFLICT (2):
+                If conflicting top-level resources (either
+                Namespaces or ProtectedApplications, depending
+                upon the scope) are encountered at the beginning
+                of a restore process, the Restore will fail.  If
+                a conflict occurs during the restore process
+                itself (e.g., because an out of band process
+                creates conflicting resources), a conflict will
+                be reported.
         """
         NAMESPACED_RESOURCE_RESTORE_MODE_UNSPECIFIED = 0
         DELETE_AND_RESTORE = 1

packages/google-cloud-gke-backup/google/cloud/gke_backup_v1/types/volume.py

@@ -93,12 +93,49 @@ class VolumeBackup(proto.Message):
     """
 
     class VolumeBackupFormat(proto.Enum):
-        r"""Identifies the format used for the volume backup."""
+        r"""Identifies the format used for the volume backup.
+
+        Values:
+            VOLUME_BACKUP_FORMAT_UNSPECIFIED (0):
+                Default value, not specified.
+            GCE_PERSISTENT_DISK (1):
+                Compute Engine Persistent Disk snapshot based
+                volume backup.
+        """
         VOLUME_BACKUP_FORMAT_UNSPECIFIED = 0
         GCE_PERSISTENT_DISK = 1
 
     class State(proto.Enum):
-        r"""The current state of a VolumeBackup"""
+        r"""The current state of a VolumeBackup
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                This is an illegal state and should not be
+                encountered.
+            CREATING (1):
+                A volume for the backup was identified and
+                backup process is about to start.
+            SNAPSHOTTING (2):
+                The volume backup operation has begun and is
+                in the initial "snapshot" phase of the process.
+                Any defined ProtectedApplication "pre" hooks
+                will be executed before entering this state and
+                "post" hooks will be executed upon leaving this
+                state.
+            UPLOADING (3):
+                The snapshot phase of the volume backup
+                operation has completed and the snapshot is now
+                being uploaded to backup storage.
+            SUCCEEDED (4):
+                The volume backup operation has completed
+                successfully.
+            FAILED (5):
+                The volume backup operation has failed.
+            DELETING (6):
+                This VolumeBackup resource (and its
+                associated artifacts) is in the process of being
+                deleted.
+        """
         STATE_UNSPECIFIED = 0
         CREATING = 1
         SNAPSHOTTING = 2
@@ -220,12 +257,37 @@ class VolumeRestore(proto.Message):
     """
 
     class VolumeType(proto.Enum):
-        r"""Supported volume types."""
+        r"""Supported volume types.
+
+        Values:
+            VOLUME_TYPE_UNSPECIFIED (0):
+                Default
+            GCE_PERSISTENT_DISK (1):
+                Compute Engine Persistent Disk volume
+        """
         VOLUME_TYPE_UNSPECIFIED = 0
         GCE_PERSISTENT_DISK = 1
 
     class State(proto.Enum):
-        r"""The current state of a VolumeRestore"""
+        r"""The current state of a VolumeRestore
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                This is an illegal state and should not be
+                encountered.
+            CREATING (1):
+                A volume for the restore was identified and
+                restore process is about to start.
+            RESTORING (2):
+                The volume is currently being restored.
+            SUCCEEDED (3):
+                The volume has been successfully restored.
+            FAILED (4):
+                The volume restoration process failed.
+            DELETING (5):
+                This VolumeRestore resource is in the process
+                of being deleted.
+        """
         STATE_UNSPECIFIED = 0
         CREATING = 1
         RESTORING = 2

packages/google-cloud-gke-backup/samples/generated_samples/snippet_metadata_google.cloud.gkebackup.v1.json

@@ -8,7 +8,7 @@
     ],
     "language": "PYTHON",
     "name": "google-cloud-gke-backup",
-    "version": "0.4.0"
+    "version": "0.1.0"
   },
   "snippets": [
     {