💥 Improve bullets a bit

royalnet/engineer/bullet.py

@@ -15,6 +15,9 @@ from . import exc
 class Bullet(metaclass=abc.ABCMeta):
     """
     The abstract base class for Bullet data models.
+
+    **All** methods of :class:`Bullet` can raise :exc:`.exc.BulletException`, such as :class:`.exc.ForbiddenError` or
+    :class:`.exc.NotSupportedError`.
     """
 
     @abc.abstractmethod
@@ -33,28 +36,33 @@ class Message(Bullet, metaclass=abc.ABCMeta):
     async def text(self) -> t.Optional[str]:
         """
         :return: The raw text contents of the message.
-        :raises .exc.NotSupportedError: If the frontend does not support text messages.
         """
         raise exc.NotSupportedError()
 
     async def timestamp(self) -> t.Optional[datetime.datetime]:
         """
         :return: The :class:`datetime.datetime` at which the message was sent.
-        :raises .exc.NotSupportedError: If the frontend does not support timestamps.
         """
         raise exc.NotSupportedError()
 
     async def reply_to(self) -> t.Optional[Message]:
         """
         :return: The :class:`.Message` this message is a reply to.
-        :raises .exc.NotSupportedError: If the frontend does not support replies.
         """
         raise exc.NotSupportedError()
 
     async def channel(self) -> t.Optional[Channel]:
         """
         :return: The :class:`.Channel` this message was sent in.
-        :raises .exc.NotSupportedError: If the frontend does not support channels.
+        """
+        raise exc.NotSupportedError()
+
+    async def send_reply(self, text: str) -> t.Optional[Message]:
+        """
+        Send a reply to this message in the same channel.
+
+        :param text: The text to reply with.
+        :return: The sent reply message.
         """
         raise exc.NotSupportedError()
 
@@ -67,21 +75,27 @@ class Channel(Bullet, metaclass=abc.ABCMeta):
     async def name(self) -> t.Optional[str]:
         """
         :return: The name of the message channel, such as the chat title.
-        :raises .exc.NotSupportedError: If the frontend does not support channel names.
         """
         raise exc.NotSupportedError()
 
     async def topic(self) -> t.Optional[str]:
         """
         :return: The topic (description) of the message channel.
-        :raises .exc.NotSupportedError: If the frontend does not support channel topics / descriptions.
         """
         raise exc.NotSupportedError()
 
     async def users(self) -> t.List[User]:
         """
         :return: A :class:`list` of :class:`.User` who can read messages sent in the channel.
-        :raises .exc.NotSupportedError: If the frontend does not support such a feature.
+        """
+        raise exc.NotSupportedError()
+
+    async def send_message(self, text: str) -> t.Optional[Message]:
+        """
+        Send a message in this channel.
+
+        :param text: The text to send in the message.
+        :return: The sent message.
         """
         raise exc.NotSupportedError()
 
@@ -94,7 +108,6 @@ class User(Bullet, metaclass=abc.ABCMeta):
     async def name(self) -> t.Optional[str]:
         """
         :return: The user's name.
-        :raises .exc.NotSupportedError: If the frontend does not support usernames.
         """
         raise exc.NotSupportedError()
 
@@ -105,6 +118,15 @@ class User(Bullet, metaclass=abc.ABCMeta):
         """
         raise exc.NotSupportedError()
 
+    async def send_message(self, text: str) -> t.Optional[Message]:
+        """
+        Send a private message to the user.
+
+        :param text: The text to send in the message.
+        :return: The sent message.
+        """
+        raise exc.NotSupportedError()
+
 
 __all__ = (
     "Bullet",

royalnet/engineer/exc.py

@@ -43,12 +43,24 @@ class BulletException(EngineerException):
     """
 
 
-class NotSupportedError(BulletException, NotImplementedError):
+class FrontendError(BulletException):
+    """
+    An error occoured while performing a frontend operation, such as sending a message.
+    """
+
+
+class NotSupportedError(FrontendError, NotImplementedError):
     """
     The requested property isn't available on the current frontend.
     """
 
 
+class ForbiddenError(FrontendError):
+    """
+    The bot user does not have sufficient permissions to perform a frontend operation.
+    """
+
+
 __all__ = (
     "EngineerException",
     "WrenchException",
@@ -57,5 +69,7 @@ __all__ = (
     "InTeleporterError",
     "OutTeleporterError",
     "BulletException",
+    "FrontendError",
     "NotSupportedError",
+    "ForbiddenError",
 )