Build interfaces · Lesson 02
Read Requests with doctor, scan and inspect
The video uses Requests, not a newly written pricing function. It asks three separate questions: is the local setup prepared, what source exists, and which contracts can this interface generator support?
By the end of this lesson
- Use doctor, scan and inspect for their distinct purposes.
- Read a readiness state with its concrete reason.
- Explain why selecting Requests.get does not remove its variadic signature.
Watch the lesson
English · 4:11 · Recorded with Apizr 0.4.3.
Chapters in this recording
| Time | Chapter |
|---|---|
| 00:00 | Read your code before exposing it. |
| 00:17 | Three commands. Three different questions. |
| 00:36 | Start from a known repository revision. |
| 01:03 | Initialize the project, then read the configuration. |
| 01:31 | Check preparation with doctor. |
| 01:57 | Inventory the source, then read the summary. |
| 02:30 | Read the state, then read the reason. |
| 02:55 | Why Requests.get is not a fixed interface. |
| 03:26 | Selection does not bypass readiness. |
| 03:52 | Next: turn a ready function into an API. |
Read the recording transcript and commands
This is the retained English narration, in the original chapter order. Commands keep the recorded version and prerequisites; setup additions in the lesson are labelled separately.
00:00 — Read your code before exposing it.
Apizr is installed. Now let us understand what it can see in a real Python project. We will use Requests to separate three questions: is the setup correct, what code exists, and which functions have a supported interface contract?
00:17 — Three commands. Three different questions.
Doctor checks the local setup. Scan inventories a repository. Inspect focuses on one source file and explains its interface contract. These analysis steps do not run the target project. A successful setup check does not mean every function can become an endpoint.
00:36 — Start from a known repository revision.
Clone the Requests release shown here and enter the checkout. The release tag and commit identify the exact source we are studying. Requests keeps its Python package under the source directory. We will scope the analysis to that directory instead of scanning examples and tests.
git clone --depth 1 --branch v2.32.5 https://github.com/psf/requests.git
cd requests
git rev-parse --short HEAD
ls src/requests
01:03 — Initialize the project, then read the configuration.
Initialize Apizr with source as the source root. This writes the project configuration and policy files. Open the configuration to see the selected root. Initialization does not choose public functions. Its local operator policy grants source analysis for this exact checkout path, so moving the project requires reviewing that grant.
apizr init . --source-root src
cat apizr.toml
ls .apizr/policies
01:31 — Check preparation with doctor.
Pass the project file and operator policy explicitly to doctor. It checks Python, Apizr, the source directories and the policies. The warning about an empty selection is expected: we have not selected any functions. Doctor confirms this preparation without scanning the source or repairing anything automatically.
apizr doctor --project apizr.toml --operator-policy .apizr/operator.json
01:57 — Inventory the source, then read the summary.
Scan the checkout with the same source root and the explicit analysis policy. Save the report so we can read its summary. In this revision, eighteen source files are inspected, with sixty four capabilities and seventy five assessments. The categories include conditional and unsupported results. This is evidence to review, not a list of functions to publish automatically.
Expected refusal: exit 1.
apizr scan . --source-root src --operator-policy .apizr/operator.json > scan.txt
echo $?
sed -n '1,13p' scan.txt
02:30 — Read the state, then read the reason.
Ready means the static evidence supports an interface contract. Conditional means some questions remain unresolved. Unsupported means this contract does not support the pattern. Ambiguous means the analysis cannot identify one coherent callable. These states describe interface evidence; they do not certify that executing the code is safe.
02:55 — Why Requests.get is not a fixed interface.
Look at the get function. It accepts arbitrary keyword arguments. Now inspect this file and read the assessment for get. Apizr reports unsupported, with a reason code for variadic input. Requests is a useful library; this particular signature does not define the fixed input contract that this generator requires.
sed -n '62,73p' src/requests/api.py
Expected refusal: exit 1.
apizr inspect src/requests/api.py > inspection.txt
sed -n '15,21p' inspection.txt
03:26 — Selection does not bypass readiness.
Selecting only get does not change its signature. Let us try generation and read the refusal. No bundle is created. The useful next step is to design a deliberate, supported function boundary and inspect it. Avoid changing dependencies or reinstalling the tool to solve a source contract problem.
Expected refusal: exit 1.
apizr generate rest src/requests/api.py --select get --output-dir rejected
test ! -e rejected && printf 'No bundle created\n'
03:52 — Next: turn a ready function into an API.
You can now verify the setup, locate the source, and explain an inspection result. In the next episode, we will use a different repository, select ready functions, generate a REST application, and make real HTTP calls.
1. Pin Requests and prepare its source root
The recorded checkout is psf/requests at v2.32.5, analysed with Apizr 0.4.3. Follow it in a fresh directory:
git clone --depth 1 --branch v2.32.5 https://github.com/psf/requests.git
cd requests
apizr init . --source-root src
cat apizr.toml
apizr doctor --project apizr.toml --operator-policy .apizr/operator.json
init writes configuration and a local analysis grant. It does not select public capabilities. Doctor's empty-selection warning is expected at this point. It checks preparation without scanning or repairing the project automatically.
2. Inventory, then explain one refusal
apizr scan . --source-root src --operator-policy .apizr/operator.json > scan.txt
apizr inspect src/requests/api.py > inspection.txt
These recorded analyses return diagnostics and may exit nonzero; read their saved reports. The recording's summary contains 18 source files, 64 capabilities and 75 assessments. Those are observations of this revision and tool version, not fixed counts for all Requests releases.
requests.get accepts arbitrary keyword arguments. The report marks its contract unsupported with a variadic-input reason. Ready, conditional, unsupported and ambiguous describe interface evidence; none certifies that execution is safe.
The next recorded command deliberately tests whether selection can bypass that finding:
apizr generate rest src/requests/api.py --select get --output-dir rejected
It is refused and creates no bundle. A deliberate fixed-contract wrapper would be a separate design exercise, not something demonstrated in this video.
Practice
Read get in src/requests/api.py, find its readiness reason, and explain the expected generation refusal. Identify which of doctor, scan and inspect answers each of these questions: valid setup, repository contents, and the contract of this file.
Check your reasoning
Doctor checks setup, scan inventories the selected source root, and inspect explains the file's supported contracts. Selecting get narrows the selection but leaves **kwargs unchanged. The useful next action is to design and review a supported boundary, rather than reinstalling Apizr or treating all discovered functions as public endpoints.