swe-programming-python

name	swe-programming-python
description	Python coding standards from authoritative docs/explanation/software-engineering/programming-languages/python/ documentation

Python Coding Standards

Purpose

Progressive disclosure of Python coding standards for agents writing Python code.

Authoritative Source: docs/explanation/software-engineering/programming-languages/python/README.md

Usage: Auto-loaded for agents when writing Python code. Provides quick reference to idioms, best practices, and antipatterns.

Quick Standards Reference

Naming Conventions

Modules and Packages: lowercase_with_underscores

• user_account.py, payment_processor.py

Classes: PascalCase

• UserAccount, PaymentProcessor

Functions and Variables: lowercase_with_underscores

• Functions: calculate_total(), find_user_by_id()
• Variables: user_name, total_amount

Constants: UPPER_CASE_WITH_UNDERSCORES

• MAX_RETRIES, DEFAULT_TIMEOUT, API_ENDPOINT

Private: Single leading underscore

• _internal_function(), _private_var

Modern Python Features (3.11+)

Type Hints: Use for all function signatures

def calculate_total(items: list[Item]) -> Decimal:
    return sum(item.price for item in items)

Dataclasses: Use for data containers

from dataclasses import dataclass

@dataclass(frozen=True)
class UserAccount:
    id: str
    name: str
    created_at: datetime

Pattern Matching: Use for complex conditionals

match payment:
    case CreditCard(number=n):
        process_credit_card(n)
    case BankTransfer(account=a):
        process_bank_transfer(a)

f-strings: Preferred for string formatting

message = f"User {name} has {count} items"

Error Handling

Specific Exceptions: Catch specific exceptions

try:
    result = process_payment(amount)
except ValueError as e:
    logger.error(f"Invalid amount: {e}")
except NetworkError as e:
    logger.error(f"Network error: {e}")

Custom Exceptions: Define for domain errors

class ValidationError(Exception):
    def __init__(self, field: str, message: str):
        self.field = field
        super().__init__(message)

Context Managers: Use for resource management

with open('file.txt', 'r') as f:
    content = f.read()

Testing Standards

pytest: Primary testing framework

• Use def test_* for test functions
• Use fixtures for setup
• Use parametrize for data-driven tests

import pytest

@pytest.mark.parametrize('input,expected', [
    (5, 10),
    (0, 0),
    (-5, -10),
])
def test_double(input, expected):
    assert double(input) == expected

Type Checking: Use mypy for static analysis

# Run: mypy src/

Security Practices

Input Validation: Validate all external input

• Use Pydantic for data validation
• Check types and bounds

SQL Injection: Use parameterized queries

cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))

Secrets Management: Never hardcode secrets

• Use environment variables
• Use python-dotenv for local development

import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv('API_KEY')

Comprehensive Documentation

For detailed guidance, refer to:

• Idioms - Python-specific patterns
• Best Practices - Clean code standards
• Anti-Patterns - Common mistakes

Related Skills

• docs-applying-content-quality
• repo-practicing-trunk-based-development

References

• Python README
• Functional Programming