Skip to content

README.md

Latest commit

 

History

History
184 lines (134 loc) · 4.52 KB

README.md

File metadata and controls

184 lines (134 loc) · 4.52 KB

PyBot

Python License Discord PRs Welcome Code Owners

Bot Discord modulaire, écrit en Python, basé exclusivement sur les slash commands.
Le bot est mono-serveur et extensible via son système de features validées par le staff.

L'objectif du projet est de permettre à la communauté de proposer des fonctionnalités et de les coder via des Pull Request, sans compromettre la stabilité du bot.

Fonctionnement général

  • Le core du bot est maintenu par le staff (Aucune modification de ce core ne sera acceptée hors membre du staff)
  • Les fonctionnalités sont isolées dans un système de features
  • Une feature n'est chargée que si elle est explicitement activée dans la configuration
  • L'instance du bot ne tourne que sur le serveur PyPro

Créer votre propre feature

Prérequis

  • Python : 3.13+
  • Un bot Discord créé via le Discord Developer Portal
  • Le scope OAuth2 application.commands activé

Installation (local)

python -m venv .venv
source .venv/bin/activate  # Windows : .venv\Scripts\activate
pip install -r requirements.txt

Créer un fichier .env (exemple dans config/.env.example)

DISCORD_TOKEN=your_discord_token_here
GUILD_ID=your_guild_id_here
CONFIG_PATH=./config/config.toml
LOG_LEVEL=info
STAFF_ROLES_IDS=

Lancer le bot :

python -m bot.core.app

Structure du projet

bot/
  core/
    app.py        # point d’entrée
    config.py     # chargement et validation de la config
    loader.py     # chargement des features
features/
  ping/
    feature.py
  say/
    feature.py
config/
  config.toml
  .env

Système de features

Chaque feature est autonome et vit dans son propre dossier.

features/<slug>/
  __init__.py
  feature.py

Contrat obligatoire

Chaque feature.py doit exposer ces informations :

  1. FEATURE (constante dictionnaire)
FEATURE = {
  "slug": "ping",
  "name": "Ping",
  "description": "Simple ping command",
  "requires_config": False,
  "permissions": [],
}

Contraintes :

  • slug doit correspondre exactement au nom du dossier
  • Le slug est unique dans le projet
  1. register(tree, config)
def register(tree, config)

Rôles :

  • Enregistrer les slash commands de la feature

Règles strictes :

  • Pas d’I/O (pas de fichiers, pas de réseau) dans register, à faire dans la fonction de la commande
  • Pas d’accès à l’environnement
  • Pas de boucles ou tâches longues
  • Pas d’effets de bord à l’import

Le paramètre config correspond au bloc [features.<slug>] du fichier TOML.

Organisation interne des features

Chaque feature est libre d'organiser son dossier interne comme elle le souhaite.
En dehors des fichiers obligatoires (feature.py, __init__.py), une feature peut contenir :

  • Des modules Python internes
  • Des sous-dossiers
  • Des fichiers de données (JSON, SQL, etc.)
features/example/
  feature.py
  __init__.py
  service.py
  repository.py
  data/
    defaults.json

Contraintes :

  • Le point d'entrée reste toujours feature.py
  • Aucun fichier externe à feature.py ne doit être importé par le core
  • L'I/O reste interdit au chargement (import/register), mais autorisé à l'exécution des commandes

Configuration

  • Les secrets vont dans .env (jamais commités)
  • Le comportement va dans config.toml

Activation des features :

enabled_features = ["ping", "say"]

Configuration par feature :

[features.say]
ephemeral_default = false

Si requires_config = true et que la section est absente, la feature est refusée au chargement.

Sécurité et stabilité

  • Les conflits de noms de slash commands sont détectés automatiquement
  • Une feature en erreur ne bloquera pas le bot
  • Le core est protégé via CODEOWNERS et règles de branche

Contribuer

Les contributions se font exclusivement via Pull Request.

Règle de base :

  • Une PR = une feature
  • Ne pas modifier le core
  • Ne pas modifier enabled_features (lors de la PR, amusez-vous en local)
  • Ne pas ajouter de dépendance sans validation
  • Inclure un test manuel simple

Voir CONTRIBUTING.md pour plus de détails.

Licence

Ce projet est distribué sous licence MIT.