Python libraries

Python libraries#

The modules described below are packaged into a library and made available to Python code executed through the {exec} python directive. Additionally, all files in the directory _python (next to conf.py) are also included recursively in the library.

tdoc.core#

This module (source) provides basic functionality for {exec} python blocks. It doesn't need to be imported explicitly: all its public symbols are available in the global scope of {exec} python blocks.

tdoc.core.new_id() → str#

Generate a unique ID, usable in the id= attribute of an HTML element.

tdoc.core.render(html, name='') → asyncio.Future#

Render an HTML snippet as an output block. Output blocks are displayed ordered by name. If an output block with the same name already exists, it is replaced with the new one.

Parameters:

  • html (str | Iterator(str)) -- The HTML snippet to be rendered.

  • name (str) -- The name of the output block.

Returns:

A Future that resolves to the size of the output block, as a (width, height) tuple.

async tdoc.core.input_line(prompt=None) → str#

Request a single line of text from the user, and wait for them to submit a reply.

Parameters:

prompt (str) -- An optional prompt to display before the input field.

async tdoc.core.input_text(prompt=None) → str#

Request a multi-line text from the user, and wait for them to submit a reply.

Parameters:

prompt (str) -- An optional prompt to display before the input field.

async tdoc.core.input_buttons(prompt, labels) → int#

Present a list of buttons and wait for the user to click one of them.

Parameters:

  • prompt (str) -- An optional prompt to display before the buttons.

  • labels (list(str)) -- The labels of the buttons to display.

Returns:

The index in labels of the button that was clicked.

async tdoc.core.pause(prompt=None, label='@icon{forward-step}')#

Present a button, and wait for the user to click it.

Parameters:

  • prompt (str) -- An optional prompt to display before the button.

  • label (str) -- The label of the button. If the label has the format @icon{...}, the corresponding icon from Font Awesome is used.

tdoc.core.redirect(stdout=None, stderr=None)#

Return a context manager that temporarily replaces sys.stdout and / or sys.stderr with the given stream(s). This function must be used instead of direct assignment or contextlib.redirect_stdout() / contextlib.redirect_stderr() to avoid redirecting the output of all code blocks on the same page.

Parameters:
import io
out = io.StringIO()
with redirect(stdout=out):
    print("Hello, world!")
print(f"Captured output: {out.getvalue().rstrip()}")

tdoc.svg#

This module (source) allows creating SVG images using simple drawing primitives and rendering them in an output block.

To create an SVG image, instantiate the Image class, add elements to it, then display it with render(). Animations can be implemented by repeatedly rendering images.

from tdoc import svg

# Create the image.
img = svg.Image(400, 100, stroke='black', fill='transparent',
                style='width: 100%; height: 100%')

# Add a red dashed circle.
img.circle(200, 50, 45, stroke=svg.Stroke('red', dash_array='4 2'))

# Add two lines, grouped to avoid repeating the blue stroke.
g = img.group(stroke=svg.Stroke('blue', width=2))
g.line(0, 0, 400, 100)
g.line(0, 100, 400, 0)

# Add a partially-transparent ellipse.
img.ellipse(200, 50, 195, 35, fill=svg.Fill('#f0f0f0', opacity=0.8))

# Display the image.
render(img)

Containers#

The following classes implement concrete containers. kwargs are forwarded to Container.

class tdoc.svg.Image(width, height, *, stylesheet=None, **kwargs)#

Represents an <svg> element, a complete SVG image. The viewport of the image is set to (0, 0, width, height), with the (0, 0) coordinate at the top left, the x axis pointing to the right and the y axis pointing down.

Parameters:

  • width,height (int) -- The size of the image in pixels.

  • stylesheet (str) -- A CSS stylesheet that is scoped to the image.

class tdoc.svg.Group(**kwargs)#

Represents a <g> element, a visible group of shapes.

class tdoc.svg.Symbol(**kwargs)#

Represents a <symbol> element, an invisible group of shapes that can be referenced by Use elements.

All concrete containers inherit from Container, which itself inherits from Shape. kwargs are forwarded to Shape.

class tdoc.svg.Container(**kwargs)#

A container of shapes. It is itself a Shape, so it can be added to other containers.

children: list#

The list of contained shapes.

add(child)#

Add a child to the container. Returns child.

circle(x, y, r, **kwargs) → Circle#

Add a <circle> to the container.

Parameters:

  • x,y -- The coordinates of the center of the circle.

  • r -- The radius of the circle.

ellipse(x, y, rx, ry, **kwargs) → Ellipse#

Add an <ellipse> to the container.

Parameters:

  • x,y -- The coordinates of the center of the ellipse.

  • rx,ry -- The horizontal and vertical radii of the ellipse.

line(x1, y1, x2, y2, **kwargs) → Line#

Add a <line> to the container.

Parameters:

  • x1,y1 -- The start coordinates of the line.

  • x2,y2 -- The end coordinates of the line.

path(*path, **kwargs) → Path#

Add a <path> to the container.

Parameters:

path -- A sequence of strings or tuples defining the path to be drawn.

polygon(*points, **kwargs) → Polygon#

Add a <polygon> to the container.

Parameters:

points -- A sequence of (x, y) tuples defining the points of the polygon.

polyline(*points, **kwargs) → Polyline#

Add a <polyline> to the container.

Parameters:

points -- A sequence of (x, y) tuples defining the points of the polyline.

rect(x, y, width, height, *, rx=None, ry=None, **kwargs) → Rect#

Add a <rect> to the container.

Parameters:

  • x,y -- The origin of the rectangle.

  • width,height -- The size of the rectangle.

  • rx,ry -- The horizontal and vertical corner radii of the rectangle.

text(x, y, text, **kwargs) → Text#

Add a <text> to the container.

Parameters:

  • x,y -- The coordinates of the start of the text (baseline).

  • text -- The text to be displayed.

group(**kwargs) → Group#

Add a <g> to the container.

symbol(**kwargs) → Symbol#

Add a <symbol> to the container.

use(href, *, x=0, y=0, **kwargs) → Use#

Add a <use> to the container.

Parameters:

  • href -- The shape to reference, an object with an id attribute (typically a concrete shape instance).

  • x,y -- The coordinates of the shape's origin.

Shapes#

The following classes implement concrete shapes. kwargs are forwarded to Shape.

class tdoc.svg.Circle(x, y, r, **kwargs)#

Represents a <circle> element.

Parameters:

  • x,y -- The coordinates of the center of the circle.

  • r -- The radius of the circle.

class tdoc.svg.Ellipse(x, y, rx, ry, **kwargs)#

Represents an <ellipse> element.

Parameters:

  • x,y -- The coordinates of the center of the ellipse.

  • rx,ry -- The horizontal and vertical radii of the ellipse.

class tdoc.svg.Line(x1, y1, x2, y2, **kwargs)#

Represents a <line> element.

Parameters:

  • x1,y1 -- The start coordinates of the line.

  • x2,y2 -- The end coordinates of the line.

class tdoc.svg.Path(*path, **kwargs)#

Represents a <path> element.

Parameters:

path -- A sequence of strings or tuples defining the path to be drawn.

class tdoc.svg.Polygon(*points, **kwargs)#

Represents a <polygon> element.

Parameters:

points -- A sequence of (x, y) tuples defining the points of the polygon.

class tdoc.svg.Polyline(*points, **kwargs)#

Represents a <polyline> element.

Parameters:

points -- A sequence of (x, y) tuples defining the points of the polyline.

class tdoc.svg.Rect(x, y, width, height, *, rx=None, ry=None, **kwargs)#

Represents a <rect> element.

Parameters:

  • x,y -- The origin of the rectangle.

  • width,height -- The size of the rectangle.

  • rx,ry -- The horizontal and vertical corner radii of the rectangle.

class tdoc.svg.Text(x, y, text, **kwargs)#

Represents a <text> element.

Parameters:

  • x,y -- The coordinates of the start of the text (baseline).

  • text -- The text to be displayed.

class tdoc.svg.Use(href, *, x=0, y=0, **kwargs)#

Represents a <use> element.

Parameters:

  • href -- The shape to reference, an object with an id attribute (typically a concrete shape instance).

  • x,y -- The coordinates of the shape's origin.

All concrete shapes, as well as all container classes, inherit from Shape.

class tdoc.svg.Shape(*, klass=None, style=None, stroke=None, fill=None, transform=None)#

A geometrical shape that can be painted.

Parameters:

  • klass (str) -- The element's class attribute, to be referenced in an Image stylesheet (class is a reserved word in Python, so it cannot be used as an argument name).

  • style (str) -- The element's style attribute.

  • stroke (str | Stroke) -- The stroke with which to paint the shape.

  • fill (str | Fill) -- The fill to use to paint the shape.

  • transform (Transform) -- A transform to apply to the shape.

property id: str#

The unique ID of the element.

Attributes#

Attribute instances are passed as arguments to shapes.

class tdoc.svg.Stroke(color=None, *, width=None, opacity=None, dash_array=None, dash_offset=None, line_cap=None, line_join=None, miter_limit=None)#

Represents a set of attributes describing a stroke, to be passed as a stroke argument.

class tdoc.svg.Fill(color=None, *, opacity=None, rule=None)#

Represents a set of attributes describing a fill, to be passed as a fill argument.

class tdoc.svg.Transform#

Represents a set of attributes describing a transform, to be passed as a transform argument.

matrix(a=0, b=0, c=0, d=0, e=0, f=0)#

Add a matrix to the transform.

translate(x=0, y=0)#

Add a translation to the transform.

scale(x=0, y=None)#

Add a scaling to the transform.

rotate(angle, x=None, y=None)#

Add a rotation (in degrees) to the transform.

skew_x(angle)#

Add an X skew (in degrees) to the tranform.

skew_y(angle)#

Add a Y skew (in degrees) to the tranform.

The tdoc.svg module exports convenience functions with the same names as the methods of Transform that create a new Transform and add a transform to it.