pydiscobasepro 2

PyDiscoBasePro v2 - The Ultimate Discord Bot Framework with hot-reloading and MongoDB support

🚀 PyDiscoBasePro - The Ultimate Discord Bot Framework

The most advanced, feature-rich Discord bot framework for Python developers

📦 Install • 📚 Documentation • 🚀 Quick Start • 💬 Discord • 🐛 Issues

---

✨ What Makes PyDiscoBasePro GOAT?

PyDiscoBasePro is not just another Discord bot framework—it's a production-ready, enterprise-grade solution that combines the best of modern Python practices with Discord's latest features. Built with scalability, maintainability, and developer experience in mind.

🔥 Key Highlights

• 🔥 Hot-Reloading: Modify code without restarting your bot
• 🗄️ MongoDB Integration: Robust data persistence with built-in models
• ⚡ Lightning Fast: Optimized for high-performance bots
• 🛡️ Production Ready: Error handling, logging, and crash recovery
• 🎯 Developer Friendly: Clean architecture, extensive docs, and CLI tools
• 📊 Analytics Dashboard: Real-time bot statistics and monitoring
• 🔧 Extensible: Plugin system for unlimited customization

---

📦 Installation

Option 1: Global Installation (Recommended)

pip install pydiscobasepro

Option 2: From Source

git clone https://github.com/code-xon/pydiscobasepro.git
cd pydiscobasepro
pip install -e .

Option 3: Quick Project Setup

# Install globally first
pip install pydiscobasepro

# Create a new bot project
pydisco create MyAwesomeBot
cd MyAwesomeBot
pip install -r requirements.txt

---

🚀 Quick Start (5 Minutes to Bot)

1. Create your bot project:

   pydisco create MyBot
   cd MyBot
   

2. Configure your bot: Edit config/config.json and add your Discord bot token.

3. Run your bot:

   python bot.py
   

4. Add your first command: Create commands/hello.py:

   import discord
   from discord import app_commands
   from discord.ext import commands
   
   class Hello:
       def __init__(self, bot, database):
           self.bot = bot
           self.database = database
           self.name = "hello"
           self.description = "Say hello!"
           self.cooldown = 3
   
           self.slash_command = app_commands.Command(
               name=self.name,
               description=self.description,
               callback=self.run_slash
           )
   
       async def run_slash(self, interaction):
           await interaction.response.send_message("Hello, World! 🌍")
   

5. Restart and test: Your bot will automatically detect and load the new command!

---

🎯 Core Features

⚡ Command System

• Prefix Commands: Traditional !command style
• Slash Commands: Modern Discord slash commands with auto-registration
• Context Menus: Right-click user/message commands
• Aliases: Multiple ways to trigger commands
• Cooldowns: Per-user, per-guild, per-command rate limiting
• Permissions: Role-based and user-specific access control

🔄 Hot-Reloading

• Zero Downtime: Modify code while bot is running
• Instant Updates: Changes applied immediately
• Development Friendly: No more restart cycles

🗄️ Database Integration

• MongoDB: Industry-standard NoSQL database
• Built-in Models: Guild configs, user profiles, command stats
• Async Operations: Non-blocking database queries
• Migration Support: Easy schema updates

📊 Dashboard & Analytics

• Real-time Stats: Guild count, user count, command usage
• Web Interface: Beautiful, responsive dashboard
• API Endpoints: Programmatic access to bot data
• Monitoring: Performance metrics and health checks

🛡️ Reliability & Security

• Error Handling: Comprehensive exception management
• Crash Recovery: Automatic restart on failures
• Logging: Structured logging to files and Discord channels
• Rate Limiting: Built-in protection against abuse

---

📚 Documentation

🏗️ Project Structure

your-bot/
├── commands/          # Bot commands
├── events/           # Discord event handlers
├── components/       # UI components (buttons, selects)
├── utils/            # Helper utilities
├── config/           # Configuration files
├── database/         # Database models and connections
├── dashboard/        # Web dashboard code
├── handlers/         # Core framework handlers
├── bot.py           # Main bot file
└── requirements.txt # Dependencies

🎮 Creating Commands

Basic Slash Command

import discord
from discord import app_commands

class Ping:
    def __init__(self, bot, database):
        self.bot = bot
        self.database = database
        self.name = "ping"
        self.description = "Check bot latency"

        self.slash_command = app_commands.Command(
            name=self.name,
            description=self.description,
            callback=self.run
        )

    async def run(self, interaction: discord.Interaction):
        latency = round(self.bot.latency * 1000)
        await interaction.response.send_message(f"Pong! {latency}ms")

Advanced Command with Permissions

class Ban:
    def __init__(self, bot, database):
        self.bot = bot
        self.database = database
        self.name = "ban"
        self.description = "Ban a user"
        self.permissions = ["ban_members"]
        self.cooldown = 30

        self.slash_command = app_commands.Command(
            name=self.name,
            description=self.description,
            callback=self.run
        )

    async def run(self, interaction: discord.Interaction, user: discord.Member, reason: str = "No reason provided"):
        # Permission checks are handled automatically
        await interaction.guild.ban(user, reason=reason)
        await interaction.response.send_message(f"Banned {user.mention}")

🎪 Creating Events

import discord
from loguru import logger

class Welcome:
    def __init__(self, bot, database):
        self.bot = bot
        self.database = database

        @self.bot.event
        async def on_member_join(member: discord.Member):
            channel = member.guild.system_channel
            if channel:
                embed = discord.Embed(
                    title="Welcome!",
                    description=f"Welcome to {member.guild.name}, {member.mention}!",
                    color=0x00ff00
                )
                await channel.send(embed=embed)

            # Update database
            profile = await self.database.get_user_profile(member.id)
            if not profile:
                profile = UserProfile(member.id)
            await self.database.update_user_profile(profile)

🎨 Creating Components

import discord
from discord.ui import Button, View

class RoleSelector:
    def __init__(self, bot, database):
        self.bot = bot
        self.database = database

        @self.bot.event
        async def on_interaction(interaction: discord.Interaction):
            if interaction.custom_id == "select_role":
                # Handle role selection
                role_id = int(interaction.values[0])
                role = interaction.guild.get_role(role_id)
                await interaction.user.add_roles(role)
                await interaction.response.send_message(f"Added {role.name} role!", ephemeral=True)

# Usage in commands:
view = View()
button = Button(label="Get Role", custom_id="get_role_button")
view.add_item(button)
await ctx.send("Click to get a role!", view=view)

🗄️ Database Operations

from database import GuildConfig, UserProfile

# Guild Configuration
guild_config = await database.get_guild_config(ctx.guild.id)
if not guild_config:
    guild_config = GuildConfig(ctx.guild.id, prefix="!")
await database.update_guild_config(guild_config)

# User Profiles
user_profile = await database.get_user_profile(ctx.author.id)
user_profile.xp += 10
user_profile.level = user_profile.xp // 100
await database.update_user_profile(user_profile)

# Command Statistics
await database.increment_command_usage("ping")
usage = await database.get_command_stats("ping")

⚙️ Configuration

{
  "token": "YOUR_BOT_TOKEN_HERE",
  "prefix": "!",
  "intents": {
    "guilds": true,
    "members": true,
    "messages": true,
    "message_content": true,
    "voice_states": true,
    "reactions": true
  },
  "mongodb": {
    "uri": "mongodb://localhost:27017",
    "database": "pydiscobasepro"
  },
  "logging": {
    "level": "INFO",
    "file": "logs/bot.log",
    "discord_channel_id": null
  },
  "dashboard": {
    "enabled": true,
    "host": "0.0.0.0",
    "port": 8080
  }
}

---

🛠️ Advanced Usage

Custom Permissions

class AdminOnly:
    def __init__(self, bot, database):
        self.bot = bot
        self.database = database
        self.permissions = ["administrator"]  # Discord permission
        # Or use custom logic in run method

Cooldown Management

from utils import cooldown_manager

async def run(self, interaction):
    key = f"{interaction.user.id}_{self.name}"
    if not await cooldown_manager.check_cooldown(key, self.cooldown):
        return await interaction.response.send_message("On cooldown!", ephemeral=True)
    # Command logic here

API Integration

from utils import api_request

async def weather(self, interaction, city: str):
    data = await api_request(f"https://api.weatherapi.com/v1/current.json?key={API_KEY}&q={city}")
    temp = data['current']['temp_c']
    await interaction.response.send_message(f"Temperature in {city}: {temp}°C")

---

🚀 Deployment

Docker Deployment

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
CMD ["python", "bot.py"]

PM2 Process Management

npm install -g pm2
pm2 start bot.py --name "MyBot"
pm2 save
pm2 startup

Systemd Service

[Unit]
Description=PyDiscoBasePro Bot
After=network.target

[Service]
Type=simple
User=botuser
WorkingDirectory=/path/to/bot
ExecStart=/usr/bin/python3 bot.py
Restart=always

[Install]
WantedBy=multi-user.target

---

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch:

   git checkout -b feature/amazing-feature
   

3. Make your changes
4. Test thoroughly
5. Submit a pull request

Development Setup

git clone https://github.com/code-xon/pydiscobasepro.git
cd pydiscobasepro
pip install -e ".[dev]"

Code Standards

• Follow PEP 8
• Add type hints
• Write comprehensive tests
• Update documentation

---

📊 Performance & Benchmarks

• Startup Time: < 2 seconds for 100+ commands
• Memory Usage: ~50MB base + 5MB per 1000 guilds
• Database Queries: < 10ms average response time
• Hot-Reload: < 1 second for code changes
• Concurrent Users: Tested with 10,000+ active users

---

🏆 Why Choose PyDiscoBasePro?

Feature	PyDiscoBasePro	Other Frameworks
Hot-Reloading	✅ Native	❌ Manual
MongoDB Integration	✅ Built-in	⚠️ Add-on
Web Dashboard	✅ Included	❌ Rare
CLI Tools	✅ Full-featured	⚠️ Basic
Production Ready	✅ Enterprise	❌ Hobby
Documentation	✅ Extensive	⚠️ Minimal
Community	🚀 Growing	📉 Stagnant

---

📞 Support & Community

• GitHub Issues: Report bugs
• Documentation: Full docs

---

📜 License

MIT License - Open source and free to use commercially.

Copyright (c) 2024 PyDiscoBasePro

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

🙏 Credits & Acknowledgments

PyDiscoBasePro was created with ❤️ by:

• Original Inspiration: Code-X Organization

Special thanks to the Discord.py community and all our contributors!

---

Made with ❤️ for the Discord developer community

⭐ Star us on GitHub • 🐛 Report Issues • 📖 Read the Docs