Metadata-Version: 2.4
Name: rcu-api
Version: 0.1.2
Summary: Dependency-free Python client for Powerful Studio Public API
Author: RCU API Community
License-Expression: MIT
Keywords: rcu-api,api,client,roblox
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# rcu-api

`rcu-api` — это простой Python-клиент для Powerful Studio Public API.
Библиотека превращает HTTP-запросы к API в обычные вызовы Python-методов и
автоматически преобразует JSON-ответы в понятные типизированные объекты.

Библиотека подходит для ботов, статистических сервисов, Discord-интеграций,
административных инструментов и любых Python-приложений, которым нужны данные
о кланах, игроках, лидербордах или игровых справочниках.

## Возможности

- получение ID клана по его тегу;
- получение подробной информации о клане;
- просмотр топа кланов;
- получение записей лидербордов;
- чтение игровых директорий, например списка питомцев;
- получение статистики и других данных игрока;
- типизированные модели вместо работы с необработанными словарями;
- понятные исключения для ошибок API, сети и параметров;
- отсутствие обязательных внешних runtime-зависимостей;
- поддержка Python 3.8 и новее.

## Установка

```bash
pip install rcu-api
```

После установки библиотеку можно импортировать так:

```python
from rcu_api import PowerfulStudioClient
```

Название пакета в PyPI — `rcu-api`, а название Python-модуля — `rcu_api`.
Это нормально: дефис используется для установки пакета, подчёркивание — для
импорта в Python.

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

```python
from rcu_api import PowerfulStudioClient

client = PowerfulStudioClient()

# Найти постоянный ID клана по тегу
clan_id = client.get_clan_id("#ABC123")
print("Clan ID:", clan_id)

# Получить информацию о клане
clan = client.get_clan(clan_id)
print("Tag:", clan.tag)
print("Level:", clan.level)
print("Members:", len(clan.members))

# Получить первые 10 кланов из рейтинга
for item in client.get_top_clans(page_size=10):
    print(item.clan_id, item.rank_score)

# Получить лидерборд
for item in client.get_leaderboard("totalAcorns", page_size=10):
    print(item.id, item.value)

# Получить игровой справочник
pets = client.get_directory("pets")
print("Directory entries:", len(pets.entries))
```

## Авторизация для данных игрока

Только endpoint игрока требует access token. Токен можно получить на странице:

<https://rcu.powerfulstudio.xyz/public/access-tokens>

Не записывайте токен прямо в исходный код и не отправляйте его в GitHub.
Используйте переменную окружения:

```bash
export RCU_ACCESS_TOKEN="ваш_токен"
```

Затем выполните запрос:

```python
import os

from rcu_api import PowerfulStudioClient

client = PowerfulStudioClient(
    access_token=os.environ["RCU_ACCESS_TOKEN"]
)

player = client.get_player(
    123456789,
    include=["presence", "stats", "clan", "currencies"],
)

if player.presence:
    print("Online:", player.presence.is_online)

if player.stats:
    print("Total clicks:", player.stats.total_clicks)
    print("Total rebirths:", player.stats.total_rebirths)

if player.clan:
    print("Clan:", player.clan.clan_id)
```

Токен можно передать и только для одного запроса:

```python
player = client.get_player(
    123456789,
    include="stats,clan",
    access_token="временный_токен",
)
```

Доступные значения параметра `include`:

- `presence` — онлайн-статус и место игрока;
- `stats` — игровая статистика;
- `index` — собранные элементы;
- `activity` — данные активности;
- `clan` — клан игрока;
- `equippedPets` — экипированные питомцы;
- `boothHistory` — история покупок;
- `currencies` — валюты игрока.

В Python можно передавать как строку `"stats,clan"`, так и список
`["stats", "clan"]`.

## Все методы клиента

### `get_clan_id(clan_tag)`

Возвращает постоянный ID клана по его тегу:

```python
clan_id = client.get_clan_id("#ABC123")
```

Ограничение API для тега: от 1 до 10 символов.

### `get_clan(clan_id)`

Возвращает объект `ClanInfo` с информацией о клане:

```python
clan = client.get_clan("clan-id")

print(clan.description)
print(clan.created_at)
print(clan.creator_id)

for member in clan.members:
    print(member.user_id, member.rank, member.rebirths)
```

В объекте доступны участники, валюты клана и сезонные значения.

### `get_top_clans(page_size=None)`

Возвращает список объектов `TopClan`:

```python
top = client.get_top_clans(page_size=25)

for clan in top:
    print(clan.clan_id, clan.rank_score)
```

`page_size` может быть от 1 до 100.

### `get_leaderboard(leaderboard_name, page_size=None, use_memory=False)`

Возвращает список объектов `LeaderboardEntry`:

```python
entries = client.get_leaderboard(
    "totalAcorns",
    page_size=50,
)

for entry in entries:
    print(entry.id, entry.value)
```

В API доступны, среди прочих, такие лидерборды:

`totalAcorns`, `clanTotalAcorns`, `seasonRebirths10`,
`clanSeasonRebirths10`, `clanRebirths`, `clanHatching`, `rebirths`,
`totalClicks`, `timePlayed`, `robuxSpent`, `eggsOpened`, `mythicalsHatched`,
`eternalsHatched`, `secretsHatched`, `divinesHatched`,
`mysteriousHatched`, `indexCollected`, `auraRolls`, `bestAuraRoll`,
`treesDestroyed`, `dungeonDamage`, `dungeonBestStage`.

Некоторые значения API может хранить в сжатом виде. Параметр `use_memory=True`
запрашивает более точное временное значение из памяти:

```python
entries = client.get_leaderboard(
    "totalClicks",
    use_memory=True,
)
```

### `get_directory(directory_name)`

Возвращает объект `DirectoryResponse`:

```python
pets = client.get_directory("pets")

for name, data in pets.entries.items():
    print(name, data)
```

Сейчас API документирует директорию `pets`.

### `get_player(user_id, include=None, access_token=None)`

Возвращает объект `PlayerInfo`. Обязательный `user_id` должен быть числом от
1 до 100000000000.

```python
player = client.get_player(
    123456789,
    include=["presence", "stats"],
)
```

## Основные модели

Методы возвращают dataclass-объекты с Python-именами в стиле `snake_case`.
Например, JSON-поле `totalClicks` становится `total_clicks`.

| Модель | Назначение |
| --- | --- |
| `ClanInfo` | информация о клане |
| `ClanMember` | участник клана |
| `TopClan` | элемент топа кланов |
| `LeaderboardEntry` | элемент лидерборда |
| `DirectoryResponse` | содержимое директории |
| `PlayerInfo` | данные игрока |
| `PlayerPresence` | онлайн-статус игрока |
| `PlayerStats` | игровая статистика |
| `ClanMembership` | информация о клане игрока |
| `Activity` | данные активности |
| `BoothHistoryEntry` | запись истории покупок |
| `CurrencyAmount` | сумма валюты участника клана |

Некоторые поля являются `None`, если соответствующий блок не был запрошен
через `include` или API не вернул это значение.

## Настройки клиента

```python
from rcu_api import PowerfulStudioClient

client = PowerfulStudioClient(
    base_url="https://public-api.powerfulstudio.xyz",
    timeout=30,
    access_token="ваш_токен",
)
```

- `base_url` — адрес API или собственного прокси;
- `timeout` — тайм-аут HTTP-запроса в секундах;
- `access_token` — токен по умолчанию для `get_player`.

По умолчанию клиент использует официальный адрес API:
`https://public-api.powerfulstudio.xyz`.

## Обработка ошибок

```python
from rcu_api import (
    AuthenticationError,
    PowerfulStudioHTTPError,
    PowerfulStudioTransportError,
    PowerfulStudioValidationError,
)

try:
    player = client.get_player(123456789)
except AuthenticationError:
    print("Для запроса игрока нужен access token")
except PowerfulStudioValidationError as error:
    print("Неверный параметр:", error)
except PowerfulStudioHTTPError as error:
    print("API вернул HTTP", error.status_code)
    print("Ответ API:", error.response_body)
except PowerfulStudioTransportError as error:
    print("Сетевая ошибка или неожиданный ответ:", error)
```

Иерархия ошибок:

- `PowerfulStudioError` — базовая ошибка библиотеки;
- `PowerfulStudioValidationError` — неверные параметры;
- `AuthenticationError` — отсутствует токен игрока;
- `PowerfulStudioHTTPError` — API вернул ошибочный HTTP-статус;
- `PowerfulStudioTransportError` — сетевой сбой или неправильный JSON.

## Ограничения API

По документации Powerful Studio Public API действуют следующие ограничения:

| Endpoint | Ограничение |
| --- | --- |
| `get_clan_id` | 10 запросов в минуту |
| `get_clan` | 100 запросов в минуту |
| `get_directory` | 2 запроса в минуту |
| `get_player` | 30 запросов в минуту |

Клиент не скрывает ошибки rate limit и не делает бесконечные повторы.
Приложение, использующее библиотеку, должно само контролировать частоту
запросов и при необходимости добавить кэширование.

## Для разработчиков библиотеки

Получить код и запустить тесты:

```bash
git clone <url-репозитория>
cd <каталог-репозитория>
python -m unittest discover -v
```

Собрать пакет локально:

```bash
python -m build
```

## Лицензия

Проект распространяется по лицензии MIT. Полный текст находится в файле
`LICENSE`.
