From 86b91d5826b6556b999f5732a87c9d4fb9b6dcc7 Mon Sep 17 00:00:00 2001 From: Aryan Shastri Date: Thu, 4 Jun 2026 11:36:49 -0400 Subject: [PATCH 1/2] Refactor: rename overly verbose methods and add PEP 257 docstrings (Fixes #20) --- db.py | 21 +++++++++++++++++++-- ui/helpers/queue_helpers.py | 12 +++++++++++- ui/views/queue_view.py | 6 +++--- 3 files changed, 33 insertions(+), 6 deletions(-) diff --git a/db.py b/db.py index 7e33317..043b318 100644 --- a/db.py +++ b/db.py @@ -74,6 +74,15 @@ async def daily_reset() -> None: def increment_help(user_id: int, user_name: str, student_name: Optional[str] = None) -> None: + """ + Records a help session for a user, incrementing both their total and daily help counts. + Creates a new user record if one does not exist. + + Args: + user_id (int): The Discord user ID. + user_name (str): The user's Discord username. + student_name (Optional[str]): The student's actual name, if provided. + """ cursor = conn.cursor() cursor.execute( """ @@ -88,12 +97,20 @@ def increment_help(user_id: int, user_name: str, student_name: Optional[str] = N ) if student_name: - _update_student_name_if_longer(user_id, student_name) + _update_student_name(user_id, student_name) conn.commit() -def _update_student_name_if_longer(user_id: int, student_name: str) -> None: +def _update_student_name(user_id: int, student_name: str) -> None: + """ + Updates the student's name in the database if the new name provided is longer + than the currently stored name. + + Args: + user_id (int): The Discord user ID of the student. + student_name (str): The new name to evaluate and potentially store. + """ cursor = conn.cursor() cursor.execute("SELECT student_name FROM user_stats WHERE user_id=?", (user_id,)) row = cursor.fetchone() diff --git a/ui/helpers/queue_helpers.py b/ui/helpers/queue_helpers.py index 7e60f38..66517a2 100644 --- a/ui/helpers/queue_helpers.py +++ b/ui/helpers/queue_helpers.py @@ -3,7 +3,17 @@ async def already_in_queue(interaction: discord.Interaction)->bool: return await interaction.client.queue.is_in_queue(interaction.user.id) -async def require_queue_open_and_not_in_queue(interaction: discord.Interaction) -> bool: +async def can_join_queue(interaction: discord.Interaction) -> bool: + """ + Checks if the help queue is currently open and verifies that the user + is not already in it. + + Args: + interaction (discord.Interaction): The interaction context from the user. + + Returns: + bool: True if the queue is open and the user is not in it, False otherwise. + """ if not interaction.client.queue.is_open: await interaction.response.send_message("Queue is closed.", ephemeral=True, delete_after=20) return False diff --git a/ui/views/queue_view.py b/ui/views/queue_view.py index 35fc58b..ce188a3 100644 --- a/ui/views/queue_view.py +++ b/ui/views/queue_view.py @@ -1,5 +1,5 @@ import discord -from ui.helpers.queue_helpers import require_queue_open_and_not_in_queue +from ui.helpers.queue_helpers import can_join_queue from db import get_times_helped_today from ui.modals import HelpModal, PassoffModal, BotIssueModal from ui.helpers.constants import DEFAULT_TIMEOUT, SHORT_TIMEOUT @@ -12,7 +12,7 @@ def __init__(self): @discord.ui.button(label="Need Help", style=discord.ButtonStyle.primary, custom_id="need_help", emoji="🙏") async def help_btn(self, interaction: discord.Interaction, button): - ok = await require_queue_open_and_not_in_queue(interaction) + ok = await can_join_queue(interaction) if not ok: return @@ -21,7 +21,7 @@ async def help_btn(self, interaction: discord.Interaction, button): @discord.ui.button(label="Passoff", style=discord.ButtonStyle.success, custom_id="passoff", emoji="💪") async def passoff_btn(self, interaction: discord.Interaction, button): - ok = await require_queue_open_and_not_in_queue(interaction) + ok = await can_join_queue(interaction) if not ok: return From 180382b76203bc12b76867f555f04e541b645eab Mon Sep 17 00:00:00 2001 From: Aryan Shastri Date: Thu, 4 Jun 2026 15:18:34 -0400 Subject: [PATCH 2/2] Refactor: clean up verbose method names and add docstrings in bot.py --- bot.py | 33 ++++++++++++++++++++++++++------- 1 file changed, 26 insertions(+), 7 deletions(-) diff --git a/bot.py b/bot.py index cf914aa..18fe319 100644 --- a/bot.py +++ b/bot.py @@ -22,6 +22,10 @@ intents.message_content = True class Bot(discord.Client): + """ + The core bot client that manages the help queue, UI views, and scheduled tasks. + Extends discord.Client to handle queue interactions and audio notifications. + """ def __init__(self): super().__init__(intents=intents) self.tree = app_commands.CommandTree(self) @@ -31,6 +35,10 @@ def __init__(self): self._player_task: Optional[asyncio.Task] = None async def setup_hook(self): + """ + Initializes bot UI components (views) and starts background scheduling tasks + before the bot fully connects to Discord. + """ # guild = self.get_guild(1503856452027023451) # print(guild.name) # self.tree.copy_global_to(guild=guild) @@ -52,7 +60,7 @@ async def on_ready(self): async def get_ta_voice_channel(self) -> discord.VoiceChannel | None: for guild in self.guilds: return get(guild.voice_channels, name=TA_VOICE_CHANNEL_NAME) - + async def _play_notifications(self) -> None: """Join TA voice channel and play random mp3 from resources once per minute until queue empty.""" @@ -129,7 +137,7 @@ async def build_queue_status(self) -> str: queue_text = await self.queue.view() return f"**Help Queue Status: {status}**\n{queue_text}" - async def fetch_or_create_queue_status_message(self) -> discord.Message | None: + async def _get_status_message(self) -> discord.Message | None: ta_channel = await self.get_ta_channel() if ta_channel is None: return None @@ -149,8 +157,8 @@ async def fetch_or_create_queue_status_message(self) -> discord.Message | None: self.queue_status_message_id = status_message.id return status_message - async def update_queue_status_message(self) -> None: - status_message = await self.fetch_or_create_queue_status_message() + async def _update_status(self) -> None: + status_message = await self._get_status_message() if status_message is None: return @@ -162,7 +170,7 @@ async def build_help_queue_count(self) -> str: count = len(self.queue.entries) return f"**Help Queue Status: {status} — {count} student{'s' if count != 1 else ''} in queue**" - async def fetch_or_create_help_queue_count_message(self) -> discord.Message | None: + async def _get_count_message(self) -> discord.Message | None: help_channel = await self.get_help_channel() if help_channel is None: return None @@ -182,14 +190,25 @@ async def fetch_or_create_help_queue_count_message(self) -> discord.Message | No self.help_queue_count_message_id = count_message.id return count_message - async def update_help_queue_count_message(self) -> None: - count_message = await self.fetch_or_create_help_queue_count_message() + async def _update_count(self) -> None: + count_message = await self._get_count_message() if count_message is None: return await count_message.edit(content=await self.build_help_queue_count()) async def queue_handler(self, interaction: discord.Interaction, question, is_passoff, in_person, student_name: str): + """ + Processes a new request to join the help queue, creates a QueueEntry, + updates the UI, and triggers the audio notification system if needed. + + Args: + interaction (discord.Interaction): The user interaction context. + question (str): The student's question or issue details. + is_passoff (bool): Indicates if this is a required pass-off assignment. + in_person (bool): Indicates if the student is physically present. + student_name (str): The student's actual name. + """ entry = QueueEntry( user_id=interaction.user.id, username=interaction.user.display_name,