docs: Add documentation for enums (#328)

* 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>
googleapis · Jan 20, 2023 · 248ab5b · 248ab5b
1 parent da2d299
commit 248ab5b
Show file tree

Hide file tree

Showing 15 changed files with 250 additions and 13 deletions.
diff --git a/google/cloud/tasks_v2/services/cloud_tasks/client.py b/google/cloud/tasks_v2/services/cloud_tasks/client.py
@@ -2488,7 +2488,7 @@ def sample_run_task():
         # Done; return the response.
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> "CloudTasksClient":
         return self
 
     def __exit__(self, type, value, traceback):

diff --git a/google/cloud/tasks_v2/types/queue.py b/google/cloud/tasks_v2/types/queue.py
@@ -149,7 +149,42 @@ class Queue(proto.Message):
     """
 
     class State(proto.Enum):
-        r"""State of the queue."""
+        r"""State of the queue.
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                Unspecified state.
+            RUNNING (1):
+                The queue is running. Tasks can be dispatched.
+
+                If the queue was created using Cloud Tasks and the queue has
+                had no activity (method calls or task dispatches) for 30
+                days, the queue may take a few minutes to re-activate. Some
+                method calls may return
+                [NOT_FOUND][google.rpc.Code.NOT_FOUND] and tasks may not be
+                dispatched for a few minutes until the queue has been
+                re-activated.
+            PAUSED (2):
+                Tasks are paused by the user. If the queue is
+                paused then Cloud Tasks will stop delivering
+                tasks from it, but more tasks can still be added
+                to it by the user.
+            DISABLED (3):
+                The queue is disabled.
+
+                A queue becomes ``DISABLED`` when
+                `queue.yaml <https://cloud.google.com/appengine/docs/python/config/queueref>`__
+                or
+                `queue.xml <https://cloud.google.com/appengine/docs/standard/java/config/queueref>`__
+                is uploaded which does not contain the queue. You cannot
+                directly disable a queue.
+
+                When a queue is disabled, tasks can still be added to a
+                queue but the tasks are not dispatched.
+
+                To permanently delete this queue and all of its tasks, call
+                [DeleteQueue][google.cloud.tasks.v2.CloudTasks.DeleteQueue].
+        """
         STATE_UNSPECIFIED = 0
         RUNNING = 1
         PAUSED = 2

diff --git a/google/cloud/tasks_v2/types/target.py b/google/cloud/tasks_v2/types/target.py
@@ -31,7 +31,26 @@
 
 
 class HttpMethod(proto.Enum):
-    r"""The HTTP method used to deliver the task."""
+    r"""The HTTP method used to deliver the task.
+
+    Values:
+        HTTP_METHOD_UNSPECIFIED (0):
+            HTTP method unspecified
+        POST (1):
+            HTTP POST
+        GET (2):
+            HTTP GET
+        HEAD (3):
+            HTTP HEAD
+        PUT (4):
+            HTTP PUT
+        DELETE (5):
+            HTTP DELETE
+        PATCH (6):
+            HTTP PATCH
+        OPTIONS (7):
+            HTTP OPTIONS
+    """
     HTTP_METHOD_UNSPECIFIED = 0
     POST = 1
     GET = 2

diff --git a/google/cloud/tasks_v2/types/task.py b/google/cloud/tasks_v2/types/task.py
@@ -163,6 +163,27 @@ class View(proto.Enum):
         retrieved by default because some data, such as payloads, might be
         desirable to return only when needed because of its large size or
         because of the sensitivity of data that it contains.
+
+        Values:
+            VIEW_UNSPECIFIED (0):
+                Unspecified. Defaults to BASIC.
+            BASIC (1):
+                The basic view omits fields which can be large or can
+                contain sensitive data.
+
+                This view does not include the [body in
+                AppEngineHttpRequest][google.cloud.tasks.v2.AppEngineHttpRequest.body].
+                Bodies are desirable to return only when needed, because
+                they can be large and because of the sensitivity of the data
+                that you choose to store in it.
+            FULL (2):
+                All information is returned.
+
+                Authorization for
+                [FULL][google.cloud.tasks.v2.Task.View.FULL] requires
+                ``cloudtasks.tasks.fullView`` `Google
+                IAM <https://cloud.google.com/iam/>`__ permission on the
+                [Queue][google.cloud.tasks.v2.Queue] resource.
         """
         VIEW_UNSPECIFIED = 0
         BASIC = 1

diff --git a/google/cloud/tasks_v2beta2/services/cloud_tasks/client.py b/google/cloud/tasks_v2beta2/services/cloud_tasks/client.py
@@ -3041,7 +3041,7 @@ def sample_run_task():
         # Done; return the response.
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> "CloudTasksClient":
         return self
 
     def __exit__(self, type, value, traceback):

diff --git a/google/cloud/tasks_v2beta2/types/queue.py b/google/cloud/tasks_v2beta2/types/queue.py
@@ -175,7 +175,47 @@ class Queue(proto.Message):
     """
 
     class State(proto.Enum):
-        r"""State of the queue."""
+        r"""State of the queue.
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                Unspecified state.
+            RUNNING (1):
+                The queue is running. Tasks can be dispatched.
+
+                If the queue was created using Cloud Tasks and the queue has
+                had no activity (method calls or task dispatches) for 30
+                days, the queue may take a few minutes to re-activate. Some
+                method calls may return
+                [NOT_FOUND][google.rpc.Code.NOT_FOUND] and tasks may not be
+                dispatched for a few minutes until the queue has been
+                re-activated.
+            PAUSED (2):
+                Tasks are paused by the user. If the queue is paused then
+                Cloud Tasks will stop delivering tasks from it, but more
+                tasks can still be added to it by the user. When a pull
+                queue is paused, all
+                [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks]
+                calls will return a
+                [FAILED_PRECONDITION][google.rpc.Code.FAILED_PRECONDITION].
+            DISABLED (3):
+                The queue is disabled.
+
+                A queue becomes ``DISABLED`` when
+                `queue.yaml <https://cloud.google.com/appengine/docs/python/config/queueref>`__
+                or
+                `queue.xml <https://cloud.google.com/appengine/docs/standard/java/config/queueref>`__
+                is uploaded which does not contain the queue. You cannot
+                directly disable a queue.
+
+                When a queue is disabled, tasks can still be added to a
+                queue but the tasks are not dispatched and
+                [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks]
+                calls return a ``FAILED_PRECONDITION`` error.
+
+                To permanently delete this queue and all of its tasks, call
+                [DeleteQueue][google.cloud.tasks.v2beta2.CloudTasks.DeleteQueue].
+        """
         STATE_UNSPECIFIED = 0
         RUNNING = 1
         PAUSED = 2

diff --git a/google/cloud/tasks_v2beta2/types/target.py b/google/cloud/tasks_v2beta2/types/target.py
@@ -31,7 +31,22 @@
 
 
 class HttpMethod(proto.Enum):
-    r"""The HTTP method used to execute the task."""
+    r"""The HTTP method used to execute the task.
+
+    Values:
+        HTTP_METHOD_UNSPECIFIED (0):
+            HTTP method unspecified
+        POST (1):
+            HTTP POST
+        GET (2):
+            HTTP GET
+        HEAD (3):
+            HTTP HEAD
+        PUT (4):
+            HTTP PUT
+        DELETE (5):
+            HTTP DELETE
+    """
     HTTP_METHOD_UNSPECIFIED = 0
     POST = 1
     GET = 2

diff --git a/google/cloud/tasks_v2beta2/types/task.py b/google/cloud/tasks_v2beta2/types/task.py
@@ -121,6 +121,29 @@ class View(proto.Enum):
         retrieved by default because some data, such as payloads, might be
         desirable to return only when needed because of its large size or
         because of the sensitivity of data that it contains.
+
+        Values:
+            VIEW_UNSPECIFIED (0):
+                Unspecified. Defaults to BASIC.
+            BASIC (1):
+                The basic view omits fields which can be large or can
+                contain sensitive data.
+
+                This view does not include the ([payload in
+                AppEngineHttpRequest][google.cloud.tasks.v2beta2.AppEngineHttpRequest]
+                and [payload in
+                PullMessage][google.cloud.tasks.v2beta2.PullMessage.payload]).
+                These payloads are desirable to return only when needed,
+                because they can be large and because of the sensitivity of
+                the data that you choose to store in it.
+            FULL (2):
+                All information is returned.
+
+                Authorization for
+                [FULL][google.cloud.tasks.v2beta2.Task.View.FULL] requires
+                ``cloudtasks.tasks.fullView`` `Google
+                IAM <https://cloud.google.com/iam/>`__ permission on the
+                [Queue][google.cloud.tasks.v2beta2.Queue] resource.
         """
         VIEW_UNSPECIFIED = 0
         BASIC = 1

diff --git a/google/cloud/tasks_v2beta3/services/cloud_tasks/client.py b/google/cloud/tasks_v2beta3/services/cloud_tasks/client.py
@@ -2490,7 +2490,7 @@ def sample_run_task():
         # Done; return the response.
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> "CloudTasksClient":
         return self
 
     def __exit__(self, type, value, traceback):

diff --git a/google/cloud/tasks_v2beta3/types/queue.py b/google/cloud/tasks_v2beta3/types/queue.py
@@ -190,14 +190,58 @@ class Queue(proto.Message):
     """
 
     class State(proto.Enum):
-        r"""State of the queue."""
+        r"""State of the queue.
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                Unspecified state.
+            RUNNING (1):
+                The queue is running. Tasks can be dispatched.
+
+                If the queue was created using Cloud Tasks and the queue has
+                had no activity (method calls or task dispatches) for 30
+                days, the queue may take a few minutes to re-activate. Some
+                method calls may return
+                [NOT_FOUND][google.rpc.Code.NOT_FOUND] and tasks may not be
+                dispatched for a few minutes until the queue has been
+                re-activated.
+            PAUSED (2):
+                Tasks are paused by the user. If the queue is
+                paused then Cloud Tasks will stop delivering
+                tasks from it, but more tasks can still be added
+                to it by the user.
+            DISABLED (3):
+                The queue is disabled.
+
+                A queue becomes ``DISABLED`` when
+                `queue.yaml <https://cloud.google.com/appengine/docs/python/config/queueref>`__
+                or
+                `queue.xml <https://cloud.google.com/appengine/docs/standard/java/config/queueref>`__
+                is uploaded which does not contain the queue. You cannot
+                directly disable a queue.
+
+                When a queue is disabled, tasks can still be added to a
+                queue but the tasks are not dispatched.
+
+                To permanently delete this queue and all of its tasks, call
+                [DeleteQueue][google.cloud.tasks.v2beta3.CloudTasks.DeleteQueue].
+        """
         STATE_UNSPECIFIED = 0
         RUNNING = 1
         PAUSED = 2
         DISABLED = 3
 
     class Type(proto.Enum):
-        r"""The type of the queue."""
+        r"""The type of the queue.
+
+        Values:
+            TYPE_UNSPECIFIED (0):
+                Default value.
+            PULL (1):
+                A pull queue.
+            PUSH (2):
+                A push queue.
+        """
         TYPE_UNSPECIFIED = 0
         PULL = 1
         PUSH = 2

diff --git a/google/cloud/tasks_v2beta3/types/target.py b/google/cloud/tasks_v2beta3/types/target.py
@@ -33,7 +33,26 @@
 
 
 class HttpMethod(proto.Enum):
-    r"""The HTTP method used to execute the task."""
+    r"""The HTTP method used to execute the task.
+
+    Values:
+        HTTP_METHOD_UNSPECIFIED (0):
+            HTTP method unspecified
+        POST (1):
+            HTTP POST
+        GET (2):
+            HTTP GET
+        HEAD (3):
+            HTTP HEAD
+        PUT (4):
+            HTTP PUT
+        DELETE (5):
+            HTTP DELETE
+        PATCH (6):
+            HTTP PATCH
+        OPTIONS (7):
+            HTTP OPTIONS
+    """
     HTTP_METHOD_UNSPECIFIED = 0
     POST = 1
     GET = 2

diff --git a/google/cloud/tasks_v2beta3/types/task.py b/google/cloud/tasks_v2beta3/types/task.py
@@ -177,6 +177,27 @@ class View(proto.Enum):
         retrieved by default because some data, such as payloads, might be
         desirable to return only when needed because of its large size or
         because of the sensitivity of data that it contains.
+
+        Values:
+            VIEW_UNSPECIFIED (0):
+                Unspecified. Defaults to BASIC.
+            BASIC (1):
+                The basic view omits fields which can be large or can
+                contain sensitive data.
+
+                This view does not include the [body in
+                AppEngineHttpRequest][google.cloud.tasks.v2beta3.AppEngineHttpRequest.body].
+                Bodies are desirable to return only when needed, because
+                they can be large and because of the sensitivity of the data
+                that you choose to store in it.
+            FULL (2):
+                All information is returned.
+
+                Authorization for
+                [FULL][google.cloud.tasks.v2beta3.Task.View.FULL] requires
+                ``cloudtasks.tasks.fullView`` `Google
+                IAM <https://cloud.google.com/iam/>`__ permission on the
+                [Queue][google.cloud.tasks.v2beta3.Queue] resource.
         """
         VIEW_UNSPECIFIED = 0
         BASIC = 1

diff --git a/samples/generated_samples/snippet_metadata_google.cloud.tasks.v2.json b/samples/generated_samples/snippet_metadata_google.cloud.tasks.v2.json
@@ -8,7 +8,7 @@
     ],
     "language": "PYTHON",
     "name": "google-cloud-tasks",
-    "version": "2.12.0"
+    "version": "0.1.0"
   },
   "snippets": [
     {

diff --git a/samples/generated_samples/snippet_metadata_google.cloud.tasks.v2beta2.json b/samples/generated_samples/snippet_metadata_google.cloud.tasks.v2beta2.json
@@ -8,7 +8,7 @@
     ],
     "language": "PYTHON",
     "name": "google-cloud-tasks",
-    "version": "2.12.0"
+    "version": "0.1.0"
   },
   "snippets": [
     {

diff --git a/samples/generated_samples/snippet_metadata_google.cloud.tasks.v2beta3.json b/samples/generated_samples/snippet_metadata_google.cloud.tasks.v2beta3.json
@@ -8,7 +8,7 @@
     ],
     "language": "PYTHON",
     "name": "google-cloud-tasks",
-    "version": "2.12.0"
+    "version": "0.1.0"
   },
   "snippets": [
     {