core.tasks

Module Contents

Classes

CustomEnvironmentHandler

Helper class that provides a standard way to create an ABC using

CallableTaskBase

Base class for user-callable tasks.

TaskHandler

Task Handler.

MetaQueryIter

This is the meta class for QueryIters.

QueryIter

BaseClass to run a database Query and process each entry matched.

DeleteEntitiesIter

Simple Query-Iter to delete all entities encountered.

Functions

removePeriodicTask(task)

Removes a periodic task from the queue. Useful to unqueue an task

retry_n_times(retries[, email_recipients, tpl])

Wrapper for deferred tasks to limit the amount of retries

noRetry(f)

Prevents a deferred Function from being called a second time

CallDeferred(func)

This is a decorator, which always calls the wrapped method deferred.

callDeferred(func)

Deprecated version of CallDeferred

PeriodicTask([interval, cronName])

Decorator to call a function periodic during maintenance.

CallableTask(fn)

Marks a Class as representing a user-callable Task.

StartupTask(fn)

Functions decorated with this are called shortly at instance startup.

runStartupTasks()

Runs all queued startupTasks.

Attributes

CUSTOM_OBJ

_gaeApp

queueRegion

headers

taskClient

_periodicTasks

_callableTasks

_deferred_tasks

_startupTasks

_appengineServiceIPs

core.tasks.CUSTOM_OBJ
class core.tasks.CustomEnvironmentHandler

Bases: abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

abstract serialize()

Serialize custom environment data

This function must not require any parameters and must return a JSON serializable object with the desired information.

Return type:

CUSTOM_OBJ

abstract restore(obj)

Restore custom environment data

This function will receive the object from serialize() and should write the information it contains to the environment of the deferred request.

Parameters:

obj (CUSTOM_OBJ) –

Return type:

None

core.tasks._gaeApp
core.tasks.queueRegion
core.tasks.headers
core.tasks.taskClient
core.tasks._periodicTasks: dict[str, dict[Callable, int]]
core.tasks._callableTasks
core.tasks._deferred_tasks
core.tasks._startupTasks = []
core.tasks._appengineServiceIPs
exception core.tasks.PermanentTaskFailure

Bases: Exception

Indicates that a task failed, and will never succeed.

Initialize self. See help(type(self)) for accurate signature.

core.tasks.removePeriodicTask(task)

Removes a periodic task from the queue. Useful to unqueue an task that has been inherited from an overridden module.

Parameters:

task (Callable) –

Return type:

None

class core.tasks.CallableTaskBase

Base class for user-callable tasks. Must be subclassed.

key
name
descr
kindName = 'server-task'
canCall()

Checks wherever the current user can execute this task :returns: bool

Return type:

bool

dataSkel()

If additional data is needed, return a skeleton-instance here. These values are then passed to execute.

abstract execute()

The actual code that should be run goes here.

class core.tasks.TaskHandler(moduleName, modulePath, *args, **kwargs)

Bases: viur.core.module.Module

Task Handler. Handles calling of Tasks (queued and periodic), and performs updatechecks Do not Modify. Do not Subclass.

Parameters:
  • moduleName (str) –

  • modulePath (str) –

adminInfo
retryCountWarningThreshold = 25
findBoundTask(task, obj, depth=0)

Tries to locate the instance, this function belongs to. If it succeeds in finding it, it returns the function and its instance (-> its “self”). Otherwise, None is returned. :param task: A callable decorated with @PeriodicTask :param obj: Object, which will be scanned in the current iteration. :param depth: Current iteration depth.

Parameters:
  • task (Callable) –

  • obj (object) –

  • depth (int) –

Return type:

Optional[tuple[Callable, object]]

queryIter(*args, **kwargs)

This processes one chunk of a queryIter (see below).

deferred(*args, **kwargs)

This catches one deferred call and routes it to its destination

cron(cronName='default', *args, **kwargs)
_validate_request(*, require_cron=False, require_taskname=True)

Validate the header and metadata of a request

If the request is valid, None will be returned. Otherwise, an exception will be raised.

Parameters:
  • require_taskname (bool) – Require “X-AppEngine-TaskName” header

  • require_cron (bool) – Require “X-Appengine-Cron” header

Return type:

None

list(*args, **kwargs)

Lists all user-callable tasks which are callable by this user

execute(taskID, *args, **kwargs)

Queues a specific task for the next maintenance run

core.tasks.retry_n_times(retries, email_recipients=None, tpl=None)

Wrapper for deferred tasks to limit the amount of retries

Parameters:
  • retries (int) – Number of maximum allowed retries

  • email_recipients (None | str | list[str]) – Email addresses to which a info should be sent when the retry limit is reached.

  • tpl (None | str) – Instead of the standard text, a custom template can be used. The name of an email template must be specified.

Return type:

Callable

core.tasks.noRetry(f)

Prevents a deferred Function from being called a second time

core.tasks.CallDeferred(func)

This is a decorator, which always calls the wrapped method deferred.

The call will be packed and queued into a Cloud Tasks queue. The Task Queue calls the TaskHandler which executed the wrapped function with the originally arguments in a different request.

In addition to the arguments for the wrapped methods you can set these:

_queue: Specify the queue in which the task should be pushed.

“default” is the default value. The queue must exist (use the queue.yaml).

_countdown: Specify a time in seconds after which the task should be called.

This time is relative to the moment where the wrapped method has been called.

_eta: Instead of a relative _countdown value you can specify a datetime

when the task is scheduled to be attempted or retried.

_name: Specify a custom name for the cloud task. Must be unique and can

contain only letters ([A-Za-z]), numbers ([0-9]), hyphens (-), colons (:), or periods (.).

_target_version: Specify a version on which to run this task.

By default, a task will be run on the same version where the wrapped method has been called.

_call_deferred: Calls the @CallDeferred decorated method directly.

This is for example necessary, to call a super method which is decorated with @CallDeferred.

# Example for use of the _call_deferred-parameter
class A(Module):
    @CallDeferred
    def task(self):
        ...

class B(A):
    @CallDeferred
    def task(self):
        super().task(_call_deferred=False)  # avoid secondary deferred call
        ...
See also:

https://cloud.google.com/python/docs/reference/cloudtasks/latest/google.cloud.tasks_v2.types.Task https://cloud.google.com/python/docs/reference/cloudtasks/latest/google.cloud.tasks_v2.types.CreateTaskRequest

Parameters:

func (Callable) –

Return type:

Callable

core.tasks.callDeferred(func)

Deprecated version of CallDeferred

core.tasks.PeriodicTask(interval=0, cronName='default')

Decorator to call a function periodic during maintenance. Interval defines a lower bound for the call-frequency for this task; it will not be called faster than each interval minutes. (Note that the actual delay between two sequent might be much larger)

Parameters:
  • interval (int) – Call at most every interval minutes. 0 means call as often as possible.

  • cronName (str) –

Return type:

Callable

core.tasks.CallableTask(fn)

Marks a Class as representing a user-callable Task. It should extend CallableTaskBase and must provide its API

Parameters:

fn (Callable) –

Return type:

Callable

core.tasks.StartupTask(fn)

Functions decorated with this are called shortly at instance startup. It’s not guaranteed that they actually run on the instance that just started up! Wrapped functions must not take any arguments.

Parameters:

fn (Callable) –

Return type:

Callable

core.tasks.runStartupTasks()

Runs all queued startupTasks. Do not call directly!

class core.tasks.MetaQueryIter(name, bases, dct)

Bases: type

This is the meta class for QueryIters. Used only to keep track of all subclasses of QueryIter so we can emit the callbacks on the correct class.

_classCache
class core.tasks.QueryIter

Bases: object

BaseClass to run a database Query and process each entry matched. This will run each step deferred, so it is possible to process an arbitrary number of entries without being limited by time or memory.

To use this class create a subclass, override the classmethods handleEntry and handleFinish and then call startIterOnQuery with an instance of a database Query (and possible some custom data to pass along)

queueName = 'default'
classmethod startIterOnQuery(query, customData=None)

Starts iterating the given query on this class. Will return immediately, the first batch will already run deferred.

Warning: Any custom data must be json-serializable and must be passed in customData. You cannot store any data on this class as each chunk may run on a different instance!

Parameters:
  • query (viur.core.db.Query) –

  • customData (Any) –

Return type:

None

classmethod _requeueStep(qryDict)

Internal use only. Pushes a new step defined in qryDict to either the taskqueue or append it to the current request if we are on the local development server.

Parameters:

qryDict (dict[str, Any]) –

Return type:

None

classmethod _qryStep(qryDict)

Internal use only. Processes one block of five entries from the query defined in qryDict and reschedules the next block.

Parameters:

qryDict (dict[str, Any]) –

Return type:

None

classmethod handleEntry(entry, customData)

Overridable hook to process one entry. “entry” will be either an db.Entity or an SkeletonInstance (if that query has been created by skel.all())

Warning: If your query has an sortOrder other than __key__ and you modify that property here it is possible to encounter that object later one again (as it may jump behind the current cursor).

classmethod handleFinish(totalCount, customData)

Overridable hook that indicates the current run has been finished.

Parameters:

totalCount (int) –

classmethod handleError(entry, customData, exception)

Handle a error occurred in handleEntry. If this function returns True, the queryIter continues, otherwise it breaks and prints the current cursor.

Return type:

bool

class core.tasks.DeleteEntitiesIter

Bases: QueryIter

Simple Query-Iter to delete all entities encountered.

..Warning: When iterating over skeletons, make sure that the

query was created using Skeleton().all(). This way the Skeleton.delete() method can be used and the appropriate post-processing can be done.

classmethod handleEntry(entry, customData)

Overridable hook to process one entry. “entry” will be either an db.Entity or an SkeletonInstance (if that query has been created by skel.all())

Warning: If your query has an sortOrder other than __key__ and you modify that property here it is possible to encounter that object later one again (as it may jump behind the current cursor).