Python Source Code Blocks in Org Mode

• :results {output, value}: Output results come from whatever the python code prints on stdout. Value results are the value of the last expression evaluated in the code block. Value mode is the default (as with other languages). In value mode you can use the following subtypes:
  • verbatim: value is returned as string. In particular, use this to prevent conversion of lists and tuples to tables.
  • table: (Org 9.7+) Try to convert the result to an Org table. Dicts, numpy arrays, and pandas DataFrames/Series can be returned as tables this way (by default, they are printed verbatim). Note that lists and tuples are already converted to table by default (use verbatim to prevent that).
  • pp: value is pretty-printed by python using pprint.pformat(%s), then inserted
• :results graphics file {output, value}: (Org 9.7+) save graphics with matplotlib. The behavior depends on whether value or output results are used. For value results, the last line should return a matplotlib Figure object to plot. For output results, the current figure (as returned by pyplot.gcf()) is cleared before evaluation, and then plotted afterwards. Specify the file to save the results to with :file.
• :return: Appends a return statement to the end of the code block. Only when result-type is value, and not in session mode.
• :python: Name of the command for executing Python code.

• :session [name]: default is no session.
• :var data=data-table: Variables can be passed into python from org-mode tables as scalars or lists. See the org-mode manual for more details.
• :exports {code, results, both, none}: Standard babel option for what to export.
• :file: Filename to save results to (e.g. for graphics).

# use return statement
# Entire source block will get indented and used as the body of main()
#+begin_src python
def foo(x):
  if x>0:
    return x+1

  else:
    return x-1

return foo(5)
#+end_src

#+RESULTS:
: 6

# don't use return statement
#+begin_src python :session
def foo(x):
  if x>0:
    return x+1
  else:
    return x-1

foo(1)
#+end_src

#+RESULTS:
: 2

A limitation of session-mode return values is that the final statement must be a top-level expression, otherwise nothing is returned.

For example, the code block below doesn't return anything, because the final expression is an indented if/else block, not a top-level expression:

#+begin_src python :session :results value
import random
if random.randint(0,10) % 2 == 0:
    "even"
else:
    "odd"
#+end_src

#+RESULTS:

To return the value of an indented block, assign the value to a variable, and return that variable as the final top-level expression:

#+begin_src python :session :results value
import random
if random.randint(0,10) % 2 == 0:
    ret = "even"
else:
    ret = "odd"
ret
#+end_src

#+RESULTS:
: even

To return plots, save the figure to a file, return the filename, and set the header argument :results file link.

For example:

#+begin_src python :session :results file link
import matplotlib
import matplotlib.pyplot as plt
fig=plt.figure(figsize=(3,2))
plt.plot([1,3,2])
fig.tight_layout()

fname = 'images/myfig.pdf'
plt.savefig(fname)
fname # return this to org-mode
#+end_src

#+RESULTS:
[[file:images/myfig.pdf]]

You can use noweb to reduce the boilerplate of saving and returning the filename; see the example below.

Depending on your Python and matplotlib installation details, you may have to set the backend explicitly to a PDF or PNG or other file-exporting backend when using session mode, for example by calling matplotlib.use('Agg'), for example:

#+begin_src python :results file link
import matplotlib, numpy
matplotlib.use('Agg')
import matplotlib.pyplot as plt
fig=plt.figure(figsize=(4,2))
x=numpy.linspace(-15,15)
plt.plot(numpy.sin(x)/x)
fig.tight_layout()
plt.savefig('images/python-matplot-fig.png')
return 'images/python-matplot-fig.png' # return filename to org-mode
#+end_src

#+RESULTS:
[[file:images/python-matplot-fig.png]]

Starting in Org 9.7, ob-python can automatically use matplotlib to save graphics results, using the header arg :results graphics file. The behavior depends on whether value or output results are used. For value results, the last line should return a matplotlib Figure object to plot. For output results, the current figure (as returned by pyplot.gcf()) is cleared before evaluation, and then plotted afterwards.

Here is an example using output results:

#+begin_src python :results graphics file output :file boxplot.svg
  import matplotlib.pyplot as plt
  import seaborn as sns
  plt.figure(figsize=(5, 5))
  tips = sns.load_dataset("tips")
  sns.boxplot(x="day", y="tip", data=tips)
#+end_src

And here is the same example using value results:

#+begin_src python :results graphics file value :file boxplot2.svg
  import matplotlib.pyplot as plt
  import seaborn as sns
  plt.figure(figsize=(5, 5))
  tips = sns.load_dataset("tips")
  sns.boxplot(x="day", y="tip", data=tips)
  return plt.gcf()
#+end_src

Prior to Org 9.7, returning a plot from a ob-python block requires saving the figure to a file and returning the filename. In the example below, we extract this to a separate block that can be referred to by other code blocks. The :noweb strip-export header argument means to allow noweb syntax, but to hide the inserted code during export.

#+name: savefig
#+begin_src python :var figname="plot.svg" width=5 height=5 :exports none
  return f"""plt.savefig('{figname}', width={width}, height={height})
  '{figname}'"""
#+end_src

#+header: :noweb strip-export
#+begin_src python :results value file link :session :exports both
  import matplotlib, numpy
  import matplotlib.pyplot as plt
  fig=plt.figure(figsize=(4,2))
  x=numpy.linspace(-15,15)
  plt.plot(numpy.sin(x)/x)
  fig.tight_layout()
  <<savefig(figname="plot.png", width=10, height=5)>>
#+end_src

In the below example, we use the external tabulate package to convert a pandas Dataframe into org-mode format, but wrap it in a noweb block so we can hide the conversion during export.

#+name: pd2org
#+begin_src python :var df="df" :exports none
  return f"return tabulate({df}, headers={df}.columns, tablefmt='orgtbl')"
#+end_src

#+header: :prologue from tabulate import tabulate
#+header: :noweb strip-export
#+begin_src python :results value raw :exports both
  import pandas as pd
  df = pd.DataFrame({
      "a": [1,2,3],
      "b": [4,5,6]
  })
  <<pd2org("df")>>
#+end_src

#+RESULTS:
|   | a | b |
|---+---+---|
| 0 | 1 | 4 |
| 1 | 2 | 5 |
| 2 | 3 | 6 |