docs: add docstrings

.pylintrc

@@ -0,0 +1,6 @@
+[MASTER]
+max-line-length=120
+init-hook='import sys; sys.path.append("src")'
+
+[MESSAGES CONTROL]
+disable=R0903

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()

stockbot-buyvm.py

@@ -16,6 +16,15 @@ URLS = [
 
 
 def get_url(url):
+    """
+    Fetches a URL and returns its text content.
+
+    Args:
+        url (str): The URL to fetch.
+
+    Returns:
+        str: The text content of the page, or None if there was an error.
+    """
     try:
         response = requests.get(url)
         response.raise_for_status()
@@ -27,6 +36,18 @@ def get_url(url):
 
 
 def get_packages(html):
+    """
+    Takes a string of HTML and extracts all the packages from it.
+
+    Args:
+        html (str): The HTML to parse.
+
+    Returns:
+        list: A list of packages, each represented as a dictionary with the following keys:
+            'name' (str): The name of the package.
+            'qty' (int): The current quantity of the package available.
+            'url' (str): The URL to order the package from, or an empty string if the package is not available.
+    """
     soup = BeautifulSoup(html, 'html.parser')
     packages = []
 
@@ -58,6 +79,20 @@ def load_config(filename):
 
 
 async def main():
+    """
+    Check BuyVM for available KVM slices and alert to a Matrix room if any are found.
+
+    The following configuration options are supported:
+
+    - `memory`: A list of integers specifying the memory quantities to check for.
+      Defaults to [512, 1, 2, 4], which corresponds to a price of $15.00 or less.
+
+    The function will log in to the Matrix server specified in the configuration,
+    then check each URL in `URLS` for available KVM slices. If any are found,
+    it will send a message to the room specified in the configuration with the
+    package name and quantity, and a link to order. Finally, it will close the
+    Matrix session.
+    """
     logger.info('checking buyvm stocks')
     config = load_config('config.json')
     bot = MatrixBot(config['matrix'])