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.

Class-level variables: - send_to_online_only (bool, default True) - if set, will only try to

send to subscribers that are actually active. This is a useful optimization.

• log_file (str, default “channel_{channelname}.log”). This is the log file to which the channel history will be saved. The {channelname} tag will be replaced by the key of the Channel. If an Attribute ‘log_file’ is set, this will be used instead. If this is None and no Attribute is found, no history will be saved.

• channel_prefix_string (str, default “[{channelname} ]”) - this is used as a simple template to get the channel prefix with .channel_prefix(). It is used in front of every channel message; use {channelmessage} token to insert the name of the current channel. Set to None if you want no prefix (or want to handle it in a hook during message generation instead.

• channel_msg_nick_pattern**(str, default **”{alias}s*?|{alias}s+?(?P<arg1>.+?)”) - this is what used when a channel subscriber gets a channel nick assigned to this channel. The nickhandler uses the pattern to pick out this channel’s name from user input. The **{alias} token will get both the channel’s key and any set/custom aliases per subscriber. You need to allow for an <arg1> regex group to catch any message that should be send to the channel. You usually don’t need to change this pattern unless you are changing channel command-style entirely.

• channel_msg_nick_replacement (str, default “channel {channelname} = $1” - this is used by the nickhandler to generate a replacement string once the nickhandler (using the channel_msg_nick_pattern) identifies that the channel should be addressed to send a message to it. The <arg1> regex pattern match from channel_msg_nick_pattern will end up at the $1 position in the replacement. Together, this allows you do e.g. ‘public Hello’ and have that become a mapping to channel public = Hello. By default, the account-level channel command is used. If you were to rename that command you must tweak the output to something like yourchannelcommandname {channelname} = $1.

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

send_to_online_only = True

log_file = 'channel_{channelname}.log'

channel_prefix_string = '[{channelname}] '

channel_msg_nick_pattern = '{alias}\\s*?|{alias}\\s+?(?P<arg1>.+?)'

channel_msg_nick_replacement = 'channel {channelname} = $1'

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.

get_log_filename()

File name to use for channel log.

Returns

str –

The filename to use (this is always assumed to be inside

settings.LOG_DIR)

set_log_filename(filename)

Set a custom log filename.

Parameters

filename (str) – The filename to set. This is a path starting from inside the settings.LOG_DIR location.

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 banlist

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

Returns

bool –

True if muting was successful, False if we were already

muted.

unmute(subscriber, **kwargs)

Removes an entity from 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).

Returns

bool –

True if unmuting was successful, False if we were already

unmuted.

ban(target, **kwargs)

Ban a given user from connecting to the channel. This will not stop users already connected, so the user must be booted for this to take effect.

Parameters

• target (Object or Account) – The entity to unmute. This need not be a subscriber.

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

Returns

bool –

True if banning was successful, False if target was already

banned.

unban(target, **kwargs)

Un-Ban a given user. This will not reconnect them - they will still have to reconnect and set up aliases anew.

Parameters

• target (Object or Account) – The entity to unmute. This need not be a subscriber.

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

Returns

bool –

True if unbanning was successful, False if target was not

previously banned.

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, creator=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.

• creator (Account or Object) – Entity to associate with this channel (used for tracking)

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.

Returns

bool –

If deletion was successful. Only time it can fail would be

if channel was already deleted. Even if it were to fail, all subscribers will be disconnected.

channel_prefix()

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

Returns

str – The channel prefix.

add_user_channel_alias(user, alias, **kwargs)

Add a personal user-alias for this channel to a given subscriber.

Parameters

• user (Object or Account) – The one to alias this channel.

• alias (str) – The desired alias.

Note

This is tightly coupled to the default channel command. If you change that, you need to change this as well.

We add two nicks - one is a plain alias -> channel.key that users need to be able to reference this channel easily. The other is a templated nick to easily be able to send messages to the channel without needing to give the full channel command. The structure of this nick is given by self.channel_msg_nick_pattern and self.channel_msg_nick_replacement. By default it maps alias <msg> -> channel <channelname> = <msg>, so that you can for example just write pub Hello to send a message.

The alias created is alias $1 -> channel channel = $1, to allow for sending to channel using the main channel command.

classmethod remove_user_channel_alias(user, alias, **kwargs)

Remove a personal channel alias from a user.

Parameters

• user (Object or Account) – The user to remove an alias from.

• alias (str) – The alias to remove.

• **kwargs – Unused by default. Can be used to pass extra variables into a custom implementation.

Notes

The channel-alias actually consists of two aliases - one channel-based one for searching channels with the alias and one inputline one for doing the ‘channelalias msg’ - call.

This is a classmethod because it doesn’t actually operate on the channel instance.

It sits on the channel because the nick structure for this is pretty complex and needs to be located in a central place (rather on, say, the channel command).

at_pre_msg(message, **kwargs)

Called before the starting of sending the message to a receiver. This is called before any hooks on the receiver itself. If this returns None/False, the sending will be aborted.

Parameters

• message (str) – The message to send.

• **kwargs (any) – Keywords passed on from .msg. This includes senders.

Returns

str, False or None –

Any custom changes made to the message. If

falsy, no message will be sent.

msg(message, senders=None, bypass_mute=False, **kwargs)

Send message to channel, causing it to be distributed to all non-muted subscribed users of that channel.

Parameters

• message (str) – The message to send.

• senders (Object, Account or list, optional) – If not given, there is no way to associate one or more senders with the message (like a broadcast message or similar).

• bypass_mute (bool, optional) – If set, always send, regardless of individual mute-state of subscriber. This can be used for global announcements or warnings/alerts.

• **kwargs (any) – This will be passed on to all hooks. Use no_prefix to exclude the channel prefix.

Notes

The call hook calling sequence is:

• msg = channel.at_pre_msg(message, **kwargs) (aborts for all if return None)

• msg = receiver.at_pre_channel_msg(msg, channel, **kwargs) (aborts for receiver if return None)

• receiver.at_channel_msg(msg, channel, **kwargs)

• receiver.at_post_channel_msg(msg, channel, **kwargs)**

Called after all receivers are processed: - channel.at_post_all_msg(message, **kwargs)

(where the senders/bypass_mute are embedded into **kwargs for later access in hooks)

at_post_msg(message, **kwargs)

This is called after sending to all valid recipients. It is normally used for logging/channel history.

Parameters

• message (str) – The message sent.

• **kwargs (any) – Keywords passed on from msg, including senders.

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

Notes

By default this adds the needed channel nicks to the joiner.

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

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>[\w\d\-]+)/$',
    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>[\w\d\-]+)/(?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>[\w\d\-]+)/$',
    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.

message_transform(*args, **kwargs)

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

format_senders(senders=None, **kwargs)

pose_transform(msgobj, sender_string, **kwargs)

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

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

pre_send_message(msg, **kwargs)

post_send_message(msg, **kwargs)

exception DoesNotExist

Bases: evennia.comms.models.ChannelDB.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.comms.models.ChannelDB.MultipleObjectsReturned

path = 'evennia.comms.comms.DefaultChannel'

typename = 'DefaultChannel'