#!/usr/bin/env python3

import argparse
from collections.abc import Sequence


def build_parser() -> argparse.ArgumentParser:
    """Create the command-line parser."""
    parser = argparse.ArgumentParser(description="Greet someone.")
    parser.add_argument("name", help="name of the person to greet")
    parser.add_argument(
        "-n",
        "--count",
        type=int,
        default=1,
        help="number of greetings (default: 1)",
    )
    parser.add_argument(
        "--uppercase",
        action="store_true",
        help="print greetings in uppercase",
    )
    return parser


def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
    """Parse and validate command-line arguments."""
    parser = build_parser()
    args = parser.parse_args(argv)

    if args.count < 1:
        parser.error("--count must be at least 1")

    return args


def format_greeting(name: str, uppercase: bool = False) -> str:
    """Return a formatted greeting."""
    greeting = f"Hello, {name}!"
    return greeting.upper() if uppercase else greeting


def main(argv: Sequence[str] | None = None) -> int:
    args = parse_args(argv)
    greeting = format_greeting(args.name, args.uppercase)

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

    return 0


# Lightweight tests: run with `python -m pytest this_file.py`.
def test_default_arguments() -> None:
    args = parse_args(["Ada"])
    assert args.name == "Ada"
    assert args.count == 1
    assert args.uppercase is False


def test_uppercase_greeting() -> None:
    args = parse_args(["Ada", "--count", "2", "--uppercase"])
    assert args.count == 2
    assert format_greeting(args.name, args.uppercase) == "HELLO, ADA!"


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