Metadata-Version: 2.4
Name: osu-schedule-client
Version: 0.1.0
Summary: Python client for Orenburg State University schedule API
Project-URL: Homepage, https://github.com/osu-platform/osu-schedule-client
Project-URL: Repository, https://github.com/osu-platform/osu-schedule-client
Project-URL: Issues, https://github.com/osu-platform/osu-schedule-client/issues
Author: Dmitry Kolyadin
License-Expression: MIT
License-File: LICENSE
Keywords: api-client,osu,python,schedule,university
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.13.3
Description-Content-Type: text/markdown

# osu-schedule-client

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

Статус: alpha

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

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

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

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

## Установка

Через pip:

```bash
pip install osu-schedule-client
```

Через uv:

```bash
uv add osu-schedule-client
```

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

```python
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`.
- Разделение моделей расписания по источнику (группа, преподаватель, аудитория).
- Явные типы для поля недели, семестра и источника расписания.

## Разработка

```bash
uv sync
uvx ruff check .
```

## Лицензия

MIT. См. файл LICENSE.
