python-coding-standards

Python Coding Standards

Quick Navigation: Level 1: Quick Start (5 min) | Level 2: Implementation (30 min) | Level 3: Mastery (Extended)

---

Level 1: Quick Start

Core Principles

1. Pythonic Code: Write idiomatic Python following "The Zen of Python"
2. Type Safety: Use type hints for all public interfaces
3. Test-First: Write tests before implementation (TDD)
4. Documentation: Docstrings for all public functions
5. Modern Python: Use Python 3.10+ features

Essential Checklist

• PEP 8 compliant (Black + isort formatted)
• Type hints on all function signatures
• pytest tests with >80% coverage
• Google-style docstrings
• Specific exception handling (no bare except:)
• No hardcoded secrets
• src layout project structure
• Pinned dependencies in requirements.txt

Quick Example

"""User authentication module."""

from dataclasses import dataclass
from typing import Optional
import bcrypt


@dataclass
class User:
    """User account data."""
    username: str
    email: str
    password_hash: str


def authenticate_user(username: str, password: str) -> Optional[User]:
    """Authenticate user with username and password.

    Args:
        username: User's username
        password: Plain text password to verify

    Returns:
        User object if authentication succeeds, None otherwise

    Raises:
        ValueError: If username or password is empty
    """
    if not username or not password:
        raise ValueError("Username and password required")

    user = _fetch_user_from_db(username)
    if user and _verify_password(password, user.password_hash):
        return user
    return None

---

Level 2: Implementation

Code Style & Formatting

PEP 8 + Black Formatting:

# Good: Black-formatted, clear naming
def calculate_user_discount(
    user: User,
    purchase_amount: Decimal,
    promo_code: Optional[str] = None
) -> Decimal:
    """Calculate discount for user purchase."""
    base_discount = _get_loyalty_discount(user)
    promo_discount = _validate_promo_code(promo_code) if promo_code else Decimal("0")
    return min(base_discount + promo_discount, Decimal("0.5"))