add comments to all functions

Reviewed-on: #5

DB.py

@@ -1,3 +1,5 @@
+import os
+
 from pymongo import MongoClient
 
 
@@ -8,7 +10,10 @@ class UseDB:
 
     def __init__(self, collection_name):
         self.series_collection = None
-        self.client = MongoClient('mongodb', 27017)
+        if os.getenv('ENV') == 'production':
+            self.client = MongoClient('mongodb', 27017)
+        else:
+            self.client = MongoClient('localhost', 27017)
         self.db = self.client['aero']
         self.series_collection = self.db[collection_name]
 

README.md

@@ -18,6 +18,9 @@ db_timetable - это удобное решение для студентов и
 - pymongo
 
 # Для запуска проекта необходимо выполнить следующие шаги:
+Основное:
+- создайте .env файл
+- напишите в нём TOKEN=токен телеграм бота
 
 Для продакшн версии:
 ```bash

additional_functions.py

@@ -1,12 +1,21 @@
-import re
 import datetime
-from aiogram.types import Message, ReplyKeyboardMarkup, KeyboardButton
+import re
+
 from aiogram import Bot
-from get import get_timetable_for_day, fetch_timetable_data
+from aiogram.types import KeyboardButton, Message, ReplyKeyboardMarkup
+
 from DB import UseDB
+from get import fetch_timetable_data, get_timetable_for_day
 
 
-def get_group_id(user_id):
+def get_group_id(user_id: int) -> int | None:
+    """
+    Функция для получения id группы по id пользователя
+
+    :param user_id: int - id пользователя
+
+    :return: int | None - либо id группы полученный по id пользователя или ничего
+    """
     db = UseDB("users")
     if db.find_document({"user_id": user_id}):
         return db.find_document({"user_id": user_id})[0]["group_id"]
@@ -14,7 +23,14 @@ def get_group_id(user_id):
         return None
 
 
-async def on_notification(msg: Message):
+async def on_notification(msg: Message) -> None:
+    """
+    Функция для отправки уведомлений пользователя по времени
+
+    :param msg: Message - объект сообщения от пользователя
+
+    :return: None
+    """
     time_on_notification = msg.text.split()[1]
     pattern = r'^([01]?[0-9]|2[0-3]):([0-5]?[0-9])$'
     if re.match(pattern, time_on_notification):
@@ -32,14 +48,22 @@ async def on_notification(msg: Message):
         )
 
 
-async def set_group(msg: Message):
+async def set_group(msg: Message) -> None:
+    """
+    Функция для установки группы пользователя
+
+    :param msg: Message - объект сообщения от пользователя
+
+    :return: None
+    """
     try:
         group_id = int(msg.text.split()[1])
     except ValueError:
-        return await msg.answer(
+        await msg.answer(
             "Указанная вами группа не найдена. "
             "Пожалуйста, проверьте корректность номера группы."
         )
+        return
     response = fetch_timetable_data(group_id)
     if "404" in str(response) or "500" in str(response):
         await msg.answer(
@@ -70,18 +94,36 @@ async def set_group(msg: Message):
         await msg.answer("Я сохранил группу для вас.", reply_markup=keyboard)
 
 
-async def timetable_for_day(msg: Message, shift: int = 0):
+async def timetable_for_day(msg: Message, shift: int = 0) -> None:
+    """
+    Функция для отправки сообщения пользователю со сдвигом на некоторое количество дней
+
+    :param msg: Message - объект сообщения от пользователя
+    :param shift: int - на сколько дней вперёд пытается пользователь получить расписание
+
+    :return: None
+    """
     group_id = get_group_id(msg.from_user.id)
     if group_id is None:
-        return await msg.answer(
+        await msg.answer(
             "Кажется, вашего пользователя нет в нашей базе данных."
             "Чтобы начать работу, пожалуйста, укажите вашу группу с "
             "помощью команды: /set_group номер_группы."
         )
+        return
     for text in get_timetable_for_day(group_id, shift):
         await msg.answer(text)
 
 
-async def timetable_day(user_id: int, group_id: int, bot: Bot):
+async def timetable_day(user_id: int, group_id: int, bot: Bot) -> None:
+    """
+    Функция для отправки сообщения пользователю по уведомлению
+
+    :param user_id: int - id пользователя
+    :param group_id: int - id группы пользователя
+    :param bot: Bot - бот, с помощью которого можно отправлять сообщения
+
+    :return: None
+    """
     for text in get_timetable_for_day(group_id, 1):
         await bot.send_message(chat_id=user_id, text=text)

docker-compose-prod.yml

@@ -11,6 +11,7 @@ services:
       - poetry run python /aero/main.py
     environment:
       - TZ=Asia/Krasnoyarsk
+      - ENV=production
   mongodb:
     image: mongo
     restart: always

get.py

@@ -1,11 +1,19 @@
+import datetime
+
 import requests
 from bs4 import BeautifulSoup
-import datetime
 
 from DB import UseDB
 
 
 def fetch_timetable_data(group_id: int) -> BeautifulSoup | None:
+    """
+    Функция для парсинга сайта по id группы пользователя
+
+    :param group_id: int - id группы пользователя
+
+    :return: BeautifulSoup | None - объект парсиного сайта или ничего если сайт не доступен
+    """
     base_url = "https://timetable.pallada.sibsau.ru/timetable/group/"
     response = requests.get(f"{base_url}{group_id}")
     if response.status_code == 200:
@@ -15,6 +23,14 @@ def fetch_timetable_data(group_id: int) -> BeautifulSoup | None:
 
 
 def extract_week_data(soup: BeautifulSoup, shift: int) -> dict:
+    """
+    Функция для получения нужной недели из сайта
+
+    :param soup: BeautifulSoup - объект парсиного сайта
+    :param shift: int - на сколько дней вперёд пытается пользователь получить расписание
+
+    :return: dict - готовый текст дня
+    """
     current_week_number = int(datetime.datetime.utcnow().isocalendar()[1])
     current_day_of_week = datetime.datetime.now().weekday()
     if current_day_of_week + shift > 6:
@@ -28,6 +44,13 @@ def extract_week_data(soup: BeautifulSoup, shift: int) -> dict:
 
 
 def parse_day_data(day_data: BeautifulSoup) -> dict:
+    """
+    Функция для получения данных из объекта дня
+
+    :param day_data: BeautifulSoup - объект дня для получения данных
+
+    :return: dict - готовый текст дня
+    """
     schedule = {}
     lines = day_data.find_all('div', {"class": "line"})
     for line in lines:
@@ -40,6 +63,13 @@ def parse_day_data(day_data: BeautifulSoup) -> dict:
 
 
 def format_lesson_details(lesson_text: str) -> str:
+    """
+    Функция для удобного преобразования урока
+
+    :param lesson_text: str - текст урока
+
+    :return: str - готовый текст урока
+    """
     if "1 подгруппа" in lesson_text or "* подгруппа" in lesson_text:
         lesson_text = f"⭐ {lesson_text} ⭐"
     elif "2 подгруппа" in lesson_text:
@@ -48,6 +78,14 @@ def format_lesson_details(lesson_text: str) -> str:
 
 
 def get_timetable_for_day(group_id: int, shift: int = 0) -> list[str]:
+    """
+    Функция для получения всех предметов в виде строк
+
+    :param group_id: int - id группы пользователя
+    :param shift: int - на сколько дней вперёд пытается пользователь получить расписание
+
+    :return: list[str] - готовый объект со строками уроков дня
+    """
     try:
         soup = fetch_timetable_data(group_id)
         if soup:
@@ -64,6 +102,14 @@ def get_timetable_for_day(group_id: int, shift: int = 0) -> list[str]:
 
 
 def get_data_in_database(group_id: int, shift: int = 0) -> dict:
+    """
+    Функция для получения данных из базы данных
+
+    :param group_id: int - id группы пользователя
+    :param shift: int - на сколько дней вперёд пытается пользователь получить расписание
+
+    :return: dict - готовый текст дня
+    """
     current_week_number = int(datetime.datetime.utcnow().isocalendar()[1])
     current_day_of_week = datetime.datetime.now().weekday()
     if current_day_of_week + shift > 6:
@@ -82,5 +128,9 @@ def get_data_in_database(group_id: int, shift: int = 0) -> dict:
     )
     response = {}
     for i in response_data:
-        response[i["lesson_time"]] = [i["lesson_name"], i["lesson_author"], i["lesson_nav"]]
+        response[i["lesson_time"]] = [
+            i["lesson_name"],
+            i["lesson_author"],
+            i["lesson_nav"]
+        ]
     return response

main.py

@@ -1,23 +1,30 @@
 import asyncio
 from datetime import datetime, timedelta
 
-from aiogram import Dispatcher, Bot, F
+import environs
+from aiogram import Bot, Dispatcher, F
 from aiogram.client.default import DefaultBotProperties
 from aiogram.enums import ParseMode
 from aiogram.filters import Command
 from aiogram.types import Message
 
+from additional_functions import (
+    on_notification,
+    set_group,
+    timetable_day,
+    timetable_for_day,
+)
 from DB import UseDB
-from additional_functions import (on_notification, set_group, timetable_for_day,
-                                  timetable_day)
 from use_database import detect_group_to_update
 
-TOKEN = "7171391557:AAGickIyKK-kCAWUO4V_5X3m1_6F4Cmgmdw"
+env = environs.Env()
+env.read_env()
+TOKEN = env.str('TOKEN')
 dp = Dispatcher()
 
 
 @dp.message(Command("start"))
-async def start_handler(msg: Message):
+async def command_start(msg: Message):
     await msg.answer(
         "Приветствую!\nЭтот бот предназначен для просмотра расписания занятий "
         "для любой группы СибГУ, включая сегодня, завтра и послезавтра.\n"
@@ -32,7 +39,7 @@ async def start_handler(msg: Message):
 
 
 @dp.message(Command("set_group"))
-async def start_handler(msg: Message):
+async def command_set_group(msg: Message):
     if len(msg.text.split()) == 2:
         await set_group(msg)
     else:
@@ -43,7 +50,7 @@ async def start_handler(msg: Message):
 
 
 @dp.message(Command("on_notification"))
-async def start_handler(msg: Message):
+async def command_on_notification(msg: Message):
     if len(msg.text.split()) == 2:
         await on_notification(msg)
     else:
@@ -55,23 +62,30 @@ async def start_handler(msg: Message):
 
 @dp.message(F.text == "сегодня")
 @dp.message(Command("today"))
-async def start_handler(msg: Message):
+async def command_today(msg: Message):
     await timetable_for_day(msg)
 
 
 @dp.message(F.text == "завтра")
 @dp.message(Command("tomorrow"))
-async def start_handler(msg: Message):
+async def command_tomorrow(msg: Message):
     await timetable_for_day(msg, 1)
 
 
 @dp.message(F.text == "послезавтра")
 @dp.message(Command("the_day_after_tomorrow"))
-async def start_handler(msg: Message):
+async def command_the_day_after_tomorrow(msg: Message):
     await timetable_for_day(msg, 2)
 
 
-async def send_notification(bot):
+async def send_notification(bot: Bot) -> None:
+    """
+    Функция отправляющая уведомления по прошествию времени
+
+    :param bot: Bot - бот, с помощью которого можно отправлять сообщения
+
+    :return: None
+    """
     while True:
         db = UseDB("users")
         responses = db.find_document({})
@@ -83,7 +97,12 @@ async def send_notification(bot):
         await asyncio.sleep(59)
 
 
-async def update_data():
+async def update_data() -> None:
+    """
+    Функция базу каждый день в полночь
+
+    :return: None
+    """
     while True:
         now = datetime.now()
         next_midnight = (
@@ -104,5 +123,6 @@ async def main() -> None:
     _ = asyncio.create_task(update_data())
     await dp.start_polling(bot)
 
+
 if __name__ == "__main__":
     asyncio.run(main())

poetry.lock

@@ -345,6 +345,26 @@ idna = ["idna (>=3.6)"]
 trio = ["trio (>=0.23)"]
 wmi = ["wmi (>=1.5.1)"]
 
+[[package]]
+name = "environs"
+version = "11.0.0"
+description = "simplified environment variable parsing"
+optional = false
+python-versions = ">=3.8"
+files = [
+    {file = "environs-11.0.0-py3-none-any.whl", hash = "sha256:e0bcfd41c718c07a7db422f9109e490746450da38793fe4ee197f397b9343435"},
+    {file = "environs-11.0.0.tar.gz", hash = "sha256:069727a8f73d8ba8d033d3cd95c0da231d44f38f1da773bf076cef168d312ee8"},
+]
+
+[package.dependencies]
+marshmallow = ">=3.13.0"
+python-dotenv = "*"
+
+[package.extras]
+dev = ["environs[tests]", "pre-commit (>=3.5,<4.0)", "tox"]
+django = ["dj-database-url", "dj-email-url", "django-cache-url"]
+tests = ["environs[django]", "pytest"]
+
 [[package]]
 name = "frozenlist"
 version = "1.4.1"
@@ -456,6 +476,25 @@ files = [
 [package.extras]
 dev = ["black (>=22.8.0,<22.9.0)", "flake8 (>=5.0.4,<5.1.0)", "isort (>=5.11.5,<5.12.0)", "mypy (>=1.4.1,<1.5.0)", "pre-commit (>=2.20.0,<2.21.0)", "pytest (>=7.1.3,<7.2.0)", "pytest-cov (>=3.0.0,<3.1.0)", "pytest-html (>=3.1.1,<3.2.0)", "types-setuptools (>=65.3.0,<65.4.0)"]
 
+[[package]]
+name = "marshmallow"
+version = "3.21.3"
+description = "A lightweight library for converting complex datatypes to and from native Python datatypes."
+optional = false
+python-versions = ">=3.8"
+files = [
+    {file = "marshmallow-3.21.3-py3-none-any.whl", hash = "sha256:86ce7fb914aa865001a4b2092c4c2872d13bc347f3d42673272cabfdbad386f1"},
+    {file = "marshmallow-3.21.3.tar.gz", hash = "sha256:4f57c5e050a54d66361e826f94fba213eb10b67b2fdb02c3e0343ce207ba1662"},
+]
+
+[package.dependencies]
+packaging = ">=17.0"
+
+[package.extras]
+dev = ["marshmallow[tests]", "pre-commit (>=3.5,<4.0)", "tox"]
+docs = ["alabaster (==0.7.16)", "autodocsumm (==0.2.12)", "sphinx (==7.3.7)", "sphinx-issues (==4.1.0)", "sphinx-version-warning (==1.1.2)"]
+tests = ["pytest", "pytz", "simplejson"]
+
 [[package]]
 name = "multidict"
 version = "6.0.5"
@@ -555,6 +594,17 @@ files = [
     {file = "multidict-6.0.5.tar.gz", hash = "sha256:f7e301075edaf50500f0b341543c41194d8df3ae5caf4702f2095f3ca73dd8da"},
 ]
 
+[[package]]
+name = "packaging"
+version = "24.0"
+description = "Core utilities for Python packages"
+optional = false
+python-versions = ">=3.7"
+files = [
+    {file = "packaging-24.0-py3-none-any.whl", hash = "sha256:2ddfb553fdf02fb784c234c7ba6ccc288296ceabec964ad2eae3777778130bc5"},
+    {file = "packaging-24.0.tar.gz", hash = "sha256:eb82c5e3e56209074766e6885bb04b8c38a0c015d0a30036ebe7ece34c9989e9"},
+]
+
 [[package]]
 name = "pydantic"
 version = "2.7.3"
@@ -746,6 +796,20 @@ snappy = ["python-snappy"]
 test = ["pytest (>=7)"]
 zstd = ["zstandard"]
 
+[[package]]
+name = "python-dotenv"
+version = "1.0.1"
+description = "Read key-value pairs from a .env file and set them as environment variables"
+optional = false
+python-versions = ">=3.8"
+files = [
+    {file = "python-dotenv-1.0.1.tar.gz", hash = "sha256:e324ee90a023d808f1959c46bcbc04446a10ced277783dc6ee09987c37ec10ca"},
+    {file = "python_dotenv-1.0.1-py3-none-any.whl", hash = "sha256:f7b63ef50f1b690dddf550d03497b66d609393b40b564ed0d674909a68ebf16a"},
+]
+
+[package.extras]
+cli = ["click (>=5.0)"]
+
 [[package]]
 name = "requests"
 version = "2.32.3"
@@ -767,6 +831,32 @@ urllib3 = ">=1.21.1,<3"
 socks = ["PySocks (>=1.5.6,!=1.5.7)"]
 use-chardet-on-py3 = ["chardet (>=3.0.2,<6)"]
 
+[[package]]
+name = "ruff"
+version = "0.4.8"
+description = "An extremely fast Python linter and code formatter, written in Rust."
+optional = false
+python-versions = ">=3.7"
+files = [
+    {file = "ruff-0.4.8-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:7663a6d78f6adb0eab270fa9cf1ff2d28618ca3a652b60f2a234d92b9ec89066"},
+    {file = "ruff-0.4.8-py3-none-macosx_11_0_arm64.whl", hash = "sha256:eeceb78da8afb6de0ddada93112869852d04f1cd0f6b80fe464fd4e35c330913"},
+    {file = "ruff-0.4.8-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:aad360893e92486662ef3be0a339c5ca3c1b109e0134fcd37d534d4be9fb8de3"},
+    {file = "ruff-0.4.8-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:284c2e3f3396fb05f5f803c9fffb53ebbe09a3ebe7dda2929ed8d73ded736deb"},
+    {file = "ruff-0.4.8-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:a7354f921e3fbe04d2a62d46707e569f9315e1a613307f7311a935743c51a764"},
+    {file = "ruff-0.4.8-py3-none-manylinux_2_17_ppc64.manylinux2014_ppc64.whl", hash = "sha256:72584676164e15a68a15778fd1b17c28a519e7a0622161eb2debdcdabdc71883"},
+    {file = "ruff-0.4.8-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:9678d5c9b43315f323af2233a04d747409d1e3aa6789620083a82d1066a35199"},
+    {file = "ruff-0.4.8-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:704977a658131651a22b5ebeb28b717ef42ac6ee3b11e91dc87b633b5d83142b"},
+    {file = "ruff-0.4.8-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:d05f8d6f0c3cce5026cecd83b7a143dcad503045857bc49662f736437380ad45"},
+    {file = "ruff-0.4.8-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:6ea874950daca5697309d976c9afba830d3bf0ed66887481d6bca1673fc5b66a"},
+    {file = "ruff-0.4.8-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:fc95aac2943ddf360376be9aa3107c8cf9640083940a8c5bd824be692d2216dc"},
+    {file = "ruff-0.4.8-py3-none-musllinux_1_2_i686.whl", hash = "sha256:384154a1c3f4bf537bac69f33720957ee49ac8d484bfc91720cc94172026ceed"},
+    {file = "ruff-0.4.8-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:e9d5ce97cacc99878aa0d084c626a15cd21e6b3d53fd6f9112b7fc485918e1fa"},
+    {file = "ruff-0.4.8-py3-none-win32.whl", hash = "sha256:6d795d7639212c2dfd01991259460101c22aabf420d9b943f153ab9d9706e6a9"},
+    {file = "ruff-0.4.8-py3-none-win_amd64.whl", hash = "sha256:e14a3a095d07560a9d6769a72f781d73259655919d9b396c650fc98a8157555d"},
+    {file = "ruff-0.4.8-py3-none-win_arm64.whl", hash = "sha256:14019a06dbe29b608f6b7cbcec300e3170a8d86efaddb7b23405cb7f7dcaf780"},
+    {file = "ruff-0.4.8.tar.gz", hash = "sha256:16d717b1d57b2e2fd68bd0bf80fb43931b79d05a7131aa477d66fc40fbd86268"},
+]
+
 [[package]]
 name = "soupsieve"
 version = "2.5"
@@ -912,4 +1002,4 @@ multidict = ">=4.0"
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.11"
-content-hash = "df3df3687ea8fc62297464b5fc70d43f3b40bffcc6b05f57cc5416a844cc246d"
+content-hash = "2e86a3f4ac5a604b1b11b405e86729d03e00280df4cfb4c132a0021ade6248ea"

pyproject.toml

@@ -12,8 +12,27 @@ aiogram = "^3.3.0"
 requests = "^2.31.0"
 bs4 = "^0.0.2"
 pymongo = "^4.6.1"
+environs = "^11.0.0"
+ruff = "^0.4.8"
 
 
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+exclude = [
+    ".git",
+    ".ruff_cache",
+    ".venv",
+    "venv",
+    "mongodb",
+    "data",
+]
+line-length = 92
+
+[tool.ruff.lint]
+select = ["E", "F", "UP", "I"]
+
+[tool.ruff.format]
+skip-magic-trailing-comma = true

use_database.py

@@ -1,10 +1,17 @@
 from bs4 import BeautifulSoup
 
-from get import fetch_timetable_data, parse_day_data
 from DB import UseDB
+from get import fetch_timetable_data, parse_day_data
 
 
 def update_database(group_id: int) -> None:
+    """
+    Функция обновление расписание в базе
+
+    :param group_id: int - id группы
+
+    :return: None
+    """
     day_mass = ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday"]
     db = UseDB("saved_data")
     soup: BeautifulSoup = fetch_timetable_data(group_id)
@@ -58,6 +65,11 @@ def update_database(group_id: int) -> None:
 
 
 def detect_group_to_update() -> None:
+    """
+    Функция для перебора всех group_id из базы пользователей
+
+    :return: None
+    """
     db = UseDB("users")
     all_users = db.find_document({})
     users_ids = []