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

Aperta
#195 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
42/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
python

Direzione di ricerca

Start with orfdata/cli.py and the orfdata/cli:run entry point, then compare the help behavior with mhcflurry/cli/help.py. Trace imports from orfdata/__init__, orfdata.proteome, and orfdata.viral while checking tab completion against the stated 100 ms budget. Done means console script completions include subcommands and flags, heavy modules stay unloaded during parser setup, and terminal help and tables follow the specified styling rules.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

This repo

Read and measured at f2e8aa6.

  • Console script: orfdata (orfdata.cli:run), with subcommands registered in a loop (orfdata/cli.py:113-115).
  • Tab cost now: 492 ms. It loads pandas, numpy and pyarrow through orfdata/__init__; orfdata.proteome (297 ms) and orfdata.viral (290 ms) are the largest parts.

Work here:

  • argcomplete dependency, plus the marker and autocomplete() in orfdata/cli.py.
  • A lazy orfdata/__init__ and an import-light parser module.
  • 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

Lingua principale
Python
Stelle
1
Fork
1
Merge medio
10h 11m
PR unite (30g)
51

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di openvax/orfdata

Tutte le issue di openvax/orfdata

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.