Skip to content

Python Plugin Mechanics¤

This exec's the block within the current python process.

  • Namespace is globals()
  • All LP context available in the ctx dicts

Output via

  • print: what is printed on stdout (embedded in fenced code, language python, pformatted if not a plain string)
  • show(): Interpreted as markdown, with rendering support supplied by python plugins.

Decide via the language argument (```<language> lp mode=python) what formatting should be applied for fenced output.

Features¤

Session Support¤

LP Source:

 ```python lp mode=python addsrc new_session=pyexample
 # fmt not given - then we open and close fenced blocks, based on output mode (print vs show)
 keys = [k for k in ctx.keys()]
 print('variable `keys` assigned')
 show('*The variable is now in session "pyexample"*.')
 ```

Result:

variable `keys` assigned

The variable is now in session "pyexample".

We can refer to the variable later:

LP Source:

 ```python lp mode=python addsrc session=pyexample fmt=mk_console
 # fmt given explicitely - then we show code and result all in one fenced block:
 print(keys)
 ```

Result:

# fmt given explicitely - then we show code and result all in one fenced block:
print(keys)


['DOCU_FILE',
 'DOCU_DIR',
 'DOCU_ROOT',
 'PROJECT_ROOT',
 'mode',
 'addsrc',
 'LP',
 'lang',
 'sourceblock',
 'timeout',
 'fetched_block_fmt',
 'fn_doc',
 'session_name',
 'fmt',
 'id']

Rendering Plugins¤

  • The rendering of arguments of the show function is based on value and type of the argument.

  • Plugins register match keys and rendering functions, which when key is matching, will render the argument of show

  • Alternatively if the "key" is a callable, it will be called with the object to be shown and can decide if returns True - then it's value, the actual rendering function will be called (see e.g. datatables python plugin).
  • You can provide your own python plugins, provided you supply an importable module lp_python_plugins, which, at it's __init__.py, imports all your plugins.

Important

LP python plugins are not lazily imported. Avoid side effects and expensive code at import time (which you should anyway, always).

Rendering Plugin Interface¤

A plugin must provide a register(fmts) function, where fmts is a dict of match keys pointing to plugin specific rendering functions.

See the matplotlib renderer.

Tips¤

Adding Post Page Hooks¤

Some python plugins want to do sth after the html was rendered.

Say we require in a show handler being called back after the html was created, in order to insert js or embed svgs (...):

from lcdoc.mkdocs.tools import add_post_page_func
add_post_page_func(python.Session.kw, embed_svgs, once=True)

The LP plugin registers an on_post_page hook, where it checks all such registered functions and calls them in insertion order, with parameters output, page, config.

Tip

Register a partial if you need more infos from during the show function call time. The hook may return modified html as a string.

See the callflow python plugin for details.