ittop-academy-api 0.0.5

Неофициальный Python SDK для взаимодействия с API Top Academy.

top-academy-api

Неофициальный асинхронный Python SDK для API Top Academy (msapi.top-academy.ru).
Базовый URL API: https://msapi.top-academy.ru/api/v2.

---

Установка

pip install ittop-academy-api

Или из репозитория:

pip install -e .

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

import asyncio
from top_academy_api import TopAcademyClient
from top_academy_api.config import APP_KEY

async def main():
    async with TopAcademyClient() as client:
        await client.auth.login(APP_KEY, "username", "password")
        user = await client.user.get_info()
        print(user.full_name)
        homeworks = await client.homework.list_homeworks(group_id=2)
        for hw in homeworks:
            print(hw.theme)

asyncio.run(main())

---

Все эндпоинты API

В таблицах ниже перечислены все методы SDK и соответствующие HTTP-запросы. В колонке Возвращает указана структура ответа (тип или поля).

Auth — client.auth

Метод SDK	HTTP	Путь	Возвращает
login(app_key, username, password)	POST	/auth/login	AuthLogin: access_token, refresh_token, expires_in_refresh, expires_in_access, user_type, city_data (id_city, prefix, name, timezone_name, ...), user_role
logout()	POST	/auth/logout	—

---

Пользователь и настройки — client.user

Метод SDK	HTTP	Путь	Возвращает
get_info()	GET	/settings/user-info	UserInfo: groups, current_group_id, photo, full_name, age, group_name, stream_name, birthday, gaming_points

---

Рейтинг (Dashboard) — client.rating

Метод SDK	HTTP	Путь	Возвращает
get_leader_stream_points()	GET	/dashboard/progress/leader-stream-points	LeaderPointsResponse: totalCount, studentPosition, weekDiff, monthDiff
get_leader_stream()	GET	/dashboard/progress/leader-stream	StreamRating: список {id, full_name, photo_path, position, amount}
get_leader_group_points()	GET	/dashboard/progress/leader-group-points	LeaderPointsResponse: totalCount, studentPosition, weekDiff, monthDiff
get_group_leaders()	GET	/dashboard/progress/leader-group	GroupRating: список {id, full_name, photo_path, position, amount}

---

Метрики и графики — client.metrics

Метод SDK	HTTP	Путь	Возвращает
get_future_exams()	GET	/dashboard/info/future-exams	Список предстоящих экзаменов (структура API)
get_activity()	GET	/dashboard/progress/activity	Список: date, action, current_point, point_types_id, achievements_id, achievements_name, ...
get_progress_chart()	GET	/dashboard/chart/progress	Список: date, points, previous_points, has_rasp
get_attendance()	GET	/dashboard/chart/attendance	AttendanceMetrics: список {date, points, previous_points, has_rasp}
get_average_grade()	GET	/dashboard/chart/average-progress	AverageGradesMetrics: список по датам

---

Домашние задания — client.homework

Метод SDK	HTTP	Путь	Возвращает
get_counters()	GET	/count/homework	HomeworkCounters: список {counter_type, counter}
get_group_history(group_id=None)	GET	/homework/settings/group-history	Список истории групп ДЗ
has_material(id_)	POST	/homework/operations/has-material	bool
list_homeworks(page_start, status, type_, group_id)	GET	/homework/operations/list	HomeworkList: список HomeworkItem (id, id_spec, theme, file_path, status, fio_teach, completion_time, ...)
get_evaluation_tags()	GET	/homework/evaluation/operations/get-tags	Список тегов для оценки ДЗ
get_info(id_)	GET	/homework/evaluation/operations/get?id=	HomeworkItem
create_homework(id_, file_path, answer_text, spent_hours, spent_minutes)	POST	/homework/operations/create (multipart)	HomeworkUploadResponse: id, filename, file_path, mark, creation_time, stud_answer, auto_mark
rate_homework(id_dom_zad, mark, comment, tags)	POST	/homework/evaluation/operations/save	HomeworkEvaluationResponse: id, id_dom_zad, id_stud, mark, comment, tags

---

Счётчики — client.count

Метод SDK	HTTP	Путь	Возвращает
get_page_counters(filter_type=0)	GET	/count/page-counters?filter_type=	Список {counter_type, counter}
get_library_count()	GET	/count/library	Ответ API (счётчик библиотеки)
get_homework_count()	GET	/count/homework	HomeworkCounters: список {counter_type, counter}

---

Расписание — client.schedule

Метод SDK	HTTP	Путь	Возвращает
get_schedule_month(date)	GET	/schedule/operations/get-month?date_filter=	ScheduleMonth: список {date, lesson, started_at, finished_at, teacher_name, subject_name, room_name}
get_schedule_day(date)	GET	/schedule/operations/get-by-date?date_filter=	ScheduleDay: список тех же полей по дням

---

Библиотека — client.library

Метод SDK	HTTP	Путь	Возвращает
get_opened_interview()	GET	/library/quiz/opened-interview	Данные открытого интервью/квиза
list_(material_type=7, recommended_type=0)	GET	/library/operations/list	Список материалов библиотеки

---

Платежи — client.payment

Метод SDK	HTTP	Путь	Возвращает
check_epay_link()	HEAD	/payment/epay/link	{ok: bool, status?: int}
get_schedule()	GET	/payment/operations/schedule	График платежей
get_index()	GET	/payment/operations/index	Индекс платежей
get_history()	GET	/payment/operations/history	История платежей
check_cancellation()	GET	/payment/operations/check-cancellation	Статус отмены

---

Профиль — client.profile

Метод SDK	HTTP	Путь	Возвращает
get_student_achievements()	GET	/profile/statistic/student-achievements	Список: id, translate_key, is_active, achieve_points (id, points_count)
get_settings()	GET	/profile/operations/settings	Объект: id, ful_name, address, date_birth, email, photo_path, phones, links, has_not_approved_data, ...

---

Прогресс — client.progress

Метод SDK	HTTP	Путь	Возвращает
get_student_visits()	GET	/progress/operations/student-visits	Посещения студента
get_student_exams()	GET	/progress/operations/student-exams	Экзамены студента

---

Портфолио — client.portfolio

Метод SDK	HTTP	Путь	Возвращает
list_()	GET	/portfolio/operations/list	Список портфолио
get_design_teachers()	GET	/portfolio/operations/design-teachers	Преподаватели по дизайну
get_design_specs(id_spec=None)	GET	/portfolio/operations/design-specs?id=	Спецификации дизайна

---

Доп. настройки — client.settings_extra

Метод SDK	HTTP	Путь	Возвращает
get_history_specs()	GET	/settings/history-specs	История спецификаций
get_group_specs()	GET	/settings/group-specs	Спецификации групп

---

Контакты — client.contacts

Метод SDK	HTTP	Путь	Возвращает
check_mailing_confirmation()	GET	/contacts/mailing/check-confirmation	Подтверждение рассылки
get_contacts()	GET	/contacts/operations/index	Контакты

---

Отзывы — client.reviews

Метод SDK	HTTP	Путь	Возвращает
list_()	GET	/reviews/index/list	Список отзывов
get_instruction()	GET	/reviews/index/instruction	Инструкция по отзывам

---

Обратная связь — client.feedback

Метод SDK	HTTP	Путь	Возвращает
get_evaluate_lesson_list()	GET	/feedback/students/evaluate-lesson-list	Список уроков для оценки
get_social_reviews()	GET	/feedback/social-review/get-review-list	Социальные отзывы

---

Новости — client.news

Метод SDK	HTTP	Путь	Возвращает
get_latest()	GET	/news/operations/latest-news	Последние новости

---

Сигналы — client.signal

Метод SDK	HTTP	Путь	Возвращает
list_()	GET	/signal/operations/signals-list	Список сигналов

---

Истории — client.story

Метод SDK	HTTP	Путь	Возвращает
get_stories()	GET	/story/operations/get-stories	Истории

---

Публичные — client.public

Метод SDK	HTTP	Путь	Возвращает
get_languages()	GET	/public/languages	Список языков

---

Файлы — client.files

Метод SDK	HTTP	Путь	Возвращает
get_file_url(file_id)	GET	/files/operations/get?id=	URL/метаданные файла (если эндпоинт доступен на msapi)

Скачивание файлов ДЗ в API может вести на внешние домены (storage.yandexcloud.net, fs.top-academy.ru).

---

Зависимости

• Python 3.10+
• httpx
• pydantic 2.x

Локальный запуск без установки

Проект использует src/ layout. Для запуска скриптов из корня репозитория (например, python tests/main.py) добавлен sitecustomize.py, который подключает src в PYTHONPATH.

Лицензия

MIT. См. LICENSE.