evennia.comms.managers

These managers define helper methods for accessing the database from Comm system components.

exception evennia.comms.managers.CommError

Bases: Exception

Raised by comm system, to allow feedback to player when caught.

evennia.comms.managers.identify_object(inp)

Helper function. Identifies if an object is an account or an object; return its database model

Parameters

inp (any) – Entity to be idtified.

Returns

identified (tuple) –

This is a tuple with (inp, identifier)

where identifier is one of “account”, “object”, “channel”, “string”, “dbref” or None.

evennia.comms.managers.to_object(inp, objtype='account')

Locates the object related to the given accountname or channel key. If input was already the correct object, return it.

Parameters

• inp (any) – The input object/string

• objtype (str) – Either ‘account’ or ‘channel’.

Returns

obj (object) – The correct object related to inp.

class evennia.comms.managers.MsgManager(*args, **kwargs)

Bases: evennia.typeclasses.managers.TypedObjectManager

This MsgManager implements methods for searching and manipulating Messages directly from the database.

These methods will all return database objects (or QuerySets) directly.

A Message represents one unit of communication, be it over a Channel or via some form of in-game mail system. Like an e-mail, it always has a sender and can have any number of receivers (some of which may be Channels).

identify_object(inp)

Wrapper to identify_object if accessing via the manager directly.

Parameters

inp (any) – Entity to be idtified.

Returns

identified (tuple) –

This is a tuple with (inp, identifier)

where identifier is one of “account”, “object”, “channel”, “string”, “dbref” or None.

get_message_by_id(idnum)

Retrieve message by its id.

Parameters

idnum (int or str) – The dbref to retrieve.

Returns

message (Msg) – The message.

get_messages_by_sender(sender, exclude_channel_messages=False)

Get all messages sent by one entity - this could be either a account or an object

Parameters

• sender (Account or Object) – The sender of the message.

• exclude_channel_messages (bool, optional) – Only return messages not aimed at a channel (that is, private tells for example)

Returns

messages (list) – List of matching messages

Raises

CommError – For incorrect sender types.

get_messages_by_receiver(recipient)

Get all messages sent to one given recipient.

Parameters

recipient (Object, Account or Channel) – The recipient of the messages to search for.

Returns

messages (list) – Matching messages.

Raises

CommError – If the recipient is not of a valid type.

get_messages_by_channel(channel)

Get all persistent messages sent to one channel.

Parameters

channel (Channel) – The channel to find messages for.

Returns

messages (list) – Persistent Msg objects saved for this channel.

search_message(sender=None, receiver=None, freetext=None, dbref=None)

Search the message database for particular messages. At least one of the arguments must be given to do a search.

Parameters

• sender (Object or Account, optional) – Get messages sent by a particular account or object

• receiver (Object, Account or Channel, optional) – Get messages received by a certain account,object or channel

• freetext (str) – Search for a text string in a message. NOTE: This can potentially be slow, so make sure to supply one of the other arguments to limit the search.

• dbref (int) – The exact database id of the message. This will override all other search criteria since it’s unique and always gives only one match.

Returns

messages (list or Msg) – A list of message matches or a single match if dbref was given.

message_search(sender=None, receiver=None, freetext=None, dbref=None)

Search the message database for particular messages. At least one of the arguments must be given to do a search.

Parameters

• sender (Object or Account, optional) – Get messages sent by a particular account or object

• receiver (Object, Account or Channel, optional) – Get messages received by a certain account,object or channel

• freetext (str) – Search for a text string in a message. NOTE: This can potentially be slow, so make sure to supply one of the other arguments to limit the search.

• dbref (int) – The exact database id of the message. This will override all other search criteria since it’s unique and always gives only one match.

Returns

messages (list or Msg) – A list of message matches or a single match if dbref was given.

class evennia.comms.managers.ChannelDBManager(*args, **kwargs)

Bases: evennia.typeclasses.managers.TypedObjectManager

This ChannelManager implements methods for searching and manipulating Channels directly from the database.

These methods will all return database objects (or QuerySets) directly.

A Channel is an in-game venue for communication. It’s essentially representation of a re-sender: Users sends Messages to the Channel, and the Channel re-sends those messages to all users subscribed to the Channel.

get_all_channels()

Get all channels.

Returns

channels (list) – All channels in game.

get_channel(channelkey)

Return the channel object if given its key. Also searches its aliases.

Parameters

channelkey (str) – Channel key to search for.

Returns

channel (Channel or None) – A channel match.

get_subscriptions(subscriber)

Return all channels a given entity is subscribed to.

Parameters

subscriber (Object or Account) – The one subscribing.

Returns

subscriptions (list) – Channel subscribed to.

search_channel(ostring, exact=True)

Search the channel database for a particular channel.

Parameters

• ostring (str) – The key or database id of the channel.

• exact (bool, optional) – Require an exact (but not case sensitive) match.

channel_search(ostring, exact=True)

Search the channel database for a particular channel.

Parameters

• ostring (str) – The key or database id of the channel.

• exact (bool, optional) – Require an exact (but not case sensitive) match.

class evennia.comms.managers.ChannelManager(*args, **kwargs)

Bases: evennia.comms.managers.ChannelDBManager, evennia.typeclasses.managers.TypeclassManager

Wrapper to group the typeclass manager to a consistent name.