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.