Metadata-Version: 2.4
Name: discordplace-sync
Version: 1.0.0
Summary: SDK officiel Python pour synchroniser les statistiques de votre bot Discord avec DiscordPlace
Project-URL: Homepage, https://discordplace.com
Project-URL: Documentation, https://discordplace.com/info
Project-URL: Repository, https://github.com/discordplace/sync
Project-URL: Issues, https://github.com/discordplace/sync/issues
Author-email: DiscordPlace Team <contact@discordplace.com>
License: MIT
License-File: LICENSE
Keywords: api,bot,bot-list,discord,discord.py,discordplace,sdk,statistics,sync
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: httpx>=0.24
Description-Content-Type: text/markdown

# DiscordPlace Sync — Python SDK

> SDK Python officiel pour synchroniser automatiquement les statistiques de votre bot Discord avec [discordplace.com](https://discordplace.com).
>
> Port Python du package npm [`discordplace-sync`](https://www.npmjs.com/package/discordplace-sync). Compatible avec **discord.py**, **disnake**, **py-cord** et **nextcord**.

## Installation

```bash
pip install discordplace-sync
```

Python ≥ 3.8 requis.

## Quickstart (discord.py)

```python
import discord
from discord.ext import commands
from discordplace_sync import DiscordPlaceSDK

intents = discord.Intents.default()
intents.members = True
bot = commands.Bot(command_prefix="!", intents=intents)

sdk = DiscordPlaceSDK(
    api_key="dpsk_xxxxx",          # disponible dans le dashboard de votre bot
    bot_id="123456789012345678",
    auto_sync=True,                # ré-envoie les stats toutes les 5 min
    sync_interval=300,             # secondes
    debug=False,
)

@bot.event
async def on_ready():
    await sdk.start()
    await sdk.auto_collect_stats(bot)   # collecte guildCount/userCount/latency/uptime
    await sdk.sync_bot_info(bot)        # envoie aussi les commandes slash + prefix

bot.run("BOT_TOKEN")
```

## Quickstart (disnake / nextcord / py-cord)

```python
import disnake
from disnake.ext import commands
from discordplace_sync import DiscordPlaceSDK

bot = commands.Bot(command_prefix="!", intents=disnake.Intents.default())
sdk = DiscordPlaceSDK(api_key="dpsk_xxxxx", bot_id="123456789012345678")

@bot.event
async def on_ready():
    await sdk.start()
    await sdk.auto_collect_stats(bot)
    await sdk.sync_bot_info(bot, treat_all_as_hybrid=True)

bot.run("BOT_TOKEN")
```

## API

### `DiscordPlaceSDK(api_key, bot_id, **options)`

| Option          | Type    | Default                          | Description                                  |
|-----------------|---------|----------------------------------|----------------------------------------------|
| `api_key`       | `str`   | **required**                     | Clé API du bot                               |
| `bot_id`        | `str`   | **required**                     | ID Discord du bot                            |
| `endpoint`      | `str`   | `https://discordplace.com/api`   | Base URL de l'API                            |
| `auto_sync`     | `bool`  | `False`                          | Active la boucle automatique                 |
| `sync_interval` | `float` | `300`                            | Secondes entre chaque sync auto              |
| `timeout`       | `float` | `10`                             | Timeout HTTP                                 |
| `retries`       | `int`   | `3`                              | Tentatives sur erreur retryable              |
| `debug`         | `bool`  | `False`                          | Active les logs DEBUG                        |

### Méthodes async

- `await sdk.start()` — démarre le SDK (et la boucle auto si activée).
- `await sdk.stop()` — arrête le SDK et ferme la session HTTP.
- `await sdk.update_stats({"guildCount": 42, ...})` — envoie un payload de stats.
- `await sdk.post_stats(...)` — alias rétro-compatible.
- `await sdk.get_stats(period="24h")` — récupère l'historique.
- `await sdk.get_api_key_info()` — infos sur la clé API.
- `await sdk.check_sync_status()` — état de synchronisation.
- `await sdk.auto_collect_stats(client)` — collecte auto + envoi.
- `await sdk.sync_bot_info(client, treat_all_as_hybrid=False, prefix_only_commands=[], slash_only_commands=[])` — synchronise infos + commandes.

### Événements

```python
sdk.on("success", lambda payload: print("✅ Stats envoyées:", payload))
sdk.on("error", lambda err: print("❌ Erreur:", err))
sdk.on("sync_success", lambda r: print("🔄 Sync info:", r))
```

Évènements disponibles : `start`, `stop`, `success`, `error`, `sync_success`, `force_sync_detected`, `force_sync_completed`. Les callbacks peuvent être sync ou async.

### Context manager

```python
async with DiscordPlaceSDK(api_key="...", bot_id="...") as sdk:
    await sdk.update_stats({"guildCount": 10})
```

## Champs de stats acceptés

`guildCount` (requis), `userCount`, `channelCount`, `commandsUsed`, `uptime` (ms), `memoryUsage` (MB), `latency` (ms), `version`, `isOnline`. Les noms `snake_case` sont aussi acceptés (`guild_count`, `user_count`, …).

## Licence

MIT © DiscordPlace Team
