evennia.comms.managers¶
These managers define helper methods for accessing the database from Comm system components.
-
exception
evennia.comms.managers.
CommError
[source]¶ Bases:
Exception
Raised by comm system, to allow feedback to player when caught.
-
evennia.comms.managers.
identify_object
(inp)[source]¶ 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')[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ Retrieve message by its id.
- Parameters
idnum (int or str) – The dbref to retrieve.
- Returns
message (Msg) – The message.
-
get_messages_by_sender
(sender)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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).
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)[source]¶ 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_channel
(channelkey)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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).
- 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)[source]¶ Bases:
evennia.comms.managers.ChannelDBManager
,evennia.typeclasses.managers.TypeclassManager
Wrapper to group the typeclass manager to a consistent name.