From 3c9795ac4fe13bcd835701f1dbcd77a593fb163b Mon Sep 17 00:00:00 2001 From: agatha 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()