Skip to content

09_QUALITY_TOOLING.md

Latest commit

 

History

History
122 lines (102 loc) · 3.45 KB

09_QUALITY_TOOLING.md

File metadata and controls

122 lines (102 loc) · 3.45 KB

09 - Quality and Tooling (From Script Writer to Team-Trusted Engineer)

Home: README

Who this is for

  • Learners who can code basics and now need reliability and repeatability.
  • Anyone preparing to share tools with teammates.

What you will build

  • A reusable Python project template.
  • A quality workflow: format, lint, test, run, release.
  • Operational logging and runbook standards.

Prerequisites

Step-by-step lab pack

Step 1 - Standard project skeleton

my_tool/
  pyproject.toml
  README.md
  requirements.txt
  src/
    my_tool/
      __init__.py
      main.py
      logic.py
      io_excel.py
      io_sql.py
      io_sw.py
  tests/
    test_logic.py

Step 2 - Configure pyproject.toml

Set standards for:

  • Ruff checks,
  • Black formatting,
  • pytest defaults.

Step 3 - Install and run tooling

python -m pip install ruff black pytest
ruff check .
black .
pytest -q

Step 4 - Logging baseline

  • structured run log per execution,
  • summary counts,
  • clear failure traces,
  • stable log path.

Step 5 - Runbook minimum

Every tool must include:

  • how to run,
  • required input format,
  • output locations,
  • failure handling,
  • support owner.

Step 6 - Quality gates before team release

Must pass before sharing:

  • linter clean,
  • format clean,
  • tests passing,
  • one end-to-end sample run,
  • README run instructions validated by another person.

Expected output

  • Repeatable project template ready for all capstones.
  • Consistent quality process for every script/tool.

Break/fix drills

  1. Introduce lint errors and fix them.
  2. Break a test and isolate regression quickly.
  3. Simulate missing input file and verify safe failure.

Troubleshooting

  • tooling conflicts:
    • centralize config in pyproject.toml.
  • flaky tests:
    • remove hidden dependencies on file order/time.
  • unreadable logs:
    • enforce stable message format and include run id.

Mastery check

Move forward when you can:

  • bootstrap a new project in under 30 minutes,
  • pass all quality gates,
  • hand project to another engineer who can run it.

Learning-style options (Play/Build/Dissect/Teach-back)

  • Play: intentionally violate style and quality rules, then recover.
  • Build: apply full template to a new mini-tool.
  • Dissect: compare two project structures and justify one.
  • Teach-back: explain why each quality gate prevents production pain.

Troubleshooting matrix (common failures)

Problem Likely cause First fix
ModuleNotFoundError wrong venv/interpreter activate .venv, reinstall package
ruff fails unused imports or style issues run ruff check . --fix then review
tests fail only on rerun hidden state in files/data isolate test data and clean temp outputs
logs missing logger not initialized early initialize logging before main workflow

Primary Sources

Optional Resources

Next

Next: concepts/errors-and-debugging.md →