diff --git a/royalnet/engineer/bullet.py b/royalnet/engineer/bullet.py index dc35c432..e32e9a22 100644 --- a/royalnet/engineer/bullet.py +++ b/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", diff --git a/royalnet/engineer/exc.py b/royalnet/engineer/exc.py index 22e57a97..bfe4c693 100644 --- a/royalnet/engineer/exc.py +++ b/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", )