Python Code Organization and Indentation

Real-World Code Organization Example

Let's look at a more comprehensive example that demonstrates good code organization practices in a real-world scenario.

#!/usr/bin/env python3
"""
Weather Data Analyzer

This module provides classes and functions for analyzing weather data.
It can calculate averages, identify trends, and generate reports.
"""

# Standard library imports
import csv
import datetime
import statistics
from typing import List, Dict, Tuple, Optional, Union

# Third-party imports
import matplotlib.pyplot as plt
import numpy as np

# Local imports
from .utils import format_date, celsius_to_fahrenheit

__version__ = '1.0.0'

# Constants
MONTHS = [
    'January', 'February', 'March', 'April', 'May', 'June',
    'July', 'August', 'September', 'October', 'November', 'December'
]

SEASONS = {
    'winter': [12, 1, 2],
    'spring': [3, 4, 5],
    'summer': [6, 7, 8],
    'fall': [9, 10, 11]
}


class WeatherRecord:
    """
    Represents a single weather record for a specific date.
    
    Attributes:
        date (datetime.date): The date of the record.
        temperature (float): Temperature in Celsius.
        humidity (float): Relative humidity as a percentage.
        precipitation (float): Precipitation amount in mm.
    """
    
    def __init__(
        self,
        date: datetime.date,
        temperature: float,
        humidity: float,
        precipitation: float
    ):
        """Initialize a weather record with the given data."""
        self.date = date
        self.temperature = temperature
        self.humidity = humidity
        self.precipitation = precipitation
    
    def temperature_fahrenheit(self) -> float:
        """Get the temperature in Fahrenheit."""
        return celsius_to_fahrenheit(self.temperature)
    
    def is_rainy(self) -> bool:
        """Check if this record indicates rain."""
        return self.precipitation > 0.1
    
    def __str__(self) -> str:
        """Return a string representation of the record."""
        return (
            f"{self.date.strftime('%Y-%m-%d')}: "
            f"{self.temperature:.1f}°C, "
            f"{self.humidity:.1f}%, "
            f"{self.precipitation:.1f}mm"
        )


class WeatherAnalyzer:
    """
    Analyzes a collection of weather records.
    
    This class provides methods to calculate statistics and identify
    patterns in weather data.
    """
    
    def __init__(self, records: List[WeatherRecord]):
        """
        Initialize with a list of weather records.
        
        Args:
            records: A list of WeatherRecord objects to analyze.
        """
        self.records = records
        self._sort_records()
    
    def _sort_records(self) -> None:
        """Sort records by date (oldest first)."""
        self.records.sort(key=lambda r: r.date)
    
    def average_temperature(self) -> float:
        """Calculate the average temperature across all records."""
        if not self.records:
            return 0.0
        return statistics.mean(r.temperature for r in self.records)
    
    def monthly_averages(self) -> Dict[str, float]:
        """
        Calculate average temperatures for each month.
        
        Returns:
            A dictionary mapping month names to average temperatures.
        """
        result = {}
        for month_number, month_name in enumerate(MONTHS, 1):
            month_records = [
                r for r in self.records 
                if r.date.month == month_number
            ]
            
            if month_records:
                avg_temp = statistics.mean(
                    r.temperature for r in month_records
                )
                result[month_name] = avg_temp
        
        return result
    
    def seasonal_analysis(self) -> Dict[str, Dict[str, float]]:
        """
        Analyze weather patterns by season.
        
        Returns:
            A dictionary with seasonal statistics.
        """
        result = {}
        
        for season, months in SEASONS.items():
            season_records = [
                r for r in self.records 
                if r.date.month in months
            ]
            
            if not season_records:
                continue
                
            result[season] = {
                'avg_temp': statistics.mean(
                    r.temperature for r in season_records
                ),
                'avg_humidity': statistics.mean(
                    r.humidity for r in season_records
                ),
                'avg_precip': statistics.mean(
                    r.precipitation for r in season_records
                ),
                'rainy_days': sum(
                    1 for r in season_records if r.is_rainy()
                )
            }
            
        return result
    
    def generate_report(self) -> str:
        """
        Generate a text report of the weather analysis.
        
        Returns:
            A formatted string containing the analysis results.
        """
        if not self.records:
            return "No data available for analysis."
            
        # Calculate date range
        start_date = min(r.date for r in self.records)
        end_date = max(r.date for r in self.records)
        
        # Start building the report
        report = [
            "Weather Analysis Report",
            "======================="
            "",
            f"Period: {start_date} to {end_date}",
            f"Total records: {len(self.records)}",
            "",
            "Overall Statistics:",
            f"- Average Temperature: {self.average_temperature():.1f}°C",
            ""
        ]
        
        # Add monthly averages
        report.append("Monthly Averages:")
        for month, avg in self.monthly_averages().items():
            report.append(f"- {month}: {avg:.1f}°C")
        
        # Add seasonal analysis
        report.append("")
        report.append("Seasonal Analysis:")
        for season, stats in self.seasonal_analysis().items():
            report.append(f"- {season.capitalize()}:")
            report.append(f"  - Avg. Temperature: {stats['avg_temp']:.1f}°C")
            report.append(f"  - Avg. Humidity: {stats['avg_humidity']:.1f}%")
            report.append(f"  - Avg. Precipitation: {stats['avg_precip']:.1f}mm")
            report.append(f"  - Rainy Days: {stats['rainy_days']}")
        
        # Join all lines and return
        return "\n".join(report)
    
    def plot_temperature_trend(self, filename: Optional[str] = None) -> None:
        """
        Plot the temperature trend over time.
        
        Args:
            filename: If provided, save the plot to this file.
                     Otherwise, display it interactively.
        """
        if not self.records:
            print("No data available for plotting.")
            return
            
        dates = [r.date for r in self.records]
        temperatures = [r.temperature for r in self.records]
        
        plt.figure(figsize=(12, 6))
        plt.plot(dates, temperatures, 'b-')
        plt.xlabel('Date')
        plt.ylabel('Temperature (°C)')
        plt.title('Temperature Trend')
        plt.grid(True)
        
        if filename:
            plt.savefig(filename)
        else:
            plt.show()


def load_weather_data(csv_file: str) -> List[WeatherRecord]:
    """
    Load weather data from a CSV file.
    
    Args:
        csv_file: Path to the CSV file.
        
    Returns:
        A list of WeatherRecord objects.
    """
    records = []
    
    try:
        with open(csv_file, 'r', newline='') as f:
            reader = csv.DictReader(f)
            for row in reader:
                try:
                    date_parts = [int(x) for x in row['date'].split('-')]
                    record = WeatherRecord(
                        date=datetime.date(*date_parts),
                        temperature=float(row['temperature']),
                        humidity=float(row['humidity']),
                        precipitation=float(row['precipitation'])
                    )
                    records.append(record)
                except (ValueError, KeyError) as e:
                    print(f"Skipping invalid row: {row} - {e}")
    except Exception as e:
        print(f"Error loading weather data: {e}")
    
    return records


if __name__ == "__main__":
    # Example usage
    data_file = "weather_data.csv"
    records = load_weather_data(data_file)
    
    if not records:
        print("No valid records found.")
        exit(1)
    
    analyzer = WeatherAnalyzer(records)
    
    # Print report
    print(analyzer.generate_report())
    
    # Plot temperature trend
    analyzer.plot_temperature_trend("temperature_trend.png")
    
    print("Analysis complete. Plot saved to temperature_trend.png")

This example demonstrates good organization through:

• Clear module docstring
• Proper import organization
• Logical grouping of constants, classes, and functions
• Comprehensive docstrings
• Consistent indentation
• Private methods preceded by underscore
• Type hints for better code understanding
• Clean separation of concerns between classes