evennia.comms.comms¶
Base typeclass for in-game Channels.
-
class
evennia.comms.comms.
DefaultChannel
(*args, **kwargs)[source]¶ 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.
- Properties:
mutelist banlist wholist
- Working methods:
get_log_filename() set_log_filename(filename) has_connection(account) - check if the given account listens to this channel connect(account) - connect account to this channel disconnect(account) - disconnect account from channel access(access_obj, access_type=’listen’, default=False) - check the
access on this channel (default access_type is listen)
create(key, creator=None, *args, **kwargs) delete() - delete this channel message_transform(msg, emit=False, prefix=True,
sender_strings=None, external=False) - called by the comm system and triggers the hooks below
- msg(msgobj, header=None, senders=None, sender_strings=None,
- persistent=None, online=False, emit=False, external=False) - main
send method, builds and sends a new message to channel.
- tempmsg(msg, header=None, senders=None) - wrapper for sending non-persistent
messages.
- distribute_message(msg, online=False) - send a message to all
connected accounts on channel, optionally sending only to accounts that are currently online (optimized for very large sends)
mute(subscriber, **kwargs) unmute(subscriber, **kwargs) ban(target, **kwargs) unban(target, **kwargs) add_user_channel_alias(user, alias, **kwargs) remove_user_channel_alias(user, alias, **kwargs)
- Useful hooks:
at_channel_creation() - called once, when the channel is created basetype_setup() at_init() at_first_save() channel_prefix() - how the channel should be
prefixed when returning to user. Returns a string
- format_senders(senders) - should return how to display multiple
senders to a channel
- pose_transform(msg, sender_string) - should detect if the
sender is posing, and if so, modify the string
- format_external(msg, senders, emit=False) - format messages sent
from outside the game, like from IRC
- format_message(msg, emit=False) - format the message body before
displaying it to the user. ‘emit’ generally means that the message should not be displayed with the sender’s name.
channel_prefix()
pre_join_channel(joiner) - if returning False, abort join post_join_channel(joiner) - called right after successful join pre_leave_channel(leaver) - if returning False, abort leave post_leave_channel(leaver) - called right after successful leave at_pre_msg(message, **kwargs) at_post_msg(message, **kwargs) web_get_admin_url() web_get_create_url() web_get_detail_url() web_get_update_url() web_get_delete_url()
-
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
()[source]¶ 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.
-
get_log_filename
()[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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
()[source]¶ 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
()[source]¶ Hook method. How the channel should prefix itself for users.
- Returns
str – The channel prefix.
-
add_user_channel_alias
(user, alias, **kwargs)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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
()[source]¶ 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
()[source]¶ 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
()[source]¶ 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
()[source]¶ 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
()[source]¶ 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
()[source]¶ 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.
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶ Bases:
evennia.comms.models.ChannelDB.MultipleObjectsReturned
-
path
= 'evennia.comms.comms.DefaultChannel'¶
-
typename
= 'DefaultChannel'¶