copilot-instructions coding-style-python.instructions.md

Python Coding Style Instructions

Overview

This instruction file enforces Python coding standards based on PEP 8, type hints, and modern Python practices.

Code Formatting

Use Black for automatic formatting and Ruff for linting.

# pyproject.toml
[tool.black]
line-length = 100
target-version = ['py311']

[tool.ruff]
line-length = 100
target-version = "py311"
select = ["E", "F", "I", "N", "W", "UP"]

Type Hints

MANDATORY: All public functions, methods, and classes must have type hints.

✅ Good:

from typing import Optional, List
from uuid import UUID

def get_customer_orders(customer_id: UUID, limit: int = 10) -> List[Order]:
    """Retrieve customer orders with type hints."""
    pass

class OrderService:
    def __init__(self, repository: OrderRepository) -> None:
        self._repository = repository

    def create_order(self, customer_id: UUID) -> Order:
        return Order(id=uuid4(), customer_id=customer_id)

❌ Bad:

def get_customer_orders(customer_id, limit=10):  # No type hints
    pass

Naming Conventions

• Classes: PascalCase (OrderService, CustomerRepository)
• Functions/Methods: snake_case (calculate_total, get_by_id)
• Constants: UPPER_SNAKE_CASE (MAX_RETRIES, DEFAULT_TIMEOUT)
• Private attributes: Leading underscore (_internal_state)
• Module names: snake_case (order_service.py)

# Good naming
class OrderProcessor:
    MAX_BATCH_SIZE = 100

    def __init__(self) -> None:
        self._cache: dict[str, Order] = {}

    def process_orders(self, orders: List[Order]) -> None:
        pass

Docstrings

Use Google-style docstrings for public APIs:

def calculate_discount(
    base_price: float,
    discount_percentage: float,
    customer_tier: str
) -> float:
    """Calculate discounted price based on customer tier.

    Args:
        base_price: The original price before discount
        discount_percentage: Discount percentage (0-100)
        customer_tier: Customer tier ("REGULAR", "PREMIUM", "VIP")

    Returns:
        The final price after applying discount

    Raises:
        ValueError: If discount_percentage is not between 0 and 100

    Example:
        >>> calculate_discount(100.0, 10.0, "PREMIUM")
        90.0
    """
    if not 0 <= discount_percentage <= 100:
        raise ValueError("Discount must be between 0 and 100")

    return base_price * (1 - discount_percentage / 100)