Org-Babel Cheat Sheet

The pattern I use to tangle (create an external code file) is:

• python as the language (since I'm not using it with an interactive session, no need for ipython)
• :noweb tangle is turned on from init.el so that I can substitute code defined elsewhere into the block
• :tangle <path to file>

  #+begin_src python :tangle literate_python/literate.py
    """A docstring for the literate.py module"""

    # imports
    import sys
    <<literate-main-imports>>

    # constants

    # exception classes

    # interface functions

    # classes


    <<LiterateClass-definition>>

    # internal functions & classes

    <<literate-main>>


    if __name__ == "__main__":
        status = main()
        sys.exit(status)
  #+end_src

Since I have :noweb tangle set, the substitions (e.g. <<literate-main-imports>>) don't get expanded in HTML/Latex output (although they do when you create the python file).

  """A docstring for the literate.py module"""

  # imports
  import sys
  <<literate-main-imports>>

If you want to show the substitutions when exporting use :noweb yes in the header.

  """A docstring for the literate.py module"""

  # imports
  import sys

The noweb substitution above (<<literate-main-imports>>) worked because there was a named-section (defined here) that it could use:

  #+name: literate-main-imports
  #+begin_src python
    from argparse import ArgumentParser
  #+end_src

The :results header argument declares how to handle what's returned from executing a code block. There are three classes of arguments and you can use up to one of each in the header.

This argument tells org-babel what to put in any exported HTML or Latex files.

Besides setting the language to plantuml you need to specify and output-file path and set :exports results so that the actual plantuml code won't be in the exported document but the diagram will.

#+begin_src plantuml :file literate_python/literateclass.png :exports results
skinparam monochrome true

LiterateClass : String who
LiterateClass : String ()
#+end_src

The main thing to remember for ob-ipython is that you need to run it as a :session. I didn't do it for most of the examples, but I've found since I first wrote this that using named sessions makes it a lot easier to work. Otherwise you might have more than one buffer with an org-babel document and they will be sharing the same ipython process, which can cause mysterious errors.

#+begin_src ipython :session session1
  # python standard library
  import os
#+end_src

When using pandas most of the methods produce values, but the info method instead prints to stdout so you have to specify this as the :results or it will popup a separate buffer with the output.

#+begin_src ipython :session session1 :results output
housing.info()
#+end_src

When you create figures, besides making sure that you use the %matplotlib inline magic, you also need to specify a file path where matplotlib can save the image.

#+BEGIN_SRC ipython :session session1 :file "images/ocean_proximity_count.png"
figure = seaborn.countplot(x="ocean_proximity", data=housing)
#+end_src

I'm using ob-ipython to use jupyter/ipython with org-babel so you have to install it (I used MELPA). In addition you need to install the python dependencies, the main ones being ipython and jupyter. Additionally, I use elpy (also from MELPA) which has its own dependencies. I think the easiest way to check and see what elpy dependencies you need is to install elpy (there's two components, an emacs one you install from melpa and a python component you install from pip) then run M-x elpy-config to see what's missing.

Since I mentioned ob-ipython and elpy I'll list what I have in my init.el file for elpy and org-babel.