name	python-coding-standards
description	Python coding standards following PEP 8, type hints, testing best practices, and modern Python patterns. Use for Python projects requiring clean, maintainable, production-ready code with comprehensive testing.

Python Coding Standards

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

Level 1: Quick Start (<2,000 tokens, 5 minutes)

Core Principles

Pythonic Code: Write idiomatic Python following "The Zen of Python" (import this)
Type Safety: Use type hints for all public interfaces and complex functions
Test-First: Write tests before implementation (TDD)
Documentation: Docstrings for all modules, classes, and public functions
Modern Python: Use Python 3.10+ features (match statements, type unions, dataclasses)

Essential Checklist

PEP 8 Compliance: Code formatted with Black, imports organized with isort
Type Hints: All function signatures and class attributes typed
Tests: pytest tests with >80% coverage, fixtures for setup/teardown
Docstrings: Google-style docstrings for public interfaces
Error Handling: Specific exceptions, proper logging, no bare except:
Security: Input validation, no hardcoded secrets, parameterized queries
Project Structure: src layout, clear separation of concerns
Dependencies: requirements.txt with pinned versions, virtual environment

Quick Example

"""User authentication module with secure password handling."""

from dataclasses import dataclass
from typing import Optional
import bcrypt


@dataclass
class User:
    """User account data.

    Attributes:
        username: Unique username (3-32 chars)
        email: Valid email address
        password_hash: bcrypt-hashed password
    """
    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

    Example:
        >>> user = authenticate_user("alice", "secret123")
        >>> assert user is not None
        >>> assert user.username == "alice"
    """
    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


def _verify_password(password: str, password_hash: str) -> bool:
    """Verify password against bcrypt hash."""
    return bcrypt.checkpw(
        password.encode('utf-8'),
        password_hash.encode('utf-8')
    )

Level 2: Implementation (<5,000 tokens, 30 minutes)

Code Style & Formatting

PEP 8 Compliance + Automation

# ✅ 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"))


# ❌ Bad: Inconsistent spacing, poor naming
def calc_disc(u,amt,pc=None):
    bd=get_ld(u)
    pd=val_pc(pc) if pc else 0
    return min(bd+pd,0.5)

Tool Configuration (see resources/configs/pyproject.toml):

[tool.black]
line-length = 88
target-version = ["py310"]

[tool.isort]
profile = "black"
line_length = 88

[tool.pylint]
max-line-length = 88
disable = ["C0111"]  # Missing docstring

Common Patterns:

# List comprehensions (readable)
active_users = [u for u in users if u.is_active]

# Dict comprehensions
user_map = {u.id: u for u in users}

# Generator expressions (memory-efficient)
total = sum(order.amount for order in orders)

# Context managers
with open("data.json") as f:
    data = json.load(f)

# Walrus operator (Python 3.8+)
if (user := get_user(user_id)) is not None:
    process_user(user)

Anti-Patterns:

# ❌ Mutable default arguments
def add_item(item, items=[]):  # Bug: shared list
    items.append(item)
    return items

# ✅ Use None and create new list
def add_item(item, items=None):
    if items is None:
        items = []
    items.append(item)
    return items


# ❌ Bare except
try:
    risky_operation()
except:  # Catches KeyboardInterrupt, SystemExit!
    pass

# ✅ Specific exceptions
try:
    risky_operation()
except (ValueError, KeyError) as e:
    logger.error(f"Operation failed: {e}")

See Also: Advanced Patterns for decorators, metaclasses, async patterns

Type Hints & Static Analysis

Type Hint Patterns:

from typing import Protocol, TypeVar, Generic, Literal
from collections.abc import Sequence, Mapping

# Basic types
def process_items(items: list[str], count: int = 10) -> dict[str, int]:
    """Process items and return counts."""
    return {item: len(item) for item in items[:count]}


# Protocols (structural typing)
class Drawable(Protocol):
    """Protocol for drawable objects."""
    def draw(self) -> None: ...


def render(obj: Drawable) -> None:
    """Render any drawable object."""
    obj.draw()


# Generics
T = TypeVar('T')

class Stack(Generic[T]):
    """Generic stack implementation."""
    def __init__(self) -> None:
        self._items: list[T] = []

    def push(self, item: T) -> None:
        self._items.append(item)

    def pop(self) -> T:
        return self._items.pop()


# Literal types (Python 3.8+)
LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR"]

def set_log_level(level: LogLevel) -> None:
    """Set logging level."""
    logging.getLogger().setLevel(level)


# Union types (Python 3.10+)
def parse_id(value: str | int) -> int:
    """Parse user ID from string or int."""
    return int(value) if isinstance(value, str) else value

mypy Configuration:

# mypy.ini
[mypy]
python_version = 3.10
warn_return_any = True
warn_unused_configs = True
disallow_untyped_defs = True
disallow_incomplete_defs = True
check_untyped_defs = True
no_implicit_optional = True
warn_redundant_casts = True
strict_equality = True

Static Analysis Tools:

# Type checking
mypy src/

# Linting
pylint src/
flake8 src/

# Security scanning
bandit -r src/

# All-in-one check
pre-commit run --all-files

Testing Standards

pytest Best Practices:

# tests/test_auth.py
"""Tests for authentication module."""

import pytest
from unittest.mock import Mock, patch
from myapp.auth import authenticate_user, User


@pytest.fixture
def mock_user():
    """Create mock user for testing."""
    return User(
        username="testuser",
        email="test@example.com",
        password_hash="$2b$12$..."
    )


@pytest.fixture
def auth_service(mock_user):
    """Create auth service with mocked database."""
    with patch('myapp.auth._fetch_user_from_db', return_value=mock_user):
        yield


def test_authenticate_valid_credentials(auth_service, mock_user):
    """Test authentication with valid credentials."""
    user = authenticate_user("testuser", "correct_password")

    assert user is not None
    assert user.username == mock_user.username
    assert user.email == mock_user.email


def test_authenticate_invalid_password(auth_service):
    """Test authentication fails with wrong password."""
    user = authenticate_user("testuser", "wrong_password")

    assert user is None


def test_authenticate_empty_username():
    """Test authentication rejects empty username."""
    with pytest.raises(ValueError, match="Username and password required"):
        authenticate_user("", "password")


@pytest.mark.parametrize("username,password,expected", [
    ("user1", "pass1", True),
    ("user2", "wrong", False),
    ("", "pass", False),
])
def test_authenticate_multiple_cases(username, password, expected):
    """Test authentication with multiple input combinations."""
    result = authenticate_user(username, password)
    assert (result is not None) == expected

Test Organization:

tests/
├── conftest.py              # Shared fixtures
├── unit/                    # Unit tests (fast, isolated)
│   ├── test_models.py
│   └── test_utils.py
├── integration/             # Integration tests (DB, API)
│   ├── test_api.py
│   └── test_database.py
└── e2e/                     # End-to-end tests (full flow)
    └── test_user_flows.py

Coverage Configuration:

# .coveragerc
[run]
source = src
omit =
    */tests/*
    */venv/*
    */__pycache__/*

[report]
exclude_lines =
    pragma: no cover
    def __repr__
    raise AssertionError
    raise NotImplementedError
    if TYPE_CHECKING:

See Also: Test Template

Documentation

Google-Style Docstrings:

def fetch_user_orders(
    user_id: int,
    start_date: datetime,
    end_date: datetime,
    status: Optional[str] = None
) -> list[Order]:
    """Fetch user orders within date range.

    Retrieves all orders for a user between start and end dates,
    optionally filtered by status. Orders are returned in descending
    order by creation date.

    Args:
        user_id: Unique user identifier
        start_date: Start of date range (inclusive)
        end_date: End of date range (inclusive)
        status: Optional order status filter ("pending", "shipped", "delivered")

    Returns:
        List of Order objects matching criteria. Empty list if no matches.

    Raises:
        ValueError: If end_date is before start_date
        UserNotFoundError: If user_id doesn't exist
        DatabaseError: If database query fails

    Example:
        >>> from datetime import datetime, timedelta
        >>> end = datetime.now()
        >>> start = end - timedelta(days=30)
        >>> orders = fetch_user_orders(123, start, end, status="shipped")
        >>> assert all(o.status == "shipped" for o in orders)

    Note:
        Results are cached for 5 minutes. Use cache_bust=True to force refresh.

    See Also:
        - fetch_all_orders(): Fetch orders for all users
        - Order: Order data class definition
    """
    if end_date < start_date:
        raise ValueError("end_date must be after start_date")

    # Implementation...

Module Documentation:

"""User authentication and authorization module.

This module provides secure user authentication using bcrypt password
hashing and JWT token-based authorization. It implements NIST 800-63B
password guidelines and supports multi-factor authentication.

Typical usage example:

    from myapp.auth import authenticate_user, generate_token

    user = authenticate_user(username, password)
    if user:
        token = generate_token(user)
        return {"token": token}

Security:
    - Passwords hashed with bcrypt (cost factor 12)
    - Tokens expire after 1 hour
    - Rate limiting: 5 attempts per 15 minutes

Attributes:
    TOKEN_EXPIRY (int): Token expiration time in seconds
    MAX_LOGIN_ATTEMPTS (int): Max failed login attempts before lockout
"""

from typing import Optional
import bcrypt
from datetime import datetime, timedelta

TOKEN_EXPIRY = 3600
MAX_LOGIN_ATTEMPTS = 5

Project Structure

Recommended Layout (src layout):

myproject/
├── src/
│   └── myapp/
│       ├── __init__.py
│       ├── api/
│       │   ├── __init__.py
│       │   ├── routes.py
│       │   └── dependencies.py
│       ├── models/
│       │   ├── __init__.py
│       │   └── user.py
│       ├── services/
│       │   ├── __init__.py
│       │   └── auth_service.py
│       └── utils/
│           ├── __init__.py
│           └── validators.py
├── tests/
│   ├── conftest.py
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── docs/
│   ├── api.md
│   └── architecture.md
├── scripts/
│   ├── setup_db.py
│   └── migrate.py
├── pyproject.toml
├── requirements.txt
├── requirements-dev.txt
├── README.md
└── .env.example

Why src layout?

Enforces testing against installed package
Prevents accidental imports from source
Matches production environment structure

Package Configuration:

# pyproject.toml
[build-system]
requires = ["setuptools>=65", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "myapp"
version = "1.0.0"
description = "My Python application"
requires-python = ">=3.10"
dependencies = [
    "fastapi>=0.100.0",
    "pydantic>=2.0.0",
    "sqlalchemy>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "pytest-cov>=4.1.0",
    "black>=23.0.0",
    "mypy>=1.5.0",
    "ruff>=0.0.290",
]

See Also: Project Template

Error Handling

Exception Hierarchy:

# exceptions.py
"""Application exception hierarchy."""


class AppError(Exception):
    """Base exception for application errors."""

    def __init__(self, message: str, code: str, details: dict = None):
        super().__init__(message)
        self.code = code
        self.details = details or {}


class ValidationError(AppError):
    """Input validation failed."""

    def __init__(self, field: str, message: str):
        super().__init__(
            message=f"Validation failed for {field}: {message}",
            code="VALIDATION_ERROR",
            details={"field": field}
        )


class AuthenticationError(AppError):
    """Authentication failed."""

    def __init__(self, reason: str = "Invalid credentials"):
        super().__init__(
            message=reason,
            code="AUTH_ERROR",
            details={"timestamp": datetime.now().isoformat()}
        )


class ResourceNotFoundError(AppError):
    """Requested resource not found."""

    def __init__(self, resource_type: str, resource_id: str | int):
        super().__init__(
            message=f"{resource_type} {resource_id} not found",
            code="NOT_FOUND",
            details={"resource_type": resource_type, "resource_id": resource_id}
        )

Error Handling Patterns:

import logging
from contextlib import contextmanager

logger = logging.getLogger(__name__)


def fetch_user(user_id: int) -> User:
    """Fetch user with comprehensive error handling."""
    try:
        user = db.query(User).filter(User.id == user_id).first()
        if not user:
            raise ResourceNotFoundError("User", user_id)
        return user

    except SQLAlchemyError as e:
        logger.error(
            "Database error fetching user",
            extra={
                "user_id": user_id,
                "error": str(e),
                "traceback": traceback.format_exc()
            }
        )
        raise AppError("Database error", "DB_ERROR") from e


@contextmanager
def handle_api_errors():
    """Context manager for API error handling."""
    try:
        yield
    except ValidationError as e:
        logger.warning(f"Validation error: {e}")
        raise HTTPException(status_code=400, detail=e.message)
    except AuthenticationError as e:
        logger.warning(f"Auth error: {e}")
        raise HTTPException(status_code=401, detail=e.message)
    except ResourceNotFoundError as e:
        logger.info(f"Resource not found: {e}")
        raise HTTPException(status_code=404, detail=e.message)
    except AppError as e:
        logger.error(f"Application error: {e}", extra=e.details)
        raise HTTPException(status_code=500, detail="Internal server error")


# Usage
@app.post("/users/")
async def create_user(user_data: UserCreate):
    with handle_api_errors():
        return user_service.create_user(user_data)

Structured Logging:

import structlog

logger = structlog.get_logger()

# Structured logging with context
logger.info(
    "user_login",
    user_id=user.id,
    username=user.username,
    ip_address=request.client.host,
    success=True
)

# Error logging with exception
try:
    process_payment(order)
except PaymentError as e:
    logger.error(
        "payment_failed",
        order_id=order.id,
        amount=order.total,
        error=str(e),
        exc_info=True  # Include stack trace
    )

Performance Practices

Profiling & Optimization:

import cProfile
import functools
import time
from typing import Callable


def profile_function(func: Callable) -> Callable:
    """Profile function execution time."""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        profiler = cProfile.Profile()
        profiler.enable()
        result = func(*args, **kwargs)
        profiler.disable()
        profiler.print_stats(sort='cumulative')
        return result
    return wrapper


def timeit(func: Callable) -> Callable:
    """Measure function execution time."""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        logger.info(f"{func.__name__} took {elapsed:.4f}s")
        return result
    return wrapper


# Memoization
from functools import lru_cache

@lru_cache(maxsize=128)
def expensive_calculation(n: int) -> int:
    """Expensive calculation with caching."""
    return sum(i ** 2 for i in range(n))


# Database optimization
from sqlalchemy.orm import joinedload

def fetch_users_with_orders():
    """Eager load related orders (N+1 query prevention)."""
    return db.query(User).options(
        joinedload(User.orders)
    ).all()


# Batch processing
def process_items_batch(items: list[Item], batch_size: int = 100):
    """Process items in batches for memory efficiency."""
    for i in range(0, len(items), batch_size):
        batch = items[i:i + batch_size]
        process_batch(batch)

Async Patterns:

import asyncio
import aiohttp
from typing import AsyncIterator


async def fetch_url(session: aiohttp.ClientSession, url: str) -> dict:
    """Fetch URL asynchronously."""
    async with session.get(url) as response:
        return await response.json()


async def fetch_all_urls(urls: list[str]) -> list[dict]:
    """Fetch multiple URLs concurrently."""
    async with aiohttp.ClientSession() as session:
        tasks = [fetch_url(session, url) for url in urls]
        return await asyncio.gather(*tasks)


async def stream_large_file(file_path: str) -> AsyncIterator[bytes]:
    """Stream large file asynchronously."""
    async with aiofiles.open(file_path, 'rb') as f:
        while chunk := await f.read(8192):
            yield chunk

Security Considerations

Input Validation:

from pydantic import BaseModel, EmailStr, Field, validator


class UserCreate(BaseModel):
    """User creation schema with validation."""

    username: str = Field(
        min_length=3,
        max_length=32,
        regex=r'^[a-zA-Z0-9_-]+$'
    )
    email: EmailStr
    password: str = Field(min_length=8)

    @validator('password')
    def password_strength(cls, v):
        """Validate password strength."""
        if not any(c.isupper() for c in v):
            raise ValueError("Password must contain uppercase letter")
        if not any(c.isdigit() for c in v):
            raise ValueError("Password must contain digit")
        if not any(c in '!@#$%^&*' for c in v):
            raise ValueError("Password must contain special character")
        return v


# SQL injection prevention (parameterized queries)
def get_user_by_email(email: str) -> User | None:
    """Fetch user by email (SQL injection safe)."""
    # ✅ Good: Parameterized query
    return db.query(User).filter(User.email == email).first()

    # ❌ Bad: String interpolation (SQL injection risk)
    # query = f"SELECT * FROM users WHERE email = '{email}'"

Secrets Management:

import os
from functools import lru_cache
from pydantic_settings import BaseSettings


class Settings(BaseSettings):
    """Application settings from environment."""

    database_url: str
    secret_key: str
    api_key: str

    class Config:
        env_file = ".env"
        env_file_encoding = "utf-8"


@lru_cache
def get_settings() -> Settings:
    """Get cached settings instance."""
    return Settings()


# Usage
settings = get_settings()
db = connect(settings.database_url)

# ❌ Never commit secrets
# API_KEY = "sk-1234567890abcdef"  # NEVER DO THIS

NIST Control Tags:

# @nist ia-2 "User authentication"
# @nist ia-5.1 "Password-based authentication"
def authenticate_user(username: str, password: str) -> User | None:
    """Authenticate user with secure password verification."""
    pass


# @nist ac-3 "Access enforcement"
# @nist ac-6 "Least privilege"
def check_permission(user: User, resource: str, action: str) -> bool:
    """Enforce role-based access control."""
    pass


# @nist sc-8 "Transmission confidentiality"
# @nist sc-13 "Cryptographic protection"
def encrypt_sensitive_data(data: str) -> str:
    """Encrypt data with AES-256-GCM."""
    pass

See Also: NIST Implementation Guide

Level 3: Mastery Resources

Advanced Topics

Advanced Patterns: Decorators, metaclasses, descriptors, async patterns, context managers
Architecture Patterns: Clean architecture, DDD, hexagonal architecture, CQRS
Testing Strategies: Property-based testing, mutation testing, contract testing

Templates & Examples

Project Template: Complete FastAPI project structure
Test Template: pytest template with fixtures and patterns
CLI Template: Click-based CLI application template
API Example: Full FastAPI REST API with auth, DB, tests

Configuration Files

pyproject.toml: Black, mypy, pytest, ruff configuration
pre-commit-config.yaml: Pre-commit hooks
mypy.ini: mypy type checking configuration
pytest.ini: pytest and coverage configuration

Tools & Scripts

setup-project.sh: Initialize new Python project
check-code-quality.sh: Run all quality checks
generate-requirements.py: Generate requirements files

Related Skills

Testing Standards - Comprehensive testing practices
Security Standards - Security implementation
API Design - RESTful API best practices

Quick Reference Commands

# Setup
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows
pip install -e ".[dev]"

# Code quality
black src/ tests/
isort src/ tests/
mypy src/
pylint src/
ruff check src/

# Testing
pytest
pytest --cov=src --cov-report=html
pytest -v -s tests/unit/  # Verbose unit tests only

# Pre-commit
pre-commit install
pre-commit run --all-files

# Build & publish
python -m build
twine upload dist/*

Examples

Basic Example: Simple Python Module

# calculator.py
"""Simple calculator module demonstrating Python best practices."""

from typing import Union

def add(a: Union[int, float], b: Union[int, float]) -> Union[int, float]:
    """Add two numbers.

    Args:
        a: First number
        b: Second number

    Returns:
        Sum of a and b

    Example:
        >>> add(2, 3)
        5
        >>> add(2.5, 1.5)
        4.0
    """
    return a + b

if __name__ == "__main__":
    import doctest
    doctest.testmod()

Production Example: FastAPI Service

# app/main.py
"""Production FastAPI service with proper structure."""

from fastapi import FastAPI, HTTPException, Depends
from pydantic import BaseModel, EmailStr
from typing import Optional
import logging

app = FastAPI(title="User Service", version="1.0.0")
logger = logging.getLogger(__name__)

class UserCreate(BaseModel):
    """User creation schema."""
    email: EmailStr
    name: str
    age: int

class User(BaseModel):
    """User response schema."""
    id: int
    email: EmailStr
    name: str
    age: int

@app.post("/users/", response_model=User, status_code=201)
async def create_user(user: UserCreate) -> User:
    """Create new user with validation."""
    try:
        # Implementation
        new_user = User(id=1, **user.dict())
        logger.info(f"Created user: {new_user.email}")
        return new_user
    except Exception as e:
        logger.error(f"Error creating user: {e}")
        raise HTTPException(status_code=500, detail="Internal server error")

Integration Example: Database with SQLAlchemy

# app/database.py
"""Database integration with SQLAlchemy ORM."""

from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker
from typing import Generator

DATABASE_URL = "postgresql://user:pass@localhost/dbname"

engine = create_engine(DATABASE_URL, pool_pre_ping=True)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()

class User(Base):
    """User database model."""
    __tablename__ = "users"

    id = Column(Integer, primary_key=True, index=True)
    email = Column(String, unique=True, index=True, nullable=False)
    name = Column(String, nullable=False)

def get_db() -> Generator:
    """Database session dependency."""
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

See examples/python-fastapi-app/ for a complete working example.

Integration Points

Upstream Dependencies

Development Tools: Black, isort, mypy, pylint for code quality
Testing Framework: pytest with pytest-cov for testing
Type Checking: mypy for static type analysis
Package Management: pip, poetry, or pipenv for dependency management

Downstream Consumers

CI/CD Systems: GitHub Actions, GitLab CI, Jenkins for automation
Code Review Tools: pre-commit hooks, SonarQube for quality gates
Documentation: Sphinx or MkDocs for API documentation generation
Containerization: Docker for packaging applications

Related Skills

Testing Standards - Comprehensive testing practices including pytest
Security Practices - Security implementation and NIST controls
API Design - RESTful and GraphQL API development
DevOps CI/CD - Continuous integration and deployment
Database SQL - Database design and optimization

Tool Ecosystem

Linters: pylint, flake8, ruff
Formatters: black, autopep8
Type Checkers: mypy, pyright
Security Scanners: bandit, safety
Documentation: sphinx, pdoc3
Testing: pytest, unittest, hypothesis

Common Pitfalls

Pitfall 1: Mutable Default Arguments

Problem: Using mutable objects (lists, dicts) as default arguments causes unexpected behavior where the same object is shared across function calls.

Solution: Use None as default and create new object inside function:

# ❌ Bad
def add_item(item, items=[]):
    items.append(item)
    return items

# ✅ Good
def add_item(item, items=None):
    if items is None:
        items = []
    items.append(item)
    return items

Prevention: Enable pylint warning W0102 (dangerous-default-value)

Pitfall 2: Bare Except Clauses

Problem: Using bare except: catches all exceptions including KeyboardInterrupt and SystemExit, making debugging difficult and preventing graceful shutdown.

Solution: Catch specific exceptions and use proper logging:

# ❌ Bad
try:
    risky_operation()
except:
    pass

# ✅ Good
try:
    risky_operation()
except (ValueError, KeyError) as e:
    logger.error(f"Operation failed: {e}", exc_info=True)
    raise

Prevention: Configure flake8 to enforce E722 (bare except)

Pitfall 3: Import * Anti-Pattern

Problem: Using from module import * pollutes namespace, makes code harder to debug, and can cause naming conflicts.

Solution: Use explicit imports:

# ❌ Bad
from os import *
from sys import *

# ✅ Good
from os import path, environ
from sys import argv, exit

Prevention: Enable pylint warning W0401 (wildcard-import)

Pitfall 4: Not Using Type Hints

Problem: Missing type hints make code harder to understand, maintain, and catch type errors at development time.

Solution: Add type hints to all public interfaces:

# ❌ Bad
def process_data(data):
    return [x * 2 for x in data]

# ✅ Good
def process_data(data: list[int]) -> list[int]:
    return [x * 2 for x in data]

Prevention: Configure mypy with disallow_untyped_defs = True

Pitfall 5: Ignoring Virtual Environments

Problem: Installing packages globally can cause version conflicts and make projects non-reproducible.

Solution: Always use virtual environments:

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Install dependencies
pip install -r requirements.txt

Prevention: Add virtual environment creation to project setup scripts

Best Practices:

Use pre-commit hooks to catch issues before committing
Configure IDE/editor with linters and type checkers
Follow PEP 8 style guide consistently with automated formatters
Write docstrings for all public APIs using Google or NumPy style
Maintain test coverage above 80% for production code
Use type hints for all function signatures and class attributes
Pin dependency versions in requirements.txt for reproducibility
Never commit secrets - use environment variables or secret management tools

Validation

This skill has been validated with:

✅ Token count: Level 1 <2,000, Level 2 <5,000
✅ Code examples: All tested and working
✅ Links: All internal references valid
✅ Resources: All bundled files created
✅ YAML frontmatter: Valid and complete

Install Skill

SKILL.md

Python Coding Standards

Level 1: Quick Start (<2,000 tokens, 5 minutes)

Core Principles

Essential Checklist

Quick Example

Quick Links to Level 2

Level 2: Implementation (<5,000 tokens, 30 minutes)

Code Style & Formatting

Type Hints & Static Analysis

Testing Standards

Documentation

Project Structure

Error Handling

Performance Practices

Security Considerations

Level 3: Mastery Resources

Advanced Topics

Templates & Examples

Configuration Files

Tools & Scripts

Related Skills

Quick Reference Commands

Examples

Basic Example: Simple Python Module

Production Example: FastAPI Service

Integration Example: Database with SQLAlchemy

Integration Points

Upstream Dependencies

Downstream Consumers

Related Skills

Tool Ecosystem

Common Pitfalls

Pitfall 1: Mutable Default Arguments

Pitfall 2: Bare Except Clauses

Pitfall 3: Import * Anti-Pattern

Pitfall 4: Not Using Type Hints

Pitfall 5: Ignoring Virtual Environments

Validation