evennia.commands.default.system

System commands

class evennia.commands.default.system.CmdAccounts(**kwargs)

Bases: MuxCommand

Manage registered accounts

Usage:

accounts [nr] accounts/delete <name or #id> [: reason]

Switches:

delete - delete an account from the server

By default, lists statistics about the Accounts registered with the game. It will list the <nr> amount of latest registered accounts If not given, <nr> defaults to 10.

key = '@accounts'

aliases = ['@account']

switch_options = ('delete',)

locks = 'cmd:perm(listaccounts) or perm(Admin)'

help_category = 'system'

func()

List the accounts

lock_storage = 'cmd:perm(listaccounts) or perm(Admin)'

search_index_entry = {'aliases': '@account', 'category': 'system', 'key': '@accounts', 'no_prefix': 'accounts account', 'tags': '', 'text': '\nManage registered accounts\n\nUsage:\n  accounts [nr]\n  accounts/delete <name or #id> [: reason]\n\nSwitches:\n  delete    - delete an account from the server\n\nBy default, lists statistics about the Accounts registered with the game.\nIt will list the <nr> amount of latest registered accounts\nIf not given, <nr> defaults to 10.\n'}

class evennia.commands.default.system.CmdReload(**kwargs)

Bases: MuxCommand

reload the server

Usage:

reload [reason]

This restarts the server. The Portal is not affected. Non-persistent scripts will survive a reload (use reset to purge) and at_reload() hooks will be called.

key = '@reload'

aliases = ['@restart']

locks = 'cmd:perm(reload) or perm(Developer)'

help_category = 'system'

func()

Reload the system.

lock_storage = 'cmd:perm(reload) or perm(Developer)'

search_index_entry = {'aliases': '@restart', 'category': 'system', 'key': '@reload', 'no_prefix': 'reload restart', 'tags': '', 'text': '\nreload the server\n\nUsage:\n  reload [reason]\n\nThis restarts the server. The Portal is not\naffected. Non-persistent scripts will survive a reload (use\nreset to purge) and at_reload() hooks will be called.\n'}

class evennia.commands.default.system.CmdReset(**kwargs)

Bases: MuxCommand

reset and reboot the server

Usage:

reset

Notes

For normal updating you are recommended to use reload rather than this command. Use shutdown for a complete stop of everything.

This emulates a cold reboot of the Server component of Evennia. The difference to shutdown is that the Server will auto-reboot and that it does not affect the Portal, so no users will be disconnected. Contrary to reload however, all shutdown hooks will be called and any non-database saved scripts, ndb-attributes, cmdsets etc will be wiped.

key = '@reset'

locks = 'cmd:perm(reload) or perm(Developer)'

help_category = 'system'

func()

Reload the system.

aliases = []

lock_storage = 'cmd:perm(reload) or perm(Developer)'

search_index_entry = {'aliases': '', 'category': 'system', 'key': '@reset', 'no_prefix': 'reset ', 'tags': '', 'text': '\nreset and reboot the server\n\nUsage:\n  reset\n\nNotes:\n  For normal updating you are recommended to use reload rather\n  than this command. Use shutdown for a complete stop of\n  everything.\n\nThis emulates a cold reboot of the Server component of Evennia.\nThe difference to shutdown is that the Server will auto-reboot\nand that it does not affect the Portal, so no users will be\ndisconnected. Contrary to reload however, all shutdown hooks will\nbe called and any non-database saved scripts, ndb-attributes,\ncmdsets etc will be wiped.\n\n'}

class evennia.commands.default.system.CmdShutdown(**kwargs)

Bases: MuxCommand

stop the server completely

Usage:

shutdown [announcement]

Gracefully shut down both Server and Portal.

key = '@shutdown'

locks = 'cmd:perm(shutdown) or perm(Developer)'

help_category = 'system'

func()

Define function

aliases = []

lock_storage = 'cmd:perm(shutdown) or perm(Developer)'

search_index_entry = {'aliases': '', 'category': 'system', 'key': '@shutdown', 'no_prefix': 'shutdown ', 'tags': '', 'text': '\nstop the server completely\n\nUsage:\n  shutdown [announcement]\n\nGracefully shut down both Server and Portal.\n'}

class evennia.commands.default.system.CmdPy(**kwargs)

Bases: MuxCommand

execute a snippet of python code

Usage:

py [cmd] py/edit py/time <cmd> py/clientraw <cmd> py/noecho

Switches:

time - output an approximate execution time for <cmd> edit - open a code editor for multi-line code experimentation clientraw - turn off all client-specific escaping. Note that this may

lead to different output depending on prototocol (such as angular brackets being parsed as HTML in the webclient but not in telnet clients)

noecho - in Python console mode, turn off the input echo (e.g. if your client

does this for you already)

Without argument, open a Python console in-game. This is a full console, accepting multi-line Python code for testing and debugging. Type exit() to return to the game. If Evennia is reloaded, the console will be closed.

Enter a line of instruction after the ‘py’ command to execute it immediately. Separate multiple commands by ‘;’ or open the code editor using the /edit switch (all lines added in editor will be executed immediately when closing or using the execute command in the editor).

A few variables are made available for convenience in order to offer access to the system (you can import more at execution time).

Available variables in py environment:

self, me : caller here : caller.location evennia : the evennia API inherits_from(obj, parent) : check object inheritance

You can explore The evennia API from inside the game by calling the __doc__ property on entities:

py evennia.__doc__ py evennia.managers.__doc__

|rNote: In the wrong hands this command is a severe security risk. It should only be accessible by trusted server admins/superusers.|n

key = '@py'

aliases = ['@!']

switch_options = ('time', 'edit', 'clientraw', 'noecho')

locks = 'cmd:perm(py) or perm(Developer)'

help_category = 'system'

arg_regex = re.compile('', re.IGNORECASE)

func()

hook function

lock_storage = 'cmd:perm(py) or perm(Developer)'

search_index_entry = {'aliases': '@!', 'category': 'system', 'key': '@py', 'no_prefix': 'py !', 'tags': '', 'text': "\nexecute a snippet of python code\n\nUsage:\n  py [cmd]\n  py/edit\n  py/time <cmd>\n  py/clientraw <cmd>\n  py/noecho\n\nSwitches:\n  time - output an approximate execution time for <cmd>\n  edit - open a code editor for multi-line code experimentation\n  clientraw - turn off all client-specific escaping. Note that this may\n    lead to different output depending on prototocol (such as angular brackets\n    being parsed as HTML in the webclient but not in telnet clients)\n  noecho - in Python console mode, turn off the input echo (e.g. if your client\n    does this for you already)\n\nWithout argument, open a Python console in-game. This is a full console,\naccepting multi-line Python code for testing and debugging. Type `exit()` to\nreturn to the game. If Evennia is reloaded, the console will be closed.\n\nEnter a line of instruction after the 'py' command to execute it\nimmediately.  Separate multiple commands by ';' or open the code editor\nusing the /edit switch (all lines added in editor will be executed\nimmediately when closing or using the execute command in the editor).\n\nA few variables are made available for convenience in order to offer access\nto the system (you can import more at execution time).\n\nAvailable variables in py environment:\n  self, me                   : caller\n  here                       : caller.location\n  evennia                    : the evennia API\n  inherits_from(obj, parent) : check object inheritance\n\nYou can explore The evennia API from inside the game by calling\nthe `__doc__` property on entities:\n    py evennia.__doc__\n    py evennia.managers.__doc__\n\n|rNote: In the wrong hands this command is a severe security risk.  It\nshould only be accessible by trusted server admins/superusers.|n\n\n"}

class evennia.commands.default.system.CmdService(**kwargs)

Bases: MuxCommand

manage system services

Usage:

service[/switch] <service>

Switches:

list - shows all available services (default) start - activates or reactivate a service stop - stops/inactivate a service (can often be restarted) delete - tries to permanently remove a service

Service management system. Allows for the listing, starting, and stopping of services. If no switches are given, services will be listed. Note that to operate on the service you have to supply the full (green or red) name as given in the list.

key = '@service'

aliases = ['@services']

switch_options = ('list', 'start', 'stop', 'delete')

locks = 'cmd:perm(service) or perm(Developer)'

help_category = 'system'

func()

Implement command

lock_storage = 'cmd:perm(service) or perm(Developer)'

search_index_entry = {'aliases': '@services', 'category': 'system', 'key': '@service', 'no_prefix': 'service services', 'tags': '', 'text': '\nmanage system services\n\nUsage:\n  service[/switch] <service>\n\nSwitches:\n  list   - shows all available services (default)\n  start  - activates or reactivate a service\n  stop   - stops/inactivate a service (can often be restarted)\n  delete - tries to permanently remove a service\n\nService management system. Allows for the listing,\nstarting, and stopping of services. If no switches\nare given, services will be listed. Note that to operate on the\nservice you have to supply the full (green or red) name as given\nin the list.\n'}

class evennia.commands.default.system.CmdAbout(**kwargs)

Bases: MuxCommand

show Evennia info

Usage:

about

Display info about the game engine.

key = '@about'

aliases = ['@version']

locks = 'cmd:all()'

help_category = 'system'

func()

Display information about server or target

lock_storage = 'cmd:all()'

search_index_entry = {'aliases': '@version', 'category': 'system', 'key': '@about', 'no_prefix': 'about version', 'tags': '', 'text': '\nshow Evennia info\n\nUsage:\n  about\n\nDisplay info about the game engine.\n'}

class evennia.commands.default.system.CmdTime(**kwargs)

Bases: MuxCommand

show server time statistics

Usage:

time

List Server time statistics such as uptime and the current time stamp.

key = '@time'

aliases = ['@uptime']

locks = 'cmd:perm(time) or perm(Player)'

help_category = 'system'

func()

Show server time data in a table.

lock_storage = 'cmd:perm(time) or perm(Player)'

search_index_entry = {'aliases': '@uptime', 'category': 'system', 'key': '@time', 'no_prefix': 'time uptime', 'tags': '', 'text': '\nshow server time statistics\n\nUsage:\n  time\n\nList Server time statistics such as uptime\nand the current time stamp.\n'}

class evennia.commands.default.system.CmdServerLoad(**kwargs)

Bases: MuxCommand

show server load and memory statistics

Usage:

server[/mem]

Switches:

mem - return only a string of the current memory usage flushmem - flush the idmapper cache

This command shows server load statistics and dynamic memory usage. It also allows to flush the cache of accessed database objects.

Some Important statistics in the table:

|wServer load|n is an average of processor usage. It’s usually between 0 (no usage) and 1 (100% usage), but may also be temporarily higher if your computer has multiple CPU cores.

The |wResident/Virtual memory|n displays the total memory used by the server process.

Evennia |wcaches|n all retrieved database entities when they are loaded by use of the idmapper functionality. This allows Evennia to maintain the same instances of an entity and allowing non-persistent storage schemes. The total amount of cached objects are displayed plus a breakdown of database object types.

The |wflushmem|n switch allows to flush the object cache. Please note that due to how Python’s memory management works, releasing caches may not show you a lower Residual/Virtual memory footprint, the released memory will instead be re-used by the program.

key = '@server'

aliases = ['@serverload']

switch_options = ('mem', 'flushmem')

locks = 'cmd:perm(list) or perm(Developer)'

help_category = 'system'

func()

Show list.

lock_storage = 'cmd:perm(list) or perm(Developer)'

search_index_entry = {'aliases': '@serverload', 'category': 'system', 'key': '@server', 'no_prefix': 'server serverload', 'tags': '', 'text': "\nshow server load and memory statistics\n\nUsage:\n   server[/mem]\n\nSwitches:\n    mem - return only a string of the current memory usage\n    flushmem - flush the idmapper cache\n\nThis command shows server load statistics and dynamic memory\nusage. It also allows to flush the cache of accessed database\nobjects.\n\nSome Important statistics in the table:\n\n|wServer load|n is an average of processor usage. It's usually\nbetween 0 (no usage) and 1 (100% usage), but may also be\ntemporarily higher if your computer has multiple CPU cores.\n\nThe |wResident/Virtual memory|n displays the total memory used by\nthe server process.\n\nEvennia |wcaches|n all retrieved database entities when they are\nloaded by use of the idmapper functionality. This allows Evennia\nto maintain the same instances of an entity and allowing\nnon-persistent storage schemes. The total amount of cached objects\nare displayed plus a breakdown of database object types.\n\nThe |wflushmem|n switch allows to flush the object cache. Please\nnote that due to how Python's memory management works, releasing\ncaches may not show you a lower Residual/Virtual memory footprint,\nthe released memory will instead be re-used by the program.\n\n"}

class evennia.commands.default.system.CmdTasks(**kwargs)

Bases: MuxCommand

Display or terminate active tasks (delays).

Usage:

tasks[/switch] [task_id or function_name]

Switches:

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.

Notes

A task is a single use method of delaying the call of a function. Calls are created in code, using evennia.utils.delay. See |luhttps://www.evennia.com/docs/latest/Command-Duration.html|ltthe docs|le for help.

By default, tasks that are canceled and never called are cleaned up after one minute.

Examples

• tasks/cancel move_callback - Cancels all movement delays from the slow_exit contrib.

  In this example slow exits creates it’s tasks with utils.delay(move_delay, move_callback)

• tasks/cancel 2 - Cancel task id 2.

key = '@tasks'

aliases = ['@task', '@delays']

switch_options = ('pause', 'unpause', 'do_task', 'call', 'remove', 'cancel')

locks = 'cmd:all();perm(Developer)'

help_category = 'system'

static coll_date_func(task)

Replace regex characters in date string and collect deferred function name.

do_task_action(*args, **kwargs)

Process the action of a tasks command.

This exists to gain support with yes or no function from EvMenu.

func()

This is the hook function that actually does all the work. It is called

by the cmdhandler right after self.parser() finishes, and so has access to all the variables defined therein.

lock_storage = 'cmd:all();cmd:perm(Developer)'

search_index_entry = {'aliases': '@task @delays', 'category': 'system', 'key': '@tasks', 'no_prefix': 'tasks task delays', 'tags': '', 'text': "\nDisplay or terminate active tasks (delays).\n\nUsage:\n    tasks[/switch] [task_id or function_name]\n\nSwitches:\n    pause   - Pause the callback of a task.\n    unpause - Process all callbacks made since pause() was called.\n    do_task - Execute the task (call its callback).\n    call    - Call the callback of this task.\n    remove  - Remove a task without executing it.\n    cancel  - Stop a task from automatically executing.\n\nNotes:\n    A task is a single use method of delaying the call of a function. Calls are created\n    in code, using `evennia.utils.delay`.\n    See |luhttps://www.evennia.com/docs/latest/Command-Duration.html|ltthe docs|le for help.\n\n    By default, tasks that are canceled and never called are cleaned up after one minute.\n\nExamples:\n    - `tasks/cancel move_callback` - Cancels all movement delays from the slow_exit contrib.\n        In this example slow exits creates it's tasks with\n        `utils.delay(move_delay, move_callback)`\n    - `tasks/cancel 2` - Cancel task id 2.\n\n"}

class evennia.commands.default.system.CmdTickers(**kwargs)

Bases: MuxCommand

View running tickers

Usage:

tickers

Note: Tickers are created, stopped and manipulated in Python code using the TickerHandler. This is merely a convenience function for inspecting the current status.

key = '@tickers'

help_category = 'system'

locks = 'cmd:perm(tickers) or perm(Builder)'

func()

This is the hook function that actually does all the work. It is called

by the cmdhandler right after self.parser() finishes, and so has access to all the variables defined therein.

aliases = []

lock_storage = 'cmd:perm(tickers) or perm(Builder)'

search_index_entry = {'aliases': '', 'category': 'system', 'key': '@tickers', 'no_prefix': 'tickers ', 'tags': '', 'text': '\nView running tickers\n\nUsage:\n  tickers\n\nNote: Tickers are created, stopped and manipulated in Python code\nusing the TickerHandler. This is merely a convenience function for\ninspecting the current status.\n\n'}

class evennia.commands.default.system.AccountDB(*args, **kwargs)

Bases: TypedObject, AbstractUser

This is a special model using Django’s ‘profile’ functionality and extends the default Django User model. It is defined as such by use of the variable AUTH_PROFILE_MODULE in the settings. One accesses the fields/methods. We try use this model as much as possible rather than User, since we can customize this to our liking.

The TypedObject supplies the following (inherited) properties:

• key - main name

• 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 AccountDB adds the following properties:

• is_connected - If any Session is currently connected to this Account

• name - alias for user.username

• sessions - sessions connected to this account

• is_superuser - bool if this account is a superuser

• is_bot - bool if this account is a bot and not a real account

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

account_subscription_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 cmdset_storage

Getter. Allows for value = self.name. Returns a list of cmdset_storage.

date_joined

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_cmdset_storage

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

db_date_created

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

db_is_bot

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

db_is_connected

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

db_key

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

db_lock_storage

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.

db_typeclass_path

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

email

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

first_name

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

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

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

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

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

groups

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.

hide_from_accounts_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.

id

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

is_active

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

property is_bot

A wrapper for getting database field db_is_bot.

property is_connected

A wrapper for getting database field db_is_connected.

is_staff

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

is_superuser

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

property key

last_login

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

last_name

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

logentry_set

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

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

**Parent.children** is a **ReverseManyToOneDescriptor** instance.

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

property name

objectdb_set

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

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

**Parent.children** is a **ReverseManyToOneDescriptor** instance.

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

objects = <evennia.accounts.manager.AccountDBManager object>

password

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

path = 'evennia.accounts.models.AccountDB'

receiver_account_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.

scriptdb_set

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

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

**Parent.children** is a **ReverseManyToOneDescriptor** instance.

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

sender_account_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.

typename = 'SharedMemoryModelBase'

property uid

Getter. Retrieves the user id

user_permissions

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.

username

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

evennia.commands.default.system.COMMAND_DEFAULT_CLASS

alias of MuxCommand

class evennia.commands.default.system.EvEditor(caller, loadfunc=None, savefunc=None, quitfunc=None, key='', persistent=False, codefunc=False)

Bases: object

This defines a line editor object. It creates all relevant commands and tracks the current state of the buffer. It also cleans up after itself.

__init__(caller, loadfunc=None, savefunc=None, quitfunc=None, key='', persistent=False, codefunc=False)

Launches a full in-game line editor, mimicking the functionality of VIM.

Parameters:

• caller (Object) – Who is using the editor.

• loadfunc (callable, optional) – This will be called as loadfunc(caller) when the editor is first started. Its return will be used as the editor’s starting buffer.

• savefunc (callable, optional) – This will be called as savefunc(caller, buffer) when the save-command is given and is used to actually determine where/how result is saved. It should return True if save was successful and also handle any feedback to the user.

• quitfunc (callable, optional) – This will optionally be called as quitfunc(caller) when the editor is exited. If defined, it should handle all wanted feedback to the user.

• quitfunc_args (tuple, optional) – Optional tuple of arguments to supply to quitfunc.

• key (str, optional) – An optional key for naming this session and make it unique from other editing sessions.

• persistent (bool, optional) – Make the editor survive a reboot. Note that if this is set, all callables must be possible to pickle

• codefunc (bool, optional) – If given, will run the editor in code mode. This will be called as codefunc(caller, buf).

Notes

In persistent mode, all the input callables (savefunc etc) must be possible to be pickled, this excludes e.g. callables that are class methods or functions defined dynamically or as part of another function. In non-persistent mode no such restrictions exist.

decrease_indent()

Decrease automatic indentation by 1 level.

deduce_indent(line, buffer)

Try to deduce the level of indentation of the given line.

display_buffer(buf=None, offset=0, linenums=True, options={'raw': False})

This displays the line editor buffer, or selected parts of it.

Parameters:

• buf (str, optional) – The buffer or part of buffer to display.

• offset (int, optional) – If buf is set and is not the full buffer, offset should define the actual starting line number, to get the linenum display right.

• linenums (bool, optional) – Show line numbers in buffer.

• options – raw (bool, optional): Tell protocol to not parse formatting information.

display_help()

Shows the help entry for the editor.

get_buffer()

Returns:

buffer (str) – The current buffer.

increase_indent()

Increase automatic indentation by 1 level.

load_buffer()

Load the buffer using the load function hook.

quit()

Cleanly exit the editor.

save_buffer()

Saves the content of the buffer.

swap_autoindent()

Swap automatic indentation on or off.

update_buffer(buf)

This should be called when the buffer has been changed somehow. It will handle unsaved flag and undo updating.

Parameters:

buf (str) – The text to update the buffer with.

update_undo(step=None)

This updates the undo position.

Parameters:

step (int, optional) – The amount of steps to progress the undo position to. This may be a negative value for undo and a positive value for redo.

class evennia.commands.default.system.EvTable(*args, **kwargs)

Bases: object

The table class holds a list of EvColumns, each consisting of EvCells so that the result is a 2D matrix.

__init__(*args, **kwargs)

Parameters:

table. (Header texts for the)

Keyword Arguments:

• table (list of lists or list of EvColumns, optional) – This is used to build the table in a quick way. If not given, the table will start out empty and add_ methods need to be used to add rows/columns.

• header (bool, optional) – True/False - turn off the header texts (*args) being treated as a header (such as not adding extra underlining)

• pad_width (int, optional) – How much empty space to pad your cells with (default is 1)

• border (str, optional)) – The border style to use. This is one of - None - No border drawing at all. - “table” - only a border around the whole table. - “tablecols” - table and column borders. (default) - “header” - only border under header. - “cols” - only vertical borders. - “incols” - vertical borders, no outer edges. - “rows” - only borders between rows. - “cells” - border around all cells.

• border_width (int, optional) – Width of table borders, if border is active. Note that widths wider than 1 may give artifacts in the corners. Default is 1.

• corner_char (str, optional) – Character to use in corners when border is active. Default is +.

• corner_top_left_char (str, optional) – Character used for “nw” corner of table. Defaults to corner_char.

• corner_top_right_char (str, optional) – Character used for “ne” corner of table. Defaults to corner_char.

• corner_bottom_left_char (str, optional) – Character used for “sw” corner of table. Defaults to corner_char.

• corner_bottom_right_char (str, optional) – Character used for “se” corner of table. Defaults to corner_char.

• pretty_corners (bool, optional) – Use custom characters to make the table corners look “rounded”. Uses UTF-8 characters. Defaults to False for maximum compatibility with various displays that may occationally have issues with UTF-8 characters.

• header_line_char (str, optional) – Character to use for underlining the header row (default is ‘~’). Requires border to not be None.

• width (int, optional) – Fixed width of table. If not set, width is set by the total width of each column. This will resize individual columns in the vertical direction to fit.

• height (int, optional) – Fixed height of table. Defaults to being unset. Width is still given precedence. If given, table cells will crop text rather than expand vertically.

• evenwidth (bool, optional) – Used with the width keyword. Adjusts columns to have as even width as possible. This often looks best also for mixed-length tables. Default is False.

• maxwidth (int, optional) – This will set a maximum width of the table while allowing it to be smaller. Only if it grows wider than this size will it be resized by expanding horizontally (or crop height is given). This keyword has no meaning if width is set.

Raises:

Exception – If given erroneous input or width settings for the data.

Notes

Beyond those table-specific keywords, the non-overlapping keywords of EvCell.__init__ are also available. These will be passed down to every cell in the table.

add_column(*args, **kwargs)

Add a column to table. If there are more rows in new column than there are rows in the current table, the table will expand with empty rows in the other columns. If too few, the new column with get new empty rows. All filling rows are added to the end.

Parameters:

• args (EvColumn or multiple strings) – Either a single EvColumn instance or a number of data string arguments to be used to create a new column.

• header (str, optional) – The header text for the column

• xpos (int, optional) – Index position in table before which to input new column. If not given, column will be added to the end of the table. Uses Python indexing (so first column is xpos=0)

Keyword Arguments:

Cell.__init__. (Other keywords as per)

add_header(*args, **kwargs)

Add header to table. This is a number of texts to be put at the top of the table. They will replace an existing header.

Parameters:

args (str) – These strings will be used as the header texts.

Keyword Arguments:

• applied (Same keywords as per EvTable.__init__. Will be)

• cells. (to the new header's)

add_row(*args, **kwargs)

Add a row to table (not a header). If there are more cells in the given row than there are cells in the current table the table will be expanded with empty columns to match. These will be added to the end of the table. In the same way, adding a line with too few cells will lead to the last ones getting padded.

Parameters:

• args (str) – Any number of string argumnets to use as the data in the row (one cell per argument).

• ypos (int, optional) – Index position in table before which to input new row. If not given, will be added to the end of the table. Uses Python indexing (so first row is ypos=0)

Keyword Arguments:

EvCell.__init__. (Other keywords are as per)

get()

Return lines of table as a list.

Returns:

table_lines (list) – The lines of the table, in order.

reformat(**kwargs)

Force a re-shape of the entire table.

Keyword Arguments:

EvTable.__init__. (Table options as per)

reformat_column(index, **kwargs)

Sends custom options to a specific column in the table.

Parameters:

index (int) – Which column to reformat. The column index is given from 0 to Ncolumns-1.

Keyword Arguments:

EvCell.__init__. (Column options as per)

Raises:

Exception – if an invalid index is found.

class evennia.commands.default.system.EvenniaPythonConsole(caller)

Bases: InteractiveConsole

Evennia wrapper around a Python interactive console.

__init__(caller)

Constructor.

The optional locals argument will be passed to the InteractiveInterpreter base class.

The optional filename argument should specify the (file)name of the input stream; it will show up in tracebacks.

write(string)

Don’t send to stderr, send to self.caller.

push(line)

Push some code, whether complete or not.

exception evennia.commands.default.system.PrintRecursionError

Bases: RecursionError

class evennia.commands.default.system.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)

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.

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.

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.

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.

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.

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_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.

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.

pause()

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

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.

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.

unpause()

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

evennia.commands.default.system.ask_yes_no(caller, prompt='Yes or No {options}?', yes_action='Yes', no_action='No', default=None, allow_abort=False, session=None, *args, **kwargs)

A helper function for asking a simple yes/no question. This will cause the system to pause and wait for input from the player.

Parameters:

• caller (Object) – The entity being asked.

• prompt (str) – The yes/no question to ask. This takes an optional formatting marker {options} which will be filled with ‘Y/N’, ‘[Y]/N’ or ‘Y/[N]’ depending on the setting of default. If allow_abort is set, then the ‘A(bort)’ option will also be available.

• yes_action (callable or str) – If a callable, this will be called with (caller, *args, **kwargs) when the Yes-choice is made. If a string, this string will be echoed back to the caller.

• no_action (callable or str) – If a callable, this will be called with (caller, *args, **kwargs) when the No-choice is made. If a string, this string will be echoed back to the caller.

• default (str optional) – This is what the user will get if they just press the return key without giving any input. One of ‘N’, ‘Y’, ‘A’ or None for no default (an explicit choice must be given). If ‘A’ (abort) is given, allow_abort kwarg is ignored and assumed set.

• allow_abort (bool, optional) – If set, the ‘A(bort)’ option is available (a third option meaning neither yes or no but just exits the prompt).

• session (Session, optional) – This allows to specify the session to send the prompt to. It’s usually only needed if caller is an Account in multisession modes greater than 2. The session is then updated by the command and is available (for example in callbacks) through caller.ndb._yes_no_question.session.

• *args – Additional arguments passed on into callables.

• **kwargs – Additional keyword args passed on into callables.

Raises:

RuntimeError, FooError – If default and allow_abort clashes.

Example

# just returning strings
ask_yes_no(caller, "Are you happy {options}?",
           "you answered yes", "you answered no")
# trigger callables
ask_yes_no(caller, "Are you sad {options}?",
           _callable_yes, _callable_no, allow_abort=True)

evennia.commands.default.system.class_from_module(path, defaultpaths=None, fallback=None)

Return a class from a module, given the class’ full python path. This is primarily used to convert db_typeclass_path:s to classes.

Parameters:

• path (str) – Full Python dot-path to module.

• defaultpaths (iterable, optional) – If a direct import from path fails, try subsequent imports by prepending those paths to path.

• fallback (str) – If all other attempts fail, use this path as a fallback. This is intended as a last-resort. In the example of Evennia loading, this would be a path to a default parent class in the evennia repo itself.

Returns:

class (Class) – An uninstantiated class recovered from path.

Raises:

ImportError – If all loading failed.

evennia.commands.default.system.evennia_local_vars(caller)

Return Evennia local variables usable in the py command as a dictionary.

evennia.commands.default.system.iter_to_str(iterable, sep=',', endsep=', and', addquote=False)

This pretty-formats an iterable list as string output, adding an optional alternative separator to the second to last entry. If addquote is True, the outgoing strings will be surrounded by quotes.

Parameters:

• iterable (any) – Usually an iterable to print. Each element must be possible to present with a string. Note that if this is a generator, it will be consumed by this operation.

• sep (str, optional) – The string to use as a separator for each item in the iterable.

• endsep (str, optional) – The last item separator will be replaced with this value.

• addquote (bool, optional) – This will surround all outgoing values with double quotes.

Returns:

str – The list represented as a string.

Notes

Default is to use ‘Oxford comma’, like 1, 2, 3, and 4.

Examples

>>> iter_to_string([1,2,3], endsep=',')
'1, 2, 3'
>>> iter_to_string([1,2,3], endsep='')
'1, 2 3'
>>> iter_to_string([1,2,3], ensdep='and')
'1, 2 and 3'
>>> iter_to_string([1,2,3], sep=';', endsep=';')
'1; 2; 3'
>>> iter_to_string([1,2,3], addquote=True)
'"1", "2", and "3"'