API

class stitch.Stitch(name, to='html', standalone=True, self_contained=True, warning=True, error='continue', prompt=None)

Helper class for managing the execution of a document. Stores configuration variables.

Notes

Attirbutes can be set via the command-line, document YAML metadata, or (where appropriate) the chunk-options line.

Attributes

to (str) The output file format. Optionally inferred by the output file file extension.
title (str) The name of the output document.
date (str)
author (str)
self_contained (bool, default True) Whether to publish a self-contained document, where things like images or CSS stylesheets are inlined as data attributes.
standalone (bool) Whether to publish a standalone document (True) or fragment (False). Standalone documents include items like <head> elements, whereas non-standlone documents are just the <body> element.
warning (bool, default True) Whether to include text printed to stderr in the output
error (str, default ‘continue’) How to handle exceptions in the executed code-chunks.
prompt (str, optional) String to put before each line of the input code. Defaults to IPython-style counters.
echo (bool, default True) Whether to include the input code-chunk in the output document.
eval (bool, default True) Whether to execute the code-chunk.
fig.width (str)
fig.height (str)
get_kernel(kernel_name)

Get a kernel from kernel_managers by kernel_name, creating it if needed.

Parameters:kernel_name : str
Returns:kp : KernelPair
kernel_managers

dict of KernelManager, KernelClient pairs, keyed by kernel name.

static name_resource_dir(name)

Give the directory name for supporting resources

parse_document_options(meta)

Modifies self to update options, depending on the document.

stitch(source)

Main method for converting a document.

Parameters:

source : str

the actual text to be converted
Returns:

doc : dict

These should be compatible with pando’s JSON AST It’s a dict with keys

  • pandoc-api-version
  • meta
  • blocks
wrap_image_output(chunk_name, data, key, attrs)

Extra handling for images

Parameters:

chunk_name, data, key : str

attrs: dict
Returns:

Para[Image]
wrap_output(chunk_name, messages, attrs)

Wrap the messages of a code-block.

Parameters:

chunk_name : str

messages : list of dicts

attrs : dict

options from the source options-line.
Returns:

output_blocks : list

Notes

Messages printed to stdout are wrapped in a CodeBlock. Messages publishing mimetypes (e.g. matplotlib figures) resuse Jupyter’s display priority. See NbConvertBase.display_data_priority.

The result should be pandoc JSON AST compatible.

Chunk Options

Code chunks are blocks that look like

```{kernel_name, [chunk_name], **kwargs}
# code
```

The kernel_name is required, and chunk_name is optional. All parameters are separated by a comma.

kernel_name(name: str)

Name of the kernel to use for executing the code chunk. Required. See jupyter kernelspec list.

chunk_name(chunk_name: str)

Name for the chunk. Controls the filename for supporting files created by that chunk. Optional.

echo(echo=True)

whether to include the input-code in the rendered output. Default True.

eval(eval=True)

Whether to execute the code cell. Default True.

results(s)

str; how to display the results

  • hide: hide the chunk output (but still execute the chunk)
warning(True)

bool; whether to include warnings (stderr) in the ouput.

width(w)

Width for output figure. See http://pandoc.org/MANUAL.html#images

Warning

This will probably change to fig.width in a future release.

height(w)

Height for output figure. See http://pandoc.org/MANUAL.html#images

Warning

This will probably change to fig.height in a future release.