evennia.comms.comms

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.

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

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.

basetype_setup()

at_channel_creation()

Called once, when the channel is first created.

has_connection(subscriber)

Checks so this account is actually listening to this channel.

Parameters

subscriber (Account or Object) – Entity to check.

Returns

has_sub (bool) –

Whether the subscriber is subscribing to

this channel or not.

Notes

This will first try Account subscribers and only try Object

if the Account fails.

property mutelist

property wholist

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

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

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

success (bool) –

Whether or not the addition was

successful.

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

success (bool) –

Whether or not the removal was

successful.

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

return (bool) – Result of lock check.

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.

Keyword Arguments

• 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

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

delete()

Deletes channel while also cleaning up channelhandler.

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

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.

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

success (bool) –

Returns True if message sending was

successful, False otherwise.

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.

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

prefix (str) – The created channel prefix.

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

formatted_list (str) – The list of names formatted appropriately.

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.

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

string (str) –

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

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

transformed (str) – A formatted string.

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

transformed (str) – The formatted message.

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

should_join (bool) – If False, channel joining is aborted.

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

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

should_leave (bool) – If False, channel parting is aborted.

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

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

result (Msg, TempMsg or bool) – If False, abort send.

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

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.

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

path (str) – URI path to Django Admin page for object.

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

path (str) – URI path to object creation page, if defined.

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

path (str) – URI path to object detail page, if defined.

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

path (str) – URI path to object update page, if defined.

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

path (str) – URI path to object deletion page, if defined.

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

path (str) – URI path to object detail page, if defined.

exception DoesNotExist

Bases: evennia.comms.models.ChannelDB.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.comms.models.ChannelDB.MultipleObjectsReturned

path = 'evennia.comms.comms.DefaultChannel'

typename = 'DefaultChannel'