# 🎓 pybsuir - Получение статистики и рейтингов студентов БГУИР

![Python](https://img.shields.io/badge/python-3.8%2B-blue?logo=python&logoColor=white)
![Async](https://img.shields.io/badge/asyncio-powered-blueviolet)

**pubsuir** — Python-библиотека для работы с официальным и неофициальным API БГУИР.  
На данный момент функционал библиотеки включает только работу с данными, которые можно также посмотреть на [этой](https://iis.bsuir.by/rating-of-students) странице.

---

## 🛠️ Установка

Через pip:

```bash
pip install pybsuir
````

**Зависимости**: по умолчанию используется `aiohttp`, которое устанавливается автоматически.

---

### Установка без зависимостей

Для большей гибкости можно установить пакет без зависимостей:

```bash
pip install pybsuir --no-deps
```

В этом случае библиотека будет использовать встроенную реализацию на основе `urllib`, что позволяет работать без внешних зависимостей. 

**Дополнительно**: Если вы хотите использовать `httpx` вместо `aiohttp`, установите его отдельно (`httpx` будет использован, если не найден `aiohttp`):

```bash
pip install httpx
```

> ⚠️ **Примечание**: Использование `httpx` или встроенной реализации скорее всего будет медленнее, чем `aiohttp`. Для оптимальной производительности рекомендуется использовать `aiohttp`.

---
---

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

```python

import asyncio
from pybsuir import BsuirStatsClient

async def main():
    client = BsuirStatsClient()
    students = await client.get_students(20657, 2)
    print(students[0])

asyncio.run(main())
```

**Вывод**:
```
{
    "studentCardNumber": "15350060",
    "average": 3.89,
    "hours": 80,
    "averageShift": 0.33000000000000007,
    "first": null,
    "second": null,
    "third": null
}
```

---

или более сложный вариант для получения статистики потока по конкретному предмету:

```python
import asyncio
from pybsuir import BsuirStatsClient

async def main():
    client = BsuirStatsClient()
    top_students = await client.get_top_students(
        speciality=20657,
        course=2,
        lesson_name_abbrev="КПрог",
        lesson_type_abbrev="ЛР"
    )

    place = 1
    for st in top_students:
        print(f"{place}. {st.student_card_number}: {' '.join([str(mark) for mark in st.marks])}")
        place += 1

asyncio.run(main())
```

**Вывод**:

```
1. 123456: 10 9 10
2. 654321: 9 10 9
...
```

---


### 📋 Основные возможности

* Список факультетов, специальностей и курсов.
* Получение рейтинга студентов по курсу и специальности.
* Получение подробной информации об успеваемости студенте.
* Все ответы приходят в виде [датаклассов](docs/Types.md).

---

## 🚨 Исключения

* `BsuirStatsException` — выбрасывается при любых ошибках HTTP-запроса.
  Содержит: `status`, `url`, `text`, `headers`.

---

## 📚 [Описание методов и пример](docs/Methods.md)

---

> 🛠️ В будущем планируется расширения возможностей библиотеки путем добавления работы с другими эндпоинтами api БГУИР.