qitangle 0.4.0

QiTangle - IPython magic to tangle (quarto) specified code cells into python source files

QiTangle - IPython magic to entangle code from notebooks.

export code from notebook cells to python source files

The first Quatro document I created was used to implement a python module based on some math formula’s from an article (about measuring sap flux in tree stems) LaTeX formated formula’s. Step by step functions were build and documented along the formula’s and some example calculations. This worked like a charm but the disadvantage was that I had to copy the code from the document into a separate python file for use in our runtime environment. It worked fine but the disadvantage to this approach is that changes in one document had to be manually copied and paste into another. Such an arrangement will inevitably lead to errors.

What I needed was a way to convert or export selected code cells into a python source code file automatically and I found this in NBDev. Using it worked fine for a while, NBDev exports your code, builds the documentation and, if desired, packages the code uploads them to PyPi. I build packages with it that I relied on. But it is pretty big, requires projects to be laid out in a certain way and occasionally the PyPi packaging fails.

So, something smaller, without the PyPi packaging, was needed and I might as well look back at the original need of simply extracting or exporting python sourcefiles from Quarto and Jupyter documents.

Install

pip install qitangle

Usage

Loading the extension

import qitangle
%reload_ext qitangle.entangle

With %reload_ext we prevent errors when rerunning this cell, something that is likely to happen in a notebook.

Entangling

Entangling is the process of exporting the individual code cells to a file in the order as specified by the cell-specification and dependencies parameters.

Each entangle invocation adds a cell to a collection, the label and dependencies determine which cells depend on which and thus ultimately the order in which they are exporting by ensuring (if possible) that the dependencies are exported before the code cell.

With --export all cells in the collection are entangled and exported in this order.

Optionally each cell can be reformated through autopep8 with --fix. When combined with --export, this will reformat the entire produced file using Black.

%%entangle

It takes the following options:

• -e, --export: Export all cells in the collection
• -f, --fix: Fix/reFormat code with autopep8

And required arguments:

• cell-specification: The modulepath and label for the code cell (required)
• dependencies: The labels of dependencies for the code cell (optional)

The format of the cell-specification and dependencies is:

cell-specifiaction = module-path SEMICOLON cell-label
cell-label = name
dependencies = name *(SPACE name)
module-path = name *(DOT name)
name = 1*TEXTDATA

A module-path looks pretty much the same as in a python import statement, the cell-label is a name for the cell within the collection of cells - or python file - specified by the module-path and the dependencies are the labels of other cells within the specified collection upon which this cell depends and which are exported before this cell, if possible.

View documentation

You can view the documentation local with (and a local .venv active)

quarto preview docs/index.qmd

Or (with a local .venv active)

quarto render docs

from docs/_site