-
Notifications
You must be signed in to change notification settings - Fork 39
Language Wrapper Architecture
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.
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:
- Constructor arguments of the
SupervizScope
Python class. - 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
.
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.