cli_args.py is intentionally standard-library-only. The same preference should apply one level above it: before installing another CLI or Python package, check whether the Python runtime already provides the operation.
For AI coding and CI, use this order as a default:
- Python standard library /
python -m/ smallpython -cwhen it already expresses the task. - Existing host CLI such as Git, curl, Node/npm, Docker, FFmpeg when that tool owns the capability.
- Pinned Docker/test environment or an added dependency when the operation genuinely needs one.
This is a preference, not a ban on external tools. Do not contort a stdlib command into a job it does not model well.
AI coding makes one-off shell commands much more frequent. Reinstalling tools for capabilities that ship with Python increases bootstrap time, platform drift, network dependence, and the number of things an agent can accidentally mutate.
The standard library is therefore a third command surface alongside the OS CLI and project-specific tools.
cli_args.py does not wrap or rename these modules. Use their real module names so provenance, Python-version behavior, and upstream documentation stay visible.
When a non-Python host (for example Node) must drive run_command / render_output without importing the module, call python -S /path/to/cli_args.py run or render with a JSON payload on stdin. That path uses the same contracts as the library API and stays stdlib-only under python -S.
These examples are useful building blocks for this repository's supported Python floor.
| Need | Standard-library command |
|---|---|
| validate / pretty-print JSON | python -m json.tool --sort-keys input.json |
| create / list / extract / test ZIP | python -m zipfile -c out.zip a.txt b.txt |
| create / list / extract TAR | python -m tarfile -c out.tar a.txt b.txt |
| serve a directory locally | python -m http.server 8000 --bind 127.0.0.1 --directory DIR |
| show platform information | python -m platform |
| syntax-check a tree | python -m compileall -q src/ |
| run unittest discovery | python -m unittest discover -v |
| run doctests | python -m doctest module.py -v |
| benchmark a snippet | python -m timeit "sum(range(100))" |
| profile a script | python -m cProfile -s cumtime script.py |
| create a virtual environment | python -m venv .venv |
| package a runnable directory | python -m zipapp app_dir -o app.pyz |
Some standard-library CLIs are version-specific. For example, the sqlite3 CLI and useful uuid command surface are available only on newer Python versions. Do not advertise a module command at the repository's Python 3.11 floor unless CI has measured it there.
The library surface is equally valuable even when the module is not a useful standalone CLI.
Examples:
# fresh scratch directory outside the checkout
python -c "import tempfile; print(tempfile.mkdtemp())"
# SHA-256 without installing a checksum package
python -c "import hashlib,sys; [print(hashlib.sha256(open(f,'rb').read()).hexdigest(), f) for f in sys.argv[1:]]" FILE
# inspect JSON with pprint
python -c "import json,pprint,sys; pprint.pp(json.load(open(sys.argv[1])))" FILE
# check whether localhost:8000 can be bound
python -c "import socket; s=socket.socket(); s.bind(('127.0.0.1',8000)); print(True)"For longer or reused logic, import the module normally instead of growing an opaque shell one-liner.
tests/test_stdlib_surfaces.py (python -m commands) executes a representative subset rather than only documenting it:
json.toolperforms a real JSON transformation.zipfilecreates and lists a real archive.tarfilecreates and lists a real archive.http.serverstarts a real localhost-only server and serves a temporary file.platformruns as a real module CLI.compileallcompiles a temporary Python source tree.tempfileis exercised through the standard Python API /python -cstyle boundary.
The Windows and macOS portability lanes also run this stdlib-command suite so these examples are not Linux-only documentation.
The fuller cross-repository cookbook originated in browser-test-kit/docs/python-m.md. This repository keeps a smaller, contract-focused subset because its purpose is argv/execution infrastructure rather than a general Python cheat sheet.
When a downstream repository repeatedly installs a tool for something already covered by a measured stdlib command, prefer documenting or reusing the stdlib route before creating another wrapper.
When an external tool has the stronger domain contract—Git, Docker, Playwright, FFmpeg, Flutter, gh, etc.—use that real tool instead of imitating it with Python.
The stdlib command itself may be portable while its terminal encoding is not. On the GitHub Windows runner, python -m zipfile -l with a Japanese filename failed under the default cp1252 stdout encoding, and tarfile -l escaped the same name. The command works when Python stdout is explicitly UTF-8:
$env:PYTHONIOENCODING = "utf-8"
python -m zipfile -l bundle.zip
python -m tarfile -l bundle.tarThe repository's tests set PYTHONIOENCODING=utf-8 only for these subprocesses while preserving the rest of the environment. This is an evidence-layer portability setting, not a dependency and not a change to cli_args.py.
Likewise, text files created with platform-default newline translation can differ before http.server ever sees them. The HTTP server fixture writes explicit bytes so the test measures the server rather than Path.write_text newline policy.
The macOS GitHub runner exposed an important evidence boundary: a spawned python -m http.server --bind 127.0.0.1 process remained alive, but a second process could not reliably complete a localhost client connection. Replacing one client library with another did not change that result.
The cross-platform contract therefore measures that the real http.server CLI starts with an ephemeral port, binds to 127.0.0.1, and enters its serving loop without exiting. It does not make runner-local networking a requirement of the stdlib command itself. Linux host tests elsewhere in the repository already exercise real local HTTP request/response behavior.
External HTTP/network access is not required.