Python notebooks for R markdown lovers using Atom and Pweave

This is a little project that I had in mind for a long time, and that I finally decided to carry out on a rainy morning.

Since I love R markdown notebooks, I wanted to have the same experience with Python. Specifically my aims were:

  • to be able to code in a Python notebook without having to learn many keyboard shortcuts
  • to have the possibilty to evaluate a single line or a selection of code in the notebook without having to run the whole cell

As you can see I didn’t aim at implementing all the wonderful functionalities of R markdown, only the bare minimum I needed for a smooth coding experience.

When I discovered Pweave I started to think that this was possible. I therefore began personalizing my Atom installation to create the coding environment I was looking for. One note: I use a Mac, therefore some keybindings will be different in another OS.

This is the result so far. Below you can find how I got there.

Install Pweave and set up the Atom environment

conda install Pweaveapm install hydrogen         # interactive coding environment
# with single line/selection evaluation

apm install language-weave # for syntax highlighting
apm atom-html-preview # use ctrl-shift-h to preview
apm atom-shell-commands # to define shell commands with shortcuts

Set a keyboard shortcut to compile md into html

Following the documentation of atom-shell-commands, I created a shortcut (in my case Ctrl-2) to compile the Pweave .pmd (python markdown) document I am working on into html. To this aim I needed to modify the ~/.atom/config.cson file appending a proper command.

"atom-shell-commands":
commands: [
{
name: "pmd2html"
command: "pweave"
arguments: [
"-f"
"md2html"
"{FileName}"
]
options:
cwd: "{FileDir}"
keymap: 'ctrl-2'
}
]

View the live html inside atom

Using the functionality of atom-html-preview we can open the live preview of the HTML created by Pweave using the shortcut Ctrl-Shift-H. From this moment on, remember to leave open the rendered html document inside Atom.

Add a snippet to create an empty python code cell

Following the Atom snippets documentation I added a snippet to the ~/.atom/snippets.cson file:

'.source.pweave.md':
'insert python cell':
'prefix': 'pycell'
'body': """```python
$0
```"""

In my case, a new cell will be added when typying pycell-TAB(actually p+TAB since I don’t have other snippets starting with p). Of course you can use a prefix of your choice other than pycell.

Create an additional shortcut to insert an empty python code cell

If you are happy using the snippet, you don’t need to complete this step. I did it because I wanted to be able to insert an new empty python cell with the same shortcut I use to insert an empty R cell into RStudio (Alt+Cmd+i).
Using the valuable information found here I modified two Atom configuration files as follows:

Append the following to ~/.atom/init.coffee

atom.commands.add 'atom-text-editor',
'custom:insert-pycell': ->
atom.workspace.getActiveTextEditor()?.insertText("""```python
```""")

Append the following to ~/.atom/keymap.cson

'atom-text-editor':
'alt-cmd-i': 'custom:insert-pycell'

Then restart Atom.

Hydrogen code line/selection/chunk evaluation

One thing that I love in RStudio markdown is the possibility to evaluate either a code cell, a single line or a highligted selection of code. To achieve this no modification is needed, as this functionality is already implemented in Hydrogen:

  • single line/selection evaluation: Shift+Enter
  • code cell evaluation: Alt-Shift-Enter

I always missed the possibility of evaluating a single line or a selection of code in Jupyter notebooks, and I will be eternally grateful if somebody can let me know whether there is actually a way to do so and I never found it.

Background color in code chunks

This was for me the toughest part, since I don’t know Less. The code found here (thanks olmokramer!) helped a lot to have a specific color background only inside the Python cells, however I had a problem in that when selecting text inside the Python cell, the selection was not highlighted. After wandering for quite some time on the Less website, I finally found the fade function that allows me to see a properly highlighted selection. The following code need to be added to the ~/.atom/styles.less file.

atom-text-editor::shadow {
.line {
position: relative;
.embedded {
&::before {
position: absolute;
top: 0;
left: 0;
width: 100%;
height: 200%;
content: '';
display: block;
z-index: -1;
}
&.python::before {
background-color: fade(#bfbfbf, 20%);
}
}
}
}

A little black spot… (covered with a white space)

The code above in the ~/.atom/styles.less does not highlight empty lines. To have the whole code cell highlighted while editing, I need to leave a white space at the beginning of empty lines. However, even if I have empty lines in the .pmd document, the final code in the HTML file will still show the desired background color.

Start using the environment

Now that everything is set up I proceed as follows to start coding in my Python markdown environment (keyboard shortcuts and snippets according to the code above):

  • create a new .pmd file (e.g touch myPmdFile.pmd)
  • convert it to html using Ctrl-2
  • open a live preview of the html file using Ctrl-Shift-H
  • start editing as a normal markdown document
  • when you want to insert a Python code cell, use p-TAB or Alt-Cmd-i
  • evaluate the current line of code or a selection of code using Shift-Enter
  • evaluate the current code cell using Alt-Shift-Enter

The HTML file will not be updated until the next Ctrl-2 call, however the plots and tables will already be visible inline in the .pmd file, which is good enough for me.

Conclusion

I hope you enjoyed this little tutorial to create Python markdown notebooks similar to R markdown notebooks. If you found it useful, I would appreciate a clap :O)

Note that Pweave gives the possibilty to convert the .pmd file as a Jupyter notebook (as well as in a number of other formats). To do so, simply run the following from the bash prompt:

pweave -f markdown myPweaveNotebook.pmd

If anybody with experience with Less is aware of how to convince Atom to apply the background color also to empty lines, s/he will have my eternal gratitude.

Incurable Researcher of Beautiful Things

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store