toyplot.html module

Functions to render the canonical HTML representation of a Toyplot figure.

class toyplot.html.RenderContext(scenegraph, root)[source]

Bases: object

Stores context data during rendering.

This is only of use for Toyplot developers and library developers who are implementing rendering code. It is not intended for end-users.

already_rendered(o)[source]

Track whether an object has already been rendered.

Used to prevent objects that can be shared, such as toyplot.coordinates.Axis, from generating duplicate markup in the output HTML.

Parameters:o (any Python object, required) –
Returns:rendered – If the given object hasn’t already been rendered, records it as rendered and returns False. Subsequent calls with the given object will always return True.
Return type:bool

Examples

The following checks to see if mark has already been rendered:

if not context.already_rendered(mark):
    # Render the mark
animation

Warning

attribute ‘toyplot.html.RenderContext.animation’ undocumented

copy(parent)[source]

Copy the current toyplot.html.RenderContext.

Creates a copy of the current render context that can be used to render children of the currently-rendered object.

Parameters:parent (any Python object, required.) –
Returns:context – The parent attribute will be set to the supplied parent object.
Return type:toyplot.html.RenderContext
define(name, dependencies=None, factory=None, value=None)[source]

Define a Javascript module that can be embedded in the output markup.

The module will only be embedded in the output if it is listed as a dependency of another module, or code specified using require().

You must specify either factory or value.

Parameters:
  • name (string, required) – Module name. Any string is valid, but alphanumerics separated with slashes are recommended. Multiple calls to define with the same name argument will be silently ignored.
  • dependencies (sequence of strings, optional) – Names of modules that are dependencies of this module.
  • factory (string, optional) – Javascript code that will construct the module, which must be a function that takes the modules listed in dependencies, in-order, as arguments, and returns the initialized module.
  • value (Python object, optional) – Arbitrary value for this module, which must be compatible with json.dumps().
get_id(o)[source]

Return a globally unique identifier for an object.

The generated identifier is cached, so multiple lookups on the same object will return consistent results.

Parameters:o (any Python object, required.) –
Returns:id – Globally unique identifier that can be used in HTML markup as an identifier that can be targeted from Javascript code.
Return type:str
parent

Current DOM node. Typical rendering code will append HTML content to this node.

require(dependencies=None, arguments=None, code=None)[source]

Embed Javascript code and its dependencies into the output markup.

The given code will be unconditionally embedded in the output markup, along with any modules listed as dependencies (plus their dependencies, and-so-on).

Parameters:
  • dependencies (sequence of strings, optional) – Names of modules that are required by this code.
  • arguments (sequence of Python objects, optional) – Additional arguments to be passed to the Javascript code, which must be compatible with json.dumps().
  • code (string, required) – Javascript code to be embedded, which must be a function that accepts the modules listed in requirements in-order, followed by the values listed in arguments in-order, as arguments.
root

Top-level DOM node.

scenegraph

Warning

attribute ‘toyplot.html.RenderContext.scenegraph’ undocumented

toyplot.html.apply_changes(html, changes)[source]

Warning

function ‘toyplot.html.apply_changes’ undocumented

toyplot.html.dispatch(*types, **kwargs)

Decorator for registering custom rendering code.

This is only of use when creating your own custom Toyplot marks. It is not intended for end-users.

Example

To register your own rendering function:

@toyplot.html.dispatch(toyplot.coordinates.Cartesian, MyCustomMark, toyplot.html.RenderContext)
def _render(axes, mark, context):
    # Rendering implementation here
toyplot.html.render(canvas, fobj=None, animation=False, style=None)[source]

Convert a canvas to its HTML DOM representation.

Generates HTML markup with an embedded SVG representation of the canvas, plus JavaScript code for interactivity. If the canvas contains animation, the markup will include an HTML user interface to control playback.

Parameters:
  • canvas (toyplot.canvas.Canvas) – The canvas to be rendered.
  • fobj (file-like object or string, optional) – The file to write. Use a string filepath to write data directly to disk. If None (the default), the HTML tree will be returned to the caller instead.
  • animation (boolean, optional) – If True, return a representation of the changes to be made to the HTML tree for animation.
  • style (dict, optional) – Dictionary of CSS styles that will be applied to the top-level output <div>.
Returns:

  • html (xml.etree.ElementTree.Element or None) – HTML representation of canvas, as a DOM tree, or None if the caller specifies the fobj parameter.
  • changes (JSON-compatible data structure, or None) – JSON-compatible representation of the animated changes to canvas.

Notes

The output HTML is the “canonical” representation of a Toyplot canvas - the other toyplot backends operate by converting the output from toyplot.html.render() to the desired end target.

Note that the output HTML is a fragment wrapped in a <div>, suitable for embedding in a larger document. It is the caller’s responsibility to supply the <html>, <body> etc. if the result is intended as a standalone HTML document.

toyplot.html.tostring(canvas, style=None)[source]

Convert a canvas to its HTML string representation.

Generates HTML markup with an embedded SVG representation of the canvas, plus JavaScript code for interactivity. If the canvas contains animation, the markup will include an HTML user interface to control playback.

Parameters:
  • canvas (toyplot.canvas.Canvas) – The canvas to be rendered.
  • style (dict, optional) – Dictionary of CSS styles that will be applied to the top-level output <div>.
Returns:

html – HTML representation of canvas as a string.

Return type:

str

Notes

The output HTML is a fragment wrapped in a <div>, suitable for embedding in a larger document. It is the caller’s responsibility to supply the <html>, <body> etc. if the result is intended as a standalone HTML document.