Metadata-Version: 2.3
Name: mtuci-private-api
Version: 0.1.0
Summary: Library for reaching MTUCI site from code
Author: MisterEblan
Author-email: MisterEblan <boy4rov.da@gmail.com>
Requires-Dist: beautifulsoup4>=4.14.2
Requires-Dist: httpx>=0.28.1
Requires-Dist: mypy>=1.18.2
Requires-Dist: pydantic>=2.12.4
Requires-Dist: pydantic-settings>=2.12.0
Requires-Dist: pyyaml>=6.0.3
Requires-Python: >=3.12
Description-Content-Type: text/markdown

![Tests](https://github.com/MisterEblan/mtuci_private_api/actions/workflows/tests.yaml/badge.svg)
![Python](https://img.shields.io/badge/python-3.12+-blue.svg)
![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)

# MTUCI Private API

Данная библиотека позволяет работать с ЛК МТУСИ из кода Python.<br>
Она работает **асинхронно**, т.к. запросы долгие в силу специфики имитации действий браузера.

> [!IMPORTANT]
> Библиотека работает с функционалом **студентов**.
> У меня нет возможности реализовать функционал старость или преподавателей, т.к. не располагаю такими аккаунтами.

# Возможности

- **Аутентификация**
- **Информация о пользователе**
- **Посещаемость**. Получение актуальной посещаемости по предметам.
- **Расписание**. Расписание предметов можно получить на определённую дату.

## Типизация

Вся библиотека типизировано настолько, насколько возможно, чтобы ей было комфортно пользоваться.

# Архитектура

Библиотека имеет несколько основных модулей:
- `auth` для аутентификации.
- `user` для получения информации о пользователе.
- `attendance` для получения информации о посещаемости.
- `schedule` для получения информации о расписании.
- `models` для моделей данных.
- `mtuci` - основные классы-оркестраторы.

В каждом из модулей (кроме `models`) всё делится на:
- Фабрики запросов.
- Парсеры.
- Сервис.

# Быстрый старт

Для старта Вам понадобится только логин и пароль от Вашего аккаунта ЛК.

```Python
import asyncio
from datetime import datetime
from src.mtuci_private_api import Mtuci

async def main():
    async with Mtuci(
        login="ваш_логин",
        password="ваш_пароль"
) as mtuci:
        # Получение информации о пользователе
        user_info = await mtuci.get_user_info()
        print(f"Студент: {user_info.name}")
        print(f"Группа: {user_info.group}")
        
        # Получение посещаемости
        attendance = await mtuci.get_attendace()
        for subject in attendance:
            print(f"{subject.subject_name}: {subject.attendance_percentage}%")
        
        # Получение расписания
        schedule = await mtuci.get_schedule(datetime(2025, 11, 21))
        for lesson in schedule.lessons:
            print(f"{lesson.start_time}: {lesson.name}")

asyncio.run(main())
```

# Сложности с аутентификацией

В проекте есть две версии аутентификации. По непонятной мне причине когда-то работает первая, а когда-то - вторая.<br>
В силу этого, был создан `AutoAuthService`, который проверяет сначала одну, а потом другую версию. Рекомендуется использовать именно его.

# Разработка

Если Вы хотите что-то поправить или внести новый функционал, то форкните репозиторий.<br>
Старайтесь соблюдать имеющуеся архитектуру и прибегайте к её изменению только в особых случаях.

В репозитории настроены Github Actions с тестами и линтингом, также приложен `.pre-commit-config.yaml` для локальных проверок перед коммитами.
