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