Metadata-Version: 2.4
Name: Async-SdamGia-Api
Version: 0.0.1
Summary: Python module for interacting with the educational platform Sdam GIA
Author-email: sayrrexe <sayrrexe@gmail.com>
License: MIT
Project-URL: Repository, https://github.com/Sayrrexe/Async-SdamGia-Api
Keywords: sdamgia,ege,education,api,scraping
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beautifulsoup4>=4.14.3
Requires-Dist: grabzit>=3.5.7.1
Requires-Dist: html2image>=2.0.7
Requires-Dist: httpx>=0.28.1
Requires-Dist: pyppeteer>=2.0.0
Requires-Dist: pytesseract>=0.3.13
Provides-Extra: dev
Requires-Dist: pytest>=8.3.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.25.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
Dynamic: license-file

# Async-sdamgia-api

Неофициальный асинхронный Python-клиент для работы с платформой `sdamgia.ru`: получение задач, поиск, работа с категориями и тестами, генерация PDF и OCR-поиск по изображению.

## Что умеет

- получать задачу по `id` (`get_problem_by_id`)
- искать задачи по тексту (`search`)
- получать задачи теста по `testid` (`get_test_by_id`)
- получать задачи категории (`get_category_by_id`)
- загружать каталог тем и категорий (`get_catalog`)
- генерировать тест (`generate_test`)
- получать ссылку на PDF теста (`generate_pdf`)
- искать задачи по изображению через OCR (`search_by_img`)

Поддерживаемые предметы (коды):
`math`, `mathb`, `phys`, `inf`, `rus`, `bio`, `en`, `chem`, `geo`, `soc`, `de`, `fr`, `lit`, `sp`, `hist`.

## Установка

Требования:
- Python `3.12+`

```bash
pip install sdamgia-api
```

Для разработки:

```bash
python -m pip install --upgrade pip
python -m pip install -e .[dev]
```

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

```python
import asyncio
from sdamgia import SdamGIA


async def main() -> None:
    async with SdamGIA() as api:
        problem = await api.get_problem_by_id("math", "1001")
        print(problem["id"], problem["answer"])


asyncio.run(main())
```

## Примеры API

```python
# Поиск задач
ids = await api.search("math", "Найдите количество")

# Каталог предмета
topics = await api.get_catalog("math")

# Генерация теста и PDF
new_test_id = await api.generate_test("math", {"full": 1})
pdf_url = await api.generate_pdf("math", new_test_id, pdf="h")
```

Рендер задачи в изображение (`get_problem_by_id`) поддерживает `img`:
- `pyppeteer`
- `grabzit`
- `html2img`

## OCR-поиск по изображению

Метод `search_by_img` использует `pytesseract`.

1. Установите Python-пакет (если не установлен):

```bash
pip install pytesseract
```

2. Установите `Tesseract-OCR` в ОС и при необходимости укажите путь:

```python
api.tesseract_src = "/usr/bin/tesseract"
# Windows пример: C:/Program Files/Tesseract-OCR/tesseract.exe
```

3. Запустите поиск:

```python
ids = await api.search_by_img("rus", "Image.jpg")
```

## Тесты

В проекте используется live-контур (реальные запросы к `*.sdamgia.ru`):

```bash
pytest -m live -q
```

Важно:
- тесты зависят от сети и доступности внешнего сайта
- структура внешнего HTML может меняться без предупреждения
- OCR ветка в тестах замокана (без обязательной установки Tesseract)

## CI

GitHub Actions запускает live-тесты на `push` и `pull_request` для Python `3.12` и `3.13`.
При падении сохраняются логи (`junit` + `live.log`) как artifacts.

## Для AI-агентов

В репозитории есть файл `AGENTS.md` с обязательными правилами для агентной разработки:

- кодстайл и требования к Python-коду
- правила по docstring (Google-style)
- требования к тестам
- список доступных skills и когда их применять

Если вы используете Codex/агента, начинайте с чтения `AGENTS.md`.

## Лицензия

MIT
