From 3c9795ac4fe13bcd835701f1dbcd77a593fb163b Mon Sep 17 00:00:00 2001
From: agatha <agatha@juggalol.com>
Date: Sun, 15 Sep 2024 18:51:34 -0400
Subject: [PATCH] docs: add docstrings for MatrixBot

---
 .pylintrc |  6 ++++
 matrix.py | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 97 insertions(+)
 create mode 100644 .pylintrc

diff --git a/.pylintrc b/.pylintrc
new file mode 100644
index 0000000..12c464a
--- /dev/null
+++ b/.pylintrc
@@ -0,0 +1,6 @@
+[MASTER]
+max-line-length=120
+init-hook='import sys; sys.path.append("src")'
+
+[MESSAGES CONTROL]
+disable=R0903
diff --git a/matrix.py b/matrix.py
index 28286a1..c657038 100644
--- a/matrix.py
+++ b/matrix.py
@@ -1,10 +1,46 @@
+"""
+matrix.py
+
+A module for interacting with the Matrix protocol.
+
+Classes:
+    MatrixBot: A Matrix bot that can send messages and markdown messages to a room.
+
+Dependencies:
+    markdown: A library for converting markdown to HTML.
+    loguru: A library for logging.
+    nio: A library for interacting with the Matrix protocol.
+"""
 import markdown
 from loguru import logger
 from nio import AsyncClient, LoginResponse
 
 
 class MatrixBot:
+    """
+    A Matrix bot that can send messages and markdown messages to a room.
+
+    Attributes:
+        config (dict): A dictionary containing the bot's configuration.
+            Expected keys are 'homeserver', 'username', 'password', 'room_id'.
+        client (AsyncClient): The Matrix client instance.
+        logged_in (bool): Whether the bot is currently logged in.
+
+    Methods:
+        __init__: Initializes the bot with a given configuration.
+        ensure_logged_in: Ensures that the bot is logged in to the Matrix homeserver.
+        send_message: Sends a message to the room specified in the bot's configuration.
+        send_markdown: Sends a markdown formatted message to the room specified in the bot's configuration.
+        close: Log out from the Matrix homeserver and close the client.
+    """
     def __init__(self, config: dict):
+        """
+        A Matrix bot that can send messages and markdown messages to a room.
+
+        Args:
+            config (dict): A dictionary containing the bot's configuration.
+                Expected keys are 'homeserver', 'username', 'password', 'room_id'.
+        """
         self.config = config
 
         self.client = AsyncClient(
@@ -14,6 +50,16 @@ class MatrixBot:
         self.logged_in = False
 
     async def ensure_logged_in(self):
+        """
+        Ensures that the bot is logged in to the Matrix homeserver.
+
+        If the bot is not logged in, attempts to log in using the provided
+        password. If the login attempt fails, logs the error and closes the
+        nio session.
+
+        If an exception occurs during the login attempt, logs the error and
+        re-raises it.
+        """
         if not self.logged_in:
             try:
                 response = await self.client.login(password=self.config['password'])
@@ -30,6 +76,22 @@ class MatrixBot:
                 raise
 
     async def send_message(self, message: str):
+        """
+        Sends a message to the room specified in the bot's configuration.
+
+        The message is sent as a simple text message, with the 'msgtype' set to
+        'm.text' and the 'body' set to the provided message.
+
+        If the bot is not logged in, attempts to log in using the provided
+        password. If the login attempt fails, logs the error and closes the
+        nio session.
+
+        If an exception occurs during the login attempt or the message sending,
+        logs the error and re-raises it.
+
+        Args:
+            message (str): The message to send to the room.
+        """
         await self.ensure_logged_in()
 
         if not self.logged_in:
@@ -51,6 +113,25 @@ class MatrixBot:
             raise
 
     async def send_markdown(self, message: str):
+        """
+        Sends a markdown formatted message to the room specified in the bot's
+        configuration.
+
+        The message is sent as a text message with the 'msgtype' set to
+        'm.text', the 'body' set to the provided message, and the 'format'
+        set to 'org.matrix.custom.html'. The 'formatted_body' is set to the
+        markdown formatted message.
+
+        If the bot is not logged in, attempts to log in using the provided
+        password. If the login attempt fails, logs the error and closes the
+        nio session.
+
+        If an exception occurs during the login attempt or the message sending,
+        logs the error and re-raises it.
+
+        Args:
+            message (str): The message to send to the room.
+        """
         await self.ensure_logged_in()
 
         if not self.logged_in:
@@ -78,6 +159,16 @@ class MatrixBot:
             raise
 
     async def close(self):
+        """
+        Log out from the Matrix homeserver and close the client.
+
+        If the bot is logged in, attempts to log out using the provided
+        password. If the login attempt fails, logs the error and closes the
+        nio session.
+
+        If an exception occurs during the login attempt or the message sending,
+        logs the error and re-raises it.
+        """
         if self.logged_in:
             try:
                 await self.client.logout()