refactor(groups): Докстринги для групповых команд

Author: AuthFailed

tgbot/handlers/__init__.py

@@ -8,7 +8,7 @@
 from tgbot.handlers.groups.admin.settings import group_settings_router
 from tgbot.handlers.groups.join import groups_router
 from tgbot.handlers.groups.user.main import group_user_router
-from tgbot.handlers.groups.whois import group_whois_router
+from tgbot.handlers.groups.user.whois import group_whois_router
 from tgbot.handlers.inline.inline import user_inline_router
 from tgbot.handlers.start import start_router
 

tgbot/handlers/common/whois.py

@@ -7,7 +7,7 @@
 from aiogram.types import Message
 from stp_database import Employee, MainRequestsRepo
 
-from tgbot.handlers.groups.whois import create_user_info_message
+from tgbot.handlers.groups.user.whois import create_user_info_message
 from tgbot.misc.helpers import get_role
 
 logger = logging.getLogger(__name__)
@@ -33,7 +33,7 @@ async def private_whois_command(
     # Проверяем авторизацию пользователя
     if not user:
         await message.reply(
-            "❌ Для использования команды /whois необходимо авторизоваться в боте"
+            "🚨 Для использования команд необходимо авторизоваться в боте"
         )
         return
 

tgbot/handlers/groups/admin/admin.py

@@ -10,12 +10,16 @@
 
 
 @group_settings_router.message(Command("settings"), GroupAdminFilter())
-async def group_settings(message: Message):
-    """Handle /settings command for groups admins."""
-    # Создаем deeplink для открытия настроек группы в личке
+async def group_settings(message: Message) -> None:
+    """Обработчик команды /settings в группе для администраторов.
+
+    Args:
+        message: Сообщение от пользователя
+    """
     settings_deeplink = await create_start_link(
         message.bot, payload=f"group_{message.chat.id}", encode=True
     )
+
     await message.answer(
         f"""<b>⚙️ Настройки группы</b>
 
@@ -24,8 +28,12 @@ async def group_settings(message: Message):
 
 
 @group_settings_router.message(Command("settings"))
-async def group_settings_non_admin(message: Message):
-    """Handle /settings command for non-admin users."""
+async def group_settings_non_admin(message: Message) -> None:
+    """Обработчик команды /settings в группе для обычных пользователей.
+
+    Args:
+        message: Сообщение от пользователя
+    """
     await message.reply(
         "Только администраторы группы могут использовать эту команду :("
     )

tgbot/handlers/groups/admin/settings.py

@@ -20,26 +20,29 @@
 
 
 @group_user_router.message(Command("admins"))
-async def admins_cmd(message: Message, user: Employee, stp_repo: MainRequestsRepo):
-    """/admins для получения списка администраторов группы"""
+async def admins_cmd(
+    message: Message, user: Employee, stp_repo: MainRequestsRepo
+) -> None:
+    """Обработчик команды /admins для групп.
+
+    Args:
+        message: Сообщение от пользователя
+        user: Экземпляр пользователя с моделью Employee
+        stp_repo: Репозиторий операций с базой STP
+    """
     try:
-        # Получаем список администраторов чата
         chat_administrators = await message.bot.get_chat_administrators(message.chat.id)
 
-        # Обрабатываем каждого администратора и проверяем их в базе данных
         admin_list = []
         owner = None
 
         for admin in chat_administrators:
             user_info = admin.user
 
-            # Проверяем администратора в базе данных
             db_user = await stp_repo.employee.get_users(user_id=user_info.id)
             if db_user:
-                # Если есть в БД, используем данные из БД с ссылкой
                 display_name = format_fullname(db_user, True, True)
             else:
-                # Если нет в БД, используем данные из Telegram
                 display_name = (
                     f"@{user_info.username}"
                     if user_info.username
@@ -78,15 +81,21 @@ async def admins_cmd(message: Message, user: Employee, stp_repo: MainRequestsRep
     except Exception as e:
         logger.error(f"Ошибка при получении списка администраторов: {e}")
         await message.reply(
-            "❌ Произошла ошибка при получении списка администраторов. Возможно, у бота недостаточно прав."
+            "🚨 Не смог найти администраторов. Возможно, у меня недостаточно прав"
         )
 
 
 @group_user_router.message(
     Command("balance"), MultiRoleFilter(SpecialistFilter(), DutyFilter())
 )
 async def balance_cmd(message: Message, user: Employee, stp_repo: MainRequestsRepo):
-    """/balance для получения своего баланса"""
+    """Обработчик команды /balance для групп.
+
+    Args:
+        message: Сообщение от пользователя
+        user: Экземпляр пользователя с моделью Employee
+        stp_repo: Репозиторий операций с базой STP
+    """
     try:
         user_balance = await stp_repo.transaction.get_user_balance(user_id=user.user_id)
         achievements_sum = await stp_repo.transaction.get_user_achievements_sum(
@@ -105,12 +114,18 @@ async def balance_cmd(message: Message, user: Employee, stp_repo: MainRequestsRe
 
     except Exception as e:
         logger.error(f"Ошибка при получении баланса: {e}")
-        await message.reply("❌ Произошла ошибка при получении баланса")
+        await message.reply("🚨 Не смог получить твой баланс. Напиши в @stp_helpbot")
 
 
 @group_user_router.message(Command("top"))
 async def top_cmd(message: Message, user: Employee, stp_repo: MainRequestsRepo):
-    """/top для получения рейтинга группы"""
+    """Обработчик команды /top для групп.
+
+    Args:
+        message: Сообщение от пользователя
+        user: Экземпляр пользователя с моделью Employee
+        stp_repo: Репозиторий операций с базой STP
+    """
     try:
         # Получаем участников группы из базы
         group_members_data = await stp_repo.group_member.get_group_members(
@@ -171,4 +186,6 @@ async def top_cmd(message: Message, user: Employee, stp_repo: MainRequestsRepo):
 
     except Exception as e:
         logger.error(f"Ошибка при получении рейтинга группы: {e}")
-        await message.reply("❌ Произошла ошибка при получении рейтинга группы")
+        await message.reply(
+            "🚨 Не смог посчитать рейтинг группы. Напиши в @stp_helpbot"
+        )

tgbot/handlers/groups/user/main.py

@@ -14,7 +14,15 @@
 
 
 def create_user_info_message(user: Employee, user_head: Employee = None) -> str:
-    """Создание сообщения с информацией о пользователе (аналогично inline search)"""
+    """Форматирование информации о пользователе.
+
+    Args:
+        user: Экземпляр пользователя с моделью Employee
+        user_head: Руководитель сотрудника
+
+    Returns:
+        Форматированный вид информации о пользователе
+    """
     # Определяем уровень доступа и эмодзи
     role_info = get_role(user.role)
 
@@ -51,12 +59,19 @@ def create_user_info_message(user: Employee, user_head: Employee = None) -> str:
 
 
 @group_whois_router.message(Command("whois"))
-async def whois_command(message: Message, user: Employee, stp_repo: MainRequestsRepo):
-    """Команда /whois для получения информации о пользователе"""
-    # Проверяем авторизацию пользователя
+async def whois_command(
+    message: Message, user: Employee, stp_repo: MainRequestsRepo
+) -> None:
+    """Обработчик команды /whois в группе.
+
+    Args:
+        message: Сообщение от пользователя
+        user: Экземпляр пользователя с моделью Employee
+        stp_repo: Репозиторий операций с базой STP
+    """
     if not user:
         await message.reply(
-            "❌ Для использования команды /whois необходимо авторизоваться в боте"
+            "🚨 Для использования команд необходимо авторизоваться в боте"
         )
         return
 
@@ -87,7 +102,7 @@ async def whois_command(message: Message, user: Employee, stp_repo: MainRequests
 
         if not target_user:
             await message.reply(
-                f"""<b>❌ Пользователь не найден</b>
+                f"""🤷🏻‍♂️ <b>Никого не нашел</b>
 
 Пользователь с ID <code>{replied_user_id}</code> не найден в базе
 
@@ -113,31 +128,39 @@ async def whois_command(message: Message, user: Employee, stp_repo: MainRequests
 
         # Логируем использование команды
         logger.info(
-            f"[WHOIS] {user.fullname} ({message.from_user.id}) запросил информацию о {target_user.fullname} ({target_user.user_id})"
+            f"[/whois] {user.fullname} ({message.from_user.id}) запросил информацию о {target_user.fullname} ({target_user.user_id})"
         )
 
     except Exception as e:
         logger.error(f"Ошибка при выполнении команды /whois: {e}")
         await message.reply(
-            "❌ Произошла ошибка при получении информации о пользователе. Попробуйте позже."
+            "🚨 Произошла ошибка при поиске сотрудника. Напиши в @stp_helpbot"
         )
 
 
-# Дополнительный хэндлер для команды /whois с аргументом (поиск по имени)
 @group_whois_router.message(Command("whois", magic=F.args))
-async def whois_with_args(message: Message, user: Employee, stp_repo: MainRequestsRepo):
-    """Команда /whois с аргументом для поиска по имени"""
-    # Проверяем авторизацию пользователя
+async def whois_with_args(
+    message: Message, user: Employee, stp_repo: MainRequestsRepo
+) -> None:
+    """Обработчик команды /whois с аргументами.
+
+    Args:
+        message: Сообщение от пользователя
+        user: Экземпляр пользователя с моделью Employee
+        stp_repo: Репозиторий операций с базой STP
+    """
     if not user:
         await message.reply(
-            "❌ Для использования команды /whois необходимо авторизоваться в боте"
+            "🚨 Для использования команд необходимо авторизоваться в боте"
         )
         return
 
     search_query = message.text.split(maxsplit=1)[1].strip()
 
     if len(search_query) < 2:
-        await message.reply("❌ Поисковый запрос слишком короткий (минимум 2 символа)")
+        await message.reply(
+            "🤔 Не могу найти пользователя. Попробуй увеличить количество символов в запросе"
+        )
         return
 
     try:
@@ -148,7 +171,7 @@ async def whois_with_args(message: Message, user: Employee, stp_repo: MainReques
 
         if not found_users:
             await message.reply(
-                f"""<b>❌ Пользователи не найдены</b>
+                f"""🤷🏻‍♂️ <b>Никого не нашел</b>
 
 По запросу "<code>{search_query}</code>" ничего не найдено.
 
@@ -204,7 +227,7 @@ async def whois_with_args(message: Message, user: Employee, stp_repo: MainReques
         users_text = "\n\n".join(user_list)
 
         await message.reply(
-            f"""<b>🔍 Найдено пользователей: {len(sorted_users)}</b>
+            f"""<b>🔍 Нашел сотрудников: {len(sorted_users)}</b>
 
 По запросу "<code>{search_query}</code>":
 
@@ -217,15 +240,11 @@ async def whois_with_args(message: Message, user: Employee, stp_repo: MainReques
 
         # Логируем использование команды
         logger.info(
-            f"[WHOIS] {user.fullname} ({message.from_user.id}) нашел {len(sorted_users)} пользователей по запросу '{search_query}'"
+            f"[/whois] {user.fullname} ({message.from_user.id}) нашел {len(sorted_users)} сотрудников по запросу '{search_query}'"
         )
 
     except Exception as e:
         logger.error(f"Ошибка при поиске пользователей для команды /whois: {e}")
         await message.reply(
-            "❌ Произошла ошибка при поиске пользователей. Попробуйте позже."
+            "🚨 Произошла ошибка при поиске сотрудника. Напиши в @stp_helpbot"
         )
-
-
-# Если создаете новый файл, экспортируйте роутер
-__all__ = ["group_whois_router"]

tgbot/handlers/groups/whois.py renamed to tgbot/handlers/groups/user/whois.py

@@ -126,7 +126,7 @@ def get_dataframe(
             return self._df_cache[cache_key]
 
         # Загрузка из файла
-        logger.info(f"[Cache] Промах для {file_path.name}:{sheet_name}, загрузка...")
+        logger.debug(f"[Cache] Промах для {file_path.name}:{sheet_name}, загрузка...")
         try:
             # Используем pandas
             df = pd.read_excel(
@@ -382,7 +382,7 @@ def invalidate(self, file_path: Path):
         if file_key in self._date_indexes:
             del self._date_indexes[file_key]
 
-        logger.info(f"[Cache] Invalidated cache for {file_path.name}")
+        logger.debug(f"[Cache] Invalidated cache for {file_path.name}")
 
     def clear(self):
         """Очищает все кэши."""