Overview

$ python3 -m venv .venv
$ .venv/bin/pip install pytest
[... pip install output ...]
$ .venv/bin/pip show pytest
Name: pytest
Version: 9.1.1
...

"""Capstone: pure transform functions -- validate and summarize inventory records.
 
No file I/O and no argparse here on purpose: every function in this module is pure,
which is exactly what makes it trivially unit-testable in tests/test_transform.py
without touching a filesystem or a CLI.
"""
 
from __future__ import annotations
 
from typing import TypedDict
 
 
class InvalidRecordError(Exception):
    """Raised when an inventory record fails validation."""
 
 
class InventoryRecord(TypedDict):
    """One row of the input JSON: an item name, its count, and its unit price."""
 
    name: str
    quantity: int
    price: float
 
 
class SummaryRecord(TypedDict):
    """One row of the output JSON: the item name plus its computed total value."""
 
    name: str
    quantity: int
    total_value: float
 
 
def validate_records(records: list[InventoryRecord]) -> list[InventoryRecord]:
    """Reject any record with a negative quantity or price.
 
    Raising a custom, named exception (rather than a bare ValueError) lets the CLI
    layer catch exactly this failure mode and print a clean message instead of a
    raw traceback -- the same distinction Example 65 draws in the learning track.
    """
    for record in records:  # => a plain for loop -- fails fast on the FIRST bad record
        if record["quantity"] < 0:
            raise InvalidRecordError(f"{record['name']!r} has a negative quantity")
        if record["price"] < 0:
            raise InvalidRecordError(f"{record['name']!r} has a negative price")
    return records  # => unchanged -- this function validates, it never mutates
 
 
def summarize(records: list[InventoryRecord]) -> list[SummaryRecord]:
    """Compute each record's total value (quantity * price) via a comprehension."""
    return [
        {
            "name": record["name"],
            "quantity": record["quantity"],
            "total_value": round(record["quantity"] * record["price"], 2),
            # => round(..., 2) keeps prices display-friendly -- Example 6's float lesson, applied
        }
        for record in records  # => one comprehension replaces a build-up loop (Example 29's pattern)
    ]
 
 
def grand_total(summary: list[SummaryRecord]) -> float:
    """Sum every summary row's total_value -- a generator expression, not a loop."""
    return round(sum(row["total_value"] for row in summary), 2)
    # => sum(... for ...) is Example 33's generator-expression pattern, not a materialized list

"""Capstone: pytest coverage for the pure functions in app.transform."""
 
import pytest
 
from app.transform import (
    InvalidRecordError,
    InventoryRecord,
    SummaryRecord,
    grand_total,
    summarize,
    validate_records,
)
 
 
def test_validate_records_accepts_clean_data() -> None:
    records: list[InventoryRecord] = [{"name": "widget", "quantity": 2, "price": 5.0}]
    assert validate_records(records) == records
 
 
def test_validate_records_rejects_negative_quantity() -> None:
    records: list[InventoryRecord] = [{"name": "widget", "quantity": -1, "price": 5.0}]
    with pytest.raises(InvalidRecordError):
        validate_records(records)
 
 
def test_summarize_computes_total_value() -> None:
    records: list[InventoryRecord] = [{"name": "widget", "quantity": 3, "price": 2.5}]
    assert summarize(records) == [{"name": "widget", "quantity": 3, "total_value": 7.5}]
 
 
def test_grand_total_sums_every_row() -> None:
    summary: list[SummaryRecord] = [
        {"name": "widget", "quantity": 3, "total_value": 7.5},
        {"name": "gadget", "quantity": 1, "total_value": 12.0},
    ]
    assert grand_total(summary) == 19.5

$ .venv/bin/pytest -q
....                                                                     [100%]
4 passed in 0.01s

"""Capstone: app package -- a small inventory-summarizer CLI."""

"""Capstone: app.__main__ -- the argparse CLI entry point (`python3 -m app`).
 
Reads an inventory JSON file, validates and summarizes it via app.transform, then
writes and prints the resulting summary JSON. A validation failure is caught here
and reported as a clean one-line message with a non-zero exit code, never a raw
traceback -- the CLI's whole job is translating transform.py's exceptions into
something a terminal user can act on.
"""
 
from __future__ import annotations
 
import argparse
import json
import sys
from pathlib import Path
 
# A cross-module import within the SAME package (Example 64's shape).
from app.transform import (
    InvalidRecordError,
    InventoryRecord,
    grand_total,
    summarize,
    validate_records,
)
 
 
def main() -> None:
    parser = argparse.ArgumentParser(
        description="Summarize an inventory JSON file's total value per item."
    )
    parser.add_argument("input", type=str, help="path to the input inventory JSON file")
    parser.add_argument("output", type=str, help="path to write the summary JSON file")
    # Example 61's argparse pattern, with two positionals instead of one.
    args = parser.parse_args()
 
    input_path = Path(args.input)
    output_path = Path(args.output)
 
    # `with` guarantees the file closes (Example 52's pattern).
    with input_path.open() as f:
        # Example 58's json.load pattern -- reads the whole file as one JSON value.
        records: list[InventoryRecord] = json.load(f)
 
    try:
        validate_records(records)
    except InvalidRecordError as err:
        # Example 65's custom-exception-class pattern: a clean message, not a raw traceback.
        print(f"invalid inventory data: {err}", file=sys.stderr)
        sys.exit(1)  # a distinct, deliberate non-zero exit code for bad input
 
    summary = summarize(records)
    payload = {"items": summary, "grand_total": grand_total(summary)}
 
    with output_path.open("w") as f:
        json.dump(payload, f)  # Example 57's json.dump-to-file pattern
 
    # Echoes the same payload to stdout for the caller to see.
    print(json.dumps(payload))
 
 
# Example 46's guard -- app.__main__ only runs main() when invoked directly
# (e.g. via `python3 -m app`), never when merely imported.
if __name__ == "__main__":
    main()

$ .venv/bin/pytest -q
....                                                                     [100%]
4 passed in 0.01s

[
  { "name": "widget", "quantity": 3, "price": 2.5 },
  { "name": "gadget", "quantity": 1, "price": 12.0 }
]

{"items": [{"name": "widget", "quantity": 3, "total_value": 7.5}, {"name": "gadget", "quantity": 1, "total_value": 12.0}], "grand_total": 19.5}

[{ "name": "widget", "quantity": -1, "price": 2.5 }]

invalid inventory data: 'widget' has a negative quantity