# 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).

      - 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)

    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)

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

  Wrapper to group the typeclass manager to a consistent name.