initial commit

.dockerignore

@@ -0,0 +1,22 @@
+venv/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.db
+*.sqlite3
+*.log
+*.log.*
+*.db-journal
+*.lock
+*.tmp
+*.swp
+*.bak
+*.backup
+.idea/
+.dockerignore
+.env
+docker-compose.yml
+README.md
+Dockerfile
+assets/

.env

@@ -0,0 +1,8 @@
+MESSAGES_SCHEDULE=* * * * *
+GRADES_SCHEDULE=*/30 * * * *
+NEW_HOMEWORK_SCHEDULE=*/30 * * * *
+NEXT_HOMEWORK_SCHEDULE=0 17 * * *
+DEEPL_LANG=EN
+DEEPL_KEY=
+BOT_TOKEN=
+ALLOWED_CHAT_ID=

.gitignore

@@ -0,0 +1,161 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+creds/

Dockerfile

@@ -0,0 +1,14 @@
+FROM python:3.11-alpine
+
+ENV PYTHONUNBUFFERED=1
+
+WORKDIR /app
+RUN mkdir -p ./creds
+COPY . .
+RUN pip install -r requirements.txt
+
+RUN apk add --no-cache tzdata
+ENV TZ=Europe/Warsaw
+
+WORKDIR /app/src
+CMD ["python", "app.py"]

README.md

@@ -0,0 +1,92 @@
+# Vulcan Bot 🤖
+
+Vulcan Bot is a non-interactive Telegram bot designed to fetch and forward updates from the Dziennik Vulcan e-diary system. It informs you about new messages, grades and homeworks. The bot can optionally translate the fetched information from Polish to a language of your choice using the Deepl API.
+
+## Features ✨
+- **Automatic Updates**: Fetches new messages, grades, assignments on a set schedule.
+- **Translation**: Optionally translates messages from Polish to the specified language using Deepl.
+- **Dockerized**: Easily deployed using Docker and docker-compose.
+
+## Limitations ⚠️
+- No interactive mode; it doesn’t respond to incoming commands.
+- Can only forward information to one specified Telegram chat.
+- Supports only one user account on Dziennik Vulcan.
+
+## Installation & Deployment 🚀
+
+### Prerequisites
+- Docker and docker-compose installed on your system.
+
+### Steps
+1. **Clone the repository**: 
+    ```shell
+    git clone https://github.com/ilugakov/vulcan-bot.git
+    cd vulcan-bot
+    ```
+2. **Configure the .env file**: The `.env` file is included in the root directory with empty or default values for some parameters (see below for details).
+3. **Build and Start the Docker Container**: 
+    ```shell
+    docker-compose up --build -d
+    ```
+4. **Authenticate Vulcan Bot with Dziennik Vulcan**:
+
+    The Token, Symbol and PIN need to be obtained from the Vulcan e-register student/parent panel (in the “Mobile access/Dostęp mobilny” tab)
+
+    Replace 'token', 'symbol' and 'pin' arguments with your values and run the following command:
+
+    ```shell
+    docker-compose exec vulcan-bot python -c "import vulcan_authorizer; import asyncio; asyncio.get_event_loop().run_until_complete(vulcan_authorizer.authenticate('token', 'symbol', 'pin', 'device_name'))" && docker-compose restart vulcan-bot
+    ```
+
+## Configuration 🔧
+
+Update the `.env` file with the following parameters:
+
+```env
+MESSAGES_SCHEDULE=* * * * *
+GRADES_SCHEDULE=*/30 * * * *
+NEW_HOMEWORK_SCHEDULE=*/30 * * * *
+NEXT_HOMEWORK_SCHEDULE=0 17 * * *
+DEEPL_LANG=EN
+DEEPL_KEY=
+BOT_TOKEN=
+ALLOWED_CHAT_ID=
+```
+
+### Explanation:
+- `*_SCHEDULE` parameters use the cron syntax to set the schedule for checking updates. If left empty or invalid, the schedule won't run. [Learn about cron syntax here](https://crontab.guru/examples.html).
+  - `MESSAGES_SCHEDULE=* * * * *`: Checks for new messages every minute.
+  - `GRADES_SCHEDULE=*/30 * * * *`: Checks for new grades every 30 minutes.
+  - `NEW_HOMEWORK_SCHEDULE=*/30 * * * *`: Checks for new homework every 30 minutes.
+  - `NEXT_HOMEWORK_SCHEDULE=0 17 * * *`: Checks for the homework with the closest deadline at 5:00 PM every day.
+- `DEEPL_LANG` and `DEEPL_KEY` are optional and required only for translation. Set the desired target language and your Deepl API key. To obtain a Deepl API key, [follow this guide](https://www.deepl.com/ru/pro-api?cta=header-pro-api).
+- `BOT_TOKEN` and `ALLOWED_CHAT_ID` are mandatory:
+  - For `BOT_TOKEN`, you need to create a new bot on Telegram. Follow [this guide](https://core.telegram.org/bots#botfather) to learn how.
+  - To find the `ALLOWED_CHAT_ID`, create a new group on Telegram, add [getidsbot](https://t.me/getidsbot) to the group, and it will display the group's ID. After acquiring the ID, remove getidsbot and add your Vulcan Bot to the group. Set the group ID as the value for `ALLOWED_CHAT_ID`.
+
+## Screenshots 📸
+<details>
+<summary>Example of the bot output</summary>
+
+![Example of the bot output](./assets/scr1.png)
+</details>
+
+
+<details>
+<summary>App registered in Vulcan system</summary>
+
+![App registered in Vulcan system](./assets/scr2.png)
+</details>
+
+
+<details>
+<summary>Example of the correct log output</summary>
+
+![Example of the correct log output](./assets/scr3.png)
+</details>
+
+## License 📄
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details
+
+## Support & Contribution 🤝
+Feel free to contribute to the development of Vulcan Bot. If you have any issues or need support, please open an issue on this repository.

docker-compose.yml

@@ -0,0 +1,9 @@
+version: '3'
+services:
+  vulcan-bot:
+    build:
+      context: .
+    volumes:
+      - ./creds:/app/creds
+    env_file:
+      - .env

requirements.txt

@@ -0,0 +1,7 @@
+aiocron==1.8
+aiogram==3.0.0
+aiohttp==3.8.5
+beautifulsoup4==4.12.2
+croniter==1.4.1
+python-dotenv==1.0.0
+vulcan_api==2.3.0