# evennia.comms.models

Models for the in-game communication system.

The comm system could take the form of channels, but can also be adopted for storing tells or in-game mail.

The comsystem’s main component is the Message (Msg), which carries the actual information between two parties. Msgs are stored in the database and usually not deleted. A Msg always have one sender (a user), but can have any number targets, both users and channels.

For non-persistent (and slightly faster) use one can also use the TempMsg, which mimics the Msg API but without actually saving to the database.

Channels are central objects that act as targets for Msgs. Accounts can connect to channels by use of a ChannelConnect object (this object is necessary to easily be able to delete connections on the fly).

class `evennia.comms.models.``Msg`(*args, **kwargs)

  Bases: `evennia.utils.idmapper.models.SharedMemoryModel`

  A single message. This model describes all ooc messages sent in-game, both to channels and between accounts.

  The Msg class defines the following database fields (all accessed via specific handler methods):

  - db_sender_accounts: Account senders

  - db_sender_objects: Object senders

  - db_sender_scripts: Script senders

  - db_sender_external: External sender (defined as string name)

  - db_receivers_accounts: Receiving accounts

  - db_receivers_objects: Receiving objects

  - db_receivers_scripts: Receiveing scripts

  - db_receiver_external: External sender (defined as string name)

  - db_header: Header text

  - db_message: The actual message text

  - db_date_created: time message was created / sent

  - db_hide_from_sender: bool if message should be hidden from sender

  - db_hide_from_receivers: list of receiver objects to hide message from

  - db_lock_storage: Internal storage of lock strings.

  `db_sender_accounts`

    Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

    In the example:

        class Pizza(Model):
            toppings = ManyToManyField(Topping, related_name='pizzas')

    **Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

    Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

  `db_sender_objects`

    Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

    In the example:

        class Pizza(Model):
            toppings = ManyToManyField(Topping, related_name='pizzas')

    **Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

    Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

  `db_sender_scripts`

    Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

    In the example:

        class Pizza(Model):
            toppings = ManyToManyField(Topping, related_name='pizzas')

    **Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

    Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

  `db_sender_external`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

  `db_receivers_accounts`

    Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

    In the example:

        class Pizza(Model):
            toppings = ManyToManyField(Topping, related_name='pizzas')

    **Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

    Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

  `db_receivers_objects`

    Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

    In the example:

        class Pizza(Model):
            toppings = ManyToManyField(Topping, related_name='pizzas')

    **Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

    Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

  `db_receivers_scripts`

    Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

    In the example:

        class Pizza(Model):
            toppings = ManyToManyField(Topping, related_name='pizzas')

    **Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

    Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

  `db_receiver_external`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

  `db_header`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

  `db_message`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

  `db_date_created`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

  `db_lock_storage`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

  `db_hide_from_accounts`

    Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

    In the example:

        class Pizza(Model):
            toppings = ManyToManyField(Topping, related_name='pizzas')

    **Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

    Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

  `db_hide_from_objects`

    Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

    In the example:

        class Pizza(Model):
            toppings = ManyToManyField(Topping, related_name='pizzas')

    **Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

    Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

  `db_tags`

    Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

    In the example:

        class Pizza(Model):
            toppings = ManyToManyField(Topping, related_name='pizzas')

    **Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

    Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

  `objects` = <evennia.comms.managers.MsgManager object>
  `locks`
  `tags`
  property `senders`

    Getter. Allows for value = self.senders

  `remove_sender`(senders)

    Remove a single sender or a list of senders.

    Parameters

      senders (Account, Object, str or list) – Senders to remove. If a string, removes the external sender.

  property `receivers`

    Getter. Allows for value = self.receivers. Returns four lists of receivers: accounts, objects, scripts and

    > external_receivers.

  `remove_receiver`(receivers)

    Remove a single receiver, a list of receivers, or a single extral receiver.

    Parameters

      receivers (Account, Object, Script, list or str) – Receiver to remove. A string removes the external receiver.

  property `hide_from`

    Getter. Allows for value = self.hide_from. Returns two lists of accounts and objects.

  `access`(accessing_obj, access_type='read', default=False)

    Checks lock access.

    Parameters

      - accessing_obj (Object or Account) – The object trying to gain access.

      - access_type (str, optional) – The type of lock access to check.

      - default (bool) – Fallback to use if access_type lock is not defined.

    Returns

      result (bool) – If access was granted or not.

  exception `DoesNotExist`

    Bases: `django.core.exceptions.ObjectDoesNotExist`

  exception `MultipleObjectsReturned`

    Bases: `django.core.exceptions.MultipleObjectsReturned`

  property `date_created`

    A wrapper for getting database field db_date_created.

  `get_next_by_db_date_created`(*, field=<django.db.models.fields.DateTimeField: db_date_created>, is_next=True, **kwargs)
  `get_previous_by_db_date_created`(*, field=<django.db.models.fields.DateTimeField: db_date_created>, is_next=False, **kwargs)
  property `header`

    A wrapper for getting database field db_header.

  `id`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

  property `lock_storage`

    A wrapper for getting database field db_lock_storage.

  property `message`

    A wrapper for getting database field db_message.

  `path` = 'evennia.comms.models.Msg'
  property `receiver_external`

    A wrapper for getting database field db_receiver_external.

  property `sender_external`

    A wrapper for getting database field db_sender_external.

  `typename` = 'SharedMemoryModelBase'

class `evennia.comms.models.``TempMsg`(senders=None, receivers=None, message='', header='', type='', lockstring='', hide_from=None)

  Bases: `object`

  This is a non-persistent object for sending temporary messages that will not be stored. It mimics the “real” Msg object, but doesn’t require sender to be given.

  `__init__`(senders=None, receivers=None, message='', header='', type='', lockstring='', hide_from=None)

    Creates the temp message.

    Parameters

      - senders (any or list, optional) – Senders of the message.

      - receivers (Account, Object, Script or list, optional) – Receivers of this message.

      - message (str, optional) – Message to send.

      - header (str, optional) – Header of message.

      - type (str, optional) – Message class, if any.

      - lockstring (str, optional) – Lock for the message.

      - hide_from (Account, Object, or list, optional) – Entities to hide this message from.

  `locks`
  `remove_sender`(sender)

    Remove a sender or a list of senders.

    Parameters

      sender (Object, Account, str or list) – Senders to remove.

  `remove_receiver`(receiver)

    Remove a receiver or a list of receivers

    Parameters

      receiver (Object, Account, Script, str or list) – Receivers to remove.

  `access`(accessing_obj, access_type='read', default=False)

    Checks lock access.

    Parameters

      - accessing_obj (Object or Account) – The object trying to gain access.

      - access_type (str, optional) – The type of lock access to check.

      - default (bool) – Fallback to use if access_type lock is not defined.

    Returns

      result (bool) – If access was granted or not.

class `evennia.comms.models.``ChannelDB`(*args, **kwargs)

  Bases: `evennia.typeclasses.models.TypedObject`

  This is the basis of a comm channel, only implementing the very basics of distributing messages.

  The Channel class defines the following database fields beyond the ones inherited from TypedObject:

  > - db_account_subscriptions: The Account subscriptions.

  > - db_object_subscriptions: The Object subscriptions.

  `db_account_subscriptions`

    Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

    In the example:

        class Pizza(Model):
            toppings = ManyToManyField(Topping, related_name='pizzas')

    **Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

    Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

  `db_object_subscriptions`

    Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

    In the example:

        class Pizza(Model):
            toppings = ManyToManyField(Topping, related_name='pizzas')

    **Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

    Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

  `objects` = <evennia.comms.managers.ChannelDBManager object>
  exception `DoesNotExist`

    Bases: `django.core.exceptions.ObjectDoesNotExist`

  exception `MultipleObjectsReturned`

    Bases: `django.core.exceptions.MultipleObjectsReturned`

  `db_attributes`

    Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

    In the example:

        class Pizza(Model):
            toppings = ManyToManyField(Topping, related_name='pizzas')

    **Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

    Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

  `db_date_created`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

  `db_key`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

  `db_lock_storage`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

  `db_tags`

    Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

    In the example:

        class Pizza(Model):
            toppings = ManyToManyField(Topping, related_name='pizzas')

    **Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

    Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

  `db_typeclass_path`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

  `get_next_by_db_date_created`(*, field=<django.db.models.fields.DateTimeField: db_date_created>, is_next=True, **kwargs)
  `get_previous_by_db_date_created`(*, field=<django.db.models.fields.DateTimeField: db_date_created>, is_next=False, **kwargs)
  `id`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

  `path` = 'evennia.comms.models.ChannelDB'
  `typename` = 'SharedMemoryModelBase'
  `subscriptions`

class `evennia.comms.models.``SubscriptionHandler`(obj)

  Bases: `object`

  This handler manages subscriptions to the channel and hides away which type of entity is subscribing (Account or Object)

  `__init__`(obj)

    Initialize the handler

    Attr:

      obj (ChannelDB): The channel the handler sits on.

  `has`(entity)

    Check if the given entity subscribe to this channel

    Parameters

      entity (str, Account or Object) – The entity to return. If a string, it assumed to be the key or the #dbref of the entity.

    Returns

      subscriber (Account, Object or None) –

      The given

        subscriber.

  `add`(entity)

    Subscribe an entity to this channel.

    Parameters

      entity (Account, Object or list) – The entity or list of entities to subscribe to this channel.

    Note

    No access-checking is done here, this must have

      been done before calling this method. Also no hooks will be called.

  `remove`(entity)

    Remove a subscriber from the channel.

    Parameters

      entity (Account, Object or list) – The entity or entities to un-subscribe from the channel.

  `all`()

    Get all subscriptions to this channel.

    Returns

      subscribers (list) –

      The subscribers. This

        may be a mix of Accounts and Objects!

  `get`()

    Get all subscriptions to this channel.

    Returns

      subscribers (list) –

      The subscribers. This

        may be a mix of Accounts and Objects!

  `online`()

    Get all online accounts from our cache :returns: subscribers (list) –

    > Subscribers who are online or

    >   are puppeted by an online account.

  `clear`()

    Remove all subscribers from channel.