From fb773a9e75f041d3865c37007b6050b4a2db047b Mon Sep 17 00:00:00 2001
From: Griatch <griatch@gmail.com>
Date: Thu, 21 Sep 2017 09:50:20 +0200
Subject: [PATCH] Cleanup of at_msg_receive/send hooks

---
 evennia/accounts/accounts.py | 44 +++++++++++++++++++++++++++++-------
 evennia/objects/objects.py   |  9 ++++----
 2 files changed, 41 insertions(+), 12 deletions(-)

diff --git a/evennia/accounts/accounts.py b/evennia/accounts/accounts.py
index 88fc60a19a..a45e51d722 100644
--- a/evennia/accounts/accounts.py
+++ b/evennia/accounts/accounts.py
@@ -810,24 +810,52 @@ class DefaultAccount(with_metaclass(TypeclassBase, AccountDB)):
         """
         pass
 
-    def at_msg_receive(self, message, from_obj=None, **kwargs):
+    def at_msg_receive(self, text=None, from_obj=None, **kwargs):
         """
-        This is currently unused.
+        This hook is called whenever someone sends a message to this
+        object using the `msg` method.
+
+        Note that from_obj may be None if the sender did not include
+        itself as an argument to the obj.msg() call - so you have to
+        check for this. .
+
+        Consider this a pre-processing method before msg is passed on
+        to the user session. If this method returns False, the msg
+        will not be passed on.
 
         Args:
-            **kwargs (dict): Arbitrary, optional arguments for users
-                overriding the call (unused by default).
+            text (str, optional): The message received.
+            from_obj (any, optional): The object sending the message.
+
+        Kwargs:
+            This includes any keywords sent to the `msg` method.
+
+        Returns:
+            receive (bool): If this message should be received.
+
+        Notes:
+            If this method returns False, the `msg` operation
+            will abort without sending the message.
 
         """
         return True
 
-    def at_msg_send(self, message, to_object, **kwargs):
+    def at_msg_send(self, text=None, to_obj=None, **kwargs):
         """
-        This is currently unused.
+        This is a hook that is called when *this* object sends a
+        message to another object with `obj.msg(text, to_obj=obj)`.
 
         Args:
-            **kwargs (dict): Arbitrary, optional arguments for users
-                overriding the call (unused by default).
+            text (str, optional): Text to send.
+            to_obj (any, optional): The object to send to.
+
+        Kwargs:
+            Keywords passed from msg()
+
+        Notes:
+            Since this method is executed by `from_obj`, if no `from_obj`
+            was passed to `DefaultCharacter.msg` this hook will never
+            get called.
 
         """
         pass
diff --git a/evennia/objects/objects.py b/evennia/objects/objects.py
index 9bbdac586a..6915c95d95 100644
--- a/evennia/objects/objects.py
+++ b/evennia/objects/objects.py
@@ -1374,7 +1374,7 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)):
         """
         pass
 
-    def at_msg_receive(self, text=None, **kwargs):
+    def at_msg_receive(self, text=None, from_obj=None, **kwargs):
         """
         This hook is called whenever someone sends a message to this
         object using the `msg` method.
@@ -1389,6 +1389,7 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)):
 
         Args:
             text (str, optional): The message received.
+            from_obj (any, optional): The object sending the message.
 
         Kwargs:
             This includes any keywords sent to the `msg` method.
@@ -1409,14 +1410,14 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)):
         message to another object with `obj.msg(text, to_obj=obj)`.
 
         Args:
-            text (str): Text to send.
-            to_obj (Object): The object to send to.
+            text (str, optional): Text to send.
+            to_obj (any, optional): The object to send to.
 
         Kwargs:
             Keywords passed from msg()
 
         Notes:
-            Since this method is executed `from_obj`, if no `from_obj`
+            Since this method is executed by `from_obj`, if no `from_obj`
             was passed to `DefaultCharacter.msg` this hook will never
             get called.