filesystem¶

def read_env_var(var_name: str) -> str:
    """
    Reads an environment variable.

    Args:
        var_name (str): Name of the environment variable.

    Returns:
        str: The value of the environment variable if valid.

    Raises:
        KeyError: If the environment variable does not exist.
        ValueError: If the environment variable is empty or contains only whitespace.
    """
    # Check if the environment variable exists
    if var_name not in os.environ:
        raise EnvVarMissingError(var_name)

    # Read the value
    value = os.environ[var_name]

    # Check if the value is empty
    if not value:
        raise EnvVarEmptyError(var_name)

    return value

def read_file_content(file_path: str | Path) -> str:
    """
    Reads a file and returns its content, rejecting an empty result.

    Args:
        file_path (str | Path): Path to the file.

    Returns:
        str: The content of the file.

    Raises:
        FileNotFoundError: If the file does not exist.
        PermissionError: If the file cannot be read due to permission issues.
        ValueError: If the file exists but is empty.
    """
    content = read_file(file_path)

    if not content:
        raise FileContentEmptyError(file_path)

    return content

def read_file(file_path: str | Path) -> str:
    """
    Reads a file and returns its content.
    Handles edge cases such as the file not existing or being unreadable.

    Args:
        file_path (str): Path to the token file.

    Returns:
        str: The content of the file.

    Raises:
        FileNotFoundError: If the file does not exist.
        PermissionError: If the file cannot be read due to permission issues.
    """
    path = Path(file_path)

    # Check if the file exists
    if not path.exists():
        raise FileMissingError(file_path)

    # Check if the file is readable
    if not os.access(path, os.R_OK):
        raise FileUnreadableError(file_path)

    # Read the file
    return path.read_text()

def ensure_gitignore(directory: str | Path) -> None:
    """
    Writes a `.gitignore` into `directory` that excludes everything but itself.

    Used for local directories (like `input/`) that hold fresh, per-run
    files that must never be committed, while still keeping the directory
    itself tracked in git.

    Args:
        directory (str | Path): Directory to write the `.gitignore` into.
    """
    # Ensure existence of .gitignore
    gitignore_path = Path(directory) / ".gitignore"
    gitignore_content = "*\n!.gitignore\n"
    gitignore_path.write_text(gitignore_content)