Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/google/cloud/tasks_v2/types/queue.py: 100%
33 statements
« prev ^ index » next coverage.py v7.2.7, created at 2023-06-07 07:07 +0000
1# -*- coding: utf-8 -*-
2# Copyright 2022 Google LLC
3#
4# Licensed under the Apache License, Version 2.0 (the "License");
5# you may not use this file except in compliance with the License.
6# You may obtain a copy of the License at
7#
8# http://www.apache.org/licenses/LICENSE-2.0
9#
10# Unless required by applicable law or agreed to in writing, software
11# distributed under the License is distributed on an "AS IS" BASIS,
12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13# See the License for the specific language governing permissions and
14# limitations under the License.
15#
16from __future__ import annotations
18from typing import MutableMapping, MutableSequence
20from google.protobuf import duration_pb2 # type: ignore
21from google.protobuf import timestamp_pb2 # type: ignore
22import proto # type: ignore
24from google.cloud.tasks_v2.types import target
26__protobuf__ = proto.module(
27 package="google.cloud.tasks.v2",
28 manifest={
29 "Queue",
30 "RateLimits",
31 "RetryConfig",
32 "StackdriverLoggingConfig",
33 },
34)
37class Queue(proto.Message):
38 r"""A queue is a container of related tasks. Queues are
39 configured to manage how those tasks are dispatched.
40 Configurable properties include rate limits, retry options,
41 queue types, and others.
43 Attributes:
44 name (str):
45 Caller-specified and required in
46 [CreateQueue][google.cloud.tasks.v2.CloudTasks.CreateQueue],
47 after which it becomes output only.
49 The queue name.
51 The queue name must have the following format:
52 ``projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID``
54 - ``PROJECT_ID`` can contain letters ([A-Za-z]), numbers
55 ([0-9]), hyphens (-), colons (:), or periods (.). For
56 more information, see `Identifying
57 projects <https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects>`__
58 - ``LOCATION_ID`` is the canonical ID for the queue's
59 location. The list of available locations can be obtained
60 by calling
61 [ListLocations][google.cloud.location.Locations.ListLocations].
62 For more information, see
63 https://cloud.google.com/about/locations/.
64 - ``QUEUE_ID`` can contain letters ([A-Za-z]), numbers
65 ([0-9]), or hyphens (-). The maximum length is 100
66 characters.
67 app_engine_routing_override (google.cloud.tasks_v2.types.AppEngineRouting):
68 Overrides for [task-level
69 app_engine_routing][google.cloud.tasks.v2.AppEngineHttpRequest.app_engine_routing].
70 These settings apply only to [App Engine
71 tasks][google.cloud.tasks.v2.AppEngineHttpRequest] in this
72 queue. [Http tasks][google.cloud.tasks.v2.HttpRequest] are
73 not affected.
75 If set, ``app_engine_routing_override`` is used for all [App
76 Engine tasks][google.cloud.tasks.v2.AppEngineHttpRequest] in
77 the queue, no matter what the setting is for the [task-level
78 app_engine_routing][google.cloud.tasks.v2.AppEngineHttpRequest.app_engine_routing].
79 rate_limits (google.cloud.tasks_v2.types.RateLimits):
80 Rate limits for task dispatches.
82 [rate_limits][google.cloud.tasks.v2.Queue.rate_limits] and
83 [retry_config][google.cloud.tasks.v2.Queue.retry_config] are
84 related because they both control task attempts. However
85 they control task attempts in different ways:
87 - [rate_limits][google.cloud.tasks.v2.Queue.rate_limits]
88 controls the total rate of dispatches from a queue (i.e.
89 all traffic dispatched from the queue, regardless of
90 whether the dispatch is from a first attempt or a retry).
91 - [retry_config][google.cloud.tasks.v2.Queue.retry_config]
92 controls what happens to particular a task after its
93 first attempt fails. That is,
94 [retry_config][google.cloud.tasks.v2.Queue.retry_config]
95 controls task retries (the second attempt, third attempt,
96 etc).
98 The queue's actual dispatch rate is the result of:
100 - Number of tasks in the queue
101 - User-specified throttling:
102 [rate_limits][google.cloud.tasks.v2.Queue.rate_limits],
103 [retry_config][google.cloud.tasks.v2.Queue.retry_config],
104 and the [queue's
105 state][google.cloud.tasks.v2.Queue.state].
106 - System throttling due to ``429`` (Too Many Requests) or
107 ``503`` (Service Unavailable) responses from the worker,
108 high error rates, or to smooth sudden large traffic
109 spikes.
110 retry_config (google.cloud.tasks_v2.types.RetryConfig):
111 Settings that determine the retry behavior.
113 - For tasks created using Cloud Tasks: the queue-level
114 retry settings apply to all tasks in the queue that were
115 created using Cloud Tasks. Retry settings cannot be set
116 on individual tasks.
117 - For tasks created using the App Engine SDK: the
118 queue-level retry settings apply to all tasks in the
119 queue which do not have retry settings explicitly set on
120 the task and were created by the App Engine SDK. See `App
121 Engine
122 documentation <https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/retrying-tasks>`__.
123 state (google.cloud.tasks_v2.types.Queue.State):
124 Output only. The state of the queue.
126 ``state`` can only be changed by called
127 [PauseQueue][google.cloud.tasks.v2.CloudTasks.PauseQueue],
128 [ResumeQueue][google.cloud.tasks.v2.CloudTasks.ResumeQueue],
129 or uploading
130 `queue.yaml/xml <https://cloud.google.com/appengine/docs/python/config/queueref>`__.
131 [UpdateQueue][google.cloud.tasks.v2.CloudTasks.UpdateQueue]
132 cannot be used to change ``state``.
133 purge_time (google.protobuf.timestamp_pb2.Timestamp):
134 Output only. The last time this queue was purged.
136 All tasks that were
137 [created][google.cloud.tasks.v2.Task.create_time] before
138 this time were purged.
140 A queue can be purged using
141 [PurgeQueue][google.cloud.tasks.v2.CloudTasks.PurgeQueue],
142 the `App Engine Task Queue SDK, or the Cloud
143 Console <https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/deleting-tasks-and-queues#purging_all_tasks_from_a_queue>`__.
145 Purge time will be truncated to the nearest microsecond.
146 Purge time will be unset if the queue has never been purged.
147 stackdriver_logging_config (google.cloud.tasks_v2.types.StackdriverLoggingConfig):
148 Configuration options for writing logs to `Stackdriver
149 Logging <https://cloud.google.com/logging/docs/>`__. If this
150 field is unset, then no logs are written.
151 """
153 class State(proto.Enum):
154 r"""State of the queue.
156 Values:
157 STATE_UNSPECIFIED (0):
158 Unspecified state.
159 RUNNING (1):
160 The queue is running. Tasks can be dispatched.
162 If the queue was created using Cloud Tasks and the queue has
163 had no activity (method calls or task dispatches) for 30
164 days, the queue may take a few minutes to re-activate. Some
165 method calls may return
166 [NOT_FOUND][google.rpc.Code.NOT_FOUND] and tasks may not be
167 dispatched for a few minutes until the queue has been
168 re-activated.
169 PAUSED (2):
170 Tasks are paused by the user. If the queue is
171 paused then Cloud Tasks will stop delivering
172 tasks from it, but more tasks can still be added
173 to it by the user.
174 DISABLED (3):
175 The queue is disabled.
177 A queue becomes ``DISABLED`` when
178 `queue.yaml <https://cloud.google.com/appengine/docs/python/config/queueref>`__
179 or
180 `queue.xml <https://cloud.google.com/appengine/docs/standard/java/config/queueref>`__
181 is uploaded which does not contain the queue. You cannot
182 directly disable a queue.
184 When a queue is disabled, tasks can still be added to a
185 queue but the tasks are not dispatched.
187 To permanently delete this queue and all of its tasks, call
188 [DeleteQueue][google.cloud.tasks.v2.CloudTasks.DeleteQueue].
189 """
190 STATE_UNSPECIFIED = 0
191 RUNNING = 1
192 PAUSED = 2
193 DISABLED = 3
195 name: str = proto.Field(
196 proto.STRING,
197 number=1,
198 )
199 app_engine_routing_override: target.AppEngineRouting = proto.Field(
200 proto.MESSAGE,
201 number=2,
202 message=target.AppEngineRouting,
203 )
204 rate_limits: "RateLimits" = proto.Field(
205 proto.MESSAGE,
206 number=3,
207 message="RateLimits",
208 )
209 retry_config: "RetryConfig" = proto.Field(
210 proto.MESSAGE,
211 number=4,
212 message="RetryConfig",
213 )
214 state: State = proto.Field(
215 proto.ENUM,
216 number=5,
217 enum=State,
218 )
219 purge_time: timestamp_pb2.Timestamp = proto.Field(
220 proto.MESSAGE,
221 number=6,
222 message=timestamp_pb2.Timestamp,
223 )
224 stackdriver_logging_config: "StackdriverLoggingConfig" = proto.Field(
225 proto.MESSAGE,
226 number=9,
227 message="StackdriverLoggingConfig",
228 )
231class RateLimits(proto.Message):
232 r"""Rate limits.
234 This message determines the maximum rate that tasks can be
235 dispatched by a queue, regardless of whether the dispatch is a first
236 task attempt or a retry.
238 Note: The debugging command,
239 [RunTask][google.cloud.tasks.v2.CloudTasks.RunTask], will run a task
240 even if the queue has reached its
241 [RateLimits][google.cloud.tasks.v2.RateLimits].
243 Attributes:
244 max_dispatches_per_second (float):
245 The maximum rate at which tasks are dispatched from this
246 queue.
248 If unspecified when the queue is created, Cloud Tasks will
249 pick the default.
251 - The maximum allowed value is 500.
253 This field has the same meaning as `rate in
254 queue.yaml/xml <https://cloud.google.com/appengine/docs/standard/python/config/queueref#rate>`__.
255 max_burst_size (int):
256 Output only. The max burst size.
258 Max burst size limits how fast tasks in queue are processed
259 when many tasks are in the queue and the rate is high. This
260 field allows the queue to have a high rate so processing
261 starts shortly after a task is enqueued, but still limits
262 resource usage when many tasks are enqueued in a short
263 period of time.
265 The `token
266 bucket <https://wikipedia.org/wiki/Token_Bucket>`__
267 algorithm is used to control the rate of task dispatches.
268 Each queue has a token bucket that holds tokens, up to the
269 maximum specified by ``max_burst_size``. Each time a task is
270 dispatched, a token is removed from the bucket. Tasks will
271 be dispatched until the queue's bucket runs out of tokens.
272 The bucket will be continuously refilled with new tokens
273 based on
274 [max_dispatches_per_second][google.cloud.tasks.v2.RateLimits.max_dispatches_per_second].
276 Cloud Tasks will pick the value of ``max_burst_size`` based
277 on the value of
278 [max_dispatches_per_second][google.cloud.tasks.v2.RateLimits.max_dispatches_per_second].
280 For queues that were created or updated using
281 ``queue.yaml/xml``, ``max_burst_size`` is equal to
282 `bucket_size <https://cloud.google.com/appengine/docs/standard/python/config/queueref#bucket_size>`__.
283 Since ``max_burst_size`` is output only, if
284 [UpdateQueue][google.cloud.tasks.v2.CloudTasks.UpdateQueue]
285 is called on a queue created by ``queue.yaml/xml``,
286 ``max_burst_size`` will be reset based on the value of
287 [max_dispatches_per_second][google.cloud.tasks.v2.RateLimits.max_dispatches_per_second],
288 regardless of whether
289 [max_dispatches_per_second][google.cloud.tasks.v2.RateLimits.max_dispatches_per_second]
290 is updated.
291 max_concurrent_dispatches (int):
292 The maximum number of concurrent tasks that Cloud Tasks
293 allows to be dispatched for this queue. After this threshold
294 has been reached, Cloud Tasks stops dispatching tasks until
295 the number of concurrent requests decreases.
297 If unspecified when the queue is created, Cloud Tasks will
298 pick the default.
300 The maximum allowed value is 5,000.
302 This field has the same meaning as `max_concurrent_requests
303 in
304 queue.yaml/xml <https://cloud.google.com/appengine/docs/standard/python/config/queueref#max_concurrent_requests>`__.
305 """
307 max_dispatches_per_second: float = proto.Field(
308 proto.DOUBLE,
309 number=1,
310 )
311 max_burst_size: int = proto.Field(
312 proto.INT32,
313 number=2,
314 )
315 max_concurrent_dispatches: int = proto.Field(
316 proto.INT32,
317 number=3,
318 )
321class RetryConfig(proto.Message):
322 r"""Retry config.
323 These settings determine when a failed task attempt is retried.
325 Attributes:
326 max_attempts (int):
327 Number of attempts per task.
329 Cloud Tasks will attempt the task ``max_attempts`` times
330 (that is, if the first attempt fails, then there will be
331 ``max_attempts - 1`` retries). Must be >= -1.
333 If unspecified when the queue is created, Cloud Tasks will
334 pick the default.
336 -1 indicates unlimited attempts.
338 This field has the same meaning as `task_retry_limit in
339 queue.yaml/xml <https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters>`__.
340 max_retry_duration (google.protobuf.duration_pb2.Duration):
341 If positive, ``max_retry_duration`` specifies the time limit
342 for retrying a failed task, measured from when the task was
343 first attempted. Once ``max_retry_duration`` time has passed
344 *and* the task has been attempted
345 [max_attempts][google.cloud.tasks.v2.RetryConfig.max_attempts]
346 times, no further attempts will be made and the task will be
347 deleted.
349 If zero, then the task age is unlimited.
351 If unspecified when the queue is created, Cloud Tasks will
352 pick the default.
354 ``max_retry_duration`` will be truncated to the nearest
355 second.
357 This field has the same meaning as `task_age_limit in
358 queue.yaml/xml <https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters>`__.
359 min_backoff (google.protobuf.duration_pb2.Duration):
360 A task will be
361 [scheduled][google.cloud.tasks.v2.Task.schedule_time] for
362 retry between
363 [min_backoff][google.cloud.tasks.v2.RetryConfig.min_backoff]
364 and
365 [max_backoff][google.cloud.tasks.v2.RetryConfig.max_backoff]
366 duration after it fails, if the queue's
367 [RetryConfig][google.cloud.tasks.v2.RetryConfig] specifies
368 that the task should be retried.
370 If unspecified when the queue is created, Cloud Tasks will
371 pick the default.
373 ``min_backoff`` will be truncated to the nearest second.
375 This field has the same meaning as `min_backoff_seconds in
376 queue.yaml/xml <https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters>`__.
377 max_backoff (google.protobuf.duration_pb2.Duration):
378 A task will be
379 [scheduled][google.cloud.tasks.v2.Task.schedule_time] for
380 retry between
381 [min_backoff][google.cloud.tasks.v2.RetryConfig.min_backoff]
382 and
383 [max_backoff][google.cloud.tasks.v2.RetryConfig.max_backoff]
384 duration after it fails, if the queue's
385 [RetryConfig][google.cloud.tasks.v2.RetryConfig] specifies
386 that the task should be retried.
388 If unspecified when the queue is created, Cloud Tasks will
389 pick the default.
391 ``max_backoff`` will be truncated to the nearest second.
393 This field has the same meaning as `max_backoff_seconds in
394 queue.yaml/xml <https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters>`__.
395 max_doublings (int):
396 The time between retries will double ``max_doublings``
397 times.
399 A task's retry interval starts at
400 [min_backoff][google.cloud.tasks.v2.RetryConfig.min_backoff],
401 then doubles ``max_doublings`` times, then increases
402 linearly, and finally retries retries at intervals of
403 [max_backoff][google.cloud.tasks.v2.RetryConfig.max_backoff]
404 up to
405 [max_attempts][google.cloud.tasks.v2.RetryConfig.max_attempts]
406 times.
408 For example, if
409 [min_backoff][google.cloud.tasks.v2.RetryConfig.min_backoff]
410 is 10s,
411 [max_backoff][google.cloud.tasks.v2.RetryConfig.max_backoff]
412 is 300s, and ``max_doublings`` is 3, then the a task will
413 first be retried in 10s. The retry interval will double
414 three times, and then increase linearly by 2^3 \* 10s.
415 Finally, the task will retry at intervals of
416 [max_backoff][google.cloud.tasks.v2.RetryConfig.max_backoff]
417 until the task has been attempted
418 [max_attempts][google.cloud.tasks.v2.RetryConfig.max_attempts]
419 times. Thus, the requests will retry at 10s, 20s, 40s, 80s,
420 160s, 240s, 300s, 300s, ....
422 If unspecified when the queue is created, Cloud Tasks will
423 pick the default.
425 This field has the same meaning as `max_doublings in
426 queue.yaml/xml <https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters>`__.
427 """
429 max_attempts: int = proto.Field(
430 proto.INT32,
431 number=1,
432 )
433 max_retry_duration: duration_pb2.Duration = proto.Field(
434 proto.MESSAGE,
435 number=2,
436 message=duration_pb2.Duration,
437 )
438 min_backoff: duration_pb2.Duration = proto.Field(
439 proto.MESSAGE,
440 number=3,
441 message=duration_pb2.Duration,
442 )
443 max_backoff: duration_pb2.Duration = proto.Field(
444 proto.MESSAGE,
445 number=4,
446 message=duration_pb2.Duration,
447 )
448 max_doublings: int = proto.Field(
449 proto.INT32,
450 number=5,
451 )
454class StackdriverLoggingConfig(proto.Message):
455 r"""Configuration options for writing logs to `Stackdriver
456 Logging <https://cloud.google.com/logging/docs/>`__.
458 Attributes:
459 sampling_ratio (float):
460 Specifies the fraction of operations to write to
461 `Stackdriver
462 Logging <https://cloud.google.com/logging/docs/>`__. This
463 field may contain any value between 0.0 and 1.0, inclusive.
464 0.0 is the default and means that no operations are logged.
465 """
467 sampling_ratio: float = proto.Field(
468 proto.DOUBLE,
469 number=1,
470 )
473__all__ = tuple(sorted(__protobuf__.manifest))