Metadata-Version: 2.4
Name: welldungeon
Version: 0.1.0
Summary: Python SDK для API игры «Подземелья Колодца» (sync + async)
Project-URL: Homepage, https://gitlab.com/Racoonchik/wd-api
Project-URL: Documentation, https://welldungeon.online/gtdoc/api
Project-URL: Repository, https://gitlab.com/Racoonchik/wd-api
Author: Racoonchik
License-Expression: MIT
License-File: LICENSE
Keywords: api,game,sdk,vk,welldungeon
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: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# wd-api

Python SDK для API игры [«Подземелья Колодца»](https://welldungeon.online/) с поддержкой **синхронного** и **асинхронного** режимов.

Документация API: https://welldungeon.online/gtdoc/api

## Установка

```bash
pip install welldungeon
```

Из GitLab (если нужна версия из репозитория):

```bash
pip install git+https://gitlab.com/Racoonchik/wd-api.git
```

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

```bash
pip install -e ".[dev]"
```

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

Токен можно получить на странице https://welldungeon.online/?act=tokens

### Синхронный клиент

```python
from welldungeon import Client

with Client(token="wd1_live_...") as client:
    info = client.get_character_info()
    print(f"{info.race}, уровень {info.level}")

    inventory = client.get_inventory()
    print(inventory.items)
```

### Асинхронный клиент

```python
import asyncio

from welldungeon import AsyncClient

async def main():
    async with AsyncClient(token="wd1_live_...") as client:
        token_info = await client.token_info()
        items = await client.lib_items()
        print(token_info.rights, len(items))

asyncio.run(main())
```

### Переменная окружения

```bash
export WELL_DUNGEON_TOKEN=wd1_live_...
```

```python
from welldungeon import Client

client = Client()  # токен из WELL_DUNGEON_TOKEN
```

## Методы

| Метод Python | API | Право токена |
|---|---|---|
| `get_character_info()` | `GetCharacterInfo` | `character_info` |
| `get_inventory()` | `GetInventory` | `inventory_read` |
| `transfer_item_to_player(player_id, item_id, count=1)` | `TransferItemToPlayer` | `transfer_player_to_player` |
| `apply_social_effect_to_player(player_id, effect_type)` | `ApplySocialEffectToPlayer` | `social_effects_player_to_player` |
| `lib_items()` | `LibItems` | — |
| `token_info()` | `TokenInfo` | — |
| `get_log(start=0, limit=100)` | `Log` | — |

## Кэш справочника предметов

```python
from welldungeon import Client, ItemsCache

with Client(token="...") as client:
    cache = ItemsCache.fetch_and_save(client, "items_cache.json")
    print(cache.get_title(13322))  # Золото
```

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

```python
from welldungeon import Client, InvalidTokenError, ConditionsNotMetError

try:
    client.token_info()
except InvalidTokenError as e:
    print(e.code, e.message)
```

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

- Не более **3 запросов в секунду** с одного IP (в клиенте есть встроенный rate limiter).
- Токен можно привязать к белому списку IP-адресов.
- Храните токен в секрете.

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

```bash
ruff check src tests
pytest -m "not integration"
```

Интеграционные тесты (нужен реальный токен):

```bash
WELL_DUNGEON_TOKEN=wd1_live_... pytest -m integration
```

## Лицензия

MIT
