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)[source]

Bases: evennia.accounts.models.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.

  • sessions (list of Sessions) - sessions connected to this account

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

  • Helper methods

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

  • execute_cmd(raw_string)

  • search(ostring, global_search=False, attribute_name=None,

    use_nicks=False, location=None, ignore_errors=False, account=False)

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

  • check_permstring(permstring)

  • 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_access()

  • at_cmdset_get(**kwargs)

  • at_first_login()

  • at_post_login(session=None)

  • at_disconnect()

  • at_message_receive()

  • at_message_send()

  • at_server_reload()

  • at_server_shutdown()

objects = <evennia.accounts.manager.AccountManager object>
property characters
disconnect_session_from_account(session, reason=None)[source]

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

  • session (Session) – Session to disconnect.

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

puppet_object(session, obj)[source]

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

  • session (Session) – session to use for puppeting

  • obj (Object) – the object to start puppeting


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


Disengage control over an object.


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


RuntimeError With message about error.


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


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.


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


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


Get all currently puppeted objects.


puppets (list)

All puppeted objects currently controlled

by this Account.

property character

This is a legacy convenience link for use with MULTISESSION_MODE.


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.


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)[source]

Checks if a given username or IP is banned.

Keyword Arguments
  • ip (str, optional) – IP address.

  • username (str, optional) – Username.


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'}])[source]

Retrieves and instantiates validators for usernames.


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


validators (list) – List of instantiated Validator objects.

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

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)

  • 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


account (DefaultAccount, None)

Account whose credentials were

provided if not banned.

errors (list): Error messages of any failures.

classmethod normalize_username(username)[source]

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)[source]

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


username (str) – Username to validate


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

classmethod validate_password(password, account=None)[source]

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


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.


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)[source]

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


password (str) – Password to set.


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.

create_character(*args, **kwargs)[source]

Create a character linked to this account.

  • 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 settings.BASE_CHARACTER_TYPECLASS.

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

  • ip (str, optiona) – 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.


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

classmethod create(*args, **kwargs)[source]

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.


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

delete(*args, **kwargs)[source]

Deletes the account permanently.


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

mechanism (these are usually not used).

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

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

  • 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)[source]

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.

  • 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 paramaters for commands at run-time.

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

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

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


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.


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)[source]

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

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


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.


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


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.


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.


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)[source]
This is triggered after an access-call on this Account has


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


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.


Called just before cmdsets on this account are requested by the command handler. The cmdsets are available as self.cmdset. 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 account currently have no cmdsets. kwargs are usually not used unless the cmdset is generated dynamically.


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.


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


Called after a successful password set/modify.


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


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


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

at_post_login(session=None, **kwargs)[source]

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

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

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


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)[source]

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

  • session (session) – Session logging in.

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

at_disconnect(reason=None, **kwargs)[source]

Called just before user is disconnected.

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


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


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

at_msg_receive(text=None, from_obj=None, **kwargs)[source]

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.

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

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

Keyword Arguments

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


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


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

at_msg_send(text=None, to_obj=None, **kwargs)[source]

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

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

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

Keyword Arguments

passed from msg() (Keywords) –


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


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.


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

at_look(target=None, session=None, **kwargs)[source]

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

  • target (Object or list, optional) – An object or a list objects to inspect.

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

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


look_string (str)

A prepared look string, ready to send

off to any recipient (usually to ourselves)

exception DoesNotExist

Bases: evennia.accounts.models.AccountDB.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.accounts.models.AccountDB.MultipleObjectsReturned

path = 'evennia.accounts.accounts.DefaultAccount'
typename = 'DefaultAccount'
class evennia.accounts.accounts.DefaultGuest(*args, **kwargs)[source]

Bases: evennia.accounts.accounts.DefaultAccount

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

classmethod create(**kwargs)[source]

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

classmethod authenticate(**kwargs)[source]

Gets or creates a Guest account object.

Keyword Arguments

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


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

at_post_login(session=None, **kwargs)[source]

In theory, guests only have one character regardless of which MULTISESSION_MODE we’re in. They don’t get a choice.

  • session (Session, optional) – Session connecting.

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


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


Once having disconnected, destroy the guest’s characters and


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

exception DoesNotExist

Bases: evennia.accounts.accounts.DefaultAccount.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.accounts.accounts.DefaultAccount.MultipleObjectsReturned

path = 'evennia.accounts.accounts.DefaultGuest'
typename = 'DefaultGuest'