Format Python

format_python

Formatting Standards

• Use exactly 4 spaces for indentation (never tabs)
• Use double quotes for all string literals consistently
• Write one import per line, group in order: stdlib → third party → first party → local
• Use snake_case for variables/functions, PascalCase for classes, UPPER_CASE for constants
• Keep lines under 88 characters, break long lines at logical points with proper indentation

Code Quality Standards

• Write valid Python syntax that passes all linter checks
• Use specific exception types like ValueError, FileNotFoundError
• Assign error messages to variables before raising exceptions
• Import only what you use - avoid unused imports, types, or variables
• Use _ for intentionally unused values to prevent F841 errors
• Use modern type hints: dict[str, Any] instead of Dict[str, Any], str | None instead of Optional[str]
• Import types only when needed - prefer built-in types over typing module when possible
• Use f-strings for general formatting, use % formatting in logging statements
• Use is/is not for None comparisons, use in/not in for membership testing
• Avoid single-letter variable names except for loop counters
• Don't shadow built-in names like list, dict, str, id, type
• Use context managers (with statements) for all file operations and resource cleanup
• Use logger = logging.getLogger(__name__) for module-level logging
• Use logging instead of print statements for all output

Code Structure

• Follow this exact order: docstring → imports → constants → classes → functions → main guard
• Write functions with single responsibility, clear parameters, and early returns for better readability
• Use clear, descriptive class names; apply proper decorators (@classmethod, @staticmethod) for class methods
• Validate all input parameters when necessary, especially for public functions

Linting Prevention (Critical for LLM Code Generation)

• Write one import per line to prevent E401 multiple imports error
• Import only modules you actively use - remove unused imports immediately to prevent F401 errors
• Omit exception variable name when not using the exception object
• Remove commented-out code and unreachable statements immediately
• Update all class references when renaming to prevent F821 undefined name errors
• Use descriptive class names without "Test" prefix for non-test classes
• Use is None instead of == None to prevent E711 comparison error

Best Practices

• Define named functions instead of lambda assignments for better readability
• Use absolute imports for clarity
• Write one statement per line for maximum readability
• Create variables only when needed; use unique, descriptive names per scope
• Use isinstance() for type comparisons instead of type() checks
• Use path.open() instead of open(path) when working with Path objects
• Use logger.exception() in except blocks for better error tracking
• Validate and sanitize all external inputs
• Use environment variables for sensitive configuration

Error Handling & Resilience

• Always handle exceptions at the appropriate level of abstraction
• Use specific exception types and provide meaningful error messages
• Log errors with sufficient context for debugging
• Implement graceful degradation when possible
• Use try-except-else-finally blocks appropriately
• Re-raise exceptions with raise ... from e to preserve stack traces
• Create custom exception classes for domain-specific errors

Performance & Efficiency

• Use generators for large datasets to conserve memory
• Prefer list comprehensions over explicit loops when readable
• Use enumerate() instead of manual index tracking
• Cache expensive computations when appropriate
• Use collections.defaultdict and collections.Counter for common patterns
• Avoid premature optimization; profile before optimizing
• Use functools.lru_cache for expensive pure functions

Data Structures & Patterns

• Use dataclasses for simple data containers
• Prefer dictionaries over classes for simple data grouping
• Use collections.namedtuple for immutable data structures
• Implement __str__ and __repr__ methods for custom classes
• Use __slots__ for memory-efficient classes with many instances
• Prefer composition over inheritance when possible

Type Safety & Documentation

• Use type hints for all function parameters and return values
• Document complex algorithms and business logic
• Use docstrings following PEP 257 conventions
• Include examples in docstrings for complex functions
• Use typing.Protocol for structural subtyping
• Prefer typing.Literal for fixed value sets

Testing & Maintainability

• Write testable code with clear separation of concerns
• Use dependency injection for external dependencies
• Make functions pure when possible (no side effects)
• Use constants for magic numbers and strings
• Keep functions small and focused on single responsibilities
• Use meaningful variable and function names that explain intent

Security & Safety

• Never use eval() or exec() with user input
• Validate and sanitize all external data
• Use secrets module for cryptographic operations
• Be cautious with file path operations to prevent directory traversal
• Use parameterized queries for database operations
• Store sensitive data in environment variables or secure vaults

Example

"""Module docstring."""

import logging
from typing import Any

# Constants
DEFAULT_TIMEOUT = 30
logger = logging.getLogger(__name__)

class ExampleClass:
    """Example class demonstrating proper patterns."""

    def __init__(self, name: str, value: int | None = None) -> None:
        """Initialize with name and optional value."""
        self.name = name
        self.value = value

    def process_data(self, data: list[dict[str, Any]]) -> bool:
        """Process data and return success status."""
        if not data:
            return False

        for item in data:
            if not isinstance(item, dict):
                return False

        return True

    def get_info(self) -> dict[str, Any]:
        """Get class information."""
        return {
            "name": self.name,
            "value": self.value,
            "has_value": self.value is not None,
        }

def main() -> None:
    """Execute main function."""
    example = ExampleClass("test")
    result = example.process_data([{"id": 1, "name": "item"}])
    logger.info("Result: %s", result)

if __name__ == "__main__":
    main()

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: theafh
• Source: theafh/ai-modules
• License: MIT

Install and usage instructions live in the source repository linked above.