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']

Plugins

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

The show function

• 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 e.g. the matplotlib renderer.

Syntax

Normal form:

# in an lp:python block
show(<plugin match>, **plugin kws)

Short form, w/o kws:

`lp:python show=<plugin match>`

Ultrashort form, with kws:

`lp:python:<match> plugin_kw1=val1 plugin_kw2=val2`

Example

`lp:python:convert pdf=img/sample.pdf width=200 addsrc`

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.