Deep Dive: How Discord.py 2.4 Handles Rate Limiting vs Nextcord 3

import asyncio
import logging
import time
from collections import defaultdict
from discord.ext import commands
from discord import DiscordException, HTTPException, RateLimitException

# Configure logging for rate limit tracking
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger('DiscordPyRateLimitDemo')

class RateLimitMonitor:
    \"\"\"Tracks per-route rate limit bucket state for Discord.py 2.4\"\"\"
    def __init__(self):
        # Bucket key: (route_method, route_path, guild_id, channel_id, user_id)
        self.buckets = defaultdict(dict)
        self.global_rate_limit = {'reset_at': 0, 'remaining': 1}

    def update_bucket(self, route_key: tuple, headers: dict):
        \"\"\"Update bucket state from Discord API response headers\"\"\"
        if 'X-RateLimit-Remaining' in headers:
            self.buckets[route_key]['remaining'] = int(headers['X-RateLimit-Remaining'])
        if 'X-RateLimit-Reset' in headers:
            self.buckets[route_key]['reset_at'] = float(headers['X-RateLimit-Reset'])
        if 'X-RateLimit-Limit' in headers:
            self.buckets[route_key]['limit'] = int(headers['X-RateLimit-Limit'])

    def check_rate_limit(self, route_key: tuple) -> float:
        \"\"\"Return seconds until rate limit resets, 0 if no limit active\"\"\"
        now = time.time()
        # Check global rate limit first
        if now < self.global_rate_limit['reset_at']:
            return self.global_rate_limit['reset_at'] - now
        # Check per-route bucket
        if route_key in self.buckets:
            bucket = self.buckets[route_key]
            if bucket.get('remaining', 1) <= 0 and now < bucket.get('reset_at', 0):
                return bucket['reset_at'] - now
        return 0.0

# Initialize monitor and bot
rate_monitor = RateLimitMonitor()
intents = commands.Intents.default()
intents.message_content = True
bot = commands.Bot(command_prefix='!', intents=intents)

@bot.event
async def on_ready():
    logger.info(f'Logged in as {bot.user} (ID: {bot.user.id})')
    logger.info(f'Tracking rate limit buckets for {len(rate_monitor.buckets)} routes')

@bot.event
async def on_rate_limit(rate_limit_info):
    \"\"\"Built-in Discord.py 2.4 event fired on 429 responses\"\"\"
    route = rate_limit_info.route
    retry_after = rate_limit_info.retry_after
    route_key = (route.method, route.path, rate_limit_info.guild_id, rate_limit_info.channel_id, rate_limit_info.user_id)
    logger.warning(f'Rate limit hit for {route.method} {route.path}: retry after {retry_after}s')
    # Update monitor state
    rate_monitor.buckets[route_key]['reset_at'] = time.time() + retry_after
    rate_monitor.buckets[route_key]['remaining'] = 0

async def safe_api_call(route_key: tuple, api_call):
    \"\"\"Wrap Discord API calls with rate limit pre-check\"\"\"
    retry_delay = rate_monitor.check_rate_limit(route_key)
    if retry_delay > 0:
        logger.info(f'Pre-empting rate limit: waiting {retry_delay:.2f}s')
        await asyncio.sleep(retry_delay)
    try:
        return await api_call()
    except RateLimitException as e:
        # Update global rate limit if applicable
        if e.global_rl:
            rate_monitor.global_rate_limit['reset_at'] = time.time() + e.retry_after
            rate_monitor.global_rate_limit['remaining'] = 0
            logger.error(f'Global rate limit hit: retry after {e.retry_after}s')
        else:
            route_key = (e.route.method, e.route.path, None, None, None)
            rate_monitor.buckets[route_key]['reset_at'] = time.time() + e.retry_after
            rate_monitor.buckets[route_key]['remaining'] = 0
        await asyncio.sleep(e.retry_after)
        return await safe_api_call(route_key, api_call)
    except HTTPException as e:
        logger.error(f'HTTP error {e.status} for {route_key}: {e.text}')
        raise

@bot.command()
async def send_bulk(ctx, channel_id: int, count: int):
    \"\"\"Bulk send messages to a channel with rate limit handling\"\"\"
    target_channel = bot.get_channel(channel_id)
    if not target_channel:
        await ctx.send('Channel not found')
        return
    success = 0
    failed = 0
    for i in range(count):
        route_key = ('POST', f'/channels/{channel_id}/messages', ctx.guild.id, channel_id, ctx.author.id)
        try:
            async def api_call():
                return await target_channel.send(f'Bulk message {i+1}/{count}')
            msg = await safe_api_call(route_key, api_call)
            success += 1
            logger.debug(f'Sent message {msg.id} to {channel_id}')
        except Exception as e:
            failed += 1
            logger.error(f'Failed to send message {i+1}: {str(e)}')
    await ctx.send(f'Sent {success} messages, failed {failed}')

if __name__ == '__main__':
    # Replace with your bot token
    bot.run('DISCORD_BOT_TOKEN_HERE')

import asyncio
import logging
import time
from nextcord.ext import commands
from nextcord import RateLimitHit, HTTPException, Interaction
from nextcord.enums import RateLimitType

# Configure logging for Nextcord rate limit tracking
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger('NextcordRateLimitDemo')

class RateLimitDebugMiddleware:
    \"\"\"Nextcord 3 built-in rate limit middleware for debugging\"\"\"
    def __init__(self):
        self.rate_limit_counts = {
            RateLimitType.GLOBAL: 0,
            RateLimitType.PER_ROUTE: 0,
            RateLimitType.PER_USER: 0
        }
        self.slowest_route = {'route': None, 'retry_after': 0.0}

    async def on_rate_limit(self, event: RateLimitHit):
        \"\"\"Middleware handler fired on every 429 response\"\"\"
        self.rate_limit_counts[event.type] += 1
        retry_after = event.retry_after
        route = event.route
        # Track slowest route
        if retry_after > self.slowest_route['retry_after']:
            self.slowest_route = {
                'route': f'{route.method} {route.path}',
                'retry_after': retry_after
            }
        # Log full context for debugging
        log_msg = (
            f'Rate limit hit: Type={event.type.name}, '
            f'Route={route.method} {route.path}, '
            f'Retry After={retry_after}s, '
            f'Guild={event.guild_id}, Channel={event.channel_id}, User={event.user_id}'
        )
        if event.global_rl:
            log_msg += ' [GLOBAL RATE LIMIT]'
        logger.warning(log_msg)
        # Automatically apply retry delay (Nextcord does this by default, but we log it)
        await asyncio.sleep(retry_after)

# Initialize middleware and bot
rate_middleware = RateLimitDebugMiddleware()
intents = commands.Intents.default()
intents.message_content = True
bot = commands.Bot(command_prefix='!', intents=intents)

# Register rate limit middleware
bot.add_rate_limit_middleware(rate_middleware)

@bot.event
async def on_ready():
    logger.info(f'Logged in as {bot.user} (ID: {bot.user.id})')
    logger.info(f'Rate limit middleware active. Tracking {len(rate_middleware.rate_limit_counts)} limit types.')

@bot.slash_command(name='bulk_send', description='Bulk send messages with Nextcord 3 rate limiting')
async def bulk_send(
    interaction: Interaction,
    channel: nextcord.SlashCommandOption(channel_types=[nextcord.ChannelType.text]),
    count: nextcord.SlashCommandOption(int, min_value=1, max_value=1000)
):
    \"\"\"Bulk send messages using Nextcord 3's built-in rate limit handling\"\"\"
    await interaction.response.defer(ephemeral=False)
    target_channel = channel
    success = 0
    failed = 0
    start_time = time.time()
    for i in range(count):
        try:
            # Nextcord automatically handles rate limits, but we can pre-check
            msg = await target_channel.send(f'Bulk message {i+1}/{count}')
            success += 1
            logger.debug(f'Sent message {msg.id} to {target_channel.id}')
        except RateLimitHit as e:
            # This is caught by the middleware, but handle edge cases
            failed += 1
            logger.error(f'Rate limit hit during send {i+1}: {e.retry_after}s retry')
        except HTTPException as e:
            failed += 1
            logger.error(f'HTTP error {e.status} for message {i+1}: {e.text}')
        except Exception as e:
            failed += 1
            logger.error(f'Unexpected error for message {i+1}: {str(e)}')
    end_time = time.time()
    elapsed = end_time - start_time
    await interaction.followup.send(
        f'Sent {success} messages, failed {failed}. '
        f'Elapsed: {elapsed:.2f}s. '
        f'Rate limits hit: Global={rate_middleware.rate_limit_counts[RateLimitType.GLOBAL]}, '
        f'Per-Route={rate_middleware.rate_limit_counts[RateLimitType.PER_ROUTE]}'
    )

@bot.command()
async def rate_stats(ctx):
    \"\"\"Show rate limit statistics from middleware\"\"\"
    stats = rate_middleware.rate_limit_counts
    slowest = rate_middleware.slowest_route
    await ctx.send(
        f'**Rate Limit Stats**\n'
        f'Global: {stats[RateLimitType.GLOBAL]}\n'
        f'Per-Route: {stats[RateLimitType.PER_ROUTE]}\n'
        f'Per-User: {stats[RateLimitType.PER_USER]}\n'
        f'Slowest Route: {slowest[\"route\"]} ({slowest[\"retry_after\"]:.2f}s retry)'
    )

if __name__ == '__main__':
    # Replace with your bot token
    bot.run('DISCORD_BOT_TOKEN_HERE')

import asyncio
import time
import statistics
from dataclasses import dataclass
from typing import List, Dict

# Benchmark configuration
BENCHMARK_CONFIG = {
    'discord_py_version': '2.4.0',
    'nextcord_version': '3.0.1',
    'hardware': 'AMD EPYC 7763 16-core, 64GB RAM, 10Gbps Ethernet',
    'discord_api_version': 'v10',
    'test_duration_seconds': 300,
    'concurrent_workers': 100,
    'target_route': 'POST /channels/{channel_id}/messages',
    'rate_limit_threshold': 50  # Stop if 50+ 429s hit
}

@dataclass
class BenchmarkResult:
    wrapper: str
    version: str
    total_requests: int
    successful_requests: int
    failed_429: int
    avg_latency_ms: float
    p99_latency_ms: float
    throughput_req_s: float
    memory_usage_mb: float

async def run_discord_py_benchmark(channel_id: int, bot_token: str) -> BenchmarkResult:
    \"\"\"Run throughput benchmark for Discord.py 2.4\"\"\"
    import discord
    from discord.ext import commands
    from discord import RateLimitException, HTTPException

    intents = commands.Intents.default()
    intents.message_content = True
    bot = commands.Bot(command_prefix='!bench_', intents=intents)
    results = {
        'total': 0,
        'success': 0,
        '429': 0,
        'latencies': []
    }
    start_time = time.time()
    end_time = start_time + BENCHMARK_CONFIG['test_duration_seconds']
    sem = asyncio.Semaphore(BENCHMARK_CONFIG['concurrent_workers'])

    @bot.event
    async def on_ready():
        logger.info(f'Discord.py benchmark bot logged in as {bot.user}')

    async def send_message_worker():
        while time.time() < end_time:
            async with sem:
                worker_start = time.time()
                try:
                    channel = bot.get_channel(channel_id)
                    if not channel:
                        await asyncio.sleep(0.1)
                        continue
                    await channel.send('Benchmark message')
                    results['success'] += 1
                    results['latencies'].append((time.time() - worker_start) * 1000)
                except RateLimitException:
                    results['429'] += 1
                except HTTPException as e:
                    if e.status == 429:
                        results['429'] += 1
                    else:
                        pass
                except Exception:
                    pass
                finally:
                    results['total'] += 1

    # Start workers
    workers = [asyncio.create_task(send_message_worker()) for _ in range(BENCHMARK_CONFIG['concurrent_workers'])]
    await bot.wait_until_ready()
    await asyncio.gather(*workers)
    await bot.close()

    # Calculate metrics
    elapsed = time.time() - start_time
    return BenchmarkResult(
        wrapper='Discord.py',
        version=BENCHMARK_CONFIG['discord_py_version'],
        total_requests=results['total'],
        successful_requests=results['success'],
        failed_429=results['429'],
        avg_latency_ms=statistics.mean(results['latencies']) if results['latencies'] else 0,
        p99_latency_ms=statistics.quantiles(results['latencies'], n=100)[98] if len(results['latencies']) > 100 else 0,
        throughput_req_s=results['success'] / elapsed,
        memory_usage_mb=0  # Would use tracemalloc in real benchmark
    )

async def run_nextcord_benchmark(channel_id: int, bot_token: str) -> BenchmarkResult:
    \"\"\"Run throughput benchmark for Nextcord 3\"\"\"
    import nextcord
    from nextcord.ext import commands
    from nextcord import RateLimitHit, HTTPException

    intents = commands.Intents.default()
    intents.message_content = True
    bot = commands.Bot(command_prefix='!bench_', intents=intents)
    results = {
        'total': 0,
        'success': 0,
        '429': 0,
        'latencies': []
    }
    start_time = time.time()
    end_time = start_time + BENCHMARK_CONFIG['test_duration_seconds']
    sem = asyncio.Semaphore(BENCHMARK_CONFIG['concurrent_workers'])

    @bot.event
    async def on_ready():
        logger.info(f'Nextcord benchmark bot logged in as {bot.user}')

    async def send_message_worker():
        while time.time() < end_time:
            async with sem:
                worker_start = time.time()
                try:
                    channel = bot.get_channel(channel_id)
                    if not channel:
                        await asyncio.sleep(0.1)
                        continue
                    await channel.send('Benchmark message')
                    results['success'] += 1
                    results['latencies'].append((time.time() - worker_start) * 1000)
                except RateLimitHit:
                    results['429'] += 1
                except HTTPException as e:
                    if e.status == 429:
                        results['429'] += 1
                    else:
                        pass
                except Exception:
                    pass
                finally:
                    results['total'] += 1

    # Start workers
    workers = [asyncio.create_task(send_message_worker()) for _ in range(BENCHMARK_CONFIG['concurrent_workers'])]
    await bot.wait_until_ready()
    await asyncio.gather(*workers)
    await bot.close()

    # Calculate metrics
    elapsed = time.time() - start_time
    return BenchmarkResult(
        wrapper='Nextcord',
        version=BENCHMARK_CONFIG['nextcord_version'],
        total_requests=results['total'],
        successful_requests=results['success'],
        failed_429=results['429'],
        avg_latency_ms=statistics.mean(results['latencies']) if results['latencies'] else 0,
        p99_latency_ms=statistics.quantiles(results['latencies'], n=100)[98] if len(results['latencies']) > 100 else 0,
        throughput_req_s=results['success'] / elapsed,
        memory_usage_mb=0  # Would use tracemalloc in real benchmark
    )

def print_benchmark_results(discord_py: BenchmarkResult, nextcord: BenchmarkResult):
    \"\"\"Print benchmark comparison table\"\"\"
    print('\n=== Benchmark Results ===')
    print(f'Hardware: {BENCHMARK_CONFIG[\"hardware\"]}')
    print(f'Test Duration: {BENCHMARK_CONFIG[\"test_duration_seconds\"]}s')
    print(f'Concurrent Workers: {BENCHMARK_CONFIG[\"concurrent_workers\"]}')
    print('\n| Metric | Discord.py 2.4 | Nextcord 3 | Difference |')
    print('| --- | --- | --- | --- |')
    print(f'| Total Requests | {discord_py.total_requests} | {nextcord.total_requests} | {discord_py.total_requests - nextcord.total_requests} |')
    print(f'| Successful Requests | {discord_py.successful_requests} | {nextcord.successful_requests} | {discord_py.successful_requests - nextcord.successful_requests} |')
    print(f'| 429 Failures | {discord_py.failed_429} | {nextcord.failed_429} | {discord_py.failed_429 - nextcord.failed_429} |')
    print(f'| Avg Latency (ms) | {discord_py.avg_latency_ms:.2f} | {nextcord.avg_latency_ms:.2f} | {discord_py.avg_latency_ms - nextcord.avg_latency_ms:.2f} |')
    print(f'| Throughput (req/s) | {discord_py.throughput_req_s:.2f} | {nextcord.throughput_req_s:.2f} | {discord_py.throughput_req_s - nextcord.throughput_req_s:.2f} |')

if __name__ == '__main__':
    # Note: This requires valid bot tokens and a test channel ID
    # asyncio.run(run_discord_py_benchmark(123456789, 'TOKEN'))
    # asyncio.run(run_nextcord_benchmark(123456789, 'TOKEN'))
    print('Benchmark script ready. Configure tokens and channel ID to run.')

# Discord.py 2.4 pre-emptive check snippet
async def pre_empt_rate_limit(route_key: tuple):
    now = time.time()
    bucket = rate_monitor.buckets.get(route_key, {})
    if bucket.get('remaining', 1) <= 0 and now < bucket.get('reset_at', 0):
        sleep_time = bucket['reset_at'] - now
        logger.info(f'Pre-empting rate limit: sleeping {sleep_time:.2f}s')
        await asyncio.sleep(sleep_time)

# Nextcord 3 middleware alert snippet
async def on_rate_limit(self, event: RateLimitHit):
    if event.global_rl:
        await send_slack_alert(f'Global rate limit hit! Retry after {event.retry_after}s')
    # Log to Datadog/New Relic
    statsd.increment(f'discord.rate_limit.{event.type.name}')

# Discord.py 2.4 increase bucket limit snippet
from discord.http import RateLimitManager
# Monkey-patch default bucket limit (not recommended for production, use fork or PR)
RateLimitManager.MAX_BUCKETS = 200_000