docs: Add documentation for enums (#239)

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

Author: gcf-owl-bot[bot]

packages/google-cloud-functions/google/cloud/functions_v1/services/cloud_functions_service/client.py

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

packages/google-cloud-functions/google/cloud/functions_v1/types/functions.py

@@ -48,7 +48,27 @@
 
 
 class CloudFunctionStatus(proto.Enum):
-    r"""Describes the current stage of a deployment."""
+    r"""Describes the current stage of a deployment.
+
+    Values:
+        CLOUD_FUNCTION_STATUS_UNSPECIFIED (0):
+            Not specified. Invalid state.
+        ACTIVE (1):
+            Function has been successfully deployed and
+            is serving.
+        OFFLINE (2):
+            Function deployment failed and the function
+            isn’t serving.
+        DEPLOY_IN_PROGRESS (3):
+            Function is being created or updated.
+        DELETE_IN_PROGRESS (4):
+            Function is being deleted.
+        UNKNOWN (5):
+            Function deployment failed and the function
+            serving state is undefined. The function should
+            be updated or deleted to move it out of this
+            state.
+    """
     CLOUD_FUNCTION_STATUS_UNSPECIFIED = 0
     ACTIVE = 1
     OFFLINE = 2
@@ -294,6 +314,16 @@ class VpcConnectorEgressSettings(proto.Enum):
 
         This controls what traffic is diverted through the VPC Access
         Connector resource. By default PRIVATE_RANGES_ONLY will be used.
+
+        Values:
+            VPC_CONNECTOR_EGRESS_SETTINGS_UNSPECIFIED (0):
+                Unspecified.
+            PRIVATE_RANGES_ONLY (1):
+                Use the VPC Access Connector only for private
+                IP space from RFC1918.
+            ALL_TRAFFIC (2):
+                Force the use of VPC Access Connector for all
+                egress traffic from the function.
         """
         VPC_CONNECTOR_EGRESS_SETTINGS_UNSPECIFIED = 0
         PRIVATE_RANGES_ONLY = 1
@@ -305,14 +335,42 @@ class IngressSettings(proto.Enum):
         This controls what traffic can reach the function.
 
         If unspecified, ALLOW_ALL will be used.
+
+        Values:
+            INGRESS_SETTINGS_UNSPECIFIED (0):
+                Unspecified.
+            ALLOW_ALL (1):
+                Allow HTTP traffic from public and private
+                sources.
+            ALLOW_INTERNAL_ONLY (2):
+                Allow HTTP traffic from only private VPC
+                sources.
+            ALLOW_INTERNAL_AND_GCLB (3):
+                Allow HTTP traffic from private VPC sources
+                and through GCLB.
         """
         INGRESS_SETTINGS_UNSPECIFIED = 0
         ALLOW_ALL = 1
         ALLOW_INTERNAL_ONLY = 2
         ALLOW_INTERNAL_AND_GCLB = 3
 
     class DockerRegistry(proto.Enum):
-        r"""Docker Registry to use for storing function Docker images."""
+        r"""Docker Registry to use for storing function Docker images.
+
+        Values:
+            DOCKER_REGISTRY_UNSPECIFIED (0):
+                Unspecified.
+            CONTAINER_REGISTRY (1):
+                Docker images will be stored in multi-regional Container
+                Registry repositories named ``gcf``.
+            ARTIFACT_REGISTRY (2):
+                Docker images will be stored in regional Artifact Registry
+                repositories. By default, GCF will create and use
+                repositories named ``gcf-artifacts`` in every region in
+                which a function is deployed. But the repository to use can
+                also be specified by the user using the
+                ``docker_repository`` field.
+        """
         DOCKER_REGISTRY_UNSPECIFIED = 0
         CONTAINER_REGISTRY = 1
         ARTIFACT_REGISTRY = 2
@@ -525,6 +583,20 @@ class SecurityLevel(proto.Enum):
         This controls the methods to enforce security (HTTPS) on a URL.
 
         If unspecified, SECURE_OPTIONAL will be used.
+
+        Values:
+            SECURITY_LEVEL_UNSPECIFIED (0):
+                Unspecified.
+            SECURE_ALWAYS (1):
+                Requests for a URL that match this handler
+                that do not use HTTPS are automatically
+                redirected to the HTTPS URL with the same path.
+                Query parameters are reserved for the redirect.
+            SECURE_OPTIONAL (2):
+                Both HTTP and HTTPS requests with URLs that
+                match the handler succeed without redirects. The
+                application can examine the request to determine
+                which protocol was used and respond accordingly.
         """
         SECURITY_LEVEL_UNSPECIFIED = 0
         SECURE_ALWAYS = 1

packages/google-cloud-functions/google/cloud/functions_v1/types/operations.py

@@ -29,7 +29,18 @@
 
 
 class OperationType(proto.Enum):
-    r"""A type of an operation."""
+    r"""A type of an operation.
+
+    Values:
+        OPERATION_UNSPECIFIED (0):
+            Unknown operation type.
+        CREATE_FUNCTION (1):
+            Triggered by CreateFunction call
+        UPDATE_FUNCTION (2):
+            Triggered by UpdateFunction call
+        DELETE_FUNCTION (3):
+            Triggered by DeleteFunction call.
+    """
     OPERATION_UNSPECIFIED = 0
     CREATE_FUNCTION = 1
     UPDATE_FUNCTION = 2

packages/google-cloud-functions/google/cloud/functions_v2/services/function_service/client.py

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

packages/google-cloud-functions/google/cloud/functions_v2/types/functions.py

@@ -55,7 +55,16 @@
 
 
 class Environment(proto.Enum):
-    r"""The environment the function is hosted on."""
+    r"""The environment the function is hosted on.
+
+    Values:
+        ENVIRONMENT_UNSPECIFIED (0):
+            Unspecified
+        GEN_1 (1):
+            Gen 1
+        GEN_2 (2):
+            Gen 2
+    """
     ENVIRONMENT_UNSPECIFIED = 0
     GEN_1 = 1
     GEN_2 = 2
@@ -100,7 +109,27 @@ class Function(proto.Message):
     """
 
     class State(proto.Enum):
-        r"""Describes the current state of the function."""
+        r"""Describes the current state of the function.
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                Not specified. Invalid state.
+            ACTIVE (1):
+                Function has been successfully deployed and
+                is serving.
+            FAILED (2):
+                Function deployment failed and the function
+                is not serving.
+            DEPLOYING (3):
+                Function is being created or updated.
+            DELETING (4):
+                Function is being deleted.
+            UNKNOWN (5):
+                Function deployment failed and the function
+                serving state is undefined. The function should
+                be updated or deleted to move it out of this
+                state.
+        """
         STATE_UNSPECIFIED = 0
         ACTIVE = 1
         FAILED = 2
@@ -172,7 +201,18 @@ class StateMessage(proto.Message):
     """
 
     class Severity(proto.Enum):
-        r"""Severity of the state message."""
+        r"""Severity of the state message.
+
+        Values:
+            SEVERITY_UNSPECIFIED (0):
+                Not specified. Invalid severity.
+            ERROR (1):
+                ERROR-level severity.
+            WARNING (2):
+                WARNING-level severity.
+            INFO (3):
+                INFO-level severity.
+        """
         SEVERITY_UNSPECIFIED = 0
         ERROR = 1
         WARNING = 2
@@ -555,6 +595,16 @@ class VpcConnectorEgressSettings(proto.Enum):
 
         This controls what traffic is diverted through the VPC Access
         Connector resource. By default PRIVATE_RANGES_ONLY will be used.
+
+        Values:
+            VPC_CONNECTOR_EGRESS_SETTINGS_UNSPECIFIED (0):
+                Unspecified.
+            PRIVATE_RANGES_ONLY (1):
+                Use the VPC Access Connector only for private
+                IP space from RFC1918.
+            ALL_TRAFFIC (2):
+                Force the use of VPC Access Connector for all
+                egress traffic from the function.
         """
         VPC_CONNECTOR_EGRESS_SETTINGS_UNSPECIFIED = 0
         PRIVATE_RANGES_ONLY = 1
@@ -566,6 +616,19 @@ class IngressSettings(proto.Enum):
         This controls what traffic can reach the function.
 
         If unspecified, ALLOW_ALL will be used.
+
+        Values:
+            INGRESS_SETTINGS_UNSPECIFIED (0):
+                Unspecified.
+            ALLOW_ALL (1):
+                Allow HTTP traffic from public and private
+                sources.
+            ALLOW_INTERNAL_ONLY (2):
+                Allow HTTP traffic from only private VPC
+                sources.
+            ALLOW_INTERNAL_AND_GCLB (3):
+                Allow HTTP traffic from private VPC sources
+                and through GCLB.
         """
         INGRESS_SETTINGS_UNSPECIFIED = 0
         ALLOW_ALL = 1
@@ -806,6 +869,15 @@ class EventTrigger(proto.Message):
     class RetryPolicy(proto.Enum):
         r"""Describes the retry policy in case of function's execution
         failure. Retried execution is charged as any other execution.
+
+        Values:
+            RETRY_POLICY_UNSPECIFIED (0):
+                Not specified.
+            RETRY_POLICY_DO_NOT_RETRY (1):
+                Do not retry.
+            RETRY_POLICY_RETRY (2):
+                Retry on any failure, retry up to 7 days with
+                an exponential backoff (capped at 10 seconds).
         """
         RETRY_POLICY_UNSPECIFIED = 0
         RETRY_POLICY_DO_NOT_RETRY = 1
@@ -1168,7 +1240,24 @@ class ListRuntimesResponse(proto.Message):
     """
 
     class RuntimeStage(proto.Enum):
-        r"""The various stages that a runtime can be in."""
+        r"""The various stages that a runtime can be in.
+
+        Values:
+            RUNTIME_STAGE_UNSPECIFIED (0):
+                Not specified.
+            DEVELOPMENT (1):
+                The runtime is in development.
+            ALPHA (2):
+                The runtime is in the Alpha stage.
+            BETA (3):
+                The runtime is in the Beta stage.
+            GA (4):
+                The runtime is generally available.
+            DEPRECATED (5):
+                The runtime is deprecated.
+            DECOMMISSIONED (6):
+                The runtime is no longer supported.
+        """
         RUNTIME_STAGE_UNSPECIFIED = 0
         DEVELOPMENT = 1
         ALPHA = 2
@@ -1321,7 +1410,24 @@ class Stage(proto.Message):
     """
 
     class Name(proto.Enum):
-        r"""Possible names for a Stage"""
+        r"""Possible names for a Stage
+
+        Values:
+            NAME_UNSPECIFIED (0):
+                Not specified. Invalid name.
+            ARTIFACT_REGISTRY (1):
+                Artifact Regsitry Stage
+            BUILD (2):
+                Build Stage
+            SERVICE (3):
+                Service Stage
+            TRIGGER (4):
+                Trigger Stage
+            SERVICE_ROLLBACK (5):
+                Service Rollback Stage
+            TRIGGER_ROLLBACK (6):
+                Trigger Rollback Stage
+        """
         NAME_UNSPECIFIED = 0
         ARTIFACT_REGISTRY = 1
         BUILD = 2
@@ -1331,7 +1437,18 @@ class Name(proto.Enum):
         TRIGGER_ROLLBACK = 6
 
     class State(proto.Enum):
-        r"""Possible states for a Stage"""
+        r"""Possible states for a Stage
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                Not specified. Invalid state.
+            NOT_STARTED (1):
+                Stage has not started.
+            IN_PROGRESS (2):
+                Stage is in progress.
+            COMPLETE (3):
+                Stage has completed.
+        """
         STATE_UNSPECIFIED = 0
         NOT_STARTED = 1
         IN_PROGRESS = 2

packages/google-cloud-functions/samples/generated_samples/snippet_metadata_google.cloud.functions.v1.json

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

packages/google-cloud-functions/samples/generated_samples/snippet_metadata_google.cloud.functions.v2.json

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