Metadata-Version: 2.4
Name: netschoolpy
Version: 1.0.2
Summary: Асинхронный клиент для «Сетевого города»
Home-page: https://github.com/Vladcom4iiik/netschoolpy
Author: Vladcom4iiik
License: Proprietary
Project-URL: Source, https://github.com/Vladcom4iiik/netschoolpy
Project-URL: Issues, https://github.com/Vladcom4iiik/netschoolpy/issues
Keywords: netschool,netschoolpy,sgo,сетевой город,дневник,госуслуги,esia,education,api,web Education,ir-tech,электронный журнал,school,web2edu,region
Classifier: Natural Language :: Russian
Classifier: Topic :: Education
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.23
Provides-Extra: qr
Requires-Dist: qrcode>=7.0; extra == "qr"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# netschoolpy

Асинхронный клиент для «Сетевого города». Дневник, оценки, домашние задания, объявления — всё программно, без браузера.

Репозиторий: https://github.com/Vladcom4iiik/netschoolpy

Ключевые слова: Сетевой город, SGO, дневник, оценки, домашние задания, Госуслуги, ESIA, QR, API.

## Документация (Docs)

Документация к проекту находится в папке [docs/](docs/). Для локального просмотра:

```bash
pip install mkdocs mkdocs-material
mkdocs serve
```

## Установка

```bash
pip install netschoolpy

# Для отображения QR-кода в терминале (опционально):
pip install netschoolpy[qr]
```

## Способы входа

### По логину/паролю SGO

```python
import asyncio
from netschoolpy import NetSchool

async def main():
    async with NetSchool("https://sgo.example.ru") as ns:
        await ns.login("ИвановИ", "password", "Школа №1")
        diary = await ns.diary()

asyncio.run(main())
```

### Через Госуслуги (логин + пароль ЕСИА)

Программный вход через Госуслуги — без браузера.
Поддерживает SMS и TOTP (приложение-аутентификатор) в качестве второго фактора.

```python
async with NetSchool("https://sgo.example.ru") as ns:
    await ns.login_via_gosuslugi(
        esia_login="+79001234567",     # телефон, email или СНИЛС
        esia_password="your_password",
    )
    diary = await ns.diary()
```

При MFA код из SMS/TOTP будет запрошен через `input()`.
Если `esia_login` / `esia_password` не указаны, они тоже запрашиваются через `input()`.

### Через Госуслуги (QR-код)

Вход без ввода логина и пароля — нужно отсканировать QR-код
в мобильном приложении «Госуслуги».

```python
async def show_qr(qr_data: str):
    """qr_data — deep-link gosuslugi://auth/signed_token=..."""
    import qrcode
    qrcode.make(qr_data).save("qr.png")
    print("Отсканируйте QR в приложении Госуслуги!")

async with NetSchool("https://sgo.example.ru") as ns:
    await ns.login_via_gosuslugi_qr(
        qr_callback=show_qr,   # вызовется после генерации QR
        qr_timeout=120,         # секунд ожидания сканирования
    )
    diary = await ns.diary()
```

- `qr_callback` — async/sync функция, получает deep-link
  `gosuslugi://auth/signed_token=...` для кодирования в QR.
  Если не указан — QR печатается в stdout (`pip install qrcode`).
- `qr_timeout` — таймаут ожидания сканирования (по-умолчанию 120 сек).

### По токену / куки (продвинутое)

```python
# По accessToken из localStorage SGO:
await ns.login_with_token("eyJ...")

# По session-store из localStorage:
await ns.login_with_session_store('{"accessToken":"eyJ..."}')

# По Cookie-строке из DevTools:
await ns.login_with_cookies("NSSESSIONID=abc123")
```

## Удержание сессии (keep-alive)

После любого входа автоматически запускается фоновая задача,
которая каждые **5 минут** пингует сервер, не давая сессии истечь.

```python
# Изменить интервал (в секундах):
ns.set_keepalive_interval(120)   # каждые 2 минуты

# Отключить keep-alive:
ns.set_keepalive_interval(0)
```

При вызове `logout()` keep-alive останавливается автоматически.

## API

```python
async with NetSchool("https://sgo.example.ru") as ns:
    await ns.login(...)

    diary = await ns.diary()                    # дневник (текущая неделя)
    diary = await ns.diary(start, end)          # дневник за период

    overdue = await ns.overdue()                # просроченные задания
    announcements = await ns.announcements()    # объявления
    attachments = await ns.attachments(...)     # вложения к заданию
    info = await ns.school_info()               # информация о школе

    await ns.download_attachment(id, buffer)    # скачать вложение
    await ns.download_profile_picture(id, buf)  # аватар пользователя
```

## Лицензия

© 2026 Vladcom4iiik. Все права защищены.
Только личное, некоммерческое использование. Подробнее — [LICENSE](LICENSE).
