core.tasks

Attributes

CUSTOM_OBJ
_gaeApp
queueRegion
headers
taskClient
_periodicTasks
_callableTasks
_deferred_tasks
_startupTasks
_appengineServiceIPs

Exceptions

PermanentTaskFailure

Indicates that a task failed, and will never succeed.

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 periodically during cron job execution.
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.
start_clear_transaction_marker()	Removes old (expired) Transaction marker

Module Contents

core.tasks.CUSTOM_OBJ

class core.tasks.CustomEnvironmentHandler

Bases: abc.ABC

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

abstractmethod 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

abstractmethod 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 = None

core.tasks.headers

core.tasks.taskClient

core.tasks._periodicTasks: dict[str, dict[Callable, datetime.timedelta]]

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 = None

name = None

descr = None

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.

abstractmethod 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 = None

This is a dict holding the information necessary for the Vi/Admin to handle this module.

name: str

Human-readable module name that will be shown in the admin tool.

handler: str (list, tree or singleton):

Allows to override the handler provided by the module. Set this only when really necessary, otherwise it can be left out and is automatically injected by the Module’s prototype.

icon: str

(Optional) Either the Shoelace icon library name or a path relative to the project’s deploy folder (e.g. /static/icons/viur.svg) for the icon used in the admin tool for this module.

columns: List[str]

(Optional) List of columns (bone names) that are displayed by default. Used only by the List handler.

filter: Dict[str, str]

(Optional) Dictionary of additional parameters that will be send along when fetching entities from the server. Can be used to filter the entities being displayed on the client-side.

display: str (“default”, “hidden” or “group”)

(Optional) “hidden” will hide the module in the admin tool’s main bar. (itwill not be accessible directly, however it’s registered with the frontend so it can be used in a relational bone). “group” will show this module in the main bar, but it will not be clickable. Clicking it will just try to expand it (assuming there are additional views defined).

preview: Union[str, Dict[str, str]]

(Optional) A url that will be opened in a new tab and is expected to display the entity selected in the table. Can be “/{{module}}/view/{{key}}”, with {{module}} and {{key}} getting replaced as needed. If more than one preview-url is needed, supply a dictionary where the key is the URL and the value the description shown to the user.

views: List[Dict[str, t.Any]]

(Optional) List of nested adminInfo like dictionaries. Used to define additional views on the module. Useful f.e. for an order module, where you want separate list of “payed orders”, “unpayed orders”, “orders waiting for shipment”, etc. If such views are defined, the top-level entry in the menu bar will expand if clicked, revealing these additional filters.

actions: List[str]

(Optional) List of actions supported by this modules. Actions can be defined by the frontend (like “add”, “edit”, “delete” or “preview”); it can be an action defined by a plugin loaded by the frontend; or it can be a so called “server side action” (see “customActions” below)

customActions: Dict[str, dict]

(Optional) A mapping of names of server-defined actions that can be used in the actions list above to their definition dictionary. See …. for more details.

disabledActions: List[str, dict]

(Optional) A list of disabled actions. The frontend will inject default actions like add or edit even if they’re not listed in actions. Listing them here will prevent that. It’s up to the frontend to decide if that action won’t be visible at all or it’s button just being disabled.

sortIndex: int

(Optional) Defines the order in which the modules will appear in the main bar in ascrending order.

indexedBones: List[str]

(Optional) List of bones, for which an (composite?) index exists in this view. This allows the fronted to signal the user that a given list can be sorted or filtered by this bone. If no additional filters are enforced by the listFilter and filter is not set, this should be all bones which are marked as indexed.

changeInvalidates: List[str]

(Optional) A list of module-names which depend on the entities handled from this module. This allows the frontend to invalidate any caches in these depended modules if the data in this module changes. Example: This module may be a list-module handling the file_rootNode entities for the file module, so a edit/add/deletion action on this module should be reflected in the rootNode-selector in the file-module itself. In this case, this property should be set to ["file"].

moduleGroup: str

(Optional) If set, should be a key of a moduleGroup defined in …. .

editViews: Dict[str, t.Any]

(Optional) If set, will embed another list-widget in the edit forms for a given entity. See …. for more details.

If this is a function, it must take no parameters and return the dictionary as shown above. This can be used to customize the appearance of the Vi/Admin to individual users.

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, *, bounce=False, **kwargs)

Queues a specific task for the next maintenance run

Parameters:

bounce (bool)

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.

If no value is given, the queue name set in conf.tasks_default_queues will be used. If the config does not have a value for this task, “default” is used as the default. 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 periodically during cron job execution.

Interval defines a lower bound for the call-frequency for the given task, specified as a timedelta.

The true interval of how often cron jobs are being executed is defined in the project’s cron.yaml file. This defaults to 4 hours (see https://github.com/viur-framework/viur-base/blob/main/deploy/cron.yaml). In case the interval defined here is lower than 4 hours, the task will be fired once every 4 hours anyway.

Parameters:

• interval (datetime.timedelta | int | float) – Call at most the given timedelta.

• 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).

core.tasks.start_clear_transaction_marker()

Removes old (expired) Transaction marker https://cloud.google.com/datastore/docs/concepts/transactions?hl=en#using_transactions https://cloud.google.com/tasks/docs/quotas?hl=en