evennia.scripts.taskhandler

Module containing the task handler for Evennia deferred tasks, persistent or not.

evennia.scripts.taskhandler.handle_error(*args, **kwargs)

Handle errors within deferred objects.

class evennia.scripts.taskhandler.TaskHandlerTask(task_id)

Bases: object

An object to represent a single TaskHandler task.

Instance Attributes:

task_id (int): the global id for this task deferred (deferred): a reference to this task’s deferred

Property Attributes:

paused (bool): check if the deferred instance of a task has been paused. called(self): A task attribute to check if the deferred instance of a task has been called.

pause()

Pause the callback of a task.

unpause()

Process all callbacks made since pause() was called.

do_task()

Execute the task (call its callback).

call()

Call the callback of this task.

remove()

Remove a task without executing it.

cancel()

Stop a task from automatically executing.

active()

Check if a task is active (has not been called yet).

exists()

Check if a task exists.

get_id()

Returns the global id for this task. For use with

__init__(task_id)

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

get_deferred()

Return the instance of the deferred the task id is using.

Returns

bool or deferred –

An instance of a deferred or False if there is no task with the id.

None is returned if there is no deferred affiliated with this id.

pause()

Pause the callback of a task. To resume use TaskHandlerTask.unpause.

unpause()

Unpause a task, run the task if it has passed delay time.

property paused

A task attribute to check if the deferred instance of a task has been paused.

This exists to mock usage of a twisted deferred object.

Returns

bool or None –

True if the task was properly paused. None if the task does not have

a deferred instance.

do_task()

Execute the task (call its callback). If calling before timedelay, cancel the deferred instance affliated to this task. Remove the task from the dictionary of current tasks on a successful callback.

Returns

bool or any – Set to False if the task does not exist in task handler. Otherwise it will be the return of the task’s callback.

call()

Call the callback of a task. Leave the task unaffected otherwise. This does not use the task’s deferred instance. The only requirement is that the task exist in task handler.

Returns

bool or any – Set to False if the task does not exist in task handler. Otherwise it will be the return of the task’s callback.

remove()

Remove a task without executing it. Deletes the instance of the task’s deferred.

Parameters

task_id (int) – an existing task ID.

Returns

bool – True if the removal completed successfully.

cancel()

Stop a task from automatically executing. This will not remove the task.

Returns

bool –

True if the cancel completed successfully.

False if the cancel did not complete successfully.

active()

Check if a task is active (has not been called yet).

Returns

bool –

True if a task is active (has not been called yet). False if

it is not (has been called) or if the task does not exist.

property called

A task attribute to check if the deferred instance of a task has been called.

This exists to mock usage of a twisted deferred object. It will not set to True if Task.call has been called. This only happens if task’s deferred instance calls the callback.

Returns

bool –

True if the deferred instance of this task has called the callback.

False if the deferred instnace of this task has not called the callback.

exists()

Check if a task exists. Most task handler methods check for existence for you.

Returns

bool – True the task exists False if it does not.

get_id()

Returns the global id for this task. For use with evennia.scripts.taskhandler.TASK_HANDLER.

Returns

task_id (int) – global task id for this task.

class evennia.scripts.taskhandler.TaskHandler

Bases: object

A light singleton wrapper allowing to access permanent tasks.

When utils.delay is called, the task handler is used to create the task.

Task handler will automatically remove uncalled but canceled from task handler. By default this will not occur until a canceled task has been uncalled for 60 second after the time it should have been called. To adjust this time use TASK_HANDLER.stale_timeout. If stale_timeout is 0 stale tasks will not be automatically removed. This is not done on a timer. I is done as new tasks are added or the load method is called.

__init__()

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

load()

Load from the ServerConfig.

This should be automatically called when Evennia starts. It populates self.tasks according to the ServerConfig.

clean_stale_tasks()

remove uncalled but canceled from task handler.

By default this will not occur until a canceled task has been uncalled for 60 second after the time it should have been called. To adjust this time use TASK_HANDLER.stale_timeout.

save()

Save the tasks in ServerConfig.

add(timedelay, callback, *args, **kwargs)

Add a new task.

If the persistent kwarg is truthy: The callback, args and values for kwarg will be serialized. Type and attribute errors during the serialization will be logged, but will not throw exceptions. For persistent tasks do not use memory references in the callback function or arguments. After a restart those memory references are no longer accurate.

Parameters

• timedelay (int or float) – time in seconds before calling the callback.

• callback (function or instance method) – the callback itself

• any (any) – any additional positional arguments to send to the callback

• *args – positional arguments to pass to callback.

• **kwargs –

  keyword arguments to pass to callback. - persistent (bool, optional): persist the task (stores it).

  Persistent key and value is removed from kwargs it will not be passed to callback.

Returns

TaskHandlerTask –

An object to represent a task.

Reference evennia.scripts.taskhandler.TaskHandlerTask for complete details.

exists(task_id)

Check if a task exists. Most task handler methods check for existence for you.

Parameters

task_id (int) – an existing task ID.

Returns

bool – True the task exists False if it does not.

active(task_id)

Check if a task is active (has not been called yet).

Parameters

task_id (int) – an existing task ID.

Returns

bool –

True if a task is active (has not been called yet). False if

it is not (has been called) or if the task does not exist.

cancel(task_id)

Stop a task from automatically executing. This will not remove the task.

Parameters

task_id (int) – an existing task ID.

Returns

bool –

True if the cancel completed successfully.

False if the cancel did not complete successfully.

remove(task_id)

Remove a task without executing it. Deletes the instance of the task’s deferred.

Parameters

task_id (int) – an existing task ID.

Returns

bool – True if the removal completed successfully.

clear(save=True, cancel=True)

Clear all tasks. By default tasks are canceled and removed from the database as well.

Parameters

• save=True (bool) – Should changes to persistent tasks be saved to database.

• cancel=True (bool) – Cancel scheduled tasks before removing it from task handler.

Returns

True (bool) – if the removal completed successfully.

call_task(task_id)

Call the callback of a task. Leave the task unaffected otherwise. This does not use the task’s deferred instance. The only requirement is that the task exist in task handler.

Parameters

task_id (int) – an existing task ID.

Returns

bool or any – Set to False if the task does not exist in task handler. Otherwise it will be the return of the task’s callback.

do_task(task_id)

Execute the task (call its callback). If calling before timedelay cancel the deferred instance affliated to this task. Remove the task from the dictionary of current tasks on a successful callback.

Parameters

task_id (int) – a valid task ID.

Returns

bool or any – Set to False if the task does not exist in task handler. Otherwise it will be the return of the task’s callback.

get_deferred(task_id)

Return the instance of the deferred the task id is using.

Parameters

task_id (int) – a valid task ID.

Returns

bool or deferred –

An instance of a deferred or False if there is no task with the id.

None is returned if there is no deferred affiliated with this id.

create_delays()

Create the delayed tasks for the persistent tasks. This method should be automatically called when Evennia starts.