evennia.comms package

This sub-package contains Evennia’s comms-system, a set of models and handlers for in-game communication via channels and messages as well as code related to external communication like IRC or RSS.

Subpackages

Submodules

evennia.comms.admin module

This defines how Comm models are displayed in the web admin interface.

class evennia.comms.admin.ChannelAdmin(model, admin_site)

Bases: django.contrib.admin.options.ModelAdmin

Defines display for Channel objects

fieldsets = ((None, {'fields': (('db_key',), 'db_lock_storage', 'db_account_subscriptions', 'db_object_subscriptions')}),)

inlines = [<class 'evennia.comms.admin.ChannelTagInline'>, <class 'evennia.comms.admin.ChannelAttributeInline'>]

list_display = ('id', 'db_key', 'db_lock_storage', 'subscriptions')

list_display_links = ('id', 'db_key')

list_select_related = True

property media

ordering = ['db_key']

raw_id_fields = ('db_object_subscriptions', 'db_account_subscriptions')

response_add(request, obj, post_url_continue=None)

Determine the HttpResponse for the add_view stage.

save_as = True

save_model(request, obj, form, change)

Model-save hook.

Parameters

• request (Request) – Incoming request.

• obj (Object) – Database object.

• form (Form) – Form instance.

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

save_on_top = True

search_fields = ['id', 'db_key', 'db_tags__db_key']

subscriptions(obj)

Helper method to get subs from a channel.

Parameters

obj (Channel) – The channel to get subs from.

class evennia.comms.admin.ChannelAttributeInline(parent_model, admin_site)

Bases: evennia.typeclasses.admin.AttributeInline

Inline display of Channel Attribute - experimental

property media

model

alias of evennia.comms.models.ChannelDB_db_attributes

related_field = 'channeldb'

class evennia.comms.admin.ChannelTagInline(parent_model, admin_site)

Bases: evennia.typeclasses.admin.TagInline

Inline display of Channel Tags - experimental

property media

model

alias of evennia.comms.models.ChannelDB_db_tags

related_field = 'channeldb'

class evennia.comms.admin.MsgAdmin(model, admin_site)

Bases: django.contrib.admin.options.ModelAdmin

Defines display for Msg objects

list_display = ('id', 'db_date_created', 'db_sender', 'db_receivers', 'db_channels', 'db_message', 'db_lock_storage')

list_display_links = ('id',)

list_select_related = True

property media

ordering = ['db_date_created', 'db_sender', 'db_receivers', 'db_channels']

save_as = True

save_on_top = True

search_fields = ['id', '^db_date_created', '^db_message']

evennia.comms.channelhandler module

The channel handler, accessed from this module as CHANNEL_HANDLER is a singleton that handles the stored set of channels and how they are represented against the cmdhandler.

If there is a channel named ‘newbie’, we want to be able to just write

newbie Hello!

For this to work, ‘newbie’, the name of the channel, must be identified by the cmdhandler as a command name. The channelhandler stores all channels as custom ‘commands’ that the cmdhandler can import and look through.

> Warning - channel names take precedence over command names, so make sure to not pick clashing channel names.

Unless deleting a channel you normally don’t need to bother about the channelhandler at all - the create_channel method handles the update.

To delete a channel cleanly, delete the channel object, then call update() on the channelhandler. Or use Channel.objects.delete() which does this for you.

class evennia.comms.channelhandler.ChannelCommand(**kwargs)

Bases: evennia.commands.command.Command

{channelkey} channel

{channeldesc}

Usage:

{lower_channelkey} <message> {lower_channelkey}/history [start] {lower_channelkey} off - mutes the channel {lower_channelkey} on - unmutes the channel

Switch:

history: View 20 previous messages, either from the end or

from <start> number of messages from the end.

Example

{lower_channelkey} Hello World! {lower_channelkey}/history {lower_channelkey}/history 30

_keyaliases = ('general',)

_matchset = {'general'}

aliases = []

arg_regex = re.compile('\\s.*?|/history.*?', re.IGNORECASE)

func()

Create a new message and send it to channel, using the already formatted input.

get_extra_info(caller, **kwargs)

Let users know that this command is for communicating on a channel.

Parameters

caller (TypedObject) – A Character or Account who has entered an ambiguous command.

Returns

A string with identifying information to disambiguate the object, conventionally with a preceding space.

help_category = 'channel names'

is_channel = True

key = 'general'

lock_storage = 'cmd:all();'

obj = None

parse()

Simple parser

search_index_entry = {'aliases': '', 'category': 'channel names', 'key': 'general', 'tags': '', 'text': '\n {channelkey} channel\n\n {channeldesc}\n\n Usage:\n {lower_channelkey} <message>\n {lower_channelkey}/history [start]\n {lower_channelkey} off - mutes the channel\n {lower_channelkey} on - unmutes the channel\n\n Switch:\n history: View 20 previous messages, either from the end or\n from <start> number of messages from the end.\n\n Example:\n {lower_channelkey} Hello World!\n {lower_channelkey}/history\n {lower_channelkey}/history 30\n\n '}

class evennia.comms.channelhandler.ChannelHandler

Bases: object

The ChannelHandler manages all active in-game channels and dynamically creates channel commands for users so that they can just give the channel’s key or alias to write to it. Whenever a new channel is created in the database, the update() method on this handler must be called to sync it with the database (this is done automatically if creating the channel with evennia.create_channel())

__init__()

Initializes the channel handler’s internal state.

add(channel)

Add an individual channel to the handler. This is called whenever a new channel is created.

Parameters

channel (Channel) – The channel to add.

Notes

To remove a channel, simply delete the channel object and run self.update on the handler. This should usually be handled automatically by one of the deletion methos of the Channel itself.

add_channel(channel)

Add an individual channel to the handler. This is called whenever a new channel is created.

Parameters

channel (Channel) – The channel to add.

Notes

To remove a channel, simply delete the channel object and run self.update on the handler. This should usually be handled automatically by one of the deletion methos of the Channel itself.

clear()

Reset the cache storage.

get(channelname=None)

Get a channel from the handler, or all channels

Parameters

channelame (str, optional) – Channel key, case insensitive.

Returns

channels (list): The matching channels in a list, or all

channels in the handler.

get_cmdset(source_object)

Retrieve cmdset for channels this source_object has access to send to.

Parameters

source_object (Object) – An object subscribing to one or more channels.

Returns

The Channel-Cmdsets source_object has

access to.

Return type

cmdsets (list)

remove(channel)

Remove channel from channelhandler. This will also delete it.

Parameters

channel (Channel) – Channel to remove/delete.

update()

Updates the handler completely, including removing old removed Channel objects. This must be called after deleting a Channel.

evennia.comms.comms module

Base typeclass for in-game Channels.

class evennia.comms.comms.DefaultChannel(*args, **kwargs)

Bases: evennia.comms.models.ChannelDB

This is the base class for all Channel Comms. Inherit from this to create different types of communication channels.

exception DoesNotExist

Bases: evennia.comms.models.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.comms.models.MultipleObjectsReturned

_meta = <Options for DefaultChannel>

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

Determines if another object has permission to access.

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) – Turns off superuser lock bypass. Be careful with this one.

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

Returns

Result of lock check.

Return type

return (bool)

at_channel_creation()

Called once, when the channel is first created.

at_first_save()

Called by the typeclass system the very first time the channel is saved to the database. Generally, don’t overload this but the hooks called by this method.

at_init()

Hook method. This is always called whenever this channel is initiated – that is, whenever it its typeclass is cached from memory. This happens on-demand first time the channel is used or activated in some way after being created but also after each server restart or reload.

basetype_setup()

channel_prefix(msg=None, emit=False, **kwargs)

Hook method. How the channel should prefix itself for users.

Parameters

• msg (str, optional) – Prefix text

• emit (bool, optional) – Switches to emit mode, which usually means to not prefix the channel’s info.

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

Returns

The created channel prefix.

Return type

prefix (str)

connect(subscriber, **kwargs)

Connect the user to this channel. This checks access.

Parameters

• subscriber (Account or Object) – the entity to subscribe to this channel.

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

Returns

Whether or not the addition was

successful.

Return type

success (bool)

classmethod create(key, account=None, *args, **kwargs)

Creates a basic Channel with default parameters, unless otherwise specified or extended.

Provides a friendlier interface to the utils.create_channel() function.

Parameters

• key (str) – This must be unique.

• account (Account) – Account to attribute this object to.

Kwargs:

aliases (list of str): List of alternative (likely shorter) keynames. description (str): A description of the channel, for use in listings. locks (str): Lockstring. keep_log (bool): Log channel throughput. typeclass (str or class): The typeclass of the Channel (not

often used).

ip (str): IP address of creator (for object auditing).

Returns

A newly created Channel. errors (list): A list of errors in string form, if any.

Return type

channel (Channel)

delete()

Deletes channel while also cleaning up channelhandler.

disconnect(subscriber, **kwargs)

Disconnect entity from this channel.

Parameters

• subscriber (Account of Object) – the entity to disconnect.

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

Returns

Whether or not the removal was

successful.

Return type

success (bool)

distribute_message(msgobj, online=False, **kwargs)

Method for grabbing all listeners that a message should be sent to on this channel, and sending them a message.

Parameters

• msgobj (Msg or TempMsg) – Message to distribute.

• online (bool) – Only send to receivers who are actually online (not currently used):

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

Notes

This is also where logging happens, if enabled.

format_external(msgobj, senders, emit=False, **kwargs)

Hook method. Used for formatting external messages. This is needed as a separate operation because the senders of external messages may not be in-game objects/accounts, and so cannot have things like custom user preferences.

Parameters

• msgobj (Msg or TempMsg) – The message to send.

• senders (list) – Strings, one per sender.

• emit (bool, optional) – A sender-agnostic message or not.

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

Returns

A formatted string.

Return type

transformed (str)

format_message(msgobj, emit=False, **kwargs)

Hook method. Formats a message body for display.

Parameters

• msgobj (Msg or TempMsg) – The message object to send.

• emit (bool, optional) – The message is agnostic of senders.

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

Returns

The formatted message.

Return type

transformed (str)

format_senders(senders=None, **kwargs)

Hook method. Function used to format a list of sender names.

Parameters

• senders (list) – Sender object names.

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

Returns

The list of names formatted appropriately.

Return type

formatted_list (str)

Notes

This function exists separately so that external sources can use it to format source names in the same manner as normal object/account names.

get_absolute_url()

Returns the URI path for a View that allows users to view details for this object.

ex. Oscar (Character) = ‘/characters/oscar/1/’

For this to work, the developer must have defined a named view somewhere in urls.py that follows the format ‘modelname-action’, so in this case a named view of ‘channel-detail’ would be referenced by this method.

ex. url(r’channels/(?P<slug>[wd-]+)/$’,

ChannelDetailView.as_view(), name=’channel-detail’)

If no View has been created and defined in urls.py, returns an HTML anchor.

This method is naive and simply returns a path. Securing access to the actual view and limiting who can view this object is the developer’s responsibility.

Returns

URI path to object detail page, if defined.

Return type

path (str)

has_connection(subscriber)

Checks so this account is actually listening to this channel.

Parameters

subscriber (Account or Object) – Entity to check.

Returns

Whether the subscriber is subscribing to

this channel or not.

Return type

has_sub (bool)

Notes

This will first try Account subscribers and only try Object

if the Account fails.

message_transform(msgobj, emit=False, prefix=True, sender_strings=None, external=False, **kwargs)

Generates the formatted string sent to listeners on a channel.

Parameters

• msgobj (Msg) – Message object to send.

• emit (bool, optional) – In emit mode the message is not associated with a specific sender name.

• prefix (bool, optional) – Prefix msg with a text given by self.channel_prefix.

• sender_strings (list, optional) – Used by bots etc, one string per external sender.

• external (bool, optional) – If this is an external sender or not.

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

msg(msgobj, header=None, senders=None, sender_strings=None, keep_log=None, online=False, emit=False, external=False)

Send the given message to all accounts connected to channel. Note that no permission-checking is done here; it is assumed to have been done before calling this method. The optional keywords are not used if persistent is False.

Parameters

• msgobj (Msg, TempMsg or str) – If a Msg/TempMsg, the remaining keywords will be ignored (since the Msg/TempMsg object already has all the data). If a string, this will either be sent as-is (if persistent=False) or it will be used together with header and senders keywords to create a Msg instance on the fly.

• header (str, optional) – A header for building the message.

• senders (Object, Account or list, optional) – Optional if persistent=False, used to build senders for the message.

• sender_strings (list, optional) – Name strings of senders. Used for external connections where the sender is not an account or object. When this is defined, external will be assumed.

• keep_log (bool or None, optional) – This allows to temporarily change the logging status of this channel message. If None, the Channel’s keep_log Attribute will be used. If True or False, that logging status will be used for this message only (note that for unlogged channels, a True value here will create a new log file only for this message).

• online (bool, optional) – online. Otherwise, messages all accounts connected. This can make things faster, but may not trigger listeners on accounts that are offline.

• emit (bool, optional) – not to be directly associated with a name.

• external (bool, optional) – Treat this message as being agnostic of its sender.

Returns

Returns True if message sending was

successful, False otherwise.

Return type

success (bool)

mute(subscriber, **kwargs)

Adds an entity to the list of muted subscribers. A muted subscriber will no longer see channel messages, but may use channel commands.

Parameters

• subscriber (Object or Account) – Subscriber to mute.

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

property mutelist

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

path = 'evennia.comms.comms.DefaultChannel'

pose_transform(msgobj, sender_string, **kwargs)

Hook method. Detects if the sender is posing, and modifies the message accordingly.

Parameters

• msgobj (Msg or TempMsg) – The message to analyze for a pose.

• sender_string (str) – The name of the sender/poser.

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

Returns

A message that combines the sender_string

component with msg in different ways depending on if a pose was performed or not (this must be analyzed by the hook).

Return type

string (str)

post_join_channel(joiner, **kwargs)

Hook method. Runs right after an object or account joins a channel.

Parameters

• joiner (object) – The joining object.

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

post_leave_channel(leaver, **kwargs)

Hook method. Runs right after an object or account leaves a channel.

Parameters

• leaver (object) – The leaving object.

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

post_send_message(msg, **kwargs)

Hook method. Run after a message is sent to the channel.

Parameters

• msg (Msg or TempMsg) – Message sent.

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

pre_join_channel(joiner, **kwargs)

Hook method. Runs right before a channel is joined. If this returns a false value, channel joining is aborted.

Parameters

• joiner (object) – The joining object.

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

Returns

If False, channel joining is aborted.

Return type

should_join (bool)

pre_leave_channel(leaver, **kwargs)

Hook method. Runs right before a user leaves a channel. If this returns a false value, leaving the channel will be aborted.

Parameters

• leaver (object) – The leaving object.

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

Returns

If False, channel parting is aborted.

Return type

should_leave (bool)

pre_send_message(msg, **kwargs)

Hook method. Runs before a message is sent to the channel and should return the message object, after any transformations. If the message is to be discarded, return a false value.

Parameters

• msg (Msg or TempMsg) – Message to send.

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

Returns

If False, abort send.

Return type

result (Msg, TempMsg or bool)

tempmsg(message, header=None, senders=None)

A wrapper for sending non-persistent messages.

Parameters

• message (str) – Message to send.

• header (str, optional) – Header of message to send.

• senders (Object or list, optional) – Senders of message to send.

typename = 'DefaultChannel'

unmute(subscriber, **kwargs)

Removes an entity to the list of muted subscribers. A muted subscriber will no longer see channel messages, but may use channel commands.

Parameters

• subscriber (Object or Account) – The subscriber to unmute.

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

web_get_admin_url()

Returns the URI path for the Django Admin page for this object.

ex. Account#1 = ‘/admin/accounts/accountdb/1/change/’

Returns

URI path to Django Admin page for object.

Return type

path (str)

classmethod web_get_create_url()

Returns the URI path for a View that allows users to create new instances of this object.

ex. Chargen = ‘/characters/create/’

For this to work, the developer must have defined a named view somewhere in urls.py that follows the format ‘modelname-action’, so in this case a named view of ‘channel-create’ would be referenced by this method.

ex. url(r’channels/create/’, ChannelCreateView.as_view(), name=’channel-create’)

If no View has been created and defined in urls.py, returns an HTML anchor.

This method is naive and simply returns a path. Securing access to the actual view and limiting who can create new objects is the developer’s responsibility.

Returns

URI path to object creation page, if defined.

Return type

path (str)

web_get_delete_url()

Returns the URI path for a View that allows users to delete this object.

ex. Oscar (Character) = ‘/characters/oscar/1/delete/’

For this to work, the developer must have defined a named view somewhere in urls.py that follows the format ‘modelname-action’, so in this case a named view of ‘channel-delete’ would be referenced by this method.

ex. url(r’channels/(?P<slug>[wd-]+)/(?P<pk>[0-9]+)/delete/$’,

ChannelDeleteView.as_view(), name=’channel-delete’)

If no View has been created and defined in urls.py, returns an HTML anchor.

This method is naive and simply returns a path. Securing access to the actual view and limiting who can delete this object is the developer’s responsibility.

Returns

URI path to object deletion page, if defined.

Return type

path (str)

web_get_detail_url()

Returns the URI path for a View that allows users to view details for this object.

ex. Oscar (Character) = ‘/characters/oscar/1/’

For this to work, the developer must have defined a named view somewhere in urls.py that follows the format ‘modelname-action’, so in this case a named view of ‘channel-detail’ would be referenced by this method.

ex. url(r’channels/(?P<slug>[wd-]+)/$’,

ChannelDetailView.as_view(), name=’channel-detail’)

If no View has been created and defined in urls.py, returns an HTML anchor.

This method is naive and simply returns a path. Securing access to the actual view and limiting who can view this object is the developer’s responsibility.

Returns

URI path to object detail page, if defined.

Return type

path (str)

web_get_update_url()

Returns the URI path for a View that allows users to update this object.

ex. Oscar (Character) = ‘/characters/oscar/1/change/’

For this to work, the developer must have defined a named view somewhere in urls.py that follows the format ‘modelname-action’, so in this case a named view of ‘channel-update’ would be referenced by this method.

ex. url(r’channels/(?P<slug>[wd-]+)/(?P<pk>[0-9]+)/change/$’,

ChannelUpdateView.as_view(), name=’channel-update’)

If no View has been created and defined in urls.py, returns an HTML anchor.

This method is naive and simply returns a path. Securing access to the actual view and limiting who can modify objects is the developer’s responsibility.

Returns

URI path to object update page, if defined.

Return type

path (str)

property wholist

evennia.comms.managers module

These managers define helper methods for accessing the database from Comm system components.

class evennia.comms.managers.ChannelDBManager

Bases: evennia.typeclasses.managers.TypedObjectManager

This ChannelManager implements methods for searching and manipulating Channels directly from the database.

These methods will all return database objects (or QuerySets) directly.

A Channel is an in-game venue for communication. It’s essentially representation of a re-sender: Users sends Messages to the Channel, and the Channel re-sends those messages to all users subscribed to the Channel.

channel_search(ostring, exact=True)

Search the channel database for a particular channel.

Parameters

• ostring (str) – The key or database id of the channel.

• exact (bool, optional) – Require an exact (but not case sensitive) match.

get_all_channels()

Get all channels.

Returns

All channels in game.

Return type

channels (list)

get_channel(channelkey)

Return the channel object if given its key. Also searches its aliases.

Parameters

channelkey (str) – Channel key to search for.

Returns

A channel match.

Return type

channel (Channel or None)

get_subscriptions(subscriber)

Return all channels a given entity is subscribed to.

Parameters

subscriber (Object or Account) – The one subscribing.

Returns

Channel subscribed to.

Return type

subscriptions (list)

search_channel(ostring, exact=True)

Search the channel database for a particular channel.

Parameters

• ostring (str) – The key or database id of the channel.

• exact (bool, optional) – Require an exact (but not case sensitive) match.

class evennia.comms.managers.ChannelManager

Bases: evennia.comms.managers.ChannelDBManager, evennia.typeclasses.managers.TypeclassManager

Wrapper to group the typeclass manager to a consistent name.

exception evennia.comms.managers.CommError

Bases: Exception

Raised by comm system, to allow feedback to player when caught.

class evennia.comms.managers.MsgManager

Bases: evennia.typeclasses.managers.TypedObjectManager

This MsgManager implements methods for searching and manipulating Messages directly from the database.

These methods will all return database objects (or QuerySets) directly.

A Message represents one unit of communication, be it over a Channel or via some form of in-game mail system. Like an e-mail, it always has a sender and can have any number of receivers (some of which may be Channels).

get_message_by_id(idnum)

Retrieve message by its id.

Parameters

idnum (int or str) – The dbref to retrieve.

Returns

The message.

Return type

message (Msg)

get_messages_by_channel(channel)

Get all persistent messages sent to one channel.

Parameters

channel (Channel) – The channel to find messages for.

Returns

Persistent Msg objects saved for this channel.

Return type

messages (list)

get_messages_by_receiver(recipient)

Get all messages sent to one given recipient.

Parameters

recipient (Object, Account or Channel) – The recipient of the messages to search for.

Returns

Matching messages.

Return type

messages (list)

Raises

CommError – If the recipient is not of a valid type.

get_messages_by_sender(sender, exclude_channel_messages=False)

Get all messages sent by one entity - this could be either a account or an object

Parameters

• sender (Account or Object) – The sender of the message.

• exclude_channel_messages (bool, optional) – Only return messages not aimed at a channel (that is, private tells for example)

Returns

List of matching messages

Return type

messages (list)

Raises

CommError – For incorrect sender types.

identify_object(inp)

Wrapper to identify_object if accessing via the manager directly.

Parameters

inp (any) – Entity to be idtified.

Returns

This is a tuple with (inp, identifier)

where identifier is one of “account”, “object”, “channel”, “string”, “dbref” or None.

Return type

identified (tuple)

message_search(sender=None, receiver=None, freetext=None, dbref=None)

Search the message database for particular messages. At least one of the arguments must be given to do a search.

Parameters

• sender (Object or Account, optional) – Get messages sent by a particular account or object

• receiver (Object, Account or Channel, optional) – Get messages received by a certain account,object or channel

• freetext (str) – Search for a text string in a message. NOTE: This can potentially be slow, so make sure to supply one of the other arguments to limit the search.

• dbref (int) – The exact database id of the message. This will override all other search criteria since it’s unique and always gives only one match.

Returns

A list of message matches or a single match if dbref was given.

Return type

messages (list or Msg)

search_message(sender=None, receiver=None, freetext=None, dbref=None)

Search the message database for particular messages. At least one of the arguments must be given to do a search.

Parameters

• sender (Object or Account, optional) – Get messages sent by a particular account or object

• receiver (Object, Account or Channel, optional) – Get messages received by a certain account,object or channel

• freetext (str) – Search for a text string in a message. NOTE: This can potentially be slow, so make sure to supply one of the other arguments to limit the search.

• dbref (int) – The exact database id of the message. This will override all other search criteria since it’s unique and always gives only one match.

Returns

A list of message matches or a single match if dbref was given.

Return type

messages (list or Msg)

evennia.comms.managers._GA()

Return getattr(self, name).

evennia.comms.managers.identify_object(inp)

Helper function. Identifies if an object is an account or an object; return its database model

Parameters

inp (any) – Entity to be idtified.

Returns

This is a tuple with (inp, identifier)

where identifier is one of “account”, “object”, “channel”, “string”, “dbref” or None.

Return type

identified (tuple)

evennia.comms.managers.to_object(inp, objtype='account')

Locates the object related to the given accountname or channel key. If input was already the correct object, return it.

Parameters

• inp (any) – The input object/string

• objtype (str) – Either ‘account’ or ‘channel’.

Returns

The correct object related to inp.

Return type

obj (object)

evennia.comms.models module

Models for the in-game communication system.

The comm system could take the form of channels, but can also be adopted for storing tells or in-game mail.

The comsystem’s main component is the Message (Msg), which carries the actual information between two parties. Msgs are stored in the database and usually not deleted. A Msg always have one sender (a user), but can have any number targets, both users and channels.

For non-persistent (and slightly faster) use one can also use the TempMsg, which mimics the Msg API but without actually saving to the database.

Channels are central objects that act as targets for Msgs. Accounts can connect to channels by use of a ChannelConnect object (this object is necessary to easily be able to delete connections on the fly).

class evennia.comms.models.Msg(*args, **kwargs)

Bases: evennia.utils.idmapper.models.SharedMemoryModel

A single message. This model describes all ooc messages sent in-game, both to channels and between accounts.

The Msg class defines the following database fields (all accessed via specific handler methods):

• db_sender_accounts: Account senders

• db_sender_objects: Object senders

• db_sender_scripts: Script senders

• db_sender_external: External senders (defined as string names)

• db_receivers_accounts: Receiving accounts

• db_receivers_objects: Receiving objects

• db_receivers_scripts: Receiveing scripts

• db_receivers_channels: Receiving channels

• db_header: Header text

• db_message: The actual message text

• db_date_created: time message was created / sent

• db_hide_from_sender: bool if message should be hidden from sender

• db_hide_from_receivers: list of receiver objects to hide message from

• db_hide_from_channels: list of channels objects to hide message from

• db_lock_storage: Internal storage of lock strings.

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

_Msg__channels_del()

Deleter. Allows for del self.channels

_Msg__channels_get()

Getter. Allows for value = self.channels. Returns a list of channels.

_Msg__channels_set(value)

Setter. Allows for self.channels = value. Requires a channel to be added.

_Msg__hide_from_del()

Deleter. Allows for del self.hide_from_senders

_Msg__hide_from_get()

Getter. Allows for value = self.hide_from. Returns 3 lists of accounts, objects and channels

_Msg__hide_from_set(hiders)

Setter. Allows for self.hide_from = value. Will append to hiders

_Msg__receivers_del()

Deleter. Clears all receivers

_Msg__receivers_get()

Getter. Allows for value = self.receivers. Returns four lists of receivers: accounts, objects, scripts and channels.

_Msg__receivers_set(receivers)

Setter. Allows for self.receivers = value. This appends a new receiver to the message.

_Msg__senders_del()

Deleter. Clears all senders

_Msg__senders_get()

Getter. Allows for value = self.sender

_Msg__senders_set(senders)

Setter. Allows for self.sender = value

__init__(*args, **kwargs)

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

_is_deleted = False

_meta = <Options for Msg>

access(accessing_obj, access_type='read', default=False)

Checks lock access.

Parameters

• accessing_obj (Object or Account) – The object trying to gain access.

• access_type (str, optional) – The type of lock access to check.

• default (bool) – Fallback to use if access_type lock is not defined.

Returns

If access was granted or not.

Return type

result (bool)

property channels

Getter. Allows for value = self.channels. Returns a list of channels.

property date_created

A wrapper for getting database field db_date_created.

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_header

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

db_hide_from_accounts

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_hide_from_channels

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_hide_from_objects

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

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

db_receivers_accounts

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_receivers_channels

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_receivers_objects

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_receivers_scripts

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_sender_accounts

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_sender_external

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

db_sender_objects

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_sender_scripts

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.

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)

property header

A wrapper for getting database field db_header.

property hide_from

Getter. Allows for value = self.hide_from. Returns 3 lists of accounts, objects and channels

id

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

property lock_storage

A wrapper for getting database field db_lock_storage.

locks

property message

A wrapper for getting database field db_message.

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

path = 'evennia.comms.models.Msg'

property receivers

Getter. Allows for value = self.receivers. Returns four lists of receivers: accounts, objects, scripts and channels.

remove_receiver(receivers)

Remove a single receiver or a list of receivers.

Parameters

receivers (Account, Object, Script, Channel or list) – Receiver to remove.

remove_sender(senders)

Remove a single sender or a list of senders.

Parameters

senders (Account, Object, str or list) – Senders to remove.

property sender_external

A wrapper for getting database field db_sender_external.

property senders

Getter. Allows for value = self.sender

tags

typename = 'SharedMemoryModelBase'

class evennia.comms.models.TempMsg(senders=None, receivers=None, channels=None, message='', header='', type='', lockstring='', hide_from=None)

Bases: object

This is a non-persistent object for sending temporary messages that will not be stored. It mimics the “real” Msg object, but doesn’t require sender to be given.

__init__(senders=None, receivers=None, channels=None, message='', header='', type='', lockstring='', hide_from=None)

Creates the temp message.

Parameters

• senders (any or list, optional) – Senders of the message.

• receivers (Account, Object, Channel or list, optional) – Receivers of this message.

• channels (Channel or list, optional) – Channels to send to.

• message (str, optional) – Message to send.

• header (str, optional) – Header of message.

• type (str, optional) – Message class, if any.

• lockstring (str, optional) – Lock for the message.

• hide_from (Account, Object, Channel or list, optional) – Entities to hide this message from.

access(accessing_obj, access_type='read', default=False)

Checks lock access.

Parameters

• accessing_obj (Object or Account) – The object trying to gain access.

• access_type (str, optional) – The type of lock access to check.

• default (bool) – Fallback to use if access_type lock is not defined.

Returns

If access was granted or not.

Return type

result (bool)

locks

remove_receiver(receiver)

Remove a receiver or a list of receivers

Parameters

receiver (Object, Account, Channel, str or list) – Receivers to remove.

remove_sender(sender)

Remove a sender or a list of senders.

Parameters

sender (Object, Account, str or list) – Senders to remove.

class evennia.comms.models.ChannelDB(*args, **kwargs)

Bases: evennia.typeclasses.models.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: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

_is_deleted = False

_meta = <Options for ChannelDB>

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

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

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

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

path = 'evennia.comms.models.ChannelDB'

subscriptions

typename = 'SharedMemoryModelBase'

evennia.comms.tests module

class evennia.comms.tests.ObjectCreationTest(methodName='runTest')

Bases: evennia.utils.test_resources.EvenniaTest

test_channel_create()

test_message_create()