From 6faf278eb38ccf33474b1859462e8d4993f6f49f Mon Sep 17 00:00:00 2001
From: Stefano Pigozzi <ste.pigozzi@gmail.com>
Date: Wed, 30 Dec 2020 14:59:37 +0100
Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20Create=20conversation=20module?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/source/_static/engineer_diagram.xml |  2 +-
 docs/source/autodoc/engineer.rst         |  4 +-
 royalnet/engineer/__init__.py            |  2 +-
 royalnet/engineer/conversation.py        | 57 ++++++++++++++++++++++++
 royalnet/royaltyping/__init__.py         |  8 ----
 5 files changed, 61 insertions(+), 12 deletions(-)
 create mode 100644 royalnet/engineer/conversation.py

diff --git a/docs/source/_static/engineer_diagram.xml b/docs/source/_static/engineer_diagram.xml
index 58c04cf8..cd8fe5ea 100644
--- a/docs/source/_static/engineer_diagram.xml
+++ b/docs/source/_static/engineer_diagram.xml
@@ -1 +1 @@
-<mxfile host="Electron" modified="2020-12-27T10:33:23.298Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/13.9.9 Chrome/85.0.4183.121 Electron/10.1.5 Safari/537.36" etag="JEjZWtflLNvLgdL41tIv" version="13.9.9" type="device"><diagram id="CE8n8ZrOl62DmRSVWgVr" name="Page-1">7VvbcqM4EP0aP2bLxtc8jnGcvWRqZ52ZzWbeZJBBiZBcQvgyXz8tIRkIjIN3Yw+ppSpJSU2rdenWOWpBOn032t0KtA4/ch/TjtP1d53+rOM440kP/irBPhUMrgepIBDET0W9THBPvmEj7BppQnwcFxQl51SSdVHoccawJwsyJATfFtVWnBZ7XaMAlwT3HqJl6QPxZZhKJ8NuJv8VkyC0Pfe65kmErLIRxCHy+TYn6t90+q7gXKalaOdiqtbOrkvabv6Dp4eBCcxknQbia7JYkMVfU+fPh+U4+EynH8Kr3tAMTu7tjLEPC2CqXMiQB5whepNJpzCTtXpKCXuGquAJ87HqpQu1rMkd52sQ9kD4hKXcG+eiRHIQhTKi5ineEfmPav7L0NQejTFVnu3ylb2tMCn2uUaq+mjtqUrWTNdsu/KqmYWMeSI8fGypTPQhEWB5TM9JFdU65nowTrnFPMIwIFAQmCJJNsVAQyZeg4Ne5lIoGK+e4uHU7gbRxPT0AHP3wpLf4y2JKGLKwSvOpA0BtWheSKh/h/Y8UROPJfKebW0ackG+gT6y3oTHQhpfO6OCxr1qaWwKHIPOJ+uI3gvRR7QrKN6hWNrRcErROiZLPT7VMAKfEDblUvLIKCFKAgZlD2xhYeeUjqo3UHVCqcspF3r2fdedz133WIBssJB4d9Sj5mnfbnmDeaOJqW8zBHEsToQ59LB6VUFgelsAyCEWwNRP6m5S0Rs4p9AborBSDEk8VRs6LkXeYaL/PhidUjDOieoVZHz5BFOL9b7wMGwLH4pLtar3agcTHJciFtwhdcAJ/oytLxnXIRyvkUdYcIdXaraDTLIwC6BEHHy6ohqUQ+L7mGk0k0ii5SH215wwqVdoOIUfWEdXQc4QBuBCvZfV4UepC+lyBmNCRAcQhsDdYhW8hRB0ihBYPxqPbvLXQ3Rf9P1rETkcnAmW+t2SO1viqV6qUU3isTDQEOIZlfb6jMRrzGK13VvuuRD3DAYX5Z6q7npV3f0E8hmXArLjjKiKI59soBio4ifBNzrjgFwhYZ4kgOU651DWAdYRkwRGaVvCQHKNK+wxvC1QWBcx39pbCw75wynW8AYzeRiPDHFklZbiZbOXxlryfAWo3g959sYtedbN2pya7DlqFHnaYefASmPIvqXOi1HncHRR6qzqbtwM5uz1T6ROtEVE84DmqhBJJaNU3cbVpTptAihHX9qpBDHCcYwCbZGwlP2UFKiH1idQvtJ3hQB+YBvHVezZbQn01OzTqb3VGsOgk1JEf8YUq/Vr05MzYuwB5C6TntTp7rohGHtdB2P/Buf5OmMwiYSnnJ/lKjn4ej0jKFkH1yKYBxZZoiKwTASz46oEzBYtT0PLSe1N0xS0tCeVXGxOE0rhPN0i5aVOo4f6ZU6jVd015DTqlF9pVWDZDK/ghKdGBr8Jg4xNxEjZjswr6vQoqM+mJ96+tIB3EuAd0OMdAd51yZ9NuWCxT067YMmuVN76gsUxd1Hv7fWEU74Ovg+5DBL2fye1gKI4Nsp26vMcBBgQK8b34euWbhkwFFycixYPuHAZWqzqrinv1sspbQWHLdKX66AHaYSixpWAyFCtBOFJ/N/yB7DF5BXWEzT5QxptMHSVpdi3FvB3ac6PNS0b0m6Tj/zmLO7A+pvuOB42kqWvfg/lTMz++PJ0i8bOh/Duy3x61ZJ0BUlXrtSgJkfb3PTyHH1s2DlEc3kUaWBpKfpNKfqcd3xnzlzrdPcTPkGoDOhhHYr+DZxOIQLAA3SfOiNW8/Vs7Nd9gyKCJDLfC6RkvFZRY78bUPN+u9tCTe2ocBPZknVtsj6y/Y4C4/vh6kmDuNqWHwu8/RpXF5g6I+63T6grPjQ/BiZn52qoZv+lkCJh9q8e/Zvv</diagram></mxfile>
\ No newline at end of file
+<mxfile host="Electron" modified="2020-12-30T12:59:53.921Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/13.9.9 Chrome/85.0.4183.121 Electron/10.1.5 Safari/537.36" etag="RuLkLSMH5iLDTAz1iPYz" version="13.9.9" type="device"><diagram id="CE8n8ZrOl62DmRSVWgVr" name="Page-1">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</diagram></mxfile>
\ No newline at end of file
diff --git a/docs/source/autodoc/engineer.rst b/docs/source/autodoc/engineer.rst
index d9bfc44c..188dc28e 100644
--- a/docs/source/autodoc/engineer.rst
+++ b/docs/source/autodoc/engineer.rst
@@ -10,10 +10,10 @@
 .. automodule:: royalnet.engineer.bullet
 
 
-``command``
+``conversation``
 -----------
 
-.. automodule:: royalnet.engineer.command
+.. automodule:: royalnet.engineer.conversation
 
 
 ``dispenser``
diff --git a/royalnet/engineer/__init__.py b/royalnet/engineer/__init__.py
index ececd140..1ab3c5ee 100644
--- a/royalnet/engineer/__init__.py
+++ b/royalnet/engineer/__init__.py
@@ -5,7 +5,7 @@ All names are inspired by the `Engineer Class of Team Fortress 2 <https://wiki.t
 """
 
 from .bullet import *
-from .command import *
+from .conversation import *
 from .discard import *
 from .dispenser import *
 from .exc import *
diff --git a/royalnet/engineer/conversation.py b/royalnet/engineer/conversation.py
new file mode 100644
index 00000000..df89ffda
--- /dev/null
+++ b/royalnet/engineer/conversation.py
@@ -0,0 +1,57 @@
+"""
+Conversations are wrapper classes that can be applied to functions which await
+:class:`~royalnet.engineer.bullet.Bullet`\\ s from a :class:`~royalnet.engineer.sentry.Sentry`.
+"""
+
+from __future__ import annotations
+import royalnet.royaltyping as t
+
+import logging
+
+from . import sentry
+
+
+log = logging.getLogger(__name__)
+
+
+class ConversationProtocol(t.Protocol):
+    """
+    Typing annotation for Conversation functions.
+    """
+    def __call__(self, *, _sentry: sentry.Sentry, **kwargs) -> t.Awaitable[t.Optional[ConversationProtocol]]:
+        ...
+
+
+class Conversation:
+    """
+    The base class for Conversations. It does nothing on its own except providing better debug information.
+    """
+
+    def __init__(self, f: ConversationProtocol):
+        self.f: ConversationProtocol = f
+
+    @classmethod
+    def new(cls):
+        """
+        A decorator that instantiates a new :class:`Conversation` object using the decorated function.
+
+        :return: The created :class:`Conversation` object.
+                 It can still be called in the same way as the previous function!
+        """
+        def decorator(f: ConversationProtocol):
+            c = cls(f=f)
+            log.debug(f"Created: {repr(c)}")
+        return decorator
+
+    def __call__(self, *, _sentry: sentry.Sentry, **kwargs) -> t.Awaitable[t.Optional[ConversationProtocol]]:
+        log.debug(f"Calling: {repr(self)}")
+        return self.f(_sentry=_sentry, **kwargs)
+
+    def __repr__(self):
+        return f"<Conversation #{id(self)}>"
+
+
+__all__ = (
+    "ConversationProtocol",
+    "Conversation"
+)
diff --git a/royalnet/royaltyping/__init__.py b/royalnet/royaltyping/__init__.py
index e12fa28d..4372f887 100644
--- a/royalnet/royaltyping/__init__.py
+++ b/royalnet/royaltyping/__init__.py
@@ -11,9 +11,6 @@ from typing import *
 # noinspection PyUnresolvedReferences
 from typing import IO, TextIO, BinaryIO
 
-if TYPE_CHECKING:
-    from royalnet.engineer import Sentry
-
 
 JSONScalar = Union[
     None,
@@ -77,8 +74,3 @@ An async generator yielding either:
 * another :data:`.AsyncAdventure`;
 * :data:`None`. 
 """
-
-
-class Conversation(Protocol):
-    def __call__(self, _sentry: "Sentry", **kwargs) -> Awaitable["Conversation"]:
-        ...