apex-accelerator python.instructions.md

Python Guidelines

Instructions for writing clean, consistent Python in this repository. Target Python 3.14 (latest stable) with Ruff for linting and formatting.

Project Context

Python is used for two purposes in this repo:

1. Architecture diagrams — diagrams library scripts in agent-output/ and .github/skills/
2. Utility scripts — validation tooling and diagram verification

Style & Formatting

• Formatter: Ruff (ruff format) — double quotes, space indentation
• Linter: Ruff with rules: E, W, F, I, B, C4, UP, SIM
• Line length: 120 characters (matches project-wide setting)
• Imports: sorted by isort rules via Ruff — stdlib, third-party, first-party
• Quotes: double quotes for strings
• Type hints: use for function signatures; pyproject.toml sets basic type checking

Package Management

• Use uv (Astral) as the package manager — installed in devcontainer
• Root dependencies in requirements.txt: diagrams, matplotlib, pillow, pytest, ruff

Diagram Scripts

Follow the existing pattern for architecture diagram generation:

"""Brief description of what the diagram shows."""

from diagrams import Cluster, Diagram
from diagrams.azure.compute import AppServices
from diagrams.azure.network import FrontDoors

with Diagram("Diagram Title", show=False, filename="output-name", direction="TB"):
    with Cluster("Resource Group"):
        # Resources...
        pass

• Always set show=False to prevent auto-opening
• Use direction="TB" (top-to-bottom) for consistency
• Group resources in Cluster blocks matching Azure resource groups
• Set explicit filename parameter to control output location

Conventions

• Use snake_case for functions, variables, and modules
• Use PascalCase for classes
• Use UPPER_SNAKE_CASE for constants
• Prefer f-strings over .format() or % formatting
• Use pathlib Path for new code — existing scripts may use os.path
• Use context managers (with) for file and network operations