evennia.scripts package

This sub-package holds the Scripts system. Scripts are database entities that can store data both in connection to Objects and Accounts or globally. They may also have a timer-component to execute various timed effects.

Subpackages

Submodules

evennia.scripts.admin module

class evennia.scripts.admin.ScriptAttributeInline(parent_model, admin_site)

Bases: evennia.typeclasses.admin.AttributeInline

Inline attribute tags.

property media

model

alias of evennia.scripts.models.ScriptDB_db_attributes

related_field = 'scriptdb'

class evennia.scripts.admin.ScriptDBAdmin(model, admin_site)

Bases: django.contrib.admin.options.ModelAdmin

Displaying the main Script page.

fieldsets = ((None, {'fields': (('db_key', 'db_typeclass_path'), 'db_interval', 'db_repeats', 'db_start_delay', 'db_persistent', 'db_obj')}),)

inlines = [<class 'evennia.scripts.admin.ScriptTagInline'>, <class 'evennia.scripts.admin.ScriptAttributeInline'>]

list_display = ('id', 'db_key', 'db_typeclass_path', 'db_obj', 'db_interval', 'db_repeats', 'db_persistent')

list_display_links = ('id', 'db_key')

list_select_related = True

property media

ordering = ['db_obj', 'db_typeclass_path']

raw_id_fields = ('db_obj',)

save_as = True

save_model(request, obj, form, change)

Model-save hook.

Parameters

• request (Request) – Incoming request.

• obj (Object) – Database object.

• form (Form) – Form instance.

• change (bool) – If this is a change or a new object.

save_on_top = True

search_fields = ['^db_key', 'db_typeclass_path']

class evennia.scripts.admin.ScriptTagInline(parent_model, admin_site)

Bases: evennia.typeclasses.admin.TagInline

Inline script tags.

property media

model

alias of evennia.scripts.models.ScriptDB_db_tags

related_field = 'scriptdb'

evennia.scripts.manager module

The custom manager for Scripts.

class evennia.scripts.manager.ScriptManager

Bases: evennia.scripts.manager.ScriptDBManager, evennia.typeclasses.managers.TypeclassManager

evennia.scripts.models module

Scripts are entities that perform some sort of action, either only once or repeatedly. They can be directly linked to a particular Evennia Object or be stand-alonw (in the latter case it is considered a ‘global’ script). Scripts can indicate both actions related to the game world as well as pure behind-the-scenes events and effects. Everything that has a time component in the game (i.e. is not hard-coded at startup or directly created/controlled by players) is handled by Scripts.

Scripts have to check for themselves that they should be applied at a particular moment of time; this is handled by the is_valid() hook. Scripts can also implement at_start and at_end hooks for preparing and cleaning whatever effect they have had on the game object.

Common examples of uses of Scripts:

• Load the default cmdset to the account object’s cmdhandler when logging in.

• Switch to a different state, such as entering a text editor, start combat or enter a dark room.

• Merge a new cmdset with the default one for changing which commands are available at a particular time

• Give the account/object a time-limited bonus/effect

class evennia.scripts.models.ScriptDB(*args, **kwargs)

Bases: evennia.typeclasses.models.TypedObject

The Script database representation.

The TypedObject supplies the following (inherited) properties:

key - main name name - alias for key typeclass_path - the path to the decorating typeclass typeclass - auto-linked typeclass date_created - time stamp of object creation permissions - perm strings dbref - #id of object db - persistent attribute storage ndb - non-persistent attribute storage

The ScriptDB adds the following properties:

desc - optional description of script obj - the object the script is linked to, if any account - the account the script is linked to (exclusive with obj) interval - how often script should run start_delay - if the script should start repeating right away repeats - how many times the script should repeat persistent - if script should survive a server reboot is_active - bool if script is currently running

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

_ScriptDB__get_obj()

Property wrapper that homogenizes access to either the db_account or db_obj field, using the same object property name.

_ScriptDB__set_obj(value)

Set account or obj to their right database field. If a dbref is given, assume ObjectDB.

_is_deleted = False

_meta = <Options for ScriptDB>

property account

A wrapper for getting database field db_account.

db_account

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

db_account_id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_attributes

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

Pizza.toppings and Topping.pizzas are ManyToManyDescriptor instances.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

db_desc

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_interval

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_is_active

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_obj

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

db_obj_id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_persistent

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_repeats

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_start_delay

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_tags

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

Pizza.toppings and Topping.pizzas are ManyToManyDescriptor instances.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

property desc

A wrapper for getting database field db_desc.

get_next_by_db_date_created(*, field=<django.db.models.fields.DateTimeField: db_date_created>, is_next=True, **kwargs)

get_previous_by_db_date_created(*, field=<django.db.models.fields.DateTimeField: db_date_created>, is_next=False, **kwargs)

id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

property interval

A wrapper for getting database field db_interval.

property is_active

A wrapper for getting database field db_is_active.

property obj

Property wrapper that homogenizes access to either the db_account or db_obj field, using the same object property name.

property object

Property wrapper that homogenizes access to either the db_account or db_obj field, using the same object property name.

objects = <evennia.scripts.manager.ScriptDBManager object>

path = 'evennia.scripts.models.ScriptDB'

property persistent

A wrapper for getting database field db_persistent.

receiver_script_set

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

Pizza.toppings and Topping.pizzas are ManyToManyDescriptor instances.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

property repeats

A wrapper for getting database field db_repeats.

sender_script_set

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

Pizza.toppings and Topping.pizzas are ManyToManyDescriptor instances.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

property start_delay

A wrapper for getting database field db_start_delay.

typename = 'SharedMemoryModelBase'

evennia.scripts.monitorhandler module

Monitors - catch changes to model fields and Attributes.

The MONITOR_HANDLER singleton from this module offers the following functionality:

• Field-monitor - track a object’s specific database field and perform

  an action whenever that field changes for whatever reason.

• Attribute-monitor tracks an object’s specific Attribute and perform

  an action whenever that Attribute changes for whatever reason.

class evennia.scripts.monitorhandler.MonitorHandler

Bases: object

This is a resource singleton that allows for registering callbacks for when a field or Attribute is updated (saved).

__init__()

Initialize the handler.

add(obj, fieldname, callback, idstring='', persistent=False, **kwargs)

Add monitoring to a given field or Attribute. A field must be specified with the full db_* name or it will be assumed to be an Attribute (so db_key, not just key).

Parameters

• obj (Typeclassed Entity) – The entity on which to monitor a field or Attribute.

• fieldname (str) – Name of field (db_*) or Attribute to monitor.

• callback (callable) – A callable on the form `callable(**kwargs), where kwargs holds keys fieldname and obj.

• idstring (str, optional) – An id to separate this monitor from other monitors of the same field and object.

• persistent (bool, optional) – If False, the monitor will survive a server reload but not a cold restart. This is default.

Kwargs:

session (Session): If this keyword is given, the monitorhandler will

correctly analyze it and remove the monitor if after a reload/reboot the session is no longer valid.

any (any): Any other kwargs are passed on to the callback. Remember that

all kwargs must be possible to pickle!

all(obj=None)

List all monitors or all monitors of a given object.

Parameters

obj (Object) – The object on which to list all monitors.

Returns

The handled monitors.

Return type

monitors (list)

at_update(obj, fieldname)

Called by the field as it saves.

clear()

Delete all monitors.

remove(obj, fieldname, idstring='')

Remove a monitor.

restore(server_reload=True)

Restore our monitors after a reload. This is called by the server process.

Parameters

server_reload (bool, optional) – If this is False, it means the server went through a cold reboot and all non-persistent tickers must be killed.

save()

Store our monitors to the database. This is called by the server process.

Since dbserialize can’t handle defaultdicts, we convert to an intermediary save format ((obj,fieldname, idstring, callback, kwargs), …)

evennia.scripts.monitorhandler._DA()

Implement delattr(self, name).

evennia.scripts.monitorhandler._GA()

Return getattr(self, name).

evennia.scripts.monitorhandler._SA()

Implement setattr(self, name, value).

evennia.scripts.scripthandler module

The script handler makes sure to check through all stored scripts to make sure they are still relevant. A scripthandler is automatically added to all game objects. You access it through the property scripts on the game object.

class evennia.scripts.scripthandler.ScriptHandler(obj)

Bases: object

Implements the handler. This sits on each game object.

__init__(obj)

Set up internal state.

Parameters

obj (Object) – A reference to the object this handler is attached to.

add(scriptclass, key=None, autostart=True)

Add a script to this object.

Parameters

• scriptclass (Scriptclass, Script or str) – Either a class object inheriting from DefaultScript, an instantiated script object or a python path to such a class object.

• key (str, optional) – Identifier for the script (often set in script definition and listings)

• autostart (bool, optional) – Start the script upon adding it.

all()

Get all scripts stored in this handler.

delete(key=None)

Forcibly delete a script from this object.

Parameters

key (str, optional) – A script key or the path to a script (in the latter case all scripts with this path will be deleted!) If no key is given, delete all scripts on the object!

get(key)

Search scripts on this object.

Parameters

key (str) – Search criterion, the script’s key or dbref.

Returns

The found scripts matching key.

Return type

scripts (list)

start(key)

Find scripts and force-start them

Parameters

key (str) – The script’s key or dbref.

Returns

The number of started scripts found.

Return type

nr_started (int)

stop(key=None)

Forcibly delete a script from this object.

Parameters

key (str, optional) – A script key or the path to a script (in the latter case all scripts with this path will be deleted!) If no key is given, delete all scripts on the object!

validate(init_mode=False)

Runs a validation on this object’s scripts only. This should be called regularly to crank the wheels.

Parameters

init_mode (str, optional) –

• This is used during server

upstart and can have three values: - False (no init mode). Called during run. - “reset” - server reboot. Kill non-persistent scripts - “reload” - server reload. Keep non-persistent scripts.

evennia.scripts.scripts module

This module defines Scripts, out-of-character entities that can store data both on themselves and on other objects while also having the ability to run timers.

class evennia.scripts.scripts.DefaultScript(*args, **kwargs)

Bases: evennia.scripts.scripts.ScriptBase

This is the base TypeClass for all Scripts. Scripts describe events, timers and states in game, they can have a time component or describe a state that changes under certain conditions.

exception DoesNotExist

Bases: evennia.scripts.scripts.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.scripts.scripts.MultipleObjectsReturned

_meta = <Options for DefaultScript>

at_idmapper_flush()

If we’re flushing this object, make sure the LoopingCall is gone too

at_repeat(**kwargs)

Called repeatedly if this Script is set to repeat regularly.

Parameters

**kwargs (dict) – Arbitrary, optional arguments for users overriding the call (unused by default).

at_script_creation()

Only called once, when script is first created.

at_server_reload()

This hook is called whenever the server is shutting down for restart/reboot. If you want to, for example, save non-persistent properties across a restart, this is the place to do it.

at_server_shutdown()

This hook is called whenever the server is shutting down fully (i.e. not for a restart).

at_start(**kwargs)

Called whenever the script is started, which for persistent scripts is at least once every server start. It will also be called when starting again after a pause (such as after a server reload)

Parameters

**kwargs (dict) – Arbitrary, optional arguments for users overriding the call (unused by default).

at_stop(**kwargs)

Called whenever when it’s time for this script to stop (either because is_valid returned False or it runs out of iterations)

Args

**kwargs (dict): Arbitrary, optional arguments for users

overriding the call (unused by default).

classmethod create(key, **kwargs)

Provides a passthrough interface to the utils.create_script() function.

Parameters

key (str) – Name of the new object.

Returns

A newly created object of the given typeclass. errors (list): A list of errors in string form, if any.

Return type

object (Object)

force_repeat()

Fire a premature triggering of the script callback. This will reset the timer and count down repeats as if the script had fired normally.

is_valid()

Is called to check if the script is valid to run at this time. Should return a boolean. The method is assumed to collect all needed information from its related self.obj.

path = 'evennia.scripts.scripts.DefaultScript'

pause(manual_pause=True)

This stops a running script and stores its active state. It WILL NOT call the at_stop() hook.

remaining_repeats()

Get the number of returning repeats for limited Scripts.

Returns

The number of repeats

remaining until the Script stops. Returns None if it has unlimited repeats.

Return type

remaining (int or None)

reset_callcount(value=0)

Reset the count of the number of calls done.

Parameters

value (int, optional) – The repeat value to reset to. Default is to set it all the way back to 0.

Notes

This is only useful if repeats != 0.

restart(interval=None, repeats=None, start_delay=None)

Restarts an already existing/running Script from the beginning, optionally using different settings. This will first call the stop hooks, and then the start hooks again. :param interval: Allows for changing the interval

of the Script. Given in seconds. if None, will use the already stored interval.

Parameters

• repeats (int, optional) – The number of repeats. If unset, will use the previous setting.

• start_delay (bool, optional) – If we should wait interval seconds before starting or not. If None, re-use the previous setting.

start(force_restart=False)

Called every time the script is started (for persistent scripts, this is usually once every server start)

Parameters

force_restart (bool, optional) – Normally an already started script will not be started again. if force_restart=True, the script will always restart the script, regardless of if it has started before.

Returns

0 or 1 depending on if the script successfully

started or not. Used in counting.

Return type

result (int)

stop(kill=False)

Called to stop the script from running. This also deletes the script.

Parameters

kill (bool, optional) –

• Stop the script without

calling any relevant script hooks.

Returns

0 if the script failed to stop, 1 otherwise.

Used in counting.

Return type

result (int)

time_until_next_repeat()

Get time until the script fires it at_repeat hook again.

Returns

Time in seconds until the script runs again.

If not a timed script, return None.

Return type

next (int)

Notes

This hook is not used in any way by the script’s stepping system; it’s only here for the user to be able to check in on their scripts and when they will next be run.

typename = 'DefaultScript'

unpause(manual_unpause=True)

Restart a paused script. This WILL call the at_start() hook.

Parameters

manual_unpause (bool, optional) – This is False if unpause is called by the server reload/reset mechanism.

Returns

True if unpause was triggered, False otherwise.

Return type

result (bool)

Raises

RuntimeError – If trying to automatically resart this script (usually after a reset/reload), but it was manually paused, and so should not the auto-unpaused.

class evennia.scripts.scripts.DoNothing(*args, **kwargs)

Bases: evennia.scripts.scripts.DefaultScript

A script that does nothing. Used as default fallback.

exception DoesNotExist

Bases: evennia.scripts.scripts.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.scripts.scripts.MultipleObjectsReturned

_meta = <Options for DoNothing>

at_script_creation()

Setup the script

path = 'evennia.scripts.scripts.DoNothing'

typename = 'DoNothing'

class evennia.scripts.scripts.Store(*args, **kwargs)

Bases: evennia.scripts.scripts.DefaultScript

Simple storage script

exception DoesNotExist

Bases: evennia.scripts.scripts.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.scripts.scripts.MultipleObjectsReturned

_meta = <Options for Store>

at_script_creation()

Setup the script

path = 'evennia.scripts.scripts.Store'

typename = 'Store'

evennia.scripts.taskhandler module

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

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. If utils.delay is called with persistent=True, the task handler stores the new task and saves.

It’s easier to access these tasks (should it be necessary) using evennia.scripts.taskhandler.TASK_HANDLER, which contains one instance of this class, and use its add and remove methods.

__init__()

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

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

Add a new persistent task in the configuration.

Parameters

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

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

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

Kwargs:

persistent (bool, optional): persist the task (store it). any (any): additional keyword arguments to send to the callback

create_delays()

Create the delayed tasks for the persistent tasks.

Note

This method should be automatically called when Evennia starts.

do_task(task_id)

Execute the task (call its callback).

Parameters

task_id (int) – a valid task ID.

Note

This will also remove it from the list of current tasks.

load()

Load from the ServerConfig.

Note

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

remove(task_id)

Remove a persistent task without executing it.

Parameters

task_id (int) – an existing task ID.

Note

A non-persistent task doesn’t have a task_id, it is not stored in the TaskHandler.

save()

Save the tasks in ServerConfig.

evennia.scripts.tests module

class evennia.scripts.tests.TestScript(methodName='runTest')

Bases: evennia.utils.test_resources.EvenniaTest

test_create()

Check the script can be created via the convenience method.

class evennia.scripts.tests.TestScriptDB(methodName='runTest')

Bases: unittest.case.TestCase

Check the singleton/static ScriptDB object works correctly

setUp()

Hook method for setting up the test fixture before exercising it.

tearDown()

Hook method for deconstructing the test fixture after testing it.

test_delete()

Check the script is removed from the database

test_deleted_script_fails_start()

Would it ever be necessary to start a deleted script?

test_deleted_script_is_invalid()

Can deleted scripts be said to be valid?

test_double_delete()

What should happen? Isn’t it already deleted?

evennia.scripts.tickerhandler module

TickerHandler

This implements an efficient Ticker which uses a subscription model to ‘tick’ subscribed objects at regular intervals.

The ticker mechanism is used by importing and accessing the instantiated TICKER_HANDLER instance in this module. This instance is run by the server; it will save its status across server reloads and be started automaticall on boot.

Example:

```python

from evennia.scripts.tickerhandler import TICKER_HANDLER

# call tick myobj.at_tick(*args, **kwargs) every 15 seconds TICKER_HANDLER.add(15, myobj.at_tick, *args, **kwargs)

```

You supply the interval to tick and a callable to call regularly with any extra args/kwargs. The callable should either be a stand-alone function in a module or the method on a typeclassed entity (that is, on an object that can be safely and stably returned from the database). Functions that are dynamically created or sits on in-memory objects cannot be used by the tickerhandler (there is no way to reference them safely across reboots and saves).

The handler will transparently set up and add new timers behind the scenes to tick at given intervals, using a TickerPool - all callables with the same interval will share the interval ticker.

To remove:

```python

TICKER_HANDLER.remove(15, myobj.at_tick)

```

Both interval and callable must be given since a single object can be subscribed to many different tickers at the same time. You can also supply idstring as an identifying string if you ever want to tick the callable at the same interval but with different arguments (args/kwargs are not used for identifying the ticker). There is also persistent=False if you don’t want to make a ticker that don’t survive a reload. If either or both idstring or persistent has been changed from their defaults, they must be supplied to the TICKER_HANDLER.remove call to properly identify the ticker to remove.

The TickerHandler’s functionality can be overloaded by modifying the Ticker class and then changing TickerPool and TickerHandler to use the custom classes

```python class MyTicker(Ticker):

# [doing custom stuff]

class MyTickerPool(TickerPool):

ticker_class = MyTicker

class MyTickerHandler(TickerHandler):

ticker_pool_class = MyTickerPool

```

If one wants to duplicate TICKER_HANDLER’s auto-saving feature in a custom handler one can make a custom AT_STARTSTOP_MODULE entry to call the handler’s save() and restore() methods when the server reboots.

class evennia.scripts.tickerhandler.Ticker(interval)

Bases: object

Represents a repeatedly running task that calls hooks repeatedly. Overload _callback to change the way it operates.

__init__(interval)

Set up the ticker

Parameters

interval (int) – The stepping interval.

_callback()

This will be called repeatedly every self.interval seconds. self.subscriptions contain tuples of (obj, args, kwargs) for each subscribing object.

If overloading, this callback is expected to handle all subscriptions when it is triggered. It should not return anything and should not traceback on poorly designed hooks. The callback should ideally work under @inlineCallbacks so it can yield appropriately.

The _hook_key, which is passed down through the handler via kwargs is used here to identify which hook method to call.

add(store_key, *args, **kwargs)

Sign up a subscriber to this ticker. :param store_key: Unique storage hash for this ticker subscription. :type store_key: str :param args: Arguments to call the hook method with. :type args: any, optional

Kwargs:

_start_delay (int): If set, this will be

used to delay the start of the trigger instead of interval.

remove(store_key)

Unsubscribe object from this ticker

Parameters

store_key (str) – Unique store key.

stop()

Kill the Task, regardless of subscriptions.

validate(start_delay=None)

Start/stop the task depending on how many subscribers we have using it.

Parameters

start_delay (int) – Time to way before starting.

class evennia.scripts.tickerhandler.TickerHandler(save_name='ticker_storage')

Bases: object

The Tickerhandler maintains a pool of tasks for subscribing objects to various tick rates. The pool maintains creation instructions and and re-applies them at a server restart.

__init__(save_name='ticker_storage')

Initialize handler

save_name (str, optional): The name of the ServerConfig

instance to store the handler state persistently.

_get_callback(callback)

Analyze callback and determine its consituents

Parameters

callback (function or method) – This is either a stand-alone function or class method on a typeclassed entitye (that is, an entity that can be saved to the database).

Returns

This is a tuple of the form (obj, path, callfunc),

where obj is the database object the callback is defined on if it’s a method (otherwise None) and vice-versa, path is the python-path to the stand-alone function (None if a method). The callfunc is either the name of the method to call or the callable function object itself.

Return type

ret (tuple)

_store_key(obj, path, interval, callfunc, idstring='', persistent=True)

Tries to create a store_key for the object.

Parameters

• obj (Object, tuple or None) – Subscribing object if any. If a tuple, this is a packed_obj tuple from dbserialize.

• path (str or None) – Python-path to callable, if any.

• interval (int) – Ticker interval.

• callfunc (callable or str) – This is either the callable function or the name of the method to call. Note that the callable is never stored in the key; that is uniquely identified with the python-path.

• idstring (str, optional) – Additional separator between different subscription types.

• persistent (bool, optional) – If this ticker should survive a system shutdown or not.

Returns

A tuple `(packed_obj, methodname, outpath, interval,

idstring, persistent)` that uniquely identifies the ticker. Here, packed_obj is the unique string representation of the object or None. The methodname is the string name of the method on packed_obj to call, or None if packed_obj is unset. path is the Python-path to a non-method callable, or None. Finally, interval idstring and persistent are integers, strings and bools respectively.

Return type

store_key (tuple)

add(interval=60, callback=None, idstring='', persistent=True, *args, **kwargs)

Add subscription to tickerhandler

Parameters

• interval (int, optional) – Interval in seconds between calling callable(*args, **kwargs)

• callable (callable function or method, optional) – This should either be a stand-alone function or a method on a typeclassed entity (that is, one that can be saved to the database).

• idstring (str, optional) – Identifier for separating this ticker-subscription from others with the same interval. Allows for managing multiple calls with the same time interval and callback.

• persistent (bool, optional) – A ticker will always survive a server reload. If this is unset, the ticker will be deleted by a server shutdown.

• kwargs (args,) – These will be passed into the callback every time it is called. This must be data possible to pickle!

Returns

The immutable store-key for this ticker. This can

be stored and passed into .remove(store_key=store_key) later to easily stop this ticker later.

Return type

store_key (tuple)

Notes

The callback will be identified by type and stored either as as combination of serialized database object + methodname or as a python-path to the module + funcname. These strings will be combined iwth interval and idstring to define a unique storage key for saving. These must thus all be supplied when wanting to modify/remove the ticker later.

all(interval=None)

Get all subscriptions.

Parameters

interval (int) – Limit match to tickers with this interval.

Returns

If interval was given, this is a list of

tickers using that interval.

tickerpool_layout (dict): If interval was not given,

this is a dict {interval1: [ticker1, ticker2, …], …}

Return type

tickers (list)

all_display()

Get all tickers on an easily displayable form.

Returns

A list of all storekeys

Return type

tickers (dict)

clear(interval=None)

Stop/remove tickers from handler.

Parameters

interval (int) – Only stop tickers with this interval.

Notes

This is the only supported way to kill tickers related to non-db objects.

remove(interval=60, callback=None, idstring='', persistent=True, store_key=None)

Remove ticker subscription from handler.

Parameters

• interval (int, optional) – Interval of ticker to remove.

• callback (callable function or method) – Either a function or the method of a typeclassed object.

• idstring (str, optional) – Identifier id of ticker to remove.

• persistent (bool, optional) – Whether this ticker is persistent or not.

• store_key (str, optional) – If given, all other kwargs are ignored and only this is used to identify the ticker.

Raises

KeyError – If no matching ticker was found to remove.

Notes

The store-key is normally built from the interval/callback/idstring/persistent values; but if the store_key is explicitly given, this is used instead.

restore(server_reload=True)

Restore ticker_storage from database and re-initialize the handler from storage. This is triggered by the server at restart.

Parameters

server_reload (bool, optional) – If this is False, it means the server went through a cold reboot and all non-persistent tickers must be killed.

save()

Save ticker_storage as a serialized string into a temporary ServerConf field. Whereas saving is done on the fly, if called by server when it shuts down, the current timer of each ticker will be saved so it can start over from that point.

ticker_pool_class

alias of TickerPool

class evennia.scripts.tickerhandler.TickerPool

Bases: object

This maintains a pool of evennia.scripts.scripts.ExtendedLoopingCall tasks for calling subscribed objects at given times.

__init__()

Initialize the pool.

add(store_key, *args, **kwargs)

Add new ticker subscriber.

Parameters

• store_key (str) – Unique storage hash.

• args (any, optional) – Arguments to send to the hook method.

remove(store_key)

Remove subscription from pool.

Parameters

store_key (str) – Unique storage hash to remove

stop(interval=None)

Stop all scripts in pool. This is done at server reload since restoring the pool will automatically re-populate the pool.

Parameters

interval (int, optional) – Only stop tickers with this interval.

ticker_class

alias of Ticker

evennia.scripts.tickerhandler._GA()

Return getattr(self, name).

evennia.scripts.tickerhandler._SA()

Implement setattr(self, name, value).