"""Example Python module for Doc2Man demonstration.

This module contains various function types to demonstrate
the docstring parsing capabilities of Doc2Man.
"""


def greet(name: str, greeting: str = "Hello") -> str:
    """Greet a person with a custom greeting message.

    Args:
        name: The name of the person to greet. Should be a non-empty string.
        greeting: The greeting word to use. Defaults to "Hello".

    Returns:
        A formatted greeting string like "Hello, John!".

    Raises:
        ValueError: If name is empty or None.

    Examples:
        >>> greet("Alice")
        'Hello, Alice!'
        >>> greet("Bob", "Hi")
        'Hi, Bob!'
    """
    if not name:
        raise ValueError("Name cannot be empty")
    return f"{greeting}, {name}!"


def calculate_sum(numbers: list[float]) -> dict[str, float]:
    """Calculate the sum and average of a list of numbers.

    Args:
        numbers: A list of numeric values. Must not be empty.

    Returns:
        A dictionary containing:
        - sum: The total sum of all numbers
        - average: The arithmetic mean
        - count: The number of elements

    Raises:
        ValueError: If the input list is empty.

    Examples:
        >>> calculate_sum([1, 2, 3, 4, 5])
        {'sum': 15, 'average': 3.0, 'count': 5}
    """
    if not numbers:
        raise ValueError("Input list cannot be empty")

    total = sum(numbers)
    count = len(numbers)

    return {
        "sum": total,
        "average": total / count if count > 0 else 0,
        "count": count
    }


class FileHandler:
    """A class for handling file operations.

    This class provides methods for reading, writing,
    and processing files with proper error handling.

    Attributes:
        filepath: The path to the file being handled.
    """

    def __init__(self, filepath: str):
        """Initialize the FileHandler with a file path.

        Args:
            filepath: Path to the file to handle.
        """
        self.filepath = filepath

    def read(self, encoding: str = "utf-8") -> str:
        """Read the entire content of the file.

        Args:
            encoding: The text encoding to use. Defaults to UTF-8.

        Returns:
            The file contents as a string.

        Raises:
            FileNotFoundError: If the file doesn't exist.
            UnicodeDecodeError: If the file cannot be decoded.

        Examples:
            >>> handler = FileHandler("example.txt")
            >>> content = handler.read()
        """
        with open(self.filepath, "r", encoding=encoding) as f:
            return f.read()

    def write(self, content: str, encoding: str = "utf-8") -> None:
        """Write content to the file.

        Args:
            content: The text content to write.
            encoding: The text encoding to use. Defaults to UTF-8.

        Examples:
            >>> handler = FileHandler("output.txt")
            >>> handler.write("Hello, World!")
        """
        with open(self.filepath, "w", encoding=encoding) as f:
            f.write(content)