Skip to content

kaleido

package: kaleido

Kaleido provides to convert plotly figures into various image formats.

Please see the README.md for more information and a quickstart.

Functions

calc_fig(fig, path, opts, topojson)

Return binary for plotly figure.

A convenience wrapper for Kaleido.calc_fig() which starts a Kaleido and executes the calc_fig().

See documentation for Kaleido.calc_fig().

write_fig(fig, path, opts, topojson, error_log, profiler, n)

Write a plotly figure(s) to a file.

A convenience wrapper for Kaleido.write_fig() which starts a Kaleido and executes the write_fig(). It takes one additional argument, n, which can be used to set the number of processes.

See documentation for Kaleido.write_fig().

write_fig_from_object(generator, error_log, profiler, n)

Write a plotly figure(s) to a file.

A convenience wrapper for Kaleido.write_fig_from_object() which starts a Kaleido and executes the write_fig_from_object() It takes one additional argument, n, which can be used to set the number of processes.

See documentation for Kaleido.write_fig_from_object().

calc_fig_sync(args, kwargs)

Call calc_fig but blocking.

write_fig_sync(args, kwargs)

Call write_fig but blocking.

write_fig_from_object_sync(args, kwargs)

Call write_fig_from_object but blocking.

Classes

class PageGenerator():

A page generator can set the versions of the js libraries used to render.

It does this by outputting the HTML used to render the plotly figures.

attributes

header - The header is the HTML that always goes at the top. Rarely needs changing.

methods

__init__(self, plotly, mathjax, others, force_cdn)

Create a PageGenerator.

arguments

plotly - the url to the plotly script to use. The default is the one plotly.py is using, if not installed, it uses the constant declared.

mathjax - the url to the mathjax script. By default is constant above. Can be set to false to turn off.

others - a list of other script urls to include. Usually strings, but can be (str, str) where its (url, encoding).

force_cdn - (default False) Don't use plotly import, use CDN

generate_index(self, path)

Generate the page.

arguments

path - If specified, page is written to path. Otherwise it is returned.

class Kaleido(choreographer.Browser):

Kaleido manages a set of image processors.

It can be used as a context (async with Kaleido(...)), but can also be used like:

k = Kaleido(...)
k = await Kaleido.open()
... # do stuff
k.close()

attributes

tmp_dir - Not documented.

methods

__init__(self, args, kwargs)

Initialize Kaleido, a choreo.Browser wrapper adding kaleido functionality.

It takes all choreo.Browser args, plus some extra. The extra are listed, see choreographer for more documentation.

Note: Chrome will throttle background tabs and windows, so non-headless multi-process configurations don't work well.

For argument page, if it is a string, it must be passed as a fully-qualified URI, like file:// or https://. If it is a Path, Path's as_uri() will be called. If it is a string or path, its expected to be an HTML file, one will not be generated.

arguments

n - the number of separate processes (windows, not seen) to use.

timeout - limit on any single render (default 90 seconds).

width - width of window (headless only)

height - height of window (headless only)

page - This can be a kaleido.PageGenerator, a pathlib.Path, or a string.

close(self)

Close the browser.

populate_targets(self)

Override the browser populate_targets to ensure the correct page.

Is called automatically during initialization, and should only be called once ever per object.

calc_fig(self, fig, path, opts, topojson)

Calculate the bytes for a figure.

This function does not support parallelism or multi-image processing like write_fig does, although its arguments are a subset of those of write_fig. This function is currently just meant to bridge the old and new API.

write_fig(self, fig, path, opts, topojson, error_log, profiler)

Call the plotly renderer via javascript on first available tab.

arguments

fig - the plotly figure or an iterable of plotly figures

path - the path to write the images to. if its a directory, we will try to generate a name. If the path contains an extension, "path/to/my_image.png", that extension will be the format used if not overridden in opts. If you pass a complete path (filename), for multiple figures, you will overwrite every previous figure.

opts - dictionary describing format, width, height, and scale of image

topojson - a link ??? TODO

error_log - a supplied list, will be populated with ErrorEntrys which can be converted to strings. Note, this is for collections errors that have to do with plotly. They will not be thrown. Lower level errors (kaleido, choreographer) will still be thrown. If not passed, all errors raise.

profiler - a supplied dictionary to collect stats about the operation about tabs, runtimes, etc.

write_fig_from_object(self, generator, error_log, profiler)

Equal to write_fig but allows the user to generate all arguments.

Generator must yield dictionaries with keys: - fig: the plotly figure - path: (optional, string or pathlib.Path) the path - opts: (optional) dictionary with: - format (string) - scale (number) - height (number) - and width (number) - topojson: (optional) topojsons are used to customize choropleths

Generators are good because, if rendering many images, one doesn't need to prerender them all. They can be rendered and yielded asynchronously.

While write_fig can also take generators, but only for the figure. In this case, the generator will specify all render-related arguments.

arguments

generator - an iterable or generator which supplies a dictionary of arguments to pass to tab.write_fig.

error_log - A supplied list, will be populated with ErrorEntrys which can be converted to strings. Note, this is for collections errors that have to do with plotly. They will not be thrown. Lower level errors (kaleido, choreographer) will still be thrown.

profiler - A supplied dictionary, will be populated with information about tabs, runtimes, etc.