python-best-practices

Files (7)

• QUICK_REFERENCE.md
• README.md
• SKILL.md
• error_handling.py · examples/
• project_structure.py · examples/
• testing_examples.py · examples/
• type_hints_demo.py · examples/

SKILL.md (first lines)

# Python Best Practices Skill

This skill provides expert guidance for writing professional, maintainable Python code that follows industry best practices and standards.

## When to Use This Skill

Use this skill when:

- Writing new Python functions, classes, or modules
- Refactoring existing Python code for better quality
- Setting up a new Python project with proper structure
- Implementing unit tests or adopting TDD
- Adding type hints for better code clarity
- Configuring linting, formatting, and type checking tools
- Managing dependencies and virtual environments
- Improving code readability and maintainability
- Following PEP 8 style guidelines

## Core Principles

### 1. PEP 8: Style Guide for Python Code

**Key Guidelines:**

- **Indentation**: Use 4 spaces per indentation level (never tabs)
- **Line Length**: Limit lines to 79 characters (99 for code, 72 for docstrings/comments)
- **Blank Lines**: 2 blank lines between top-level functions/classes, 1 within classes
- **Imports**:
  - One import per line
  - Order: standard library, third-party, local (each group separated by blank line)
  - Avoid wildcard imports (`from module import *`)
- **Naming Conventions**:
  - `snake_case` for functions, variables, methods
  - `PascalCase` for classes
  - `UPPER_CASE` for constants
  - Leading underscore `_private` for internal use
- **Whitespace**:
  - No trailing whitespace
  - One space around operators: `x = 1`, not `x=1`
  - No space before function parentheses: `func(x)`, not `func (x)`

**Example:**

```python
"""Module docstring describing purpose."""

import os
import sys
from pathlib import Path

import numpy as np
import pandas as pd

from mypackage.module import MyClass

# Constants
MAX_RETRIES = 3
DEFAULT_TIMEOUT = 30


class DataProcessor:
    """Process and analyze data sets.

    Attributes:
        name: Processor name
        threshold: Minimum value threshold
    """

    def __init__(self, name: str, threshold: float = 0.5):
        """Initialize processor.

        Args:
            name: Name of the processor
            threshold: Threshold value for filtering (default: 0.5)
        """
        self.name = name
        self.threshold = threshold

    def process_data(self, data: list[float]) -> list[float]:
        """Process data by filtering values below threshold.

        Args:
            data: List of numeric values to process

        Returns:
            Filtered list containing only values >= threshold

        Raises:
            ValueError: If data is empty
        """
        if not data:
            raise ValueError("Data cannot be empty")

        return [x for x in data if x >= self.threshold]
```

### 2. Readability and Clarity

**Write Self-Documenting Code:**

```python
# Bad: unclear variable names
def calc(x, y, z):
    return x * y / z

# Good: descriptive names
def calculate_unit_price(total_cost: float, quantity: int, tax_rate: float) -> float:
    """Calculate price per unit including tax."""
    return total_cost * (1 + tax_rate) / quantity
```

**Use Docstrings:**

```python
def fetch_user_data(user_id: int, include_history: bool = False) -> dict:
    """Fetch user data from the database.

    Args:
        user_id: Unique identifier for the user

From woernfl/ai-lab, MIT.

More from woernfl/ai-lab