"""A small command-line greeting utility."""

from __future__ import annotations

import argparse
from collections.abc import Sequence


def positive_int(value: str) -> int:
    """Return a positive integer.

    >>> positive_int("3")
    3
    >>> positive_int("0")
    Traceback (most recent call last):
    ...
    argparse.ArgumentTypeError: value must be a positive integer
    """
    try:
        number = int(value)
    except ValueError as exc:
        raise argparse.ArgumentTypeError("value must be an integer") from exc

    if number < 1:
        raise argparse.ArgumentTypeError("value must be a positive integer")
    return number


def build_parser() -> argparse.ArgumentParser:
    """Create and configure the CLI parser."""
    parser = argparse.ArgumentParser(description="Print a friendly greeting.")
    parser.add_argument("name", help="name of the person to greet")
    parser.add_argument(
        "-n",
        "--count",
        type=positive_int,
        default=1,
        help="number of greetings to print (default: 1)",
    )
    parser.add_argument(
        "--uppercase",
        action="store_true",
        help="print the greeting in uppercase",
    )
    return parser


def format_greeting(name: str, uppercase: bool = False) -> str:
    """Format a greeting.

    >>> format_greeting("Ada")
    'Hello, Ada!'
    >>> format_greeting("Ada", uppercase=True)
    'HELLO, ADA!'
    """
    greeting = f"Hello, {name}!"
    return greeting.upper() if uppercase else greeting


def main(argv: Sequence[str] | None = None) -> int:
    """Parse arguments and print the requested greetings."""
    args = build_parser().parse_args(argv)
    greeting = format_greeting(args.name, args.uppercase)

    for _ in range(args.count):
        print(greeting)

    return 0


if __name__ == "__main__":
    raise SystemExit(main())