Esiste un modo per utilizzare doctest e sphinx per testare e documentare le applicazioni della riga di comando?

Question

Ho un modulo Python per il quale sto scrivendo un tutorial usando Sphinx inclusi doctest.

Questo modulo viene fornito con alcuni programmi di supporto.

Vorrei includere questi programmi di supporto nella documentazione e avere doctest controllare che l'output standard sia sincronizzato tra la versione corrente del programma e la documentazione.

Suppongo di poter utilizzare il modulo sh o popen per controllare lo standard output di un determinato programma, ma preferisco che questi trucchi non vengano visualizzati nei documenti, altrimenti gli utenti non programmatori verranno sicuramente persi.

C'è un modo per farlo?

Answer 1

Il modulo doctest controlla solo le istruzioni che possono essere eseguite dal prompt interattivo di Python.

strumenti a linea di comando possono essere richiamati dal prompt interattivo Python usando il modulo subprocess:

# Create Helper Function 
>>> import subprocess 
>>> run_commandline = lambda cmd: subprocess.check_output(cmd, shell=True).decode() 

# Doctestable command-line calls 
>>> print(run_commandline('cal 7 2017')) 
    July 2017 
Su Mo Tu We Th Fr Sa 
        1 
2 3 4 5 6 7 8 
9 10 11 12 13 14 15 
16 17 18 19 20 21 22 
23 24 25 26 27 28 29 
30 31 

>>> print(run_commandline('echo $BASH_VERSION')) 
3.2.57(1)-release 

Ci sono probabilmente alcuni modi per hackerare doctest o sfinge per ottenere ciò che si desidera in modo più diretto, ma questa tecnica usi le API pubblicizzate per doctest, sfinge e sottoprocesso esattamente nel modo in cui sono state progettate per essere utilizzate (doctest è progettato per riprodurre sessioni di prompt interattive trovate in docstrings e il sottoprocesso è progettato per eseguire strumenti da riga di comando direttamente da python e catturarne l'output).

suppongo di poter utilizzare il modulo sh, o popen per verificare lo standard uscita di un determinato programma, ma preferisco che questi trucchi non mostrano su nei documenti, altrimenti gli utenti non programmatori saranno certamente perso.

Due pensieri: in primo luogo, i dettagli di tali chiamate possono essere per lo più nascosti in una funzione di supporto per ridurre al minimo la distrazione. In secondo luogo, se hai bisogno di invocare programmi da riga di comando da Python, non è un trucco usare popen o sottoprocesso poiché questi sono gli strumenti progettati specificamente per fare quelle chiamate da Python.