evennia.accounts.accounts

Typeclass for Account objects.

Note that this object is primarily intended to store OOC information, not game info! This object represents the actual user (not their character) and has NO actual presence in the game world (this is handled by the associated character object, so you should customize that instead for most things).

class evennia.accounts.accounts.DefaultAccount(*args, **kwargs)

Bases: AccountDB

This is the base Typeclass for all Accounts. Accounts represent the person playing the game and tracks account info, password etc. They are OOC entities without presence in-game. An Account can connect to a Character Object in order to “enter” the game.

Account Typeclass API:

• Available properties (only available on initiated typeclass objects)

• key (string) - name of account

• name (string)- wrapper for user.username

• aliases (list of strings) - aliases to the object. Will be saved to

  database as AliasDB entries but returned as strings.

• dbref (int, read-only) - unique #id-number. Also “id” can be used.

• date_created (string) - time stamp of object creation

• permissions (list of strings) - list of permission strings

• user (User, read-only) - django User authorization object

• obj (Object) - game object controlled by account. ‘character’ can also

  be used.

• is_superuser (bool, read-only) - if the connected user is a superuser

• Handlers

• locks - lock-handler: use locks.add() to add new lock strings

• db - attribute-handler: store/retrieve database attributes on this

  self.db.myattr=val, val=self.db.myattr

• ndb - non-persistent attribute handler: same as db but does not

  create a database entry when storing data

• scripts - script-handler. Add new scripts to object with scripts.add()

• cmdset - cmdset-handler. Use cmdset.add() to add new cmdsets to object

• nicks - nick-handler. New nicks with nicks.add().

• sessions - session-handler. Use session.get() to see all sessions connected, if any

• options - option-handler. Defaults are taken from settings.OPTIONS_ACCOUNT_DEFAULT

• characters - handler for listing the account’s playable characters

• Helper methods (check autodocs for full updated listing)

• msg(text=None, from_obj=None, session=None, options=None, **kwargs)

• execute_cmd(raw_string)

• search(searchdata, return_puppet=False, search_object=False, typeclass=None,

  nofound_string=None, multimatch_string=None, use_nicks=True, quiet=False, **kwargs)

• is_typeclass(typeclass, exact=False)

• swap_typeclass(new_typeclass, clean_attributes=False, no_default=True)

• access(accessing_obj, access_type=’read’, default=False, no_superuser_bypass=False, **kwargs)

• check_permstring(permstring)

• get_cmdsets(caller, current, **kwargs)

• get_cmdset_providers()

• uses_screenreader(session=None)

• get_display_name(looker, **kwargs)

• get_extra_display_name_info(looker, **kwargs)

• disconnect_session_from_account()

• puppet_object(session, obj)

• unpuppet_object(session)

• unpuppet_all()

• get_puppet(session)

• get_all_puppets()

• is_banned(**kwargs)

• get_username_validators(validator_config=settings.AUTH_USERNAME_VALIDATORS)

• authenticate(username, password, ip=””, **kwargs)

• normalize_username(username)

• validate_username(username)

• validate_password(password, account=None)

• set_password(password, **kwargs)

• get_character_slots()

• get_available_character_slots()

• create_character(*args, **kwargs)

• create(*args, **kwargs)

• delete(*args, **kwargs)

• channel_msg(message, channel, senders=None, **kwargs)

• idle_time()

• connection_time()

• Hook methods

basetype_setup() at_account_creation()

> note that the following hooks are also found on Objects and are

usually handled on the character level:

• at_init()

• at_first_save()

• at_access()

• at_cmdset_get(**kwargs)

• at_password_change(**kwargs)

• at_first_login()

• at_pre_login()

• at_post_login(session=None)

• at_failed_login(session, **kwargs)

• at_disconnect(reason=None, **kwargs)

• at_post_disconnect(**kwargs)

• at_message_receive()

• at_message_send()

• at_server_reload()

• at_server_shutdown()

• at_look(target=None, session=None, **kwargs)

• at_post_create_character(character, **kwargs)

• at_post_add_character(char)

• at_post_remove_character(char)

• at_pre_channel_msg(message, channel, senders=None, **kwargs)

• at_post_chnnel_msg(message, channel, senders=None, **kwargs)

cmdset_provider_order = 50

cmdset_provider_error_order = 0

cmdset_provider_type = 'account'

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

default_character_typeclass = 'typeclasses.characters.Character'

lockstring = 'examine:perm(Admin);edit:perm(Admin);delete:perm(Admin);boot:perm(Admin);msg:all();noidletimeout:perm(Builder) or perm(noidletimeout)'

cmdset

scripts

nicks

sessions

options

characters

get_cmdset_providers() → dict[str, CmdSetProvider]

Overrideable method which returns a dictionary of every kind of object which has a cmdsethandler linked to this Account, and should participate in cmdset merging.

Accounts have no way of being aware of anything besides themselves, unfortunately.

Returns:

dict[str, CmdSetProvider] – The CmdSetProviders linked to this Object.

at_post_add_character(character: DefaultCharacter)

Called after a character is added to this account’s list of playable characters.

Use it to easily implement custom logic when a character is added to an account.

Parameters:

character (DefaultCharacter) – The character that was added.

at_post_remove_character(character: DefaultCharacter)

Called after a character is removed from this account’s list of playable characters.

Use it to easily implement custom logic when a character is removed from an account.

Parameters:

character (DefaultCharacter) – The character that was removed.

uses_screenreader(session=None)

Shortcut to determine if a session uses a screenreader. If no session given, will return true if any of the sessions use a screenreader.

Parameters:

session (Session, optional) – The session to check for screen reader.

get_extra_display_name_info(looker, **kwargs)

Used in .get_display_name() to provide extra information to the looker. We split this to be consistent with the Object version of this method.

This is used e.g. by the find command by default.

get_display_name(looker, **kwargs)

This is used by channels and other OOC communications methods to give a custom display of this account’s input.

Parameters:

• looker (Account) – The one that will see this name.

• **kwargs – Unused by default, can be used to pass game-specific data.

Returns:

str – The name, possibly modified.

disconnect_session_from_account(session, reason=None)

Access method for disconnecting a given session from the account (connection happens automatically in the sessionhandler)

Parameters:

• session (Session) – Session to disconnect.

• reason (str, optional) – Eventual reason for the disconnect.

puppet_object(session, obj)

Use the given session to control (puppet) the given object (usually a Character type).

Parameters:

• session (Session) – session to use for puppeting

• obj (Object) – the object to start puppeting

Raises:

RuntimeError – If puppeting is not possible, the exception.msg will contain the reason.

unpuppet_object(session)

Disengage control over an object.

Parameters:

session (Session or list) – The session or a list of sessions to disengage from their puppets.

Raises:

RuntimeError With message about error. –

unpuppet_all()

Disconnect all puppets. This is called by server before a reset/shutdown.

get_puppet(session)

Get an object puppeted by this session through this account. This is the main method for retrieving the puppeted object from the account’s end.

Parameters:

session (Session) – Find puppeted object based on this session

Returns:

puppet (Object) – The matching puppeted object, if any.

get_all_puppets()

Get all currently puppeted objects.

Returns:

puppets (list) –

All puppeted objects currently controlled

by this Account.

property character

This is a legacy convenience link for use with MULTISESSION_MODE.

Returns:

puppets (Object or list) –

Users of MULTISESSION_MODE 0 or 1 will

always get the first puppet back. Users of higher **MULTISESSION_MODE**s will get a list of all puppeted objects.

property puppet

This is a legacy convenience link for use with MULTISESSION_MODE.

Returns:

puppets (Object or list) –

Users of MULTISESSION_MODE 0 or 1 will

always get the first puppet back. Users of higher **MULTISESSION_MODE**s will get a list of all puppeted objects.

classmethod is_banned(**kwargs)

Checks if a given username or IP is banned.

Keyword Arguments:

• ip (str, optional) – IP address.

• username (str, optional) – Username.

Returns:

is_banned (bool) – Whether either is banned or not.

classmethod get_username_validators(validator_config=[{'NAME': 'django.contrib.auth.validators.ASCIIUsernameValidator'}, {'NAME': 'django.core.validators.MinLengthValidator', 'OPTIONS': {'limit_value': 3}}, {'NAME': 'django.core.validators.MaxLengthValidator', 'OPTIONS': {'limit_value': 30}}, {'NAME': 'evennia.server.validators.EvenniaUsernameAvailabilityValidator'}])

Retrieves and instantiates validators for usernames.

Parameters:

validator_config (list) – List of dicts comprising the battery of validators to apply to a username.

Returns:

validators (list) – List of instantiated Validator objects.

classmethod authenticate(username, password, ip='', **kwargs)

Checks the given username/password against the database to see if the credentials are valid.

Note that this simply checks credentials and returns a valid reference to the user– it does not log them in!

To finish the job: After calling this from a Command, associate the account with a Session: - session.sessionhandler.login(session, account)

…or after calling this from a View, associate it with an HttpRequest: - django.contrib.auth.login(account, request)

Parameters:

• username (str) – Username of account

• password (str) – Password of account

• ip (str, optional) – IP address of client

Keyword Arguments:

session (Session, optional) – Session requesting authentication

Returns:

account (DefaultAccount, None) –

Account whose credentials were

provided if not banned.

errors (list): Error messages of any failures.

classmethod normalize_username(username)

Django: Applies NFKC Unicode normalization to usernames so that visually identical characters with different Unicode code points are considered identical.

(This deals with the Turkish “i” problem and similar annoyances. Only relevant if you go out of your way to allow Unicode usernames though– Evennia accepts ASCII by default.)

In this case we’re simply piggybacking on this feature to apply additional normalization per Evennia’s standards.

classmethod validate_username(username)

Checks the given username against the username validator associated with Account objects, and also checks the database to make sure it is unique.

Parameters:

username (str) – Username to validate

Returns:

valid (bool) – Whether or not the password passed validation errors (list): Error messages of any failures

classmethod validate_password(password, account=None)

Checks the given password against the list of Django validators enabled in the server.conf file.

Parameters:

password (str) – Password to validate

Keyword Arguments:

account (DefaultAccount, optional) – Account object to validate the password for. Optional, but Django includes some validators to do things like making sure users aren’t setting passwords to the same value as their username. If left blank, these user-specific checks are skipped.

Returns:

valid (bool) – Whether or not the password passed validation error (ValidationError, None): Any validation error(s) raised. Multiple

errors can be nested within a single object.

set_password(password, **kwargs)

Applies the given password to the account. Logs and triggers the at_password_change hook.

Parameters:

password (str) – Password to set.

Notes

This is called by Django also when logging in; it should not be mixed up with validation, since that would mean old passwords in the database (pre validation checks) could get invalidated.

get_character_slots() → int | None

Returns the number of character slots this account has, or None if there are no limits.

By default, that’s settings.MAX_NR_CHARACTERS but this makes it easy to override. Maybe for your game, players can be rewarded with more slots, somehow.

Returns:

int (optional) –

The number of character slots this account has, or None

if there are no limits.

get_available_character_slots() → int | None

Returns the number of character slots this account has available, or None if there are no limits.

Returns:

int (optional) –

The number of open character slots this account has, or None

if there are no limits.

check_available_slots(**kwargs) → str | None

Helper method used to determine if an account can create additional characters using the character slot system.

Returns:

str (optional) –

An error message regarding the status of slots. If present, this

will halt character creation. If not, character creation can proceed.

create_character(*args, **kwargs)

Create a character linked to this account.

Parameters:

• key (str, optional) – If not given, use the same name as the account.

• typeclass (str, optional) – Typeclass to use for this character. If not given, use self.default_character_class.

• permissions (list, optional) – If not given, use the account’s permissions.

• ip (str, optional) – The client IP creating this character. Will fall back to the one stored for the account if not given.

• kwargs (any) – Other kwargs will be used in the create_call.

Returns:

Object – A new character of the character_typeclass type. None on an error. list or None: A list of errors, or None.

at_post_create_character(character, **kwargs)

An overloadable hook method that allows for further customization of newly created characters.

classmethod create(*args, **kwargs)

Creates an Account (or Account/Character pair for MULTISESSION_MODE<2) with default (or overridden) permissions and having joined them to the appropriate default channels.

Keyword Arguments:

• username (str) – Username of Account owner

• password (str) – Password of Account owner

• email (str, optional) – Email address of Account owner

• ip (str, optional) – IP address of requesting connection

• guest (bool, optional) – Whether or not this is to be a Guest account

• permissions (str, optional) – Default permissions for the Account

• typeclass (str, optional) – Typeclass to use for new Account

• character_typeclass (str, optional) – Typeclass to use for new char when applicable.

Returns:

account (Account) – Account if successfully created; None if not errors (list): List of error messages in string form

delete(*args, **kwargs)

Deletes the account persistently.

Notes

*args and **kwargs are passed on to the base delete

mechanism (these are usually not used).

Returns:

bool –

If deletion was successful. Only time it fails would be

if the Account was already deleted. Note that even on a failure, connected resources (nicks/aliases etc) will still have been deleted.

msg(text=None, from_obj=None, session=None, options=None, **kwargs)

Evennia -> User This is the main route for sending data back to the user from the server.

Parameters:

• text (str or tuple, optional) – The message to send. This is treated internally like any send-command, so its value can be a tuple if sending multiple arguments to the text oob command.

• from_obj (Object or Account or list, optional) – Object sending. If given, its at_msg_send() hook will be called. If iterable, call on all entities.

• session (Session or list, optional) – Session object or a list of Sessions to receive this send. If given, overrules the default send behavior for the current MULTISESSION_MODE.

• options (list) – Protocol-specific options. Passed on to the protocol.

Keyword Arguments:

any (dict) – All other keywords are passed on to the protocol.

execute_cmd(raw_string, session=None, **kwargs)

Do something as this account. This method is never called normally, but only when the account object itself is supposed to execute the command. It takes account nicks into account, but not nicks of eventual puppets.

Parameters:

• raw_string (str) – Raw command input coming from the command line.

• session (Session, optional) – The session to be responsible for the command-send

Keyword Arguments:

kwargs (any) – Other keyword arguments will be added to the found command object instance as variables before it executes. This is unused by default Evennia but may be used to set flags and change operating parameters for commands at run-time.

at_pre_channel_msg(message, channel, senders=None, **kwargs)

Called by the Channel just before passing a message into channel_msg. This allows for tweak messages per-user and also to abort the receive on the receiver-level.

Parameters:

• message (str) – The message sent to the channel.

• channel (Channel) – The sending channel.

• senders (list, optional) – Accounts or Objects acting as senders. For most normal messages, there is only a single sender. If there are no senders, this may be a broadcasting message.

• **kwargs – These are additional keywords passed into channel_msg. If no_prefix=True or emit=True are passed, the channel prefix will not be added (**[channelname]: ** by default)

Returns:

str or None –

Allows for customizing the message for this recipient.

If returning None (or False) message-receiving is aborted. The returning string will be passed into self.channel_msg.

Notes

This support posing/emotes by starting channel-send with : or ;.

channel_msg(message, channel, senders=None, **kwargs)

This performs the actions of receiving a message to an un-muted channel.

Parameters:

• message (str) – The message sent to the channel.

• channel (Channel) – The sending channel.

• senders (list, optional) – Accounts or Objects acting as senders. For most normal messages, there is only a single sender. If there are no senders, this may be a broadcasting message or similar.

• **kwargs – These are additional keywords originally passed into Channel.msg.

Notes

Before this, Channel.at_pre_channel_msg will fire, which offers a way to customize the message for the receiver on the channel-level.

at_post_channel_msg(message, channel, senders=None, **kwargs)

Called by self.channel_msg after message was received.

Parameters:

• message (str) – The message sent to the channel.

• channel (Channel) – The sending channel.

• senders (list, optional) – Accounts or Objects acting as senders. For most normal messages, there is only a single sender. If there are no senders, this may be a broadcasting message.

• **kwargs – These are additional keywords passed into channel_msg.

search(searchdata, return_puppet=False, search_object=False, typeclass=None, nofound_string=None, multimatch_string=None, use_nicks=True, quiet=False, **kwargs)

This is similar to DefaultObject.search but defaults to searching for Accounts only.

Parameters:

• searchdata (str or int) – Search criterion, the Account’s key or dbref to search for.

• return_puppet (bool, optional) – Instructs the method to return matches as the object the Account controls rather than the Account itself (or None) if nothing is puppeted).

• search_object (bool, optional) – Search for Objects instead of Accounts. This is used by e.g. the @examine command when wanting to examine Objects while OOC.

• typeclass (Account typeclass, optional) – Limit the search only to this particular typeclass. This can be used to limit to specific account typeclasses or to limit the search to a particular Object typeclass if search_object is True.

• nofound_string (str, optional) – A one-time error message to echo if searchdata leads to no matches. If not given, will fall back to the default handler.

• multimatch_string (str, optional) – A one-time error message to echo if searchdata leads to multiple matches. If not given, will fall back to the default handler.

• use_nicks (bool, optional) – Use account-level nick replacement.

• quiet (bool, optional) – If set, will not show any error to the user, and will also lead to returning a list of matches.

Returns:

match (Account, Object or None) – A single Account or Object match. list: If quiet=True this is a list of 0, 1 or more Account or Object matches.

Notes

Extra keywords are ignored, but are allowed in call in order to make API more consistent with objects.objects.DefaultObject.search.

access(accessing_obj, access_type='read', default=False, no_superuser_bypass=False, **kwargs)

Determines if another object has permission to access this object in whatever way.

Parameters:

• accessing_obj (Object) – Object trying to access this one.

• access_type (str, optional) – Type of access sought.

• default (bool, optional) – What to return if no lock of access_type was found

• no_superuser_bypass (bool, optional) – Turn off superuser lock bypassing. Be careful with this one.

Keyword Arguments:

kwargs (any) – Passed to the at_access hook along with the result.

Returns:

result (bool) – Result of access check.

property idle_time

Returns the idle time of the least idle session in seconds. If no sessions are connected it returns nothing.

property connection_time

Returns the maximum connection time of all connected sessions in seconds. Returns nothing if there are no sessions.

basetype_setup()

This sets up the basic properties for an account. Overload this with at_account_creation rather than changing this method.

at_account_creation()

This is called once, the very first time the account is created (i.e. first time they register with the game). It’s a good place to store attributes all accounts should have, like configuration values etc.

at_init()

This is always called whenever this object is initiated – that is, whenever it its typeclass is cached from memory. This happens on-demand first time the object is used or activated in some way after being created but also after each server restart or reload. In the case of account objects, this usually happens the moment the account logs in or reconnects after a reload.

at_first_save()

This is a generic hook called by Evennia when this object is saved to the database the very first time. You generally don’t override this method but the hooks called by it.

at_access(result, accessing_obj, access_type, **kwargs)

This is triggered after an access-call on this Account has

completed.

Parameters:

• result (bool) – The result of the access check.

• accessing_obj (any) – The object requesting the access check.

• access_type (str) – The type of access checked.

Keyword Arguments:

kwargs (any) – These are passed on from the access check and can be used to relay custom instructions from the check mechanism.

Notes

This method cannot affect the result of the lock check and its return value is not used in any way. It can be used e.g. to customize error messages in a central location or create other effects based on the access result.

at_cmdset_get(**kwargs)

Called just before cmdsets on this object are requested by the command handler. If changes need to be done on the fly to the cmdset before passing them on to the cmdhandler, this is the place to do it. This is called also if the object currently have no cmdsets.

Keyword Arguments:

• caller (Object, Account or Session) – The object requesting the cmdsets.

• current (CmdSet) – The current merged cmdset.

• force_init (bool) – If True, force a re-build of the cmdset. (seems unused)

• **kwargs – Arbitrary input for overloads.

get_cmdsets(caller, current, **kwargs)

Called by the CommandHandler to get a list of cmdsets to merge.

Parameters:

• caller (obj) – The object requesting the cmdsets.

• current (cmdset) – The current merged cmdset.

• **kwargs – Arbitrary input for overloads.

Returns:

tuple – A tuple of (current, cmdsets), which is probably self.cmdset.current and self.cmdset.cmdset_stack

at_first_login(**kwargs)

Called the very first time this account logs into the game. Note that this is called before at_pre_login, so no session is established and usually no character is yet assigned at this point. This hook is intended for account-specific setup like configurations.

Parameters:

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

at_password_change(**kwargs)

Called after a successful password set/modify.

Parameters:

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

at_pre_login(**kwargs)

Called every time the user logs in, just before the actual login-state is set.

Parameters:

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

at_post_login(session=None, **kwargs)

Called at the end of the login process, just before letting the account loose.

Parameters:

• session (Session, optional) – Session logging in, if any.

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

Notes

This is called before an eventual Character’s at_post_login hook. By default it is used to set up auto-puppeting based on MULTISESSION_MODE

at_failed_login(session, **kwargs)

Called by the login process if a user account is targeted correctly but provided with an invalid password. By default it does nothing, but exists to be overridden.

Parameters:

• session (session) – Session logging in.

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

at_disconnect(reason=None, **kwargs)

Called just before user is disconnected.

Parameters:

• reason (str, optional) – The reason given for the disconnect, (echoed to the connection channel by default).

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

at_post_disconnect(**kwargs)

This is called after disconnection is complete. No messages can be relayed to the account from here. After this call, the account should not be accessed any more, making this a good spot for deleting it (in the case of a guest account account, for example).

Parameters:

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

at_msg_receive(text=None, from_obj=None, **kwargs)

This hook is called whenever someone sends a message to this object using the msg method.

Note that from_obj may be None if the sender did not include itself as an argument to the obj.msg() call - so you have to check for this. .

Consider this a pre-processing method before msg is passed on to the user session. If this method returns False, the msg will not be passed on.

Parameters:

• text (str, optional) – The message received.

• from_obj (any, optional) – The object sending the message.

Keyword Arguments:

method. (This includes any keywords sent to the msg)

Returns:

receive (bool) – If this message should be received.

Notes

If this method returns False, the msg operation will abort without sending the message.

at_msg_send(text=None, to_obj=None, **kwargs)

This is a hook that is called when this object sends a message to another object with obj.msg(text, to_obj=obj).

Parameters:

• text (str, optional) – Text to send.

• to_obj (any, optional) – The object to send to.

Keyword Arguments:

msg() (Keywords passed from)

Notes

Since this method is executed by from_obj, if no from_obj was passed to DefaultCharacter.msg this hook will never get called.

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

ooc_appearance_template = '--------------------------------------------------------------------\n{header}\n\n{sessions}\n\n  |whelp|n - more commands\n  |wpublic <text>|n - talk on public channel\n  |wcharcreate <name> [=description]|n - create new character\n  |wchardelete <name>|n - delete a character\n  |wic <name>|n - enter the game as character (|wooc|n to get back here)\n  |wic|n - enter the game as latest character controlled.\n\n{characters}\n{footer}\n--------------------------------------------------------------------'

at_look(target=None, session=None, **kwargs)

Called when this object executes a look. It allows to customize just what this means.

Parameters:

• target (Object or list, optional) – An object or a list objects to inspect. This is normally a list of characters.

• session (Session, optional) – The session doing this look.

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

Returns:

look_string (str) –

A prepared look string, ready to send

off to any recipient (usually to ourselves)

exception DoesNotExist

Bases: DoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

path = 'evennia.accounts.accounts.DefaultAccount'

typename = 'DefaultAccount'

class evennia.accounts.accounts.DefaultGuest(*args, **kwargs)

Bases: DefaultAccount

This class is used for guest logins. Unlike Accounts, Guests and their characters are deleted after disconnection.

classmethod create(**kwargs)

Forwards request to cls.authenticate(); returns a DefaultGuest object if one is available for use.

classmethod authenticate(**kwargs)

Gets or creates a Guest account object.

Keyword Arguments:

ip (str, optional) – IP address of requester; used for ban checking, throttling and logging

Returns:

account (Object) – Guest account object, if available errors (list): List of error messages accrued during this request.

at_post_login(session=None, **kwargs)

By default, Guests only have one character regardless of which MAX_NR_CHARACTERS we use. They also always auto-puppet a matching character and don’t get a choice.

Parameters:

• session (Session, optional) – Session connecting.

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

at_server_shutdown()

We repeat the functionality of at_disconnect() here just to be on the safe side.

at_post_disconnect(**kwargs)

Once having disconnected, destroy the guest’s characters and

Parameters:

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

exception DoesNotExist

Bases: DoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

path = 'evennia.accounts.accounts.DefaultGuest'

typename = 'DefaultGuest'

class evennia.accounts.accounts.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.

class evennia.accounts.accounts.AccountManager(*args, **kwargs)

Bases: AccountDBManager, TypeclassManager

class evennia.accounts.accounts.AccountSessionHandler(account)

Bases: object

Manages the session(s) attached to an account.

__init__(account)

Initializes the handler.

Parameters:

account (Account) – The Account on which this handler is defined.

get(sessid=None)

Get the sessions linked to this object.

Parameters:

sessid (int, optional) – Specify a given session by session id.

Returns:

sessions (list) –

A list of Session objects. If sessid

is given, this is a list with one (or zero) elements.

all()

Alias to get(), returning all sessions.

Returns:

sessions (list) – All sessions.

count()

Get amount of sessions connected.

Returns:

sesslen (int) – Number of sessions handled.

class evennia.accounts.accounts.ChannelDB(*args, **kwargs)

Bases: TypedObject

This is the basis of a comm channel, only implementing the very basics of distributing messages.

The Channel class defines the following database fields beyond the ones inherited from TypedObject:

• db_account_subscriptions: The Account subscriptions.

• db_object_subscriptions: The Object subscriptions.

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

db_account_subscriptions

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

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

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.

objects = <evennia.comms.managers.ChannelDBManager object>

path = 'evennia.comms.models.ChannelDB'

subscriptions

typename = 'SharedMemoryModelBase'

class evennia.accounts.accounts.CharactersHandler(owner: DefaultAccount)

Bases: object

A simple Handler that lives on DefaultAccount as .characters via @lazy_property used to wrap access to .db._playable_characters.

__init__(owner: DefaultAccount)

Create the CharactersHandler.

Parameters:

owner – The Account that owns this handler.

add(character: DefaultCharacter)

Add a character to this account’s list of playable characters.

Parameters:

character (DefaultCharacter) – The character to add.

remove(character: DefaultCharacter)

Remove a character from this account’s list of playable characters.

Parameters:

character (DefaultCharacter) – The character to remove.

all() → list[DefaultCharacter]

Get all playable characters.

Returns:

list[DefaultCharacter] – All playable characters.

count() → int

Get the number of playable characters.

Returns:

int – The number of playable characters.

class evennia.accounts.accounts.CmdSetHandler(obj, init_true=True)

Bases: object

The CmdSetHandler is always stored on an object, this object is supplied as an argument.

The ‘current’ cmdset is the merged set currently active for this object. This is the set the game engine will retrieve when determining which commands are available to the object. The cmdset_stack holds a history of all CmdSets to allow the handler to remove/add cmdsets at will. Doing so will re-calculate the ‘current’ cmdset.

__init__(obj, init_true=True)

This method is called whenever an object is recreated.

Parameters:

• obj (Object) – An reference to the game object this handler belongs to.

• init_true (bool, optional) – Set when the handler is initializing and loads the current cmdset.

add(cmdset, emit_to_obj=None, persistent=False, default_cmdset=False, **kwargs)

Add a cmdset to the handler, on top of the old ones, unless it is set as the default one (it will then end up at the bottom of the stack)

Parameters:

• cmdset (CmdSet or str) – Can be a cmdset object or the python path to such an object.

• emit_to_obj (Object, optional) – An object to receive error messages.

• persistent (bool, optional) – Let cmdset remain across server reload.

• default_cmdset (Cmdset, optional) – Insert this to replace the default cmdset position (there is only one such position, always at the bottom of the stack).

Notes

An interesting feature of this method is if you were to send it an already instantiated cmdset (i.e. not a class), the current cmdsethandler’s obj attribute will then not be transferred over to this already instantiated set (this is because it might be used elsewhere and can cause strange effects). This means you could in principle have the handler launch command sets tied to a different object than the handler. Not sure when this would be useful, but it’s a ‘quirk’ that has to be documented.

add_default(cmdset, emit_to_obj=None, persistent=True, **kwargs)

Shortcut for adding a default cmdset.

Parameters:

• cmdset (Cmdset) – The Cmdset to add.

• emit_to_obj (Object, optional) – Gets error messages

• persistent (bool, optional) – The new Cmdset should survive a server reboot.

all()

Get all cmdsets.

Returns:

cmdsets (list) – All the command sets currently in the handler.

clear()

Removes all Command Sets from the handler except the default one (use self.remove_default to remove that).

delete(cmdset=None, default_cmdset=False)

Remove a cmdset from the handler.

Parameters:

• cmdset (CommandSet or str, optional) – This can can be supplied either as a cmdset-key, an instance of the CmdSet or a python path to the cmdset. If no key is given, the last cmdset in the stack is removed. Whenever the cmdset_stack changes, the cmdset is updated. If default_cmdset is set, this argument is ignored.

• default_cmdset (bool, optional) – If set, this will remove the default cmdset (at the bottom of the stack).

delete_default()

This explicitly deletes only the default cmdset.

get()

Get all cmdsets.

Returns:

cmdsets (list) – All the command sets currently in the handler.

has(cmdset, must_be_default=False)

checks so the cmdsethandler contains a given cmdset

Parameters:

• cmdset (str or Cmdset) – Cmdset key, pythonpath or Cmdset to check the existence for.

• must_be_default (bool, optional) – Only return True if the checked cmdset is the default one.

Returns:

has_cmdset (bool) – Whether or not the cmdset is in the handler.

has_cmdset(cmdset, must_be_default=False)

checks so the cmdsethandler contains a given cmdset

Parameters:

• cmdset (str or Cmdset) – Cmdset key, pythonpath or Cmdset to check the existence for.

• must_be_default (bool, optional) – Only return True if the checked cmdset is the default one.

Returns:

has_cmdset (bool) – Whether or not the cmdset is in the handler.

remove(cmdset=None, default_cmdset=False)

Remove a cmdset from the handler.

Parameters:

• cmdset (CommandSet or str, optional) – This can can be supplied either as a cmdset-key, an instance of the CmdSet or a python path to the cmdset. If no key is given, the last cmdset in the stack is removed. Whenever the cmdset_stack changes, the cmdset is updated. If default_cmdset is set, this argument is ignored.

• default_cmdset (bool, optional) – If set, this will remove the default cmdset (at the bottom of the stack).

remove_default()

This explicitly deletes only the default cmdset.

reset()

Force reload of all cmdsets in handler. This should be called after _CACHED_CMDSETS have been cleared (normally this is handled automatically by @reload).

update(init_mode=False)

Re-adds all sets in the handler to have an updated current

Parameters:

init_mode (bool, optional) – Used automatically right after this handler was created; it imports all persistent cmdsets from the database.

Notes

This method is necessary in order to always have a .current cmdset when working with the cmdsethandler in code. But the CmdSetHandler doesn’t (cannot) consider external cmdsets and game state. This means that the .current calculated from this method will likely not match the true current cmdset as determined at run-time by cmdhandler.get_and_merge_cmdsets(). So in a running game the responsibility of keeping .current upt-to-date belongs to the central cmdhandler.get_and_merge_cmdsets()!

exception evennia.accounts.accounts.ImproperlyConfigured

Bases: Exception

Django is somehow improperly configured

class evennia.accounts.accounts.ModelAttributeBackend(handler, attrtype)

Bases: IAttributeBackend

Uses Django models for storing Attributes.

__init__(handler, attrtype)

do_batch_finish(attr_objs)

Called after batch_add completed. Used for handling database operations and/or caching complications.

Parameters:

attr_objs (list of IAttribute) – The Attributes created/updated thus far.

do_batch_update_attribute(attr_obj, category, lock_storage, new_value, strvalue)

Called opnly by batch add. For the database backend, this is a method of updating that can alter category and lock-storage.

Parameters:

• attr_obj (IAttribute) – The Attribute being altered.

• category (str or None) – The attribute’s (new) category.

• lock_storage (str) – The attribute’s new locks.

• new_value (obj) – The Attribute’s new value.

• strvalue (bool) – Signifies if this is a strvalue Attribute. Value MUST be a string or this will lead to Trouble. Ignored for InMemory attributes.

do_create_attribute(key, category, lockstring, value, strvalue)

Does the hard work of actually creating Attributes, whatever is needed.

Parameters:

• key (str) – The Attribute’s key.

• category (str or None) – The Attribute’s category, or None

• lockstring (str) – Any locks for the Attribute.

• value (obj) – The Value of the Attribute.

• strvalue (bool) – Signifies if this is a strvalue Attribute. Value MUST be a string or this will lead to Trouble. Ignored for InMemory attributes.

Returns:

attr (IAttribute) – The new Attribute.

do_delete_attribute(attr)

Does the hard work of actually deleting things.

Parameters:

attr (IAttribute) – The attribute to delete.

do_update_attribute(attr, value, strvalue)

Simply sets a new Value to an Attribute.

Parameters:

• attr (IAttribute) – The Attribute being changed.

• value (obj) – The Value for the Attribute.

• strvalue (bool) – If True, value is expected to be a string.

query_all()

Fetch all Attributes from this object.

Returns:

attrlist (list) – A list of Attribute objects.

query_category(category)

Returns every matching Attribute as a list, given a category.

This method calls up whatever storage the backend uses.

Parameters:

category (str or None) – The category to query.

Returns:

attrs (list) – The discovered Attributes.

query_key(key, category)

Parameters:

• key (str) – The key of the Attribute being searched for.

• category (str or None) – The category of the desired Attribute.

Returns:

attribute (IAttribute) – A single Attribute.

class evennia.accounts.accounts.NickHandler(*args, **kwargs)

Bases: AttributeHandler

Handles the addition and removal of Nicks. Nicks are special versions of Attributes with an _attrtype hardcoded to nick. They also always use the strvalue fields for their data.

__init__(*args, **kwargs)

Setup the AttributeHandler.

Parameters:

obj (TypedObject) – An Account, Object, Channel, ServerSession (not technically a typed object), etc. backend_class (IAttributeBackend class): The class of the backend to use.

add(pattern, replacement, category='inputline', pattern_is_regex=False, **kwargs)

Add a new nick, a mapping pattern -> replacement.

Parameters:

• pattern (str) – A pattern to match for. This will be parsed for shell patterns using the fnmatch library and can contain $N-markers to indicate the locations of arguments to catch. If pattern_is_regex=True, this must instead be a valid regular expression and the $N-markers must be named argN that matches numbered regex groups (see examples).

• replacement (str) – The string (or template) to replace key with (the “nickname”). This may contain $N markers to indicate where to place the argument-matches

• category (str, optional) – the category within which to retrieve the nick. The “inputline” means replacing data sent by the user.

• pattern_is_regex (bool) – If True, the pattern will be parsed as a raw regex string. Instead of using $N markers in this string, one then must mark numbered arguments as a named regex-groupd named argN. For example, (?P<arg1>.+?) will match the behavior of using $1 in the shell pattern.

• **kwargs (any, optional) – These are passed on to AttributeHandler.get.

Notes

For most cases, the shell-pattern is much shorter and easier. The regex pattern form can be useful for more complex matchings though, for example in order to add optional arguments, such as with (?P<argN>.*?).

Example

• pattern (default shell syntax): “gr $1 at $2”

• pattern (with pattern_is_regex=True): r”gr (?P<arg1>.+?) at (?P<arg2>.+?)”

• replacement: “emote With a flourish, $1 grins at $2.”

get(key=None, category='inputline', return_tuple=False, **kwargs)

Get the replacement value matching the given key and category

Parameters:

• key (str or list, optional) – the attribute identifier or multiple attributes to get. if a list of keys, the method will return a list.

• category (str, optional) – the category within which to retrieve the nick. The “inputline” means replacing data sent by the user.

• return_tuple (bool, optional) – return the full nick tuple rather than just the replacement. For non-template nicks this is just a string.

• kwargs (any, optional) – These are passed on to AttributeHandler.get.

Returns:

str or tuple – The nick replacement string or nick tuple.

has(key, category='inputline')

Parameters:

• key (str or iterable) – The Nick key or keys to check for.

• category (str) – Limit the check to Nicks with this category (note, that None is the default category).

Returns:

has_nick (bool or list) –

If the Nick exists on this object

or not. If key was given as an iterable then the return is a list of booleans.

nickreplace(raw_string, categories=('inputline', 'channel'), include_account=True)

Apply nick replacement of entries in raw_string with nick replacement.

Parameters:

• raw_string (str) – The string in which to perform nick replacement.

• categories (tuple, optional) – Replacement categories in which to perform the replacement, such as “inputline”, “channel” etc.

• include_account (bool, optional) – Also include replacement with nicks stored on the Account level.

• kwargs (any, optional) – Not used.

Returns:

string (str) –

A string with matching keys replaced with

their nick equivalents.

remove(key, category='inputline', **kwargs)

Remove Nick with matching category.

Parameters:

• key (str) – A key for the nick to match for.

• category (str, optional) – the category within which to removethe nick. The “inputline” means replacing data sent by the user.

• kwargs (any, optional) – These are passed on to AttributeHandler.get.

class evennia.accounts.accounts.ObjectDB(*args, **kwargs)

Bases: TypedObject

All objects in the game use the ObjectDB model to store data in the database. This is handled transparently through the typeclass system.

Note that the base objectdb is very simple, with few defined fields. Use attributes to extend your type class with new database-stored variables.

The TypedObject supplies the following (inherited) properties:

• key - main name

• name - alias for key

• db_typeclass_path - the path to the decorating typeclass

• db_date_created - time stamp of object creation

• permissions - perm strings

• locks - lock definitions (handler)

• dbref - #id of object

• db - persistent attribute storage

• ndb - non-persistent attribute storage

The ObjectDB adds the following properties:

• account - optional connected account (always together with sessid)

• sessid - optional connection session id (always together with account)

• location - in-game location of object

• home - safety location for object (handler)

• scripts - scripts assigned to object (handler from typeclass)

• cmdset - active cmdset on object (handler from typeclass)

• aliases - aliases for this object (property)

• nicks - nicknames for other things in Evennia (handler)

• sessions - sessions connected to this object (see also account)

• has_account - bool if an active account is currently connected

• contents - other objects having this object as location

• exits - exits from this object

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

property account

A wrapper for getting database field db_account.

at_db_location_postsave(new)

This is called automatically after the location field was saved, no matter how. It checks for a variable _safe_contents_update to know if the save was triggered via the location handler (which updates the contents cache) or not.

Parameters:

new (bool) – Set if this location has not yet been saved before.

property cmdset_storage

getter

contents_cache

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

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_destination

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_destination_id

db_home

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_home_id

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_location

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_location_id

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_sessid

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.

property destination

A wrapper for getting database field db_destination.

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

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)

hide_from_objects_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 home

A wrapper for getting database field db_home.

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

id

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

property location

Get location

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

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

objects = <evennia.objects.manager.ObjectDBManager object>

path = 'evennia.objects.models.ObjectDB'

receiver_object_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_object_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 sessid

A wrapper for getting database field db_sessid.

typename = 'SharedMemoryModelBase'

class evennia.accounts.accounts.OptionHandler(obj, options_dict=None, savefunc=None, loadfunc=None, save_kwargs=None, load_kwargs=None)

Bases: object

This is a generic Option handler. Retrieve options either as properties on this handler or by using the .get method.

This is used for Account.options but it could be used by Scripts or Objects just as easily. All it needs to be provided is an options_dict.

__init__(obj, options_dict=None, savefunc=None, loadfunc=None, save_kwargs=None, load_kwargs=None)

Initialize an OptionHandler.

Parameters:

• obj (object) – The object this handler sits on. This is usually a TypedObject.

• options_dict (dict) – A dictionary of option keys, where the values are options. The format of those tuples is: (‘key’, “Description to show”, ‘option_type’, <default value>)

• savefunc (callable) – A callable for all options to call when saving itself. It will be called as savefunc(key, value, **save_kwargs). A common one to pass would be AttributeHandler.add.

• loadfunc (callable) – A callable for all options to call when loading data into itself. It will be called as loadfunc(key, default=default, **load_kwargs). A common one to pass would be AttributeHandler.get.

• save_kwargs (any) – Optional extra kwargs to pass into savefunc above.

• load_kwargs (any) – Optional extra kwargs to pass into loadfunc above.

Notes

Both loadfunc and savefunc must be specified. If only one is given, the other will be ignored and in-memory storage will be used.

all(return_objs=False)

Get all options defined on this handler.

Parameters:

return_objs (bool, optional) – Return the actual Option objects rather than their values.

Returns:

all_options (dict) –

All options on this handler, either {key: value}

or {key: <Option>} if return_objs is True.

get(key, default=None, return_obj=False, raise_error=False)

Retrieves an Option stored in the handler. Will load it if it doesn’t exist.

Parameters:

• key (str) – The option key to retrieve.

• default (any) – What to return if the option is defined.

• return_obj (bool, optional) – If True, returns the actual option object instead of its value.

• raise_error (bool, optional) – Raise Exception if key is not found in options.

Returns:

option_value (any or Option) – An option value the Option itself.

Raises:

KeyError – If option is not defined.

set(key, value, **kwargs) → BaseOption

Change an individual option.

Parameters:

• key (str) – The key of an option that can be changed. Allows partial matching.

• value (str) – The value that should be checked, coerced, and stored.:

• kwargs (any, optional) – These are passed into the Option’s validation function, save function and display function and allows to customize either.

Returns:

BaseOption –

The matched object. Its new value can be accessed with

op.value or op.display().

class evennia.accounts.accounts.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.

Returns:

Script – The newly created Script.

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:

scripts (queryset) – The found scripts matching key.

has(key)

Determine if a given script exists on this object.

Parameters:

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

Returns:

bool – If the script exists or not.

remove(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!

start(key)

Find scripts and force-start them

Parameters:

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

Returns:

nr_started (int) – The number of started scripts found.

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!

class evennia.accounts.accounts.ServerConfig(*args, **kwargs)

Bases: WeakSharedMemoryModel

On-the fly storage of global settings.

Properties defined on ServerConfig:

• key: Main identifier

• value: Value stored in key. This is a pickled storage.

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

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_value

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

id

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

property key

Getter. Allows for value = self.key

objects = <evennia.server.manager.ServerConfigManager object>

path = 'evennia.server.models.ServerConfig'

store(key, value)

Wrap the storage.

Parameters:

• key (str) – The name of this store.

• value (str) – The data to store with this key.

typename = 'WeakSharedMemoryModelBase'

property value

Getter. Allows for value = self.value

class evennia.accounts.accounts.Throttle(**kwargs)

Bases: object

Keeps a running count of failed actions per IP address.

Available methods indicate whether or not the number of failures exceeds a particular threshold.

This version of the throttle is usable by both the terminal server as well as the web server, imposes limits on memory consumption by using deques with length limits instead of open-ended lists, and uses native Django caches for automatic key eviction and persistence configurability.

__init__(**kwargs)

Allows setting of throttle parameters.

Keyword Arguments:

• name (str) – Name of this throttle.

• limit (int) – Max number of failures before imposing limiter. If None, the throttle is disabled.

• timeout (int) – number of timeout seconds after max number of tries has been reached.

• cache_size (int) – Max number of attempts to record per IP within a rolling window; this is NOT the same as the limit after which the throttle is imposed!

check(ip)

This will check the session’s address against the storage dictionary to check they haven’t spammed too many fails recently.

Parameters:

ip (str) – IP address of requestor

Returns:

throttled (bool) –

True if throttling is active,

False otherwise.

error_msg = 'Too many failed attempts; you must wait a few minutes before trying again.'

get(ip=None)

Convenience function that returns the storage table, or part of.

Parameters:

ip (str, optional) – IP address of requestor

Returns:

storage (dict) –

When no IP is provided, returns a dict of all

current IPs being tracked and the timestamps of their recent failures.

timestamps (deque): When an IP is provided, returns a deque of

timestamps of recent failures only for that IP.

get_cache_key(*args, **kwargs)

Creates a ‘prefixed’ key containing arbitrary terms to prevent key collisions in the same namespace.

record_ip(ip, *args, **kwargs)

Tracks keys as they are added to the cache (since there is no way to get a list of keys after-the-fact).

Parameters:

ip (str) – IP being added to cache. This should be the original IP, not the cache-prefixed key.

remove(ip, *args, **kwargs)

Clears data stored for an IP from the throttle.

Parameters:

ip (str) – IP to clear.

touch(key, *args, **kwargs)

Refreshes the timeout on a given key and ensures it is recorded in the key register.

Parameters:

key (str) – Key of entry to renew.

unrecord_ip(ip, *args, **kwargs)

Forces removal of a key from the key registry.

Parameters:

ip (str) – IP to remove from list of keys.

update(ip, failmsg='Exceeded threshold.')

Store the time of the latest failure.

Parameters:

• ip (str) – IP address of requestor

• failmsg (str, optional) – Message to display in logs upon activation of throttle.

Returns:

None

class evennia.accounts.accounts.TypeclassBase(name, bases, attrs)

Bases: SharedMemoryModelBase

Metaclass which should be set for the root of model proxies that don’t define any new fields, like Object, Script etc. This is the basis for the typeclassing system.

exception evennia.accounts.accounts.ValidationError(message, code=None, params=None)

Bases: Exception

An error while validating data.

__init__(message, code=None, params=None)

The message argument can be a single error, a list of errors, or a dictionary that maps field names to lists of errors. What we define as an “error” can be either a simple string or an instance of ValidationError with its message attribute set, and what we define as list or dictionary can be an actual list or dict or an instance of ValidationError with its error_list or error_dict attribute set.

property message_dict

property messages

update_error_dict(error_dict)

evennia.accounts.accounts.authenticate(request=None, **credentials)

If the given credentials are valid, return a User object.

evennia.accounts.accounts.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.accounts.accounts.getrandbits(k) → x.  Generates an int with k random bits.

evennia.accounts.accounts.import_string(dotted_path)

Import a dotted module path and return the attribute/class designated by the last name in the path. Raise ImportError if the import failed.

evennia.accounts.accounts.is_iter(obj)

Checks if an object behaves iterably.

Parameters:

obj (any) – Entity to check for iterability.

Returns:

is_iterable (bool) – If obj is iterable or not.

Notes

Strings are not accepted as iterable (although they are actually iterable), since string iterations are usually not what we want to do with a string.

class evennia.accounts.accounts.lazy_property(func: Callable[[...], TProp], name=None, doc=None)

Bases: Generic[TProp]

Delays loading of property until first access. Credit goes to the Implementation in the werkzeug suite: http://werkzeug.pocoo.org/docs/utils/#werkzeug.utils.cached_property

This should be used as a decorator in a class and in Evennia is mainly used to lazy-load handlers:

@lazy_property
def attributes(self):
    return AttributeHandler(self)

Once initialized, the AttributeHandler will be available as a property “attributes” on the object. This is read-only since this functionality is pretty much exclusively used by handlers.

__init__(func: Callable[[...], TProp], name=None, doc=None)

Store all properties for now

evennia.accounts.accounts.make_iter(obj)

Makes sure that the object is always iterable.

Parameters:

obj (any) – Object to make iterable.

Returns:

iterable (list or iterable) –

The same object

passed-through or made iterable.

evennia.accounts.accounts.to_str(text, session=None)

Try to decode a bytestream to a python str, using encoding schemas from settings or from Session. Will always return a str(), also if not given a str/bytes.

Parameters:

• text (any) – The text to encode to bytes. If a str, return it. If also not bytes, convert to str using str() or repr() as a fallback.

• session (Session, optional) – A Session to get encoding info from. Will try this before falling back to settings.ENCODINGS.

Returns:

decoded_text (str) – The decoded text.

Notes

If text is already str, return it as is.

evennia.accounts.accounts.variable_from_module(module, variable=None, default=None)

Retrieve a variable or list of variables from a module. The variable(s) must be defined globally in the module. If no variable is given (or a list entry is None), all global variables are extracted from the module.

Parameters:

• module (string or module) – Python path, absolute path or a module.

• variable (string or iterable, optional) – Single variable name or iterable of variable names to extract. If not given, all variables in the module will be returned.

• default (string, optional) – Default value to use if a variable fails to be extracted. Ignored if variable is not given.

Returns:

variables (value or list) – A single value or a list of values depending on if variable is given or not. Errors in lists are replaced by the default argument.