aibot88 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