6.8. CLI-приложение

mkdir -p /tmp/csvstat/src/csvstat /tmp/csvstat/tests && cd /tmp/csvstat

cat > src/csvstat/__init__.py <<'PY'
"""csvstat — статистика по числовой колонке CSV."""

__version__ = "1.0.0"
PY

cat > src/csvstat/cli.py <<'PY'
"""CLI: статистика по числовой колонке CSV.

Коды возврата:
    0 — успех
    1 — ошибка данных (файл не найден, некорректный CSV)
    2 — ошибка использования (выставляет argparse)
    3 — указанная колонка не найдена
"""
from __future__ import annotations

import argparse
import csv
import statistics
import sys
from pathlib import Path
from typing import TextIO

from . import __version__

EXIT_OK = 0
EXIT_DATA_ERROR = 1
EXIT_COLUMN_NOT_FOUND = 3


def compute(rows: list[dict[str, str]], column: str) -> dict[str, float]:
    """Считает статистику по колонке.

    Raises:
        KeyError: колонка отсутствует.
        ValueError: в колонке нет числовых значений.
    """
    if not rows:
        raise ValueError("нет строк данных")
    if column not in rows[0]:
        raise KeyError(column)

    values: list[float] = []
    skipped = 0
    for row in rows:
        raw = (row.get(column) or "").strip()
        if not raw:
            skipped += 1
            continue
        try:
            values.append(float(raw))
        except ValueError:
            skipped += 1

    if not values:
        raise ValueError(f"в колонке {column!r} нет числовых значений")

    return {
        "count": len(values),
        "skipped": skipped,
        "min": min(values),
        "max": max(values),
        "mean": statistics.fmean(values),
        "median": statistics.median(values),
    }


def format_stats(stats: dict[str, float]) -> str:
    order = ("count", "min", "max", "mean", "median")
    width = max(len(k) for k in order)
    return "\n".join(
        f"{k:<{width}}  {stats[k]:g}" if k == "count" else f"{k:<{width}}  {stats[k]:.4g}"
        for k in order
    )


def build_parser() -> argparse.ArgumentParser:
    p = argparse.ArgumentParser(
        prog="csvstat",
        description="Статистика по числовой колонке CSV.",
    )
    p.add_argument("path", nargs="?", type=Path,
                   help="файл CSV; без него читается стандартный ввод")
    p.add_argument("-c", "--column", required=True, help="имя колонки")
    p.add_argument("-d", "--delimiter", default=",", help="разделитель (по умолчанию запятая)")
    p.add_argument("--version", action="version", version=f"csvstat {__version__}")
    return p


def read_rows(stream: TextIO, delimiter: str) -> list[dict[str, str]]:
    return list(csv.DictReader(stream, delimiter=delimiter))


def main(argv: list[str] | None = None) -> int:
    args = build_parser().parse_args(argv)

    try:
        if args.path is not None:
            if not args.path.is_file():
                print(f"ошибка: файл не найден: {args.path}", file=sys.stderr)
                return EXIT_DATA_ERROR
            with args.path.open(encoding="utf-8", newline="") as fh:
                rows = read_rows(fh, args.delimiter)
        else:
            rows = read_rows(sys.stdin, args.delimiter)
    except (OSError, csv.Error) as exc:
        print(f"ошибка чтения: {exc}", file=sys.stderr)
        return EXIT_DATA_ERROR

    try:
        stats = compute(rows, args.column)
    except KeyError:
        available = ", ".join(rows[0].keys()) if rows else "(нет данных)"
        print(f"ошибка: колонка {args.column!r} не найдена", file=sys.stderr)
        print(f"доступные колонки: {available}", file=sys.stderr)
        return EXIT_COLUMN_NOT_FOUND
    except ValueError as exc:
        print(f"ошибка: {exc}", file=sys.stderr)
        return EXIT_DATA_ERROR

    # результат — в stdout
    print(format_stats(stats))
    # диагностика — в stderr
    if stats["skipped"]:
        print(f"пропущено нечисловых значений: {stats['skipped']:g}", file=sys.stderr)
    return EXIT_OK
PY

cat > src/csvstat/__main__.py <<'PY'
import sys

from .cli import main

if __name__ == "__main__":
    sys.exit(main())
PY

cat > tests/test_cli.py <<'PY'
import io

import pytest

from csvstat.cli import compute, main


ROWS = [
    {"name": "a", "value": "10"},
    {"name": "b", "value": "20"},
    {"name": "c", "value": "30"},
]


def test_compute_basic():
    s = compute(ROWS, "value")
    assert s["count"] == 3
    assert s["min"] == 10
    assert s["max"] == 30
    assert s["mean"] == 20


def test_compute_skips_non_numeric():
    rows = ROWS + [{"name": "d", "value": "нечисло"}, {"name": "e", "value": ""}]
    s = compute(rows, "value")
    assert s["count"] == 3
    assert s["skipped"] == 2


def test_compute_missing_column_raises():
    with pytest.raises(KeyError):
        compute(ROWS, "нет-такой")


def test_compute_no_numeric_raises():
    with pytest.raises(ValueError, match="нет числовых"):
        compute([{"v": "x"}, {"v": "y"}], "v")


def test_main_reads_stdin(monkeypatch, capsys):
    monkeypatch.setattr("sys.stdin", io.StringIO("name,value\na,1\nb,3\n"))
    assert main(["--column", "value"]) == 0
    assert "mean" in capsys.readouterr().out


def test_main_missing_file_returns_1(capsys):
    assert main(["/nonexistent.csv", "--column", "v"]) == 1
    assert "не найден" in capsys.readouterr().err


def test_main_missing_column_returns_3(monkeypatch, capsys):
    monkeypatch.setattr("sys.stdin", io.StringIO("name,value\na,1\n"))
    assert main(["--column", "нет-такой"]) == 3
    err = capsys.readouterr().err
    assert "не найдена" in err
    assert "доступные колонки" in err


def test_main_no_numeric_returns_1(monkeypatch, capsys):
    monkeypatch.setattr("sys.stdin", io.StringIO("v\nx\ny\n"))
    assert main(["--column", "v"]) == 1


def test_parser_requires_column():
    with pytest.raises(SystemExit) as exc:
        main([])
    assert exc.value.code == 2


def test_result_to_stdout_diagnostics_to_stderr(monkeypatch, capsys):
    monkeypatch.setattr("sys.stdin", io.StringIO("v\n1\nx\n2\n"))
    assert main(["--column", "v"]) == 0
    out, err = capsys.readouterr()
    assert "mean" in out
    assert "mean" not in err
    assert "пропущено" in err
PY

cat > pyproject.toml <<'EOF'
[project]
name = "csvstat"
version = "1.0.0"
description = "Статистика по числовой колонке CSV"
requires-python = ">=3.11"
dependencies = []

[project.scripts]
csvstat = "csvstat.cli:main"

[build-system]
requires = ["setuptools>=77"]
build-backend = "setuptools.build_meta"

[tool.setuptools.packages.find]
where = ["src"]
EOF

cat > .dockerignore <<'EOF'
Dockerfile*
.dockerignore
README.md
csvstat
.git
.venv
__pycache__
*.py[cod]
.pytest_cache
*.csv
EOF

# tests не исключён: его копирует стадия test, а .dockerignore
# действует на всю сборку сразу (урок 5.1)

cat > Dockerfile <<'EOF'
# syntax=docker/dockerfile:1

FROM python:3.13-slim AS base
ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1 \
    PATH="/opt/venv/bin:$PATH"
WORKDIR /work
RUN useradd --create-home --uid 10001 appuser

FROM base AS builder
RUN python -m venv /opt/venv
COPY pyproject.toml .
COPY src/ ./src/
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install .

# Требование 7: тесты как стадия сборки
FROM builder AS test
RUN --mount=type=cache,target=/root/.cache/pip pip install pytest==9.1.1
COPY tests/ ./tests/
RUN pytest -q tests/

FROM base AS runtime
COPY --from=builder --chown=10001:10001 /opt/venv /opt/venv
USER 10001:10001

# Требование 1: exec form — аргументы доходят до приложения
ENTRYPOINT ["csvstat"]
CMD ["--help"]
EOF

# ── Проверка требований ──
docker build -q -t csvstat . > /dev/null
echo "образ собран"

cat > sample.csv <<'EOF'
name,value,note
alpha,10,ok
beta,20,ok
gamma,30,ok
delta,,пусто
epsilon,нечисло,плохо
EOF

echo
echo "═══ Требование 1: аргументы доходят ═══"
docker run --rm -v "$PWD/sample.csv:/work/sample.csv:ro" csvstat sample.csv --column value

echo
echo "═══ Требование 2: чтение stdin ═══"
docker run --rm -i csvstat --column value < sample.csv 2>/dev/null

echo
echo "═══ Требование 3: разделение потоков ═══"
echo -n "  только stdout: "; docker run --rm -i csvstat --column value < sample.csv 2>/dev/null | tr '\n' ' '
echo
echo -n "  только stderr: "; docker run --rm -i csvstat --column value < sample.csv 2>&1 1>/dev/null

echo
echo "═══ Требование 4: коды возврата ═══"
docker run --rm -i csvstat --column value < sample.csv > /dev/null 2>&1; echo "  успех:            $?"
docker run --rm csvstat /nonexistent.csv --column v > /dev/null 2>&1; echo "  файл не найден:   $?"
docker run --rm csvstat --no-such-flag > /dev/null 2>&1; echo "  неверный аргумент: $?"
docker run --rm -i csvstat --column нет-такой < sample.csv > /dev/null 2>&1; echo "  колонки нет:      $?"

echo
echo "═══ Требование 5: непривилегированный пользователь ═══"
printf '  UID: %s\n' "$(docker run --rm --entrypoint id csvstat -u)"

echo
echo "═══ Требование 6: владелец созданных файлов ═══"
mkdir -p out
docker run --rm --user "$(id -u):$(id -g)" \
    -v "$PWD:/work" csvstat sample.csv --column value 2>/dev/null > out/result.txt
printf '  владелец файла: %s (текущий пользователь: %s:%s)\n' \
    "$(stat -c '%u:%g' out/result.txt)" "$(id -u)" "$(id -g)"

echo
echo "═══ Требование 7: тесты в сборке ═══"
docker build -q --target test -t csvstat:test . > /dev/null && echo "  тесты прошли"

# обёртка
cat > csvstat <<'SH'
#!/usr/bin/env bash
set -euo pipefail
IMAGE="${CSVSTAT_IMAGE:-csvstat}"
args=(--rm --user "$(id -u):$(id -g)" -v "$PWD:/work" -w /work)
[ -t 0 ] || args+=(-i)
exec docker run "${args[@]}" "$IMAGE" "$@"
SH
chmod +x csvstat

echo
echo "═══ Обёртка ═══"
./csvstat sample.csv --column value 2>/dev/null
echo "  ─── в конвейере ───"
./csvstat --column value < sample.csv 2>/dev/null | grep mean

образ собран

═══ Требование 1: аргументы доходят ═══
count   3
min     10
max     30
mean    20
median  20
пропущено нечисловых значений: 2

═══ Требование 2: чтение stdin ═══
count   3
min     10
max     30
mean    20
median  20

═══ Требование 3: разделение потоков ═══
  только stdout: count   3 min     10 max     30 mean    20 median  20 
  только stderr: пропущено нечисловых значений: 2

═══ Требование 4: коды возврата ═══
  успех:            0
  файл не найден:   1
  неверный аргумент: 2
  колонки нет:      3

═══ Требование 5: непривилегированный пользователь ═══
  UID: 10001

═══ Требование 6: владелец созданных файлов ═══
  владелец файла: 1000:1000 (текущий пользователь: 1000:1000)

═══ Требование 7: тесты в сборке ═══
  тесты прошли

═══ Обёртка ═══
count   3
min     10
max     30
mean    20
median  20
  ─── в конвейере ───
mean    20

cd /tmp && docker rmi -f csvstat csvstat:test > /dev/null 2>&1; rm -rf /tmp/csvstat