Blockpad - Python Integration

Python Integration Notes

Introduction

Blockpad integrates with Python to be able to run Python scripts and use Python libraries within Blockpad files.

Blockpad uses the interpreter on your local computer. This is different from Excel's Python integration, which entirely relies on the Microsoft cloud. In Blockpad, no data ever leaves your computer unless you direct it to.

Because Blockpad uses your local interpreter, you can use any Python libraries you like.

Blockpad files with Python integration depend on the local interpreter, so it is important to be careful sharing files between users. If a file is opened on a computer with a different Python version installed globally or with different packages, the formulas will calculate differently.

Basics

You can access Python from the functions in Library.Scripts.Python.

Eval - runs a Python expression in "eval" mode and returns the result.

Examples:

Library.Scripts.Python.Eval("2+2")
Library.Scripts.Python.Eval("a+b", {a: 4m, b: 10ft})

Exec - runs a Python script in "exec" mode and returns an object of all the resulting variable values

Example:

Library.Scripts.Python.Exec(TextJoin("\n", ["n=1", "for i in range(1, a):", " n *= 2"], {a: 4})

Module - gets a reference to a Python module

np=Library.Scripts.Python.Module("numpy")

plt=Library.Scripts.Python.Module("matplotlib.pyplot")

InterpreterInfo - gets the file path of the Python interpreter that Blockpad is linked to

As usual, you can import Library.Scripts or Library.Scripts.Python to shorten the formulas needed to refer to these resources.

Python values in Blockpad

Simple Python values are translated directly as Blockpad values. These include numbers, strings, and booleans, and datetime values.

Likewise, simple Blockpad values are translated into corresponding numbers, strings, and booleans in Python.

Other Python values are kept alive in a pool in Python so that they may be passed back and forth. This allows functions, arrays, tuples, and other objects to be handled. For these objects, Blockpad keeps a reference to the original Python object, which you can use to get members, call Python functions, and access arrays seamlessly from Blockpad formulas.

Using Python modules

You can import a Python module with the Module function:

np=Library.Scripts.Python.Module("numpy")

You can then use the module's functions directly from the Blockpad formula:

array=np.identity(10)

Displaying images

You can use the new Image function in Library.Docs to define an image that can be shown in Blockpad. Note that arrays from numpy (or opencv) that refer to images do not define what pixel format (BGRA, RGB, BGR, or grayscale) is used. When you work with images in Python normally, you keep track of pixel formats yourself. For Blockpad to treat these as images, rather than plain arrays, you need to specify a format with the Image function.

For example, you can display an image with these steps:

cv2 = Library.Scripts.Python.Module("cv2")

image data = cv2.imread("C:\\path to image... .jpg")

Library.Docs.Image(image data, "bgr")

Images with formulas

With version 1.6, it is possible to show images in equations, fields, and table cells.

It is also possible to specify an image object with a formula. To do this, you can go to insert an image, choose Use Formula, and enter a formula such as the one above, using the Library.Docs.Image function.

Special libraries

Blockpad has special behaviors with the following libraries, if they are installed with your Python interpreter:

NumPy - Blockpad is optimized to be able to receive binary data from NumPy arrays for displaying images

Pint - Blockpad sends and receives numbers with units to and from Python via quantity types in the Pint library

Using Blockpad as a Jupyter notebook

To set up a Blockpad files that looks and runs like a Jupyter notebook, you can put scripts in fields. Fields set to "Inline" mode will appear as multiline text in the document. You can put equations using the field value and the Python Exec function to run each script block.

Warnings

Python scripts, as is generally the case, can range from simple arithmetic operations to procedures that can affect your file system and other sensitive resources. You should only run scripts you trust. Blockpad will confirm you trust a file before allowing Python resources in that file to run.

Blockpad does not sandbox scripts that it runs in Python. Make sure only to use files you trust.

When working with large Python resources in Blockpad, it can become important to think of memory and processor utilization. Please keep in mind:

Python objects are kept alive in the Python process as long as they are referenced in a Blockpad file. If you have large or many objects retained in formula results, this may cause large memory usage.

If you use large Python arrays in an array formula, you can cause slow behavior as Blockpad will have to copy over many values from Python.

Each Python function call (Exec, Eval, or Module) is limited to 10 seconds to run. After that, a timeout error will occur. You can update formulas manually through the Formulas menu if you need to try again.

Future plans

Future plans for the Python integration include:

Ability to define virtual environments for a specific Python version and specified set of pip libraries, that will have consistent behavior across Windows, Mac, and web platforms
Ability to run Python in a secure sandbox
Built-in SymPy to improve solver section features and provide other math features
Ability to run Python in a sandbox.
Python script frames, both embedded in reports and as a top level frame.

If you have any thoughts about how we should develop the Python integration in the future, please contact us. We would love to hear from you as we continue to develop this feature.