"""ASCII key/value table printing.

Replaces the bash original's ad-hoc `echo`/`printf` table blocks (STEP 1, 7,
8) and the nameref-based print_map_as_table() helper (STAGE 3) with a single
generic function. Python has no need for bash's nameref indirection -- the
dict is just passed directly.

The bash version used a Unicode combining-overline row as an ersatz bottom
border; that's purely decorative with no functional role, so it's replaced
here with a plain ASCII divider of matching visual weight -- a deliberate,
low-risk cosmetic judgment call, not a fidelity gap.
"""
from __future__ import annotations

from collections.abc import Iterable


def print_kv_table(
    rows: dict[str, str] | Iterable[tuple[str, str]],
    col1: str,
    col2: str,
    title: str | None = None,
    width1: int = 36,
    width2: int = 36,
) -> None:
    items = list(rows.items()) if isinstance(rows, dict) else list(rows)
    border = "=" * (width1 + width2 + 7)

    if title:
        print(border)
        print(title)
        print(border)
    else:
        print("_" * (width1 + width2 + 7))

    print(f"| {col1:<{width1}} | {col2:<{width2}} |")
    print("-" * (width1 + width2 + 7))
    for key, value in items:
        print(f"| {key:<{width1}} | {value:<{width2}} |")
    print("-" * (width1 + width2 + 7))

    if title:
        print()