Tab completion (argcomplete) and the shared subtle help colors for the varcode command line

Open
  • Is something wrong?
#697 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
cli, developer-experience

Research direction

Start with varcode.cli.main and varcode.cli.genes_script, then read the parser changes in #683 and the reference mhcflurry/cli/help.py. Check the project’s dependency and README files, and compare import costs for both console scripts. Done means both scripts complete flags, build their parsers without heavy imports, and share the specified terminal-only help styling; the issue also calls for subprocess completion and import tests.

Written by the indexing model from the issue text.

Description

This repo

Read and measured at 56e681e.

  • Console scripts: varcode (varcode.cli.main:main) and varcode-genes (varcode.cli.genes_script:main).
  • Tab cost now: 662 ms (varcode) and 503 ms (varcode-genes). Both load pandas, numpy and pyarrow, mostly through varcode/__init__; varcode.annotators alone is 393 ms.
  • The CLI's subcommand structure is being reworked in #683. Do this on top of #683's parser once it lands, rather than on the current one.

Work here:

  • argcomplete dependency, plus the marker and autocomplete() in both entry modules.
  • Make the parser module import-light: a lazy varcode/__init__ (PEP 562 __getattr__ for its re-exports), with heavy imports moved into the command functions.
  • Use the shared help parser.

How the numbers were measured: wall time of python -c 'import argcomplete, <entry module>', median of 5 runs. This repo's default branch was installed in a fresh Python 3.12 venv (pandas 3.1.0, Apple silicon) with a populated pyensembl cache. One Tab press costs about this, plus roughly 1 ms to build the parser. The floor, import argcomplete, argparse alone, is 40 ms.

Goal

Give every OpenVax command-line tool the same tab completion and the same subtle help styling, so they behave like one toolkit. The same issue is filed in each repo that ships a console script: openvax/pyensembl#514, openvax/varcode#697, openvax/isovar#684, openvax/varlens#54, openvax/orfdata#195, openvax/mhctools#636, openvax/mhcflurry#514, openvax/topiary#588, openvax/vaxrank#794, pirl-unc/mhcgnomes#237, pirl-unc/mhcseqs#104.

Tab completion: argcomplete

  • Add argcomplete>=3 as a runtime dependency. It has no dependencies of its own. topiary already uses it.
  • In every console-script entry module, put the marker comment # PYTHON_ARGCOMPLETE_OK within the first 1024 bytes. Global activation only completes scripts that carry it.
  • Call argcomplete.autocomplete(parser) immediately before parse_args().
  • Keep it fast. Every Tab press re-runs the program up to the autocomplete() call, so building the parser must not import heavy modules.
    • Budget: 100 ms per Tab. Python start-up plus argcomplete plus a 600-option parser measures 44 ms (Python 3.12, Apple silicon), and building a real parser takes about 1 ms. Anything above the floor is imports.
    • Build the parser in a module that imports only argparse and constants. Import the package's heavy parts inside the functions that run commands.
  • Subcommands. If subcommands are dispatched lazily, then while completing ("_ARGCOMPLETE" in os.environ) import only the chosen subcommand's module and attach its parser, so its flags complete.
  • Dynamic values. Complete them only where cheap and local, for example installed Ensembl releases or species names. Never touch the network.
  • Docs. In the README's "Command line" section, say how to turn it on: activate-global-python-argcomplete once (covers every OpenVax tool), or eval "$(register-python-argcomplete <tool>)" per tool.
  • Tests:
    1. Run each console script with _ARGCOMPLETE=1, COMP_LINE, COMP_POINT and _ARGCOMPLETE_STDOUT_FILENAME set, and check that the expected subcommands and flags come back.
    2. In a subprocess, import the parser module and assert that none of the heavy modules (pandas, numpy, torch, pysam, …) are in sys.modules.

Help styling: one hue, mostly plain

Reference implementation: mhcflurry/cli/help.py (color_enabled, style_help, HelpFormatter, HelpArgumentParser).

  • One hue. Use ANSI cyan at normal intensity (\033[36m), so the terminal's own palette picks the shade and it suits light and dark themes. No bright colors (codes 90–97), no backgrounds, no second hue.

  • What gets styled:

    • option flags (--release, -o) in cyan;
    • section headings in bold cyan;
    • usage: in bold.

    Everything else stays plain: descriptions, help text, metavars and defaults.

  • When. Style only when writing to a terminal (isatty()), and never when NO_COLOR is set or TERM=dumb.

  • format_help() stays plain text, because docs generation and tests read it. Apply styling only when printing.

  • Python 3.14+: pass color=False to ArgumentParser. Its built-in theme uses five hues (blue, magenta, cyan, green, yellow), mostly bold; turning it off makes every supported Python version look the same.

  • Tables that commands print (installed genomes, downloads and so on): bold cyan header row. Status values may use dim (\033[2m) for "absent / not applicable" and yellow (\033[33m) for warnings only. Normal values, including "OK", stay plain: no green, no red. Same enable rules.

Where the code lives

Use the same helper code as mhcflurry/cli/help.py, with identical colors and rules. If a shared package is created for these helpers, use it instead of a copy.

https://claude.ai/code/session_01JHJhwj29oDqoeu7TYd34Pi

Dominant language
Python
Stars
88
Forks
28
Avg merge
4h 34m
Merged PRs (30d)
52

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from openvax/varcode

All issues in openvax/varcode

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.