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

Abierto
#195 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
42/100
Tipo de issue
Nueva funcionalidad
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
python

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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

Lenguaje dominante
Python
Estrellas
1
Forks
1
Merge medio
10 h 11 min
PR fusionados (30 d)
51

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de openvax/orfdata

Todos los issues de openvax/orfdata

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.