Using pweave module

Pweave can also be used as module from the Python interpreter. This has some advantages over just using the scripts. First the execution of the code will be faster because all modules all already imported. Second you can work interactively with the data after the code from the document has been run. Further it is possible to fully customize the document execution and formatting using the Pweb class.

pweave module contains two functions weave() and tangle() that offer the same functionality as the command line scripts.


This document was also created with Pweave, have a look at the source.

Simple weaving and tangling:

Here’s and example of simple weaving and tangling using example document ma.Pnw. Notice that pweave prints out the progress so in case of an error you can tell in which chunk it occurred. Also in case of an error returns already evaluated results from the documents namespace PwebProcessorGlobals.globals to global namespace.

>>> import pweave
>>> # Weave a pandoc document with default options
>>> pweave.weave('ma.mdw', doctype = "pandoc")
Processing chunk 1 named None from line 22
Processing chunk 2 named None from line 31
Processing chunk 3 named None from line 42
Pweaved ma.mdw to
>>> # Extract the code
>>> pweave.tangle('ma.mdw')
Tangled code from ma.mdw to

Pweave function reference

pweave.weave(file, doctype=None, informat=None, shell=u'python', shell_path=None, plot=True, docmode=False, cache=False, figdir=u'figures', cachedir=u'cache', figformat=None, returnglobals=True, listformats=False, output=None)[source]

Processes a Pweave document and writes output to a file

  • filestring input file
  • doctypestring output document format: call with listformats true to get list of supported formats.
  • informatstring input format: “noweb”, “markdown”, “notebook” or “script”
  • shellstring shell used to run code: “python”, “ipython”, “matlab” or “octave”
  • shell_pathstring Set the path of shell to run code, only affects “epython” shell
  • plotbool use matplotlib
  • docmodebool use documentation mode, chunk code and results will be loaded from cache and inline code will be hidden
  • cachebool Cache results to disk for documentation mode
  • figdirstring directory path for figures
  • cachedirstring directory path for cached results used in documentation mode
  • figformatstring format for saved figures (e.g. ‘.png’), if None then the default for each format is used
  • returnglobalsbool if True the namespace of the executed document is added to callers global dictionary. Then it is possible to work interactively with the data while writing the document. IronPython needs to be started with -X:Frames or this won’t work.
  • listformatsbool List available formats and exit
  • outputstring output file

Tangles a noweb file i.e. extracts code from code chunks to a .py file

Parameters:filestring the pweave document containing the code
pweave.publish(file, doc_format=u'html', theme=u'skeleton', latex_engine=u'pdflatex')[source]

Publish python script and results to html or pdf, expects that doc chunks are written in markdown.

”:param file: string input file” ”:param format: string output format “html” of “pdf”, pdf output requires pandoc and pdflatex in your path. :param: string latex_engine the command for running latex. Defaults to “pdflatex”.

pweave.convert(file, informat=u'noweb', outformat=u'script', pandoc_args=None, listformats=False)[source]

Convert input file from script to noweb or vice versa

  • filestring input file
  • informatstring input format noweb, script or notebook
  • outformatstring input format noweb or script
  • pandoc_argsstring arguments passed to pandoc to convert doc chunks. e.g. to convert from markdown to latex use: “-f markdown -t latex” . Note that each doc chunk is converted separately so you can’t use pandocs -s option.
  • listformatsbool List available formats and exit

Convert input file from script format to noweb format, similar to Knitr’s spin.

More options with Pweb Class

Weaving, tangling and pweave options are implemented using Pweb class. There is an example about customizations and the class reference is below.

Pweb Class

class pweave.Pweb(file=None, format=u'tex', shell=u'python', output=None, figdir=u'figures')[source]

Processes a complete document

cachedir = u'cache'

Pweave cache directory


Detect output format based on file extension


Detect input format based on file extension

documentationmode = None

Use documentation mode?


Format the code for writing


Get current format dictionary. See:

parse(string=None, basename=u'string_input')[source]

Parse document


Execute code in the document

setformat(doctype=u'tex', Formatter=None, theme=None)[source]

Set output format for the document

setreader(Reader=<class 'pweave.readers.PwebReader'>)[source]

Set class reading for reading documents, readers can be used to implement different input markups


Tangle the document


Update existing format, See:


Weave the document, equals -> parse, run, format, write


Write formatted code to file