api-pattern-python

API pattern — Python

Consistency is the point: the same kind of work looks the same everywhere, so the reviewer and the next agent read it without re-learning. You do not invent structure — you locate the codebase's canonical example and replicate it. The depth is in .claude/rules/project-structure.md.

Procedure

1. Find the canonical example. If the spec names one under "Reuse this pattern," read it. Otherwise Grep for the nearest sibling of the same shape and pick the most recent, most-tested one — not the oldest. Useful anchors:

   • the package's public surface: src/*/__init__.py (what the codebase chooses to export)
   • a CLI command: Grep for argparse, add_parser(, @click.command, or @app.command
   • a loader/parser of the same input kind: Grep for yaml.safe_load, json.load, Path(
   • the project's exception base: Grep for class .*Error\( / Exception\)
   • the entry-point wiring: [project.scripts] in pyproject.toml

2. Extract the pattern, don't paraphrase it. Note, from the example:

   • Layering — CLI/entry point (parses args, prints, sets the exit code) → service function (pure logic, returns values, raises domain errors) → I/O or client. Human output lives at the CLI layer only; the layer below it logs and returns.
   • The signature — fully annotated params and return. What typed object it returns (dataclass / TypedDict / model), not a raw dict[str, Any].
   • Validation — where external input is parsed into that typed object, at the boundary, once.
   • Error model — which domain exception it raises and from which base; what it deliberately does not catch. Confirm it never swallows (except: pass) and never bare-excepts.
   • Logging — logging.getLogger(__name__), structured, on failure paths.
   • Naming and placement — snake_case module under the right package, one concern per module.
   • The test shape — tests/test_<module>.py, test_scenario_expected_result names, fixtures (tmp_path, monkeypatch) over setup methods, @pytest.mark.parametrize for variant cases.