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)

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.

Returns

QuerySet – 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

Queryset – Matching messages.

Raises

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

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, Account or Script, optional) – Get messages sent by a particular sender.

• 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

Queryset – Iterable with 0, 1 or more matches.

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, Account or Script, optional) – Get messages sent by a particular sender.

• 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

Queryset – Iterable with 0, 1 or more matches.

create_message(senderobj, message, receivers=None, locks=None, tags=None, header=None, **kwargs)

Create a new communication Msg. Msgs represent a unit of database-persistent communication between entites.

Parameters

• senderobj (Object, Account, Script, str or list) – The entity (or entities) sending the Msg. If a str, this is the id-string for an external sender type.

• message (str) – Text with the message. Eventual headers, titles etc should all be included in this text string. Formatting will be retained.

• receivers (Object, Account, Script, str or list) – An Account/Object to send to, or a list of them. If a string, it’s an identifier for an external receiver.

• locks (str) – Lock definition string.

• tags (list) – A list of tags or tuples (tag[,category[,data]]).

• header (str) – Mime-type or other optional information for the message

Notes

The Comm system is created to be very open-ended, so it’s fully possible to let a message both go several receivers at the same time, it’s up to the command definitions to limit this as desired.

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.

Returns

Queryset – Iterable with 0, 1 or more matches.

create_channel(key, aliases=None, desc=None, locks=None, keep_log=True, typeclass=None, tags=None, attrs=None)

Create A communication Channel. A Channel serves as a central hub for distributing Msgs to groups of people without specifying the receivers explicitly. Instead accounts may ‘connect’ to the channel and follow the flow of messages. By default the channel allows access to all old messages, but this can be turned off with the keep_log switch.

Parameters

key (str) – This must be unique.

Keyword Arguments

• aliases (list of str) – List of alternative (likely shorter) keynames.

• desc (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).

• tags (list) – A list of tags or tuples (tag[,category[,data]]).

• attrs (list) – List of attributes on form (name, value[,category[,lockstring]])

Returns

channel (Channel) – A newly created channel.

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.

Returns

Queryset – Iterable with 0, 1 or more matches.

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.