Uppgifter

New in Django 6.0.

Uppgiftsramverket tillhandahåller avtalet och infrastrukturen för bakgrundsarbete, inte motorn som kör det. API:t för uppgifter definierar hur arbete beskrivs, köas och spåras, men lämnar den faktiska körningen till extern infrastruktur.

Uppgiftsdefinition

Dekoratorn task

task(*, priority=0, queue_name='default', backend='default', takes_context=False, **kwargs)[source]

Dekoratorn @task definierar en Task-instans. Alla nyckelordsargument skickas direkt till serverdelens task_class (som har Task som standard).

Följande standardargument stöds:

• priority: Anger priority för Task. Standardvärdet är 0.

• queue_name: Anger queue_name för Task. Standardvärdet är "default".

• backend: Anger backend för Task. Standardvärdet är "default".

• takes_context: Styr om funktionen Task accepterar en TaskContext. Standardvärdet är False. Mer information finns i uppgiftskontext.

Anpassade uppgiftsserverdelar kan definiera en anpassad task_class som accepterar ytterligare argument. De kan skickas via dekoratorn @task:

@task(foo=5, bar=600)
def my_task():
    pass

Changed in Django 6.1:

Stöd för att skicka godtyckliga **kwargs till dekoratorn @task lades till.

Om den definierade Task inte är giltig enligt serverdelen utlöses InvalidTask.

Användningsexempel finns i defining tasks.

Task

class Task[source]

Representerar en Task som ska köras i bakgrunden. Uppgifter ska definieras med dekoratorn task().

Attribut för Task kan inte ändras. Mer information finns i modifying Tasks.

priority

Prioriteten för Task. Prioriteter måste vara mellan -100 och 100, där högre tal ger högre prioritet och körs tidigare.

Serverdelen måste ha supports_priority satt till True för att använda den här funktionen.

backend

Aliaset för den serverdel som Task ska köas till. Det måste matcha en serverdel som definieras i BACKEND.

queue_name

Namnet på kön som Task ska köas till. Standardvärdet är "default". Det måste matcha en kö som definieras i QUEUES, om inte QUEUES är satt till [].

run_after

Den tidigaste tidpunkt då Task körs. Det kan vara en timedelta, som används relativt den aktuella tiden, en tidszonsmedveten datetime, eller None om tiden inte är begränsad. Standardvärdet är None.

Det här attributet kan anges med using().

Serverdelen måste ha supports_defer satt till True för att använda den här funktionen. Annars utlöses InvalidTask.

name[source]

Namnet på funktionen som har dekorerats med task(). Namnet är inte nödvändigtvis unikt.

using(*, priority=None, backend=None, queue_name=None, run_after=None)[source]

Skapar en ny Task med ändrade standardvärden. Den befintliga Task lämnas oförändrad.

using gör det möjligt att ändra följande attribut:

• priority

• backend

• queue_name

• run_after

Användningsexempel finns i modifying Tasks.

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

Köar Task till serverdelen för Task för senare körning.

Argument skickas till funktionen för Task efter en rundresa genom en cykel med json.dumps()/json.loads(). Därför måste alla argument kunna JSON-serialiseras och behålla sin typ efter rundresan.

Om Task inte är giltig enligt serverdelen utlöses InvalidTask.

Användningsexempel finns i enqueueing Tasks.

aenqueue(*args, **kwargs)

Den async-variant av enqueue.

get_result(result_id)[source]

Hämtar ett resultat efter dess id.

Om resultatet inte finns utlöses TaskResultDoesNotExist. Om resultatet inte har samma typ som den aktuella uppgiften utlöses TaskResultMismatch. Om serverdelen inte har stöd för get_result() utlöses NotImplementedError.

aget_result(*args, **kwargs)

Den async-variant av get_result.

Uppgiftskontext

class TaskContext[source]

Innehåller kontext för den körande Task. Kontext skickas endast till en Task om den definierades med takes_context=True.

Attribut för TaskContext kan inte ändras.

task_result

Den TaskResult som för närvarande körs.

attempt[source]

Antalet aktuella körningsförsök för den här uppgiften, med start på 1.

Uppgiftsresultat

class TaskResultStatus[source]

En Enum som representerar statusen för en TaskResult.

READY

Task har just köats eller är redo att köras igen.

RUNNING

Task körs för närvarande.

FAILED

Task utlöste ett undantag under körningen eller kunde inte starta.

SUCCESSFUL

Task har körts färdigt utan fel.

class TaskResult[source]

TaskResult lagrar informationen om en specifik körning av en Task.

Attribut för TaskResult kan inte ändras.

task

Task som resultatet köades för.

id

En unik identifierare för resultatet som kan skickas till Task.get_result().

Formatet för id beror på den serverdel som används. Id:n för uppgiftsresultat är alltid strängar med färre än 64 tecken.

Mer information finns i uppgiftsresultat.

status

Statusen för resultatet.

enqueued_at

Tidpunkten då Task köades.

started_at

Tidpunkten då Task började köras vid sitt första försök.

last_attempted_at

Tidpunkten då den senaste körningen av Task började köras.

finished_at

Tidpunkten då Task kördes färdigt, oavsett om den misslyckades eller lyckades.

backend

Serverdelen som resultatet kommer från.

errors

En lista med instanser av TaskError för de fel som utlöstes som en del av varje körning av uppgiften.

return_value[source]

Returvärdet från funktionen Task.

Om Task inte kördes färdigt utan fel utlöses ValueError.

Användningsexempel finns i return values.

refresh()[source]

Uppdatera resultatets attribut från kölagret.

arefresh()

Den async-variant av TaskResult.refresh().

is_finished[source]

Om Task har körts färdigt, oavsett om det lyckades eller inte.

attempts[source]

Antalet gånger som uppgiften har körts.

Om uppgiften för närvarande körs räknas den inte som ett försök.

worker_ids

Id:n för de arbetare som har kört uppgiften.

Uppgiftsfel

class TaskError

Innehåller information om det fel som utlöstes under körningen av en Task.

traceback

Återspårningen (som en sträng) från undantaget som utlöstes när Task misslyckades.

exception_class

Undantagsklassen som utlöstes vid körningen av Task.

Serverdelar

Serverdelar hanterar hur uppgifter lagras och körs. Alla serverdelar delar ett gemensamt gränssnitt som definieras av BaseTaskBackend och anger kärnmetoderna för att köa uppgifter och hämta resultat.

Grundläggande serverdel

class BaseTaskBackend[source]

BaseTaskBackend är basklassen för alla uppgiftsserverdelar.

task_class

Den underklass till Task som ska användas när uppgifter skapas med dekoratorn task(). Standard är Task. Anpassade serverdelar kan åsidosätta detta för att använda en anpassad underklass av Task med ytterligare attribut.

options

En ordbok med extra parametrar för uppgiftsserverdelen. Dessa anges med inställningen OPTIONS.

enqueue(task, args, kwargs)[source]

Uppgiftsserverdelar som är underklasser till BaseTaskBackend ska åtminstone implementera denna metod.

När metoden implementeras köar enqueue() task, en Task-instans, för senare körning. args är positionsargumenten och kwargs är nyckelordsargumenten som ska skickas till task. Returnerar en TaskResult.

aenqueue(task, args, kwargs)

Varianten async av BaseTaskBackend.enqueue().

get_result(result_id)[source]

Hämta ett resultat med dess id. Om resultatet inte finns utlöses TaskResultDoesNotExist.

Om serverdelen inte stöder get_result() utlöses NotImplementedError.

aget_result(result_id)

Varianten async av BaseTaskBackend.get_result().

validate_task(task)[source]

Kontrollerar om den angivna Task kan köas med serverdelen. Om uppgiften inte är giltig utlöses InvalidTask.

Funktionsflaggor

Vissa serverdelar kanske inte stöder alla funktioner som Django tillhandahåller. Det går att identifiera vilka funktioner en serverdel stöder och eventuellt ändra beteendet därefter.

BaseTaskBackend.supports_defer

Om serverdelen stöder att köa uppgifter som ska köras efter en viss tid med attributet run_after.

BaseTaskBackend.supports_async_task

Om serverdelen stöder att köa asynkrona funktioner (korutiner).

BaseTaskBackend.supports_get_result

Om serverdelen stöder att hämta Task-resultat från en annan tråd efter att de har köats.

BaseTaskBackend.supports_priority

Om serverdelen stöder att köra uppgifter i den ordning som deras priority anger.

Tabellen nedan anger vilka av de inbyggda serverdelarna som stöder vilka funktioner:

Funktion	DummyBackend	ImmediateBackend
supports_defer	Ja	Nej
supports_async_task	Ja	Ja
supports_get_result	Nej	Nej [1]
supports_priority	Ja [2]	Ja [3]

Tillgängliga serverdelar

Django innehåller endast serverdelar för utveckling och testning. De stöder lokal körning och inspektion. För serverdelar redo för produktion, se Konfigurera en uppgiftsbackend.

Omedelbar serverdel

class ImmediateBackend[source]

Den omedelbara serverdelen kör uppgifter omedelbart i stället för i bakgrunden.

Dummy backend

class DummyBackend[source]

Den fiktiva serverdelen kör inte köade uppgifter. I stället lagrar den uppgiftsresultat för senare inspektion.

results

En lista med resultat för de kölagda Tasks, i den ordning de kölades.

clear()[source]

Rensar listan över lagrade resultat.

Undantag

exception InvalidTask[source]

Utlöses när den Task som försöker köas är ogiltig.

exception InvalidTaskBackend[source]

Utlöses när den begärda BaseTaskBackend är ogiltig.

exception TaskResultDoesNotExist[source]

Utlöses av get_result() när angivet result_id inte finns.

exception TaskResultMismatch[source]

Utlöses av get_result() när angivet result_id tillhör en annan Task än den aktuella Task.

Fotnoter

[1]

ImmediateBackend stöder inte officiellt get_result(), trots att API:et implementeras, eftersom resultatet inte kan hämtas från en annan tråd.

[2]

DummyBackend har supports_priority=True så att den kan användas som en direkt ersättning i tester. Eftersom denna backend aldrig kör Tasks har värdet priority ingen effekt.

[3]

ImmediateBackend har supports_priority=True så att den kan användas som en direkt ersättning i tester. Eftersom Tasks körs så snart de schemaläggs har värdet priority ingen effekt.