Add tutorial-mirror object

docs/source/Howto/Starting/Python-basic-introduction.md

@@ -441,7 +441,7 @@ On the game command-line, let's create a mirror:
 A mirror should appear in your location.
 
     > look mirror
-    The mirror shows your reflection:
+    mirror shows your reflection:
     This is User #1
 
 What you are seeing is actually your own avatar in the game, the same thing that is available as `me` in the `py`
@@ -483,7 +483,7 @@ find that Evennia provides ample tools for tagging, searching and finding things
 Now that we know how to find the 'mirror' object, we just need to use that instead of `me`!
 
     > py mirror = self.search("mirror") ; mirror.msg("Mirror, Mirror on the wall ...")
-    The mirror echoes back to you: 
+    mirror echoes back to you:
     "Mirror, Mirror on the wall ..."
 
 The mirror is useful for testing  because its `.msg` method just echoes whatever is sent to it back to the room. More common
@@ -567,7 +567,7 @@ string. Let's combine this with searching for the mirror.
 
     > mirror = me.search("mirror")
     > hello_world(mirror, "Mirror, Mirror on the wall ...")
-    The mirror echoes back to you: 
+    mirror echoes back to you:
     "Mirror, Mirror on the wall ..."
 
 Exit the `py` mode with

evennia/contrib/tutorial_examples/mirror.py

@@ -0,0 +1,61 @@
+"""
+TutorialMirror
+
+A simple mirror object to experiment with.
+
+"""
+
+from evennia import DefaultObject
+from evennia.utils import make_iter
+from evennia import logger
+
+
+class TutorialMirror(DefaultObject):
+    """
+    A simple mirror object that
+    - echoes back the description of the object looking at it
+    - echoes back whatever is being sent to its .msg - to the
+      sender, if given, otherwise to the location of the mirror.
+
+    """
+
+    def return_appearance(self, looker, **kwargs):
+        """
+        This formats the description of this object. Called by the 'look' command.
+
+        Args:
+            looker (Object): Object doing the looking.
+            **kwargs (dict): Arbitrary, optional arguments for users
+                overriding the call (unused by default).
+        """
+
+        if isinstance(looker, self.__class__):
+            # avoid infinite recursion by having two mirrors look at each other
+            return "The image of yourself stretches into infinity."
+        return f"{self.key} shows your reflection:\n{looker.db.desc}"
+
+    def msg(self, text=None, from_obj=None, **kwargs):
+        """
+        Simply override .msg to echo back to the messenger or to the current
+        location.
+
+        Args:
+            text (str or tuple, optional): The message to send. This
+                is treated internally like any send-command, so its
+                value can be a tuple if sending multiple arguments to
+                the `text` oob command.
+            from_obj (obj or iterable)
+                given, at_msg_send will be called. This value will be
+                passed on to the protocol. If iterable, will execute hook
+                on all entities in it.
+        """
+        if not text:
+            text = "<silence>"
+        if from_obj:
+            for obj in make_iter(from_obj):
+                obj.msg(f"{self.key} echoes back to you:\n\"{text}\".")
+        elif self.location:
+            self.location.msg_contents(f"{self.key} echoes back:\n\"{text}\".", exclude=[self])
+        else:
+            # no from_obj and no location, just log
+            logger.log_msg(f"{self.key}.msg was called without from_obj and .location is None.")