Python Best Practices: Clean Code and PEP 8 Guidelines

# Variables and functions: use snake_case (lowercase with underscores)
user_name = "John"
email_address = "john@example.com"
def calculate_total():
    pass
def get_user_by_id():
    pass

# Constants: use UPPER_SNAKE_CASE (all uppercase with underscores)
MAX_CONNECTIONS = 100
API_BASE_URL = "https://api.example.com"
DEFAULT_TIMEOUT = 30

# Classes: use PascalCase (each word capitalized)
class UserAccount:
    pass
class DatabaseConnection:
    pass
class HTTPRequestHandler:
    pass

# Private methods and attributes: prefix with single underscore
class MyClass:
    def _private_method(self):
        """Internal method, not part of public API"""
        pass
    
    def _internal_variable(self):
        return self._cache

# Name mangling: prefix with double underscore (rarely used)
class MyClass:
    def __very_private_method(self):
        """Name is mangled to _MyClass__very_private_method"""
        pass

# Module names: short, lowercase, underscores if needed
# my_module.py, database_utils.py

# Package names: short, lowercase, no underscores
# mypackage, databaseutils

# Bad naming
def calc(x, y):
    return x * y

# Good naming
def calculate_total_price(price, quantity):
    """Calculate total price for given quantity."""
    return price * quantity

# Bad naming
d = {}  # What is this dictionary for?
lst = []  # What does this list contain?

# Good naming
user_data = {}
shopping_cart = []

# Use 4 spaces for indentation (never tabs)
def my_function():
    if condition:
        do_something()
        if nested_condition:
            do_something_else()

# Maximum line length: 79 characters (or 99 for comments)
# Use parentheses for line continuation
long_variable_name = (
    "This is a very long string that exceeds "
    "the 79 character limit, so we break it "
    "across multiple lines"
)

# Or use backslash (less preferred)
result = value1 + value2 +          value3 + value4

# Better: use parentheses
result = (value1 + value2 +
          value3 + value4)

# Use blank lines to separate functions and classes
def function_one():
    pass


def function_two():
    pass


class MyClass:
    def method_one(self):
        pass
    
    def method_two(self):
        pass

# Use spaces around operators
result = x + y  # Good
result=x+y      # Bad

# No spaces around = in function arguments
def function(x=1, y=2):  # Good
    pass

def function(x = 1, y = 2):  # Bad
    pass

# Use spaces after commas
items = [1, 2, 3, 4]  # Good
items = [1,2,3,4]      # Bad

# Good: Single responsibility, clear naming, type hints
def calculate_discount(price: float, discount_percent: float) -> float:
    """
    Calculate the discounted price after applying a percentage discount.
    
    Args:
        price: Original price (must be positive)
        discount_percent: Discount percentage between 0 and 100
    
    Returns:
        The discounted price
    
    Raises:
        ValueError: If price is negative or discount is out of range
    
    Example:
        >>> calculate_discount(100.0, 10.0)
        90.0
    """
    if price < 0:
        raise ValueError("Price must be positive")
    if discount_percent < 0 or discount_percent > 100:
        raise ValueError("Discount must be between 0 and 100")
    
    return price * (1 - discount_percent / 100)


# Bad: Does too many things, unclear naming
def calc(x, y, z):
    if x < 0:
        return None
    if y < 0 or y > 100:
        return None
    result = x * (1 - y / 100)
    print(f"Result: {result}")
    return result


# Good: Small, focused functions
def validate_email(email: str) -> bool:
    """Check if email format is valid."""
    return "@" in email and "." in email.split("@")[1]


def send_email(to: str, subject: str, body: str) -> bool:
    """Send an email to the specified address."""
    if not validate_email(to):
        raise ValueError(f"Invalid email address: {to}")
    # Email sending logic here
    return True

# Bad: Deep nesting
def process_user(user):
    if user:
        if user.is_active:
            if user.has_permission:
                if user.balance > 0:
                    return process_payment(user)
                else:
                    return "Insufficient balance"
            else:
                return "No permission"
        else:
            return "User inactive"
    else:
        return "User not found"

# Good: Early returns (guard clauses)
def process_user(user):
    if not user:
        return "User not found"
    if not user.is_active:
        return "User inactive"
    if not user.has_permission:
        return "No permission"
    if user.balance <= 0:
        return "Insufficient balance"
    
    return process_payment(user)

def calculate_total(items: list[dict], tax_rate: float = 0.1) -> float:
    """
    Calculate the total price of items including tax.
    
    This function takes a list of items with 'price' and 'quantity' keys,
    calculates the subtotal, and applies the specified tax rate.
    
    Args:
        items: List of dictionaries, each containing 'price' and 'quantity'
        tax_rate: Tax rate as a decimal (default: 0.1 for 10%)
    
    Returns:
        Total price including tax, rounded to 2 decimal places
    
    Raises:
        ValueError: If items list is empty or tax_rate is negative
    
    Example:
        >>> items = [{"price": 10.0, "quantity": 2}, {"price": 5.0, "quantity": 1}]
        >>> calculate_total(items, 0.1)
        27.5
    """
    if not items:
        raise ValueError("Items list cannot be empty")
    if tax_rate < 0:
        raise ValueError("Tax rate cannot be negative")
    
    subtotal = sum(item["price"] * item["quantity"] for item in items)
    total = subtotal * (1 + tax_rate)
    return round(total, 2)


class User:
    """
    Represents a user in the system.
    
    Attributes:
        name: User's full name
        email: User's email address
        age: User's age in years
    
    Methods:
        get_display_name: Returns formatted display name
        is_adult: Checks if user is 18 or older
    """
    
    def __init__(self, name: str, email: str, age: int):
        self.name = name
        self.email = email
        self.age = age
    
    def get_display_name(self) -> str:
        """Return formatted display name."""
        return f"{self.name} ({self.email})"
    
    def is_adult(self) -> bool:
        """Check if user is 18 years or older."""
        return self.age >= 18

from typing import List, Dict, Optional, Union

# Basic type hints
def greet(name: str) -> str:
    return f"Hello, {name}!"

def add_numbers(a: int, b: int) -> int:
    return a + b

# Collections
def process_items(items: List[str]) -> List[str]:
    return [item.upper() for item in items]

def get_user_data(user_id: int) -> Dict[str, Union[str, int]]:
    return {"name": "John", "age": 30}

# Optional types
def find_user(email: str) -> Optional[Dict[str, str]]:
    # Returns user dict or None
    users = {"john@example.com": {"name": "John"}}
    return users.get(email)

# Class type hints
class User:
    def __init__(self, name: str, age: int):
        self.name: str = name
        self.age: int = age
    
    def get_info(self) -> Dict[str, Union[str, int]]:
        return {"name": self.name, "age": self.age}

# Be specific with exceptions
def divide(a: float, b: float) -> float:
    """Divide two numbers."""
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return a / b

# Use custom exceptions for domain-specific errors
class InsufficientFundsError(Exception):
    """Raised when account has insufficient funds."""
    pass

class BankAccount:
    def __init__(self, balance: float):
        self.balance = balance
    
    def withdraw(self, amount: float):
        if amount <= 0:
            raise ValueError("Withdrawal amount must be positive")
        if amount > self.balance:
            raise InsufficientFundsError(
                f"Insufficient funds. Balance: {self.balance}, Requested: {amount}"
            )
        self.balance -= amount

# Handle exceptions appropriately
def process_payment(account: BankAccount, amount: float) -> bool:
    try:
        account.withdraw(amount)
        return True
    except InsufficientFundsError as e:
        print(f"Payment failed: {e}")
        return False
    except ValueError as e:
        print(f"Invalid input: {e}")
        return False

# Traditional approach
squares = []
for x in range(10):
    squares.append(x ** 2)

# Pythonic approach (list comprehension)
squares = [x ** 2 for x in range(10)]

# With condition
even_squares = [x ** 2 for x in range(10) if x % 2 == 0]

# Dictionary comprehension
square_dict = {x: x ** 2 for x in range(10)}

# Set comprehension
unique_squares = {x ** 2 for x in range(10)}

# Nested comprehensions (use sparingly)
matrix = [[i * j for j in range(3)] for i in range(3)]
# Result: [[0, 0, 0], [0, 1, 2], [0, 2, 4]]

# Generator expressions (memory efficient for large data)
large_squares = (x ** 2 for x in range(1000000))
# Use when you don't need the full list in memory

# Install tools
pip install flake8 black pylint mypy

# flake8 - Checks PEP 8 compliance
flake8 your_file.py

# black - Auto-formats code to PEP 8
black your_file.py

# pylint - Comprehensive code analysis
pylint your_file.py

# mypy - Static type checking
mypy your_file.py