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. It is also 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.

Simple weaving and tangling:

Here’s and example of simple weaving and tangling using example document ma.mdw. Notice that pweave prints out the progress so in case of an error you can tell in which chunk it occurred.

import pweave
# Weave a pandoc document with default options
pweave.weave('ma.mdw', doctype = "pandoc")
Traceback (most recent call last)~/anaconda3/lib/python3.6/site-
packages/pweave/ in read_file_or_url(source)
     15     try:
---> 16         codefile =, 'r', encoding='utf-8')
     17         contents =
FileNotFoundError: [Errno 2] No such file or directory: 'ma.mdw'
During handling of the above exception, another exception occurred:
ValueError                                Traceback (most recent call
last)<ipython-input-1-00fa7e3b1899> in <module>()
      1 import pweave
      2 # Weave a pandoc document with default options
----> 3 pweave.weave('ma.mdw', doctype = "pandoc")
~/anaconda3/lib/python3.6/site-packages/pweave/ in
weave(file, doctype, informat, kernel, plot, docmode, cache, figdir,
cachedir, figformat, listformats, output, mimetype)
     49     doc = Pweb(file, informat=informat, doctype=doctype,
     50                kernel=kernel, output=output, figdir=figdir,
---> 51                mimetype=mimetype
     52                )
     53     doc.documentationmode = docmode
~/anaconda3/lib/python3.6/site-packages/pweave/ in
__init__(self, source, doctype, informat, kernel, output, figdir,
     69         self.setformat(doctype)
---> 70 = informat)
     72     def _setwd(self):
~/anaconda3/lib/python3.6/site-packages/pweave/ in read(self,
string, basename, reader)
    107         if string is None:
--> 108             self.reader = Reader(file=self.source)
    109         else:
    110             self.reader = self.Reader(string=string)
~/anaconda3/lib/python3.6/site-packages/pweave/ in
__init__(self, file, string)
     36         # Get input from string or
     37         if file is not None:
---> 38             self.rawtext = read_file_or_url(self.source)
     39         else:
     40             self.rawtext = string
~/anaconda3/lib/python3.6/site-packages/pweave/ in
     18         codefile.close()
     19     except IOError:
---> 20         r = request.urlopen(source)
     21         contents ="utf-8")
     22         r.close()
~/anaconda3/lib/python3.6/urllib/ in urlopen(url, data,
timeout, cafile, capath, cadefault, context)
    221     else:
    222         opener = _opener
--> 223     return, data, timeout)
    225 def install_opener(opener):
~/anaconda3/lib/python3.6/urllib/ in open(self, fullurl,
data, timeout)
    509         # accept a URL or a Request object
    510         if isinstance(fullurl, str):
--> 511             req = Request(fullurl, data)
    512         else:
    513             req = fullurl
~/anaconda3/lib/python3.6/urllib/ in __init__(self, url,
data, headers, origin_req_host, unverifiable, method)
    327                  origin_req_host=None, unverifiable=False,
    328                  method=None):
--> 329         self.full_url = url
    330         self.headers = {}
    331         self.unredirected_hdrs = {}
~/anaconda3/lib/python3.6/urllib/ in full_url(self, url)
    353         self._full_url = unwrap(url)
    354         self._full_url, self.fragment =
--> 355         self._parse()
    357     @full_url.deleter
~/anaconda3/lib/python3.6/urllib/ in _parse(self)
    382         self.type, rest = splittype(self._full_url)
    383         if self.type is None:
--> 384             raise ValueError("unknown url type: %r" %
    385, self.selector = splithost(rest)
    386         if
ValueError: unknown url type: 'ma.mdw'
# Extract the code
Traceback (most recent call last)<ipython-input-1-d41c1a734f25> in
      1 # Extract the code
----> 2 pweave.tangle('ma.mdw')
~/anaconda3/lib/python3.6/site-packages/pweave/ in
tangle(file, informat)
     64     :param file: ``string`` the pweave document containing the
     65     """
---> 66     doc = Pweb(file, kernel = None, informat = informat)
     67     doc.tangle()
~/anaconda3/lib/python3.6/site-packages/pweave/ in
__init__(self, source, doctype, informat, kernel, output, figdir,
     67         self.theme = "skeleton"
---> 69         self.setformat(doctype)
     70 = informat)
~/anaconda3/lib/python3.6/site-packages/pweave/ in
setformat(self, doctype, Formatter)
    149         self.formatter = Formatter([],
--> 150                                    kernel = self.kernel,
    151                                    language = self.language,
    152                                    mimetype =
AttributeError: 'Pweb' object has no attribute 'kernel'

Pweave function reference

pweave.weave(file, doctype=None, informat=None, kernel='python3', plot=True, docmode=False, cache=False, figdir='figures', cachedir='cache', figformat=None, listformats=False, output=None, mimetype=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”
  • kernelstring Jupyter kernel used to run code: default is python3
  • 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
  • listformatsbool List available formats and exit
  • outputstring output file
  • mimetypestring Source document’s text mimetype. This is used to set cell type in Jupyter notebooks.
pweave.tangle(file, informat=None)[source]

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='html', theme='skeleton', latex_engine='pdflatex', output=None)[source]

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

  • filestring input file”
  • formatstring output format “html” of “pdf”, pdf output requires pandoc and pdflatex in your path.
  • latex_enginestring the command for running latex. Defaults to “pdflatex”.
  • outputstring output file. Use .tex extension for pdf output.
pweave.convert(file, informat='noweb', outformat='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(source, doctype=None, *, informat=None, kernel='python3', output=None, figdir='figures', mimetype=None)[source]

Process a Pweave document

  • sourcestring name of the input document.
  • doctypestring output format.
  • informatstring input format
  • kernelstring name of jupyter kernel used to run code
  • outputstring output path
  • figdirstring figure directory
  • mimetype – Source document’s text mimetype. This is used to set cell type in Jupyter notebooks
documentationmode = None

Use documentation mode


Format executed code for writing.


Get current format dictionary. See:

read(string=None, basename='string_input', reader=None)[source]

Parse document

Param:None (set automatically), reader name or class object

Execute code in the document

setformat(doctype=None, Formatter=None)[source]

Set formatter by name or class. You can pass either

  • doctype – The name of Pweave output format
  • Formatter – Formatter class

Set the kernel for jupyter_client


Tangle the document


Update existing format, See:


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


Write formatted code to file