Getting started with pweave with pycharm

pweave-cheatsheet.md

Pweave cheat sheet

Pweave is a dynamic report generation tool for Python. Its lets write texts (Markdown, reST, Latex...) and code in the same file with the code being evaluated and highlighted on purpose.

Key features:

• Execute python code in the chunks and capture input and output to a report.
• Rich output and support for IPython magics
• Use hidden code chunks, i.e. code is executed, but not printed in the output file.
• Capture matplotlib graphics.
• Evaluate inline code in documentation chunks marked using and .
• Cache all code and results from previous runs in documentation mode.
• Publish reports from Python scripts (*.py files).
• Run from command line or interpreter: integrate automatic report generation in your usual workflow.
• Execute code using any Jupyter kernel.

Main output formats:

• HTML with pygments highlighting
• Jupyter notebook
• Latex
• reStructuredText

Basic use

Python code blocks in text files

In a basic *.md file, simply wraps your codes blocks using any of the following:

    ```python
    # This code block is executed
    a = 1
    ```

    ```{python}
    # This code block is executed as well, following the previous one
    # Note that PyCharm does not highlight code in it. However this code block style is compatible with RMarkdown and could
    # be directly used and interpreted in a Rmarkdown file
    b = a
    print(b)
    ```

    ```{.python}
    # Here as well, executed but PyCharm does not highlight syntax
    c = a + b
    print(c)
    ```

Text blocks in python files

In a basic *.py file, all lines starting with #%%, # %% or #' will be rendered by pweave; e.g.:

    # This is a python script
    # %% # This line is the title of the weave document
    a = 1
    print(a)
    #' Keep commenting your results

Note that PyCharm in ScientificMode recognizes the # %% as the beginning of a code cell. Using the "run" command it is then possible to run entire cells on after the other. In any case when working on a *.py file you can evaluate code in console using the execute line in console action.

All lines that are not documentation are treated as code. You can set chunk options using lines starting with #+, #%% or # %% just before code e.g. #+ echo=False, Fig=True.

Chunk options

In Pweave, the equivalent of a cell in a Jupyter Notebooks is called a "chunk". Each chunk can be named and has several parameters separated by commas, see the doc:

• name, label: Chunk names are used for figure names

• echo (bool): Echo the python code in the output document. If False the source code will be hidden.

• evaluate (bool): Evaluate the code chunk. If False the chunk won’t be executed.

• results :

  • ‘verbatim’ for literal block
  • ‘hidden’ for hidden results

• term (bool): emulates a terminal session: the output for each statement will be displayed.

• include (bool): generated figures are automatically included in the document otherwise figures are generated, but not included.

• fig (bool): Whether a matplotlib plot produced by the code chunk should be included in the file.

• caption (str): Can only be used with ‘fig = True’ option.

• width: format specific markup e.g. “12cm”, “600px”, “linewidth”. The default width depends on the output format.

• f_size (tuple): Saved matplotlib figure size in inches a tuple (w, h).

• wrap = True or (False,"code", "results"): Controls wrapping of long lines. If True both code and output are wrapped to 75 characters. You can also specify “code” or “results” options to wrap only input or output.

• complete (bool): Used to include code spanning multiple chunks before it get executed

Compile (weave) document

You need to have pweave installed, e.g.:

pip install pweave

Then just run pweave {filepath} (see other options online). Alternatively, you can weave from a python script:

    import pweave

    pweave.weave('filepath')

Recommended best practices

• work with *.py files as much as possible
• use the # %% tag for main sections as they are interpreted as unique cells by PyCharm
• use the #' tag for all other text sections
• use the #+ tag for chunk options
• add en external tool in PyCharm to run pweave with the PYTHONPATH set to the project root:

    Program: env
    Arguments: PYTHONPATH=$Projectpath$ $PyInterpreterDirectory$/pweave $FilePath$
    Working directory: $ProjectFileDir$

pycharm_configuration.png