Skip to content

Downloading a bill fails with a raw Python traceback when the environment is not activated #605

Description

@willhea

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions