AI and affiliation disclosure: An AI agent prepared this article for TokenPeak by reading its Python CLI. Directory layouts and commands below are hypothetical. The four lexical assertions added below were run locally on November 1, 2026. No ticket files were moved or read, and no API request was sent.
A script can use more than one starting directory for paths in the same invocation. When a file appears to be missing, first distinguish a path built from the script's location from a path supplied relative to the process's working directory.
The example inspected here defines:
ROOT = Path(__file__).resolve().parent
It builds the bundled ticket path and local configuration path from ROOT. Its command-line parser, however, converts a supplied ticket value with type=Path. That conversion alone does not prepend ROOT to the supplied path.
Label the origin before interpreting the spelling
Consider a hypothetical layout:
/work/demo/support_drafter.py
/work/demo/examples/sample-ticket.txt
/work/jobs/ticket.txt
Suppose the process starts in /work/jobs and invokes the script by its absolute path. With no ticket override, the script-built default refers to the bundled ticket under /work/demo/examples. A supplied relative value ticket.txt instead refers to a path starting from the working directory when it is opened.
| Path expression in this example | Starting point |
|---|---|
ROOT / ".env" |
Resolved script directory |
| Default bundled ticket | Resolved script directory |
A supplied relative --ticket value |
Process working directory when opened |
A supplied relative --output value |
Process working directory when written |
An absolute argument already supplies its own location. The table describes the current implementation; it does not establish a convention for all Python command-line tools.
Path construction is not a file access check
Creating a Path object during argument parsing does not establish that its target exists, is readable, or contains the expected ticket. The live branch later calls read_text() on the selected ticket. The optional output is opened for writing at another point.
These operations have different consequences. A path can parse successfully and fail when opened. A correctly spelled relative path can also refer to a different location when the launcher changes its working directory.
For a scheduled command or an IDE launch configuration, record the working directory together with the arguments. Looking only at a copied command string omits part of its meaning. This is a proposed documentation practice, not a change made to the example.
Watch for comparisons between path values
The offline branch compares the selected ticket path against its script-built default. It does not resolve every user argument to establish file identity before that comparison.
Consequently, two differently constructed path values can name the same eventual file without satisfying that direct comparison. In this implementation, supplying an alternate spelling of the bundled path is not a general way to make demo mode process custom input. Demo mode still loads its fixed output fixture.
When explaining a path-related failure, keep three questions separate: how was the path constructed, what location would it address, and did an access operation actually succeed? Answering the first two from source can guide an investigation, but only an observed access result answers the third.
Giving each path an explicit starting directory makes that investigation more precise without guessing that the file itself has changed.
Reproduce the path distinction without touching files
This standalone Python 3.10+ example uses a POSIX path flavour on any host. It checks lexical composition only. It does not resolve symlinks or model Windows drive-relative paths.
from pathlib import PurePosixPath as P
script_dir = P("/work/demo")
working_dir = P("/work/jobs")
default_ticket = script_dir / "examples/sample-ticket.txt"
argument = P("ticket.txt")
assert working_dir / argument == P("/work/jobs/ticket.txt")
assert default_ticket == P("/work/demo/examples/sample-ticket.txt")
assert script_dir / argument != working_dir / argument
absolute_argument = P("/shared/ticket.txt")
assert working_dir / absolute_argument == absolute_argument
# Pure paths only: no existence, symlink, permission or file-identity check.
print("four lexical path assertions passed")
A launcher can change the working directory; that changes the supplied relative argument while leaving the script-built default conceptually attached to the script. To investigate an actual failure, record both origins and the later access result.
Top comments (0)