celery.app.task — Celery 5.5.2 documentation (original) (raw)

This document describes the current stable version of Celery (5.5). For development docs,go here.

Task implementation: request context and the task base class.

class celery.app.task.Context(*args, **kwargs)[source]

Task request variables (Task.request).

class celery.app.task.Task[source]

Task base class.

Note

When called tasks apply the run() method. This method must be defined by all tasks (that is unless the __call__() method is overridden).

AsyncResult(task_id, **kwargs)[source]

Get AsyncResult instance for the specified task.

Parameters:

task_id (str) – Task id to get result for.

exception MaxRetriesExceededError(*args, **kwargs)

The tasks max restart limit has been exceeded.

exception OperationalError

Recoverable message transport connection error.

Request = 'celery.worker.request:Request'

Request class used, or the qualified name of one.

Strategy = 'celery.worker.strategy:default'

Execution strategy used, or the qualified name of one.

abstract = True

Deprecated attribute abstract here for compatibility.

acks_late = False

When enabled messages for this task will be acknowledged afterthe task has been executed, and not right before (the default behavior).

Please note that this means the task may be executed twice if the worker crashes mid execution.

The application default can be overridden with thetask_acks_late setting.

acks_on_failure_or_timeout = True

When enabled messages for this task will be acknowledged even if it fails or times out.

Configuring this setting only applies to tasks that are acknowledged after they have been executed and only iftask_acks_late is enabled.

The application default can be overridden with thetask_acks_on_failure_or_timeout setting.

add_to_chord(sig, lazy=False)[source]

Add signature to the chord the current task is a member of.

Added in version 4.0.

Currently only supported by the Redis result backend.

Parameters:

after_return(status, retval, task_id, args, kwargs, einfo)[source]

Handler called after the task returns.

Parameters:

Returns:

The return value of this handler is ignored.

Return type:

None

apply(args=None, kwargs=None, link=None, link_error=None, task_id=None, retries=None, throw=None, logfile=None, loglevel=None, headers=None, **options)[source]

Execute this task locally, by blocking until the task returns.

Parameters:

Returns:

pre-evaluated result.

Return type:

celery.result.EagerResult

apply_async(args=None, kwargs=None, task_id=None, producer=None, link=None, link_error=None, shadow=None, **options)[source]

Apply tasks asynchronously by sending a message.

Parameters:

Returns:

Promise of future evaluation.

Return type:

celery.result.AsyncResult

Raises:

property backend

The result store backend used for this task.

before_start(task_id, args, kwargs)[source]

Handler called before the task starts.

Added in version 5.2.

Parameters:

Returns:

The return value of this handler is ignored.

Return type:

None

chunks(it, n)[source]

Create a chunks task for this task.

default_retry_delay = 180

Default time in seconds before a retry of the task should be executed. 3 minutes by default.

delay(*args, **kwargs)[source]

Star argument version of apply_async().

Does not support the extra options enabled by apply_async().

Parameters:

Returns:

Future promise.

Return type:

celery.result.AsyncResult

expires = None

Default task expiry time.

ignore_result = False

If enabled the worker won’t store task state and return values for this task. Defaults to the task_ignore_resultsetting.

map(it)[source]

Create a xmap task from it.

max_retries = 3

Maximum number of retries before giving up. If set to None, it will never stop retrying.

name = None

Name of the task.

classmethod on_bound(app)[source]

Called when the task is bound to an app.

Note

This class method can be defined to do additional actions when the task class is bound to an app.

on_failure(exc, task_id, args, kwargs, einfo)[source]

Error handler.

This is run by the worker when the task fails.

Parameters:

Returns:

The return value of this handler is ignored.

Return type:

None

on_replace(sig)[source]

Handler called when the task is replaced.

Must return super().on_replace(sig) when overriding to ensure the task replacement is properly handled.

Added in version 5.3.

Parameters:

sig (Signature) – signature to replace with.

on_retry(exc, task_id, args, kwargs, einfo)[source]

Retry handler.

This is run by the worker when the task is to be retried.

Parameters:

Returns:

The return value of this handler is ignored.

Return type:

None

on_success(retval, task_id, args, kwargs)[source]

Success handler.

Run by the worker if the task executes successfully.

Parameters:

Returns:

The return value of this handler is ignored.

Return type:

None

priority = None

Default task priority.

rate_limit = None

None (no rate limit), ‘100/s’ (hundred tasks a second), ‘100/m’ (hundred tasks a minute),`’100/h’` (hundred tasks an hour)

Type:

Rate limit for this task type. Examples

reject_on_worker_lost = None

Even if acks_late is enabled, the worker will acknowledge tasks when the worker process executing them abruptly exits or is signaled (e.g., KILL/INT, etc).

Setting this to true allows the message to be re-queued instead, so that the task will execute again by the same worker, or another worker.

Warning: Enabling this can cause message loops; make sure you know what you’re doing.

replace(sig)[source]

Replace this task, with a new task inheriting the task id.

Execution of the host task ends immediately and no subsequent statements will be run.

Added in version 4.0.

Parameters:

Raises:

property request

Get current request object.

request_stack = <celery.utils.threads._LocalStack object>

Task request stack, the current request will be the topmost.

resultrepr_maxsize = 1024

Max length of result representation used in logs and events.

retry(args=None, kwargs=None, exc=None, throw=True, eta=None, countdown=None, max_retries=None, **options)[source]

Retry the task, adding it to the back of the queue.

Example

from imaginary_twitter_lib import Twitter from proj.celery import app

@app.task(bind=True) ... def tweet(self, auth, message): ... twitter = Twitter(oauth=auth) ... try: ... twitter.post_status_update(message) ... except twitter.FailWhale as exc: ... # Retry in 5 minutes. ... raise self.retry(countdown=60 * 5, exc=exc)

Note

Although the task will never return above as retry raises an exception to notify the worker, we use raise in front of the retry to convey that the rest of the block won’t be executed.

Parameters:

Raises:

celery.exceptions.Retry – To tell the worker that the task has been re-sent for retry. This always happens, unless the throw keyword argument has been explicitly set to False, and is considered normal operation.

run(*args, **kwargs)[source]

The body of the task executed by workers.

s(*args, **kwargs)[source]

Create signature.

Shortcut for .s(*a, **k) -> .signature(a, k).

send_event(type_, retry=True, retry_policy=None, **fields)[source]

Send monitoring event message.

This can be used to add custom event types in https://pypi.org/project/Flower/and other monitors.

Parameters:

type (str) – Type of event, e.g. "task-failed".

Keyword Arguments:

send_events = True

If enabled the worker will send monitoring events related to this task (but only if the worker is configured to send task related events). Note that this has no effect on the task-failure event case where a task is not registered (as it will have no task class to check this flag).

serializer = 'json'

The name of a serializer that are registered withkombu.serialization.registry. Default is ‘json’.

shadow_name(args, kwargs, options)[source]

Override for custom task name in worker logs/monitoring.

Example

from celery.utils.imports import qualname

def shadow_name(task, args, kwargs, options): return qualname(args[0])

@app.task(shadow_name=shadow_name, serializer='pickle') def apply_function_async(fun, *args, **kwargs): return fun(*args, **kwargs)

Parameters:

si(*args, **kwargs)[source]

Create immutable signature.

Shortcut for .si(*a, **k) -> .signature(a, k, immutable=True).

signature(args=None, *starargs, **starkwargs)[source]

Create signature.

Returns:

object for

this task, wrapping arguments and execution options for a single task invocation.

Return type:

signature

soft_time_limit = None

Soft time limit. Defaults to the task_soft_time_limit setting.

starmap(it)[source]

Create a xstarmap task from it.

store_errors_even_if_ignored = False

When enabled errors will be stored even if the task is otherwise configured to ignore results.

subtask(args=None, *starargs, **starkwargs)

Create signature.

Returns:

object for

this task, wrapping arguments and execution options for a single task invocation.

Return type:

signature

throws = ()

Tuple of expected exceptions.

These are errors that are expected in normal operation and that shouldn’t be regarded as a real error by the worker. Currently this means that the state will be updated to an error state, but the worker won’t log the event as an error.

time_limit = None

Hard time limit. Defaults to the task_time_limit setting.

track_started = False

If enabled the task will report its status as ‘started’ when the task is executed by a worker. Disabled by default as the normal behavior is to not report that level of granularity. Tasks are either pending, finished, or waiting to be retried.

Having a ‘started’ status can be useful for when there are long running tasks and there’s a need to report what task is currently running.

The application default can be overridden using thetask_track_started setting.

trail = True

If enabled the request will keep track of subtasks started by this task, and this information will be sent with the result (result.children).

typing = True

Enable argument checking. You can set this to false if you don’t want the signature to be checked when calling the task. Defaults to Celery.strict_typing.

update_state(task_id=None, state=None, meta=None, **kwargs)[source]

Update task state.

Parameters:

celery.app.task.TaskType

Here for backwards compatibility as tasks no longer use a custom meta-class.