python-quality

Python Quality — Patterns & Standards

Coding standards and Pythonic patterns for claude-code-discord-bridge development. Based on PEP 8, modern Python 3.12+ idioms, and project conventions.

When to Activate

• Writing new Python code in this project
• Reviewing code for quality
• Refactoring existing code

Project-Specific Standards

Type Hints (Mandatory)

from __future__ import annotations  # Required in EVERY file

# Good: Full type annotations
async def run_claude_in_thread(
    thread: discord.Thread,
    runner: ClaudeRunner,
    repo: SessionRepository,
    prompt: str,
    session_id: str | None,
) -> str | None:
    ...

# Bad: Missing annotations
async def run_claude_in_thread(thread, runner, repo, prompt, session_id):
    ...

Union Types (3.12+ Syntax)

# Good: Modern syntax
def process(value: str | None) -> dict[str, list[int]]:
    ...

# Bad: Old-style typing
from typing import Optional, Dict, List
def process(value: Optional[str]) -> Dict[str, List[int]]:
    ...

Dataclasses for State

from dataclasses import dataclass, field

@dataclass
class SessionState:
    session_id: str | None = None
    thread_id: int = 0
    accumulated_text: str = ""
    active_tools: dict[str, discord.Message] = field(default_factory=dict)

Error Handling

import contextlib

# Discord API calls that may fail: suppress gracefully
with contextlib.suppress(discord.HTTPException):
    await message.add_reaction(emoji)

# Business logic: handle explicitly
try:
    async for event in runner.run(prompt):
        process(event)
except Exception:
    logger.exception("Failed to run CLI for thread %d", thread.id)
    await thread.send(embed=error_embed("An unexpected error occurred."))

Logging (Not Print)

import logging
logger = logging.getLogger(__name__)

# Good
logger.info("Starting CLI: %s", " ".join(args[:6]))
logger.warning("Session %s timed out after %ds", session_id, timeout)
logger.exception("Unexpected error in thread %d", thread.id)

# Bad — never use print() in library code