runpython#

Description#

Location: RunPythonDirective.

In conf.py:

extensions = [ ...
    'sphinx_runpython.runpython.sphinxext_runpython_extension']

Documentation means many examples which needs to be updated when a change happen unless the documentation runs the example itself and update its output. That’s what this directive does. It adds as raw text whatever comes out throught the standard output.

<<<

import os
for i, name in enumerate(os.listdir(".")):
    print(i, name)

>>>

    0 sphinx_runpython
    1 .git
    2 setup.cfg
    3 .gitignore
    4 MANIFEST.in
    5 pyproject.toml
    6 requirements-dev.txt
    7 dist
    8 README.rst
    9 LICENSE
    10 requirements.txt
    11 CHANGELOGS.rst
    12 _doc
    13 _unittests
    14 setup.py
    15 azure-pipelines.yml
    16 .github

The output can also be compiled as RST format and the code can be hidden. It is useful if the documentation is a copy/paste of some external process or function. This function can be directly called from the documentation. The output must be converted into RST format. It is then added to the documentation. It is quite useful to display the version of some installed modules.

  • file 0: sphinx_runpython

  • file 1: .git

  • file 2: setup.cfg

  • file 3: .gitignore

  • file 4: MANIFEST.in

  • file 5: pyproject.toml

  • file 6: requirements-dev.txt

  • file 7: dist

  • file 8: README.rst

  • file 9: LICENSE

  • file 10: requirements.txt

  • file 11: CHANGELOGS.rst

  • file 12: _doc

  • file 13: _unittests

  • file 14: setup.py

  • file 15: azure-pipelines.yml

  • file 16: .github

If the code throws an exception (except a syntax error), it can be caught by adding the option :exception:. The directive displays the traceback.

<<<

import os
for i, name in enumerate(os.listdir("not existing")):
    pass

>>>

    
    [runpythonerror]
    
    Traceback (most recent call last):
        exec(obj, globs, loc)
      File "", line 6, in <module>
      File "", line 4, in run_python_script_140353119102272
    FileNotFoundError: [Errno 2] No such file or directory: 'not existing'

The directive can also be used to display images with a tweak however. It consists in writing rst code. The variable __WD__ indicates the local directory.

<<<

print('__WD__=%r' % __WD__)

>>>

    __WD__='/home/runner/work/sphinx-runpython/sphinx-runpython/_doc/api'

Applied to images…

The image needs to be save in the same folder than the rst file.

api/oo.png\n:width:201px

Option :toggle: can hide the code or the output or both but let the user unhide it by clicking on a button.

<<<

for i in range(0, 10):
    print("i=", i)

The last option of runpython allows the user to keep some context from one execution to the next one.

<<<

a_to_keep = 5
print("a_to_keep", "=", a_to_keep)

>>>

    a_to_keep = 5

<<<

a_to_keep += 5
print("a_to_keep", "=", a_to_keep)

>>>

    a_to_keep = 10

sphinx-autorun offers a similar service except it cannot produce compile :epkg:`RST` content, hide the source and a couple of other options.

Interesting functions#

sphinx_runpython.runpython.run_cmd(cmd, sin='', shell=False, wait=False, log_error=True, stop_running_if=None, encerror='ignore', encoding='utf8', change_path=None, communicate=True, preprocess=True, timeout=None, catch_exit=False, logf=None, tell_if_no_output=None, prefix_log=None)[source]#

Runs a command line and wait for the result.

Parameters:

  • cmd – command line

  • sin – sin: what must be written on the standard input

  • shell – if True, cmd is a shell command (and no command window is opened)

  • wait – call proc.wait

  • log_error – if log_error, call logf (error)

  • stop_running_if – the function stops waiting if some condition is fulfilled. The function received the last line from the logs. Signature: stop_waiting_if(last_out, last_err) -> bool. The function must return True to stop waiting. This function can also be used to intercept the standard output and the standard error while running.

  • encerror – encoding errors (ignore by default) while converting the output into a string

  • encoding – encoding of the output

  • change_path – change the current path if not None (put it back after the execution)

  • communicate – use method communicate which is supposed to be safer, parameter wait must be True

  • preprocess – preprocess the command line if necessary (not available on Windows) (False to disable that option)

  • timeout – when data is sent to stdin (sin), a timeout is needed to avoid waiting for ever (timeout is in seconds)

  • catch_exit – catch SystemExit exception

  • logf – logging function (if not None, bypass others parameters)

  • tell_if_no_output – tells if there is no output every tell_if_no_output seconds

  • prefix_log – add a prefix to a line before printing it

Returns:

content of stdout, stdres (only if wait is True)

from sphinx_runpython.runpython import run_cmd
out, err = run_cmd("python setup.py install", wait=True)

If you are using this function to run :epkg:`git` function, parameter shell must be True. The function catches SystemExit exception. See Constantly print Subprocess output while process is running. If wait is False, the function returns the started process. __exit__ should be called if wait if False. Parameter prefix_log was added.