Language Wrapper Architecture

Overview

This section provides a high-level overview of the interactions between Kaleido's Python and C++ layers. While not a formal specification, it should be helpful as reference for adding support for other wrapper langauges.

Initialization Interface

The first time an image export request is made in the Python library, the Kaleido C++ executable is launched as a long-running subprocess of the Python interpreter using subprocess.Popen. The first, and only, positional argument should be the scope name. After that, a series of flags of the form --flag are passed to the executable.

These flags correspond to either:

1. Constructor arguments of the SupervizScope Python class.
2. Chromium command line flags (https://peter.sh/experiments/chromium-command-line-switches/).

When construction is complete, the Kaledo executable will write a single line to standard-out. This is a JSON string with code and message properties. The Python wrapper reads this line from standard-in and converts it from JSON to a Python dict. If initialization was successful, the code key is 0 and message key is ignored. If something went wrong (e.g. a validation failure), then the code will be a non-zero integer and an error message will be included. In this case, the Python layer will raise a ValueError with the returned message. Note: Eventually it would be helpful to specify interpretations of various error codes that could be used consistently across libraries. At this point, all that matters is whether the code is 0 or not 0.

Export Interface

Each time an image export request is made of the Python library, a request JSON string is formed and written to standard-in, followed by a newline.

The wrapper library is responsible for making sure that the JSON string does not contain internal newline characters (as would be the case when JSON is pretty-printed)

This JSON string should contain the figure specification in the data property, as well as format, width, height, scale options. In response, the Kaleido C++ executable will write a single JSON string, followed by a newline, to standard out. This JSON string also has the code and message properties. Again, if something went wrong, code will be non-zero and the message will describe the problem. And again, the Python layer will raise a ValueError with the contents of the message. If code is 0, then the result property will contain the image data, which is returned by the Python layer as a bytes object.