File Operations

Provides patterns for file handling in report generation workflows.

Reading Files

from pathlib import Path

def read_text(filepath: str, encoding: str = "utf-8") -> str:
    """Read text file contents."""
    return Path(filepath).read_text(encoding=encoding)

def read_lines(filepath: str, strip: bool = True) -> list[str]:
    """Read file as list of lines."""
    lines = Path(filepath).read_text().splitlines()
    return [line.strip() for line in lines] if strip else lines

def read_bytes(filepath: str) -> bytes:
    """Read binary file contents."""
    return Path(filepath).read_bytes()

Writing Files

from pathlib import Path

def write_text(filepath: str, content: str, encoding: str = "utf-8"):
    """Write text to file, creating directories if needed."""
    path = Path(filepath)
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(content, encoding=encoding)

def write_bytes(filepath: str, content: bytes):
    """Write binary content to file."""
    path = Path(filepath)
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_bytes(content)

def append_text(filepath: str, content: str, encoding: str = "utf-8"):
    """Append text to file."""
    with open(filepath, "a", encoding=encoding) as f:
        f.write(content)

Directory Operations

from pathlib import Path
import shutil

def ensure_dir(dirpath: str) -> Path:
    """Create directory if it doesn't exist."""
    path = Path(dirpath)
    path.mkdir(parents=True, exist_ok=True)
    return path

def list_files(dirpath: str, pattern: str = "*") -> list[Path]:
    """List files matching pattern in directory."""
    return list(Path(dirpath).glob(pattern))

def list_files_recursive(dirpath: str, pattern: str = "*") -> list[Path]:
    """List files matching pattern recursively."""
    return list(Path(dirpath).rglob(pattern))

def copy_file(src: str, dst: str):
    """Copy file to destination."""
    Path(dst).parent.mkdir(parents=True, exist_ok=True)
    shutil.copy2(src, dst)

def copy_dir(src: str, dst: str):
    """Copy directory recursively."""
    shutil.copytree(src, dst, dirs_exist_ok=True)

def move_file(src: str, dst: str):
    """Move file to destination."""
    Path(dst).parent.mkdir(parents=True, exist_ok=True)
    shutil.move(src, dst)

def delete_file(filepath: str):
    """Delete file if it exists."""
    path = Path(filepath)
    if path.exists():
        path.unlink()

def delete_dir(dirpath: str):
    """Delete directory recursively."""
    shutil.rmtree(dirpath, ignore_errors=True)

Path Utilities

from pathlib import Path
from datetime import datetime

def get_extension(filepath: str) -> str:
    """Get file extension without dot."""
    return Path(filepath).suffix.lstrip(".")

def change_extension(filepath: str, new_ext: str) -> str:
    """Change file extension."""
    path = Path(filepath)
    return str(path.with_suffix(f".{new_ext.lstrip('.')}"))

def get_filename(filepath: str, with_extension: bool = True) -> str:
    """Get filename from path."""
    path = Path(filepath)
    return path.name if with_extension else path.stem

def join_paths(*parts: str) -> str:
    """Join path parts."""
    return str(Path(*parts))

def get_unique_filename(filepath: str) -> str:
    """Generate unique filename if file exists."""
    path = Path(filepath)
    if not path.exists():
        return filepath

    stem = path.stem
    suffix = path.suffix
    counter = 1

    while True:
        new_path = path.parent / f"{stem}_{counter}{suffix}"
        if not new_path.exists():
            return str(new_path)
        counter += 1

def timestamped_filename(base: str, ext: str) -> str:
    """Generate timestamped filename."""
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    return f"{base}_{timestamp}.{ext.lstrip('.')}"

Temporary Files

import tempfile
from pathlib import Path
from contextlib import contextmanager

@contextmanager
def temp_file(suffix: str = "", content: str = None):
    """
    Create temporary file, optionally with content.

    Usage:
        with temp_file(suffix=".txt", content="Hello") as path:
            # Use the temp file
            print(path)
        # File is automatically deleted
    """
    fd, path = tempfile.mkstemp(suffix=suffix)
    try:
        if content:
            Path(path).write_text(content)
        yield path
    finally:
        Path(path).unlink(missing_ok=True)

@contextmanager
def temp_dir():
    """
    Create temporary directory.

    Usage:
        with temp_dir() as dirpath:
            # Use the temp directory
            pass
        # Directory is automatically deleted
    """
    path = tempfile.mkdtemp()
    try:
        yield path
    finally:
        shutil.rmtree(path, ignore_errors=True)

CSV Operations

import csv
from typing import List, Dict

def read_csv(filepath: str, has_header: bool = True) -> List[Dict]:
    """Read CSV file as list of dictionaries."""
    with open(filepath, newline="", encoding="utf-8") as f:
        if has_header:
            reader = csv.DictReader(f)
            return list(reader)
        else:
            reader = csv.reader(f)
            return [{"col_" + str(i): v for i, v in enumerate(row)} for row in reader]

def write_csv(filepath: str, data: List[Dict], fieldnames: List[str] = None):
    """Write list of dictionaries to CSV file."""
    if not data:
        return

    Path(filepath).parent.mkdir(parents=True, exist_ok=True)
    fieldnames = fieldnames or list(data[0].keys())

    with open(filepath, "w", newline="", encoding="utf-8") as f:
        writer = csv.DictWriter(f, fieldnames=fieldnames)
        writer.writeheader()
        writer.writerows(data)

Helper Script

Use helper.py for the FileManager class with comprehensive file handling utilities.