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. The list will be filtered so each sender-string only occurs once.

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