Source code for lunapi.destrat_cli

"""Command-line adapter for the pure-Python :mod:`lunapi.destrat` reader.

The command follows the useful, query-oriented part of the native
``destrat`` grammar.  Database paths and an optional command selector are
positional; ``-r`` and ``-c`` consume factor specifications, including level
restrictions such as ``F/11,15``.
"""

from __future__ import annotations

import argparse
import sqlite3
import sys
import textwrap
from shutil import get_terminal_size
from typing import Sequence

import pandas as pd

from .destrat import destrat


def _parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        prog="destrat.py",
        description="Query Luna SQLite/destrat output databases.",
        epilog=(
            "Examples: destrat.py out.db; "
            "destrat.py out.db +PSD -r CH F -v PSD; "
            "destrat.py out.db +PSD -r F/11,15 CH"
        ),
    )
    parser.add_argument(
        "items",
        nargs="+",
        metavar="DB|COMMAND",
        help="database path(s), followed optionally by +COMMAND or [COMMAND]",
    )
    parser.add_argument(
        "-r", dest="rows", action="append", nargs="+", metavar="FACTOR",
        help="row stratifier(s), e.g. CH F/11,15; may be repeated",
    )
    parser.add_argument(
        "-c", dest="columns", action="append", nargs="+", metavar="FACTOR",
        help="column stratifier(s), e.g. B; may be repeated",
    )
    parser.add_argument(
        "-v", dest="variables", action="append", nargs="+", metavar="VARIABLE",
        help="variable(s) to extract; may be repeated",
    )
    parser.add_argument(
        "-i", dest="individuals", action="append", nargs="+", metavar="ID",
        help="individual ID(s) to include; may be repeated",
    )
    parser.add_argument(
        "-s", dest="statement", metavar="COMMAND",
        help="select a command, as an alternative to +COMMAND",
    )
    parser.add_argument(
        "-x", dest="summary", action="store_true",
        help="print the output summary (the default without a command)",
    )
    parser.add_argument(
        "-d", dest="dictionary", action="store_true",
        help="print the command/variable dictionary",
    )
    parser.add_argument(
        "-p", dest="precision", type=int, metavar="N",
        help="print numeric values with N decimal places",
    )
    # Native destrat uses -f to select database output mode.  The Python
    # reader is database-only, so accepting it keeps common invocations
    # compatible without changing behavior.
    parser.add_argument("-f", dest="database_mode", action="store_true", help=argparse.SUPPRESS)
    parser.add_argument(
        "-n", dest="include_command", action="store_true",
        help="prepend a CMD column to extracted output",
    )
    parser.add_argument(
        "-b", "--behead", dest="behead", action="store_true",
        help="print each extracted row as name/value pairs",
    )
    return parser


def _flatten(groups: list[list[str]] | None) -> list[str]:
    return [item for group in (groups or []) for item in group]


def _split_items(items: Sequence[str]) -> tuple[list[str], str | None]:
    """Split database paths from an optional native-style command selector."""

    databases = []
    command = None
    for item in items:
        if item.startswith("+") and len(item) > 1:
            if command is not None:
                raise ValueError("only one command selector may be specified")
            command = item[1:]
        elif len(item) > 2 and item.startswith("[") and item.endswith("]"):
            if command is not None:
                raise ValueError("only one command selector may be specified")
            command = item[1:-1]
        else:
            databases.append(item)
    if not databases:
        raise ValueError("at least one database path is required")
    return databases, command


def _format_frame(frame: pd.DataFrame, precision: int | None) -> str:
    kwargs = {"sep": "\t", "index": False, "na_rep": "NA", "lineterminator": "\n"}
    if precision is not None:
        kwargs["float_format"] = f"%.{precision}f"
    return frame.to_csv(**kwargs)


def _format_summary(frame: pd.DataFrame) -> str:
    """Format the summary with wrapped variable lists for terminal reading."""

    if frame.empty:
        return frame.to_string(index=False)

    columns = ["CMD", "FACTORS", "N_VARS"]
    widths = {
        column: max(len(column), max(len(str(value)) for value in frame[column]))
        for column in columns
    }
    prefix_width = sum(widths.values()) + 3 * len(columns)
    terminal_width = max(80, get_terminal_size((120, 20)).columns)
    variable_width = max(30, terminal_width - prefix_width - 1)

    header = (
        f"{'CMD':<{widths['CMD']}}   "
        f"{'FACTORS':<{widths['FACTORS']}}   "
        f"{'N_VARS':>{widths['N_VARS']}}   VARIABLES"
    )
    lines = [header]
    continuation = " " * (prefix_width + 1)
    for row in frame.itertuples(index=False):
        values = dict(zip(frame.columns, row))
        variables = str(values.get("VARIABLES", ""))
        wrapped = textwrap.wrap(
            variables,
            width=variable_width,
            break_long_words=False,
            break_on_hyphens=False,
        ) or [""]
        prefix = (
            f"{str(values['CMD']):<{widths['CMD']}}   "
            f"{str(values['FACTORS']):<{widths['FACTORS']}}   "
            f"{str(values['N_VARS']):>{widths['N_VARS']}}   "
        )
        lines.append(prefix + wrapped[0])
        lines.extend(continuation + part for part in wrapped[1:])
    return "\n".join(lines)


def _format_behead(frame: pd.DataFrame) -> str:
    """Format rows like Luna's ``behead`` utility."""

    lines = []
    for row in frame.itertuples(index=False, name=None):
        for column, value in zip(frame.columns, row):
            if pd.isna(value):
                value = "NA"
            lines.append(f"{str(column):>25}   {str(value):<20}")
        lines.append("")
    return "\n".join(lines)


def _write(text: str) -> None:
    sys.stdout.write(text)
    if text and not text.endswith("\n"):
        sys.stdout.write("\n")


[docs] def main(argv: Sequence[str] | None = None) -> int: """Run the Python destrat command and return an exit status.""" args = _parser().parse_args(sys.argv[1:] if argv is None else argv) try: databases, command = _split_items(args.items) if args.statement is not None: if command is not None: raise ValueError("cannot specify both +COMMAND/[COMMAND] and -s") command = args.statement.lstrip("+#") db = destrat(databases) if args.dictionary: _write(db.vars().to_string(index=False)) return 0 if command is None: if args.rows or args.columns or args.variables or args.individuals: raise ValueError("-r, -c, -v and -i require a command selector") _write(_format_summary(db.tables())) return 0 frame = db.get( command, r=_flatten(args.rows) or None, c=_flatten(args.columns) or None, v=_flatten(args.variables) or None, ids=_flatten(args.individuals) or None, ) if args.include_command: frame = frame.copy() frame.insert(0, "CMD", command) if args.behead: _write(_format_behead(frame)) else: _write(_format_frame(frame, args.precision)) return 0 except (FileNotFoundError, ValueError, KeyError, sqlite3.Error) as exc: print(f"destrat.py: error: {exc}", file=sys.stderr) return 1
if __name__ == "__main__": # pragma: no cover raise SystemExit(main())