Capstone: a Dependable Automation Tool

Scenario: Operations needs a tool that reads JSON config, validates it, checks commands, logs UTC results, and exits honestly.

New words, in plain English

• Capstone - a final project combining earlier skills
• Logging - structured runtime records for people and systems
• Idempotent - safe to repeat without unintended extra effects
• Dry run - show intended work without changing the target

Split the tool into parse, validate, plan, execute, and report functions. Use dataclasses or small classes for state, pathlib for paths, logging instead of scattered prints, exceptions at boundaries, tests for pure logic, and a main guard returning an exit code.

Analogy: A Python program is like a clear set of instructions for a careful helper: names label things, indentation groups steps, and errors explain where the helper became confused.

A small, real example

import logging, sys
from pathlib import Path

def main() -> int:
    logging.basicConfig(level=logging.INFO)
    config = Path("config.json")
    if not config.exists():
        logging.error("missing config: %s", config)
        return 2
    logging.info("validated %s", config)
    return 0

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

Tip: Make the safe path the easy path: validate before mutation, log decisions, and preserve evidence on failure.

Goal: Practice this idea in the py-subprocess-automation challenge at /labs/python. Fix the broken program, run it yourself, then use check to prove the real end state.