What's wrong
Downloading a bill fails with a raw Python traceback naming a third-party library, instead of a message saying what to do, when the terminal has not activated the project's environment. The comparison command in the same Quickstart handles the identical situation with a one-line explanation and the exact command to run.
tools/fetch_bills.py is step 2 of the README Quickstart, so it is the first command a new user runs after setup. It carries no environment guard:
Traceback (most recent call last):
File ".../tools/fetch_bills.py", line 18, in <module>
import httpx
ModuleNotFoundError: No module named 'httpx'
diff_bill.py, Quickstart step 3, carries one. It was added by #398 (ship the diff engine as an installable src/deltatrack package), which made these commands depend on an install:
diff_bill.py: DeltaTrack is not installed in this environment.
Run `source ./init` from the project folder first (it installs dependencies and activates the environment), then try again.
The rationale is written into diff_bill.py itself: without the guard, the un-activated case produces "a raw traceback whose top frame is an import line, which does not tell a non-technical user that the answer is one documented command." That reasoning applies to tools/fetch_bills.py unchanged, and with more force, because a user following the Quickstart in order meets it first.
How it surfaced
Running the README Quickstart commands in a shell that had not sourced ./init, as part of a review of the running instructions. Output quoted above is real, from ./tools/fetch_bills.py --help on develop at 97f91ba, macOS.
Why it matters
The Quickstart is written for a non-technical reader. Steps 2 and 3 fail for the same reason but report it in completely different registers: one names the fix, the other names a library the reader has never heard of and offers no next step. A reader who stops at step 2 never reaches the command that would have explained the problem.
What to do
Verification
A passing suite is not evidence here, since the suite runs inside an environment where the import succeeds. The fix has to be shown against a shell with no activation, for example env -u VIRTUAL_ENV PATH=/usr/bin:/bin ./tools/fetch_bills.py --help, confirming the output names an action the reader can take.
Refs #398, #315
What's wrong
Downloading a bill fails with a raw Python traceback naming a third-party library, instead of a message saying what to do, when the terminal has not activated the project's environment. The comparison command in the same Quickstart handles the identical situation with a one-line explanation and the exact command to run.
tools/fetch_bills.pyis step 2 of the README Quickstart, so it is the first command a new user runs after setup. It carries no environment guard:diff_bill.py, Quickstart step 3, carries one. It was added by #398 (ship the diff engine as an installablesrc/deltatrackpackage), which made these commands depend on an install:The rationale is written into
diff_bill.pyitself: without the guard, the un-activated case produces "a raw traceback whose top frame is an import line, which does not tell a non-technical user that the answer is one documented command." That reasoning applies totools/fetch_bills.pyunchanged, and with more force, because a user following the Quickstart in order meets it first.How it surfaced
Running the README Quickstart commands in a shell that had not sourced
./init, as part of a review of the running instructions. Output quoted above is real, from./tools/fetch_bills.py --helpondevelopat97f91ba, macOS.Why it matters
The Quickstart is written for a non-technical reader. Steps 2 and 3 fail for the same reason but report it in completely different registers: one names the fix, the other names a library the reader has never heard of and offers no next step. A reader who stops at step 2 never reaches the command that would have explained the problem.
What to do
tools/fetch_bills.pythe same guarddiff_bill.pyhas. Smallest change, consistent with the intent recorded in Give the diff engine its own package directory, so the product is a unit that can be installed #398. It puts a third copy of the guard in the tree.tools/do not currently share an import path for this, so it is not a free move.Verification
A passing suite is not evidence here, since the suite runs inside an environment where the import succeeds. The fix has to be shown against a shell with no activation, for example
env -u VIRTUAL_ENV PATH=/usr/bin:/bin ./tools/fetch_bills.py --help, confirming the output names an action the reader can take.Refs #398, #315