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-TABorAlt-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.
