osu-schedule-client

Python SDK для работы с расписанием Оренбургского государственного университета. Клиент обращается к legacy API и возвращает нормализованные Pydantic-модели.

Статус: alpha

Почему проект появился

Оригинальный API расписания возвращает сложные для понимания данные и требует дополнительной обработки кодировки ответа. Этот клиент предоставляет устойчивый слой доступа, нормализацию и типизированные модели, чтобы разработчики могли работать с расписанием как с обычным Python API.

Ключевые возможности

• Асинхронный клиент поверх httpx.
• Нормализация и стабилизация полей расписания.
• Четкая модельная схема на Pydantic v2.
• Удобный импорт моделей и SDK-ориентированный API.

Установка

Через pip:

pip install osu-schedule-client

Через uv:

uv add osu-schedule-client

Примеры работы с API

import asyncio

from osu_schedule_client import OsuScheduleClient


async def main() -> None:
    async with OsuScheduleClient() as client:
        # Получаем факультеты
        faculties = await client.reference.get_faculties()

        print("Факультеты (первые 5):")
        for faculty in faculties[:5]:
            print(f"  [{faculty.id}] {faculty.name}")

        # Берём первый факультет
        faculty = faculties[0]

        print(f"\nВыбран факультет: {faculty.full_name}")

        # Получаем потоки (годы набора)
        potoks = await client.reference.get_potoks(faculty.id)

        print("\nПотоки:")
        for potok in potoks:
            print(f"  [{potok.id}] {potok.name} (год набора: {potok.enrollment_year})")

        # Берём первый поток
        potok = potoks[0]

        # Получаем группы
        groups = await client.reference.get_groups(
            faculty_id=faculty.id,
            potok_id=potok.id,
        )

        print("\nГруппы (первые 5):")
        for group in groups[:5]:
            print(
                f"  [{group.id}] "
                f"{group.name} | "
                f"{group.education_level} | "
                f"{group.education_form}"
            )

        # Берём первую группу
        group = groups[0]

        print(f"\nПолучаем расписание группы: {group.name}")

        lessons = await client.schedule.get_by_group(group.id)

        print(f"\nНайдено занятий: {len(lessons)}\n")

        for lesson in lessons[:5]:
            print(
                f"{lesson.date} "
                f"{lesson.time_range} | "
                f"{lesson.subject} | "
                f"{lesson.teacher_name} | "
                f"ауд. {lesson.auditorium_name}"
            )


if __name__ == "__main__":
    asyncio.run(main())

Архитектура

transport -> api -> mapping -> models

• transport: сетевой слой и декодирование legacy JSON.
• api: низкоуровневые методы доступа к конечным точкам.
• mapping: нормализация и стабилизация нестабильных полей.
• models: Pydantic-модели домена расписания.

Ошибки и устойчивость

Запросы выполняются с ретраями. Ошибки httpx (сетевые и HTTP) пробрасываются наружу, чтобы вы могли использовать свои стратегии обработки.

Особенности

• Нормализация времени и дат в datetime.
• Разделение моделей расписания по источнику (группа, преподаватель, аудитория).
• Явные типы для поля недели, семестра и источника расписания.

Разработка

uv sync
uvx ruff check .

Лицензия

MIT. См. файл LICENSE.