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: 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()

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

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_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() → Optional[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() → Optional[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) → Optional[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

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

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

passed from msg() (Keywords) –

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

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)

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: evennia.accounts.accounts.DefaultAccount.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.accounts.accounts.DefaultAccount.MultipleObjectsReturned

path = 'evennia.accounts.accounts.DefaultGuest'

typename = 'DefaultGuest'