Metadata-Version: 2.4
Name: chesshome
Version: 0.1.0
Summary: Python client for ChessHome platform API
Author-email: ChessHome <noreply@chesshome.pro>
License-Expression: MIT
Project-URL: Homepage, https://chesshome.pro
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Dynamic: license-file

# ♟️ ChessHome Python Client

Официальный Python-клиент для платформы [Chess Home](https://chesshome.pro).  
Позволяет взаимодействовать с API: управлять турнирами, форумом, клубами, решать задачи, отправлять личные сообщения и многое другое.

---

## 🚀 Установка

```bash
pip install chesshome
```

Или установка из исходников:

```bash
git clone https://github.com/your_username/chesshome-py.git
cd chesshome-py
pip install -e .
```

---

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

```python
from chesshome import ChessHomeClient

# Создаём клиент и авторизуемся
client = ChessHomeClient()
client.login("ваш_логин", "ваш_пароль")

# Получаем свой профиль
me = client.get_me()
print(f"Привет, {me.username}! Рейтинг: {me.rating}")

# Список активных турниров
tours = client.get_tournaments(status="active")
for t in tours:
    print(f"{t.name} — {t.participantsCount} участников")

# Создаём тему на форуме
result = client.create_forum_thread(
    title="Моя первая тема",
    body="Привет! Это тест через Python-клиент."
)
print(f"Тема создана: {result['thread']['slug']}")

# Отправляем личное сообщение
client.send_dm("friend", "Привет! Как дела?")
```

---

## 📚 Документация по методам

### 🔑 Авторизация

| Метод | Описание |
|-------|----------|
| `login(username, password)` | Вход в аккаунт, возвращает клиент с токеном |

### 👤 Пользователи

| Метод | Описание |
|-------|----------|
| `get_me()` | Получить свой профиль (`User`) |
| `get_user(username)` | Получить профиль другого пользователя |
| `search_users(query)` | Поиск пользователей по нику |
| `follow(username)` | Подписаться на пользователя |
| `unfollow(username)` | Отписаться |
| `check_follow(username)` | Проверить, подписан ли ты на пользователя |
| `get_followers(username)` | Список подписчиков пользователя |
| `get_following(username)` | Список подписок пользователя |
| `get_online_friends()` | Друзья онлайн (на кого подписан и онлайн) |

### 🏆 Турниры

| Метод | Описание |
|-------|----------|
| `get_tournaments(status)` | Список турниров (`active`, `upcoming`, `finished`) |
| `get_tournament(id)` | Детали турнира |
| `join_tournament(id)` | Вступить в турнир |
| `leave_tournament(id)` | Покинуть турнир |

### 💬 Форум

| Метод | Описание |
|-------|----------|
| `get_forum_threads(page, limit)` | Список тем |
| `get_forum_thread(slug)` | Получить тему с ответами |
| `create_forum_thread(title, body)` | Создать тему |
| `reply_to_thread(thread_id, body)` | Ответить в тему |

### 📰 Блог

| Метод | Описание |
|-------|----------|
| `get_blog_posts(page, limit)` | Список постов |
| `get_blog_post(post_id)` | Получить пост |
| `like_blog_post(post_id, unlike)` | Поставить/снять лайк |

### 🧩 Задачи (Puzzles)

| Метод | Описание |
|-------|----------|
| `get_puzzles(topic, difficulty, limit, offset)` | Список задач |
| `get_puzzle(puzzle_id)` | Детали задачи |
| `attempt_puzzle(puzzle_id, correct, moves)` | Отправить результат решения |

### ⚡ Storm

| Метод | Описание |
|-------|----------|
| `get_storm_puzzles(topics)` | Получить набор задач для шторма |
| `finish_storm(score, total_attempted, correct, wrong, time_bonus)` | Завершить забег |

### 🏛️ Клубы

| Метод | Описание |
|-------|----------|
| `get_clubs()` | Список всех клубов |
| `get_club(club_id)` | Информация о клубе |
| `create_club(name, description)` | Создать клуб (макс. 5 на пользователя) |
| `join_club(club_id)` | Вступить в клуб |
| `leave_club(club_id)` | Покинуть клуб |
| `update_club(club_id, name, description)` | Обновить клуб (только админ) |
| `get_club_chat(club_id)` | Чат клуба (только для участников) |

### ✉️ Личные сообщения (DM)

| Метод | Описание |
|-------|----------|
| `get_conversations()` | Список диалогов |
| `get_messages(partner, since)` | История сообщений с пользователем |
| `send_dm(to, text)` | Отправить сообщение |
| `mark_dm_read(partner)` | Отметить все сообщения как прочитанные |
| `block_user(username)` | Заблокировать пользователя |
| `unblock_user(username)` | Разблокировать |

### 🌐 Глобальный чат

| Метод | Описание |
|-------|----------|
| `get_global_chat(limit)` | Последние сообщения глобального чата (только чтение) |

### 📊 Статистика

| Метод | Описание |
|-------|----------|
| `get_stats()` | Общая статистика платформы |

---

## 🧪 Примеры использования

### Получение статистики

```python
stats = client.get_stats()
print(f"Всего пользователей: {stats['totals']['users']}")
print(f"Сыграно партий: {stats['totals']['games']}")
```

### Работа с клубами

```python
# Создать клуб
new_club = client.create_club("Мой клуб", "Описание клуба")
print(f"Клуб создан: {new_club.id}")

# Вступить в клуб
client.join_club(new_club.id)

# Получить чат клуба
chat = client.get_club_chat(new_club.id)
for msg in chat.get('messages', []):
    print(f"{msg['username']}: {msg['message']}")
```

### Задачи (Puzzles)

```python
# Получить задачи по теме "Мат в 1 ход"
puzzles = client.get_puzzles(topic="mate1", limit=5)
for p in puzzles:
    print(p['title'], p['difficulty'])

# Отправить результат решения (пример)
# client.attempt_puzzle(puzzles[0]['id'], correct=True, moves=[...])
```

### Подписки

```python
# Подписаться на пользователя
client.follow("username")

# Проверить подписку
is_following = client.check_follow("username")
print(is_following)

# Получить список подписчиков
followers = client.get_followers("username")
for f in followers:
    print(f['username'])
```

---


## 📄 Лицензия

MIT License. См. файл [LICENSE](LICENSE).

---

**Разработано с ❤️ для сообщества Chess Home**
