Annikka/evennia
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Converted the comm system folder to use Google style doc strings, as per #709.

Browse source
This commit is contained in:
Griatch 2015-05-16 11:03:17 +02:00
parent e84db3df54
commit e37079aa5b
5 changed files with 512 additions and 201 deletions
Download patch file Download diff file Expand all files Collapse all files

238
evennia/comms/comms.py
View file

@ -1,8 +1,8 @@
"""
Default Typeclass for Comms.
Base typeclass for in-game Channels.
See objects.objects for more information on Typeclassing.
"""
from django.conf import settings
from evennia.typeclasses.models import TypeclassBase
from evennia.comms.models import Msg, TempMsg, ChannelDB
@ -13,8 +13,9 @@ from evennia.utils.utils import make_iter
class DefaultChannel(ChannelDB):
"""
This is the base class for all Comms. Inherit from this to create different
types of communication channels.
This is the base class for all Channel Comms. Inherit from this to
create different types of communication channels.
"""
# typeclass setup
__metaclass__ = TypeclassBase
@ -25,6 +26,7 @@ class DefaultChannel(ChannelDB):
Called by the typeclass system the very first time the channel
is saved to the database. Generally, don't overload this but
the hooks called by this method.
"""
self.at_channel_creation()
@ -51,6 +53,7 @@ class DefaultChannel(ChannelDB):
def at_channel_creation(self):
"""
Called once, when the channel is first created.
"""
pass
@ -133,15 +136,19 @@ class DefaultChannel(ChannelDB):
def access(self, accessing_obj, access_type='listen', default=False):
"""
Determines if another object has permission to access.
accessing_obj - object trying to access this one
access_type - type of access sought
default - what to return if no lock of access_type was found
Args:
accessing_obj (Object): Object trying to access this one.
access_type (str): Type of access sought.
default (bool): What to return if no lock of access_type was found
"""
return self.locks.check(accessing_obj, access_type=access_type, default=default)
def delete(self):
"""
Deletes channel while also cleaning up channelhandler
Deletes channel while also cleaning up channelhandler.
"""
self.attributes.clear()
self.aliases.clear()
@ -153,6 +160,15 @@ class DefaultChannel(ChannelDB):
sender_strings=None, external=False):
"""
Generates the formatted string sent to listeners on a channel.
Args:
msg (str): Message to send.
emit (bool, optional): In emit mode the message is not associated
with a specific sender name.
prefix (bool, optional): Prefix `msg` with a text given by `self.channel_prefix`.
sender_strings (list, optional): Used by bots etc, one string per external sender.
external (bool, optional): If this is an external sender or not.
"""
if sender_strings or external:
body = self.format_external(msg, sender_strings, emit=emit)
@ -167,6 +183,11 @@ class DefaultChannel(ChannelDB):
"""
Method for grabbing all listeners that a message should be
sent to on this channel, and sending them a message.
msg (str): Message to distribute.
online (bool): Only send to receivers who are actually online
(not currently used):
"""
# get all players connected to this channel and send to them
for entity in self.subscriptions.all():
@ -185,26 +206,34 @@ class DefaultChannel(ChannelDB):
done before calling this method. The optional keywords are not used if
persistent is False.
msgobj - a Msg/TempMsg instance or a message string. If one of the
former, the remaining keywords will be ignored. If a string,
this will either be sent as-is (if persistent=False) or it
will be used together with header and senders keywords to
create a Msg instance on the fly.
senders - an object, player or a list of objects or players.
Optional if persistent=False.
sender_strings - Name strings of senders. Used for external
connections where the sender is not a player or object. When
this is defined, external will be assumed.
external - Treat this message agnostic of its sender.
persistent (default False) - ignored if msgobj is a Msg or TempMsg.
Args:
msgobj (Msg, TempMsg or str): If a Msg/TempMsg, the remaining
keywords will be ignored (since the Msg/TempMsg object already
has all the data). If a string, this will either be sent as-is
(if persistent=False) or it will be used together with `header`
and `senders` keywords to create a Msg instance on the fly.
header (str, optional): A header for building the message.
senders (Object, Player or list, optional): Optional if persistent=False, used
to build senders for the message.
sender_strings (list, optional): Name strings of senders. Used for external
connections where the sender is not a player or object.
When this is defined, external will be assumed.
persistent (bool, optional): Ignored if msgobj is a Msg or TempMsg.
If True, a Msg will be created, using header and senders
keywords. If False, other keywords will be ignored.
online (bool) - If this is set true, only messages people who are
online (bool, optional) - If this is set true, only messages people who are
online. Otherwise, messages all players connected. This can
make things faster, but may not trigger listeners on players
that are offline.
emit (bool) - Signals to the message formatter that this message is
emit (bool, optional) - Signals to the message formatter that this message is
not to be directly associated with a name.
external (bool, optional): Treat this message as being
agnostic of its sender.
Returns:
success (bool): Returns `True` if message sending was
successful, `False` otherwise.
"""
if senders:
senders = make_iter(senders)
@ -238,6 +267,12 @@ class DefaultChannel(ChannelDB):
def tempmsg(self, message, header=None, senders=None):
"""
A wrapper for sending non-persistent messages.
Args:
message (str): Message to send.
header (str, optional): Header of message to send.
senders (Object or list, optional): Senders of message to send.
"""
self.msg(message, senders=senders, header=header, persistent=False)
@ -247,28 +282,57 @@ class DefaultChannel(ChannelDB):
def channel_prefix(self, msg=None, emit=False):
"""
How the channel should prefix itself for users. Return a string.
Hook method. How the channel should prefix itself for users.
Args:
msg (str, optional): Prefix text
emit (bool, optional): Switches to emit mode, which usually
means to ignore any sender information. Not used by default.
Returns:
prefix (str): The created channel prefix.
"""
return '[%s] ' % self.key
def format_senders(self, senders=None):
"""
Function used to format a list of sender names.
Hook method. Function used to format a list of sender names.
Args:
senders (list): Sender object names.
Returns:
formatted_list (str): The list of names formatted appropriately.
Notes:
This function exists separately so that external sources
can use it to format source names in the same manner as
normal object/player names.
This function exists separately so that external sources can use
it to format source names in the same manner as normal object/player
names.
"""
if not senders:
return ''
return ', '.join(senders)
def pose_transform(self, msg, sender_string):
def pose_transform(self, msgobj, sender_string):
"""
Detects if the sender is posing, and modifies the message accordingly.
Hook method. Detects if the sender is posing, and modifies the
message accordingly.
Args:
msgob (Msg or TempMsg): The message to analyze for a pose.
sender_string (str): The name of the sender/poser.
Returns:
string (str): A message that combines the `sender_string`
component with `msg` in different ways depending on if a
pose was performed or not (this must be analyzed by the
hook).
"""
pose = False
message = msg.message
message = msgobj.message
message_start = message.lstrip()
if message_start.startswith((':', ';')):
pose = True
@ -281,91 +345,131 @@ class DefaultChannel(ChannelDB):
else:
return '%s: %s' % (sender_string, message)
def format_external(self, msg, senders, emit=False):
def format_external(self, msgobj, senders, emit=False):
"""
Used for formatting external messages. This is needed as a separate
operation because the senders of external messages may not be in-game
objects/players, and so cannot have things like custom user
preferences.
Hook method. Used for formatting external messages. This is
needed as a separate operation because the senders of external
messages may not be in-game objects/players, and so cannot
have things like custom user preferences.
Args:
msgobj (Msg or TempMsg): The message to send.
senders (list): Strings, one per sender.
emit (bool, optional): A sender-agnostic message or not.
Returns:
transformed (str): A formatted string.
senders should be a list of strings, each containing a sender.
msg should contain the body of the message to be sent.
"""
if not senders:
emit = True
if emit:
return msg.message
if emit or not senders:
return msgobj.message
senders = ', '.join(senders)
return self.pose_transform(msg, senders)
return self.pose_transform(msgobj, senders)
def format_message(self, msg, emit=False):
def format_message(self, msgobj, emit=False):
"""
Formats a message body for display.
Hook method. Formats a message body for display.
Args:
msgob (Msg or TempMsg): The message object to send.
emit (bool, optional): The message is agnostic of senders.
Returns:
transformed (str): The formatted message.
If emit is True, it means the message is intended to be posted detached
from an identity.
"""
# We don't want to count things like external sources as senders for
# the purpose of constructing the message string.
senders = [sender for sender in msg.senders if hasattr(sender, 'key')]
senders = [sender for sender in msgobj.senders if hasattr(sender, 'key')]
if not senders:
emit = True
if emit:
return msg.message
return msgobj.message
else:
senders = [sender.key for sender in msg.senders]
senders = [sender.key for sender in msgobj.senders]
senders = ', '.join(senders)
return self.pose_transform(msg, senders)
return self.pose_transform(msgobj, senders)
def pre_join_channel(self, joiner):
"""
Run right before a channel is joined. If this returns a false value,
channel joining is aborted.
Hook method. Runs right before a channel is joined. If this
returns a false value, channel joining is aborted.
Args:
joiner (object): The joining object.
Returns:
should_join (bool): If `False`, channel joining is aborted.
"""
return True
def post_join_channel(self, joiner):
"""
Run right after an object or player joins a channel.
Hook method. Runs right after an object or player joins a channel.
Args:
joiner (object): The joining object.
"""
return True
pass
def pre_leave_channel(self, leaver):
"""
Run right before a user leaves a channel. If this returns a false
Hook method. Runs right before a user leaves a channel. If this returns a false
value, leaving the channel will be aborted.
Args:
joiner (object): The joining object.
Returns:
should_leave (bool): If `False`, channel parting is aborted.
"""
return True
def post_leave_channel(self, leaver):
"""
Run right after an object or player leaves a channel.
Hook method. Runs right after an object or player leaves a channel.
Args:
joiner (object): The joining object.
"""
pass
def pre_send_message(self, msg):
"""
Run before a message is sent to the channel.
This should return the message object, after any transformations.
Hook method. Runs before a message is sent to the channel and
should return the message object, after any transformations.
If the message is to be discarded, return a false value.
Args:
msg (Msg or TempMsg): Message to send.
Returns:
result (Msg, TempMsg or bool): If False, abort send.
"""
return msg
def post_send_message(self, msg):
"""
Run after a message is sent to the channel.
Hook method. Run after a message is sent to the channel.
Args:
msg (Msg or TempMsg): Message sent.
"""
pass
def at_init(self):
"""
This is always called whenever this channel is initiated --
that is, whenever it its typeclass is cached from memory. This
happens on-demand first time the channel is used or activated
in some way after being created but also after each server
restart or reload.
Hook method. This is always called whenever this channel is
initiated -- that is, whenever it its typeclass is cached from
memory. This happens on-demand first time the channel is used
or activated in some way after being created but also after
each server restart or reload.
"""
pass