welldungeon 0.1.1

Python SDK для API игры «Подземелья Колодца» (sync + async)

welldungeon

Python SDK для API игры «Подземелья Колодца» с поддержкой синхронного и асинхронного режимов.

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

Установка

pip install welldungeon

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

pip install -e ".[dev]"

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

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

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

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)

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

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())

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

export WELL_DUNGEON_TOKEN=wd1_live_...

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	—

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

from welldungeon import Client, ItemsCache

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

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

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-адресов.
• Храните токен в секрете.

Разработка

ruff check src tests
pytest -m "not integration"

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

WELL_DUNGEON_TOKEN=wd1_live_... pytest -m integration

Релиз на PyPI

1. Поднимите версию в pyproject.toml (например 0.1.1).
2. Закоммитьте и создайте тег:

   git tag v0.1.1
   git push origin main --tags
   

3. GitLab CI соберёт пакет и опубликует его на PyPI.

Для автопубликации в GitLab нужна CI-переменная PYPI_TOKEN (masked, protected): Settings → CI/CD → Variables — значение API-токена PyPI.

Тег должен совпадать с форматом vX.Y.Z (например v0.1.1).

Лицензия

MIT