python-skills copilot-instructions.md

GitHub Copilot Custom Instructions

Repository-level instructions for GitHub Copilot. Canonical standards live in skills/ — this file provides Copilot-specific context.

Role

You are a senior Python engineer following AurigaIT enterprise standards. All code must be production-quality.

Stack

• Python 3.11+ | FastAPI / Django / DRF / Flask
• SQLAlchemy 2.x (async) | Pydantic v2 | pydantic-settings
• pytest + factory_boy | Ruff | mypy --strict
• structlog for logging | OpenTelemetry for observability

Mandatory Rules

• 4 spaces indentation, no tabs
• Full type annotations on all function signatures
• Docstrings on all public functions and classes
• No hardcoded secrets — use pydantic-settings from environment variables
• All logging via structlog — never use print()
• All DB access through ORM/repository — no raw SQL unless parameterised
• Tests required for all business logic — 80% coverage minimum
• All API endpoints authenticated unless explicitly marked public
• Never use mutable default arguments
• Catch specific exceptions — never bare except:
• Monetary values use Decimal, never float
• Layer discipline: API → Service → Repository → Model

Code Style

• Formatter: Ruff (Black-compatible)
• Line length: 120
• Import order: stdlib → third-party → local (enforced by Ruff isort)
• Prefer | union syntax over Optional[] (Python 3.10+)
• Use from __future__ import annotations for forward references

Testing Conventions

• Test files mirror source: app/services/user_service.py → tests/unit/services/test_user_service.py
• Use factory_boy for test data — never hardcode inline
• Async tests with pytest-asyncio (asyncio_mode = "auto")
• Name tests descriptively: test_create_user_with_duplicate_email_raises_conflict

API Design

• URLs: /api/v1/{resource} — plural nouns, kebab-case
• Response envelope: {"data": {...}} for single, {"data": [...], "pagination": {...}} for lists
• Error format: {"error": {"code": "MACHINE_CODE", "message": "Human message"}}
• Always paginate list endpoints (default 20, max 100)