org-contrib/babel/languages: add doc for python
[worg.git] / org-contrib / babel / languages / ob-doc-python.org
1 #+OPTIONS:    H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
5 #+TITLE:      Python Source Code Blocks in Org Mode
6 #+AUTHOR:     Gary Oberbrunner
7 #+EMAIL:      garyo[at]oberbrunner[dot]com
8 #+LANGUAGE:   en
9 #+STYLE:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
10 #+LINK_UP:    ../languages.html
11 #+LINK_HOME:  http://orgmode.org/worg/
12 #+EXPORT_EXCLUDE_TAGS: noexport
13
14 #+name: banner
15 #+begin_html
16   <div id="subtitle" style="float: center; text-align: center;">
17   <p>
18   Org Mode support for <a href="http://python.org/">Python</a>
19   </p>
20   <p>
21   <a href="http://python.org/">
22   <img src="http://www.python.org/images/python-logo.gif"/>
23   </a>
24   </p>
25   </div>
26 #+end_html
27
28 * Template Checklist [10/12]                                       :noexport:
29   - [X] Revise #+TITLE:
30   - [X] Indicate #+AUTHOR:
31   - [X] Add #+EMAIL:
32   - [X] Revise banner source block [3/3]
33     - [X] Add link to a useful language web site
34     - [X] Replace "Language" with language name
35     - [X] Find a suitable graphic and use it to link to the language
36       web site
37   - [X] Write an [[Introduction]]
38   - [X] Describe [[Requirements%20and%20Setup][Requirements and Setup]]
39   - [X] Replace "Language" with language name in [[Org%20Mode%20Features%20for%20Language%20Source%20Code%20Blocks][Org Mode Features for Language Source Code Blocks]]
40   - [X] Describe [[Header%20Arguments][Header Arguments]]
41   - [X] Describe support for [[Sessions]]
42   - [ ] Describe [[Result%20Types][Result Types]]
43   - [ ] Describe [[Other]] differences from supported languages
44   - [X] Provide brief [[Examples%20of%20Use][Examples of Use]]
45 * Introduction
46 Python is a high-level, readable, interpreted language which can be
47 used for many common computing tasks.  It runs on most modern
48 operating systems.  Python source code blocks are fully supported in
49 Org Mode with a wide variety of Python-specific header arguments.
50
51 Python source code blocks in Org Mode can be used to define functions,
52 filter and analyze data, create graphics and figures, and produce
53 reproducible research papers.
54
55 * Requirements and Setup
56 Python source code blocks in Org Mode require a working python installation.
57 Python is included in Mac OS X and often in Gnu/Linux, and is easily
58 available for Windows.  Python installers are located at
59 the [[http://www.python.org/download/][Python download site]].
60
61 Org Mode supports graphical output for LaTeX and HTML documents using
62 [[http://matplotlib.org/][Matplotlib]].
63
64 To configure your emacs org-mode to use python, you'll need to ensure
65 that =org-babel-load-languages= includes an entry for it.
66 Typically, =org-babel-load-languages= will contain many entries.  The
67 example below omits other languages.
68
69 #+begin_src emacs-lisp :tangle yes
70   (org-babel-do-load-languages
71    'org-babel-load-languages
72    '((python . t)))
73 #+end_src
74
75 * Org Mode Features for Python Source Code Blocks
76 ** Header Arguments
77 *** Language-Specific Header Arguments
78  - =:results {output, value}=: Value mode is the default (as with
79    other languages).  In value mode you can use the following subtypes:
80     - =raw=: value is inserted directly
81     - =pp=: value is pretty-printed by python using =pprint.pformat(%s)=, then inserted
82     - =file=: value is interpreted as a filename to be interpolated
83       when exporting; commonly used for graphics output.
84  - =:preamble=: Preamble code, inserted before the body (not commonly
85    used).  Default is none.
86  - =:return=: Value to return (only when result-type is value, and not
87    in session mode; not commonly used).  Default is None; in
88    non-session mode use return() to return a value.
89
90 *** Common Header Arguments
91  - =:session [name]=: default is no session.
92  - =:var data=data-table=: Variables can be passed into python from org-mode tables as
93    scalars or lists.  See the org-mode manual for more details.
94  - =:exports {code, results, both, none}=: Standard babel option for what to export.
95
96 ** Sessions
97 Session mode is fully supported in python, including named sessions.
98 In session mode, each block is run in the same long-running python
99 interactive interpreter session, as if you had typed that block into
100 python.  You can have multiple sessions, all independent.
101
102 Sessions can be used to define functions, set up variables, and share
103 code between source blocks.
104
105 Session mode in python is slightly different from non-session mode,
106 because in session mode you are talking to a single "interactive"
107 python session.  In python's interactive mode, blank lines are
108 special: they indicate the end of an indented block.  So you have to
109 write your org-mode python a little differently when using session
110 mode.
111
112 Also, in non-session mode, the python code block will be wrapped in a
113 function, so to return a value (in =:results value= mode) you have to
114 use a =return= statement.  In session mode, the python code is
115 evaluated directly by the interpreter, not in a function context, and
116 the last statement's value will be automatically returned, so you must
117 _not_ use a =return= statement.
118
119  - Session mode:
120 #+begin_example
121 # blank lines not OK in indented blocks, and don't use return()
122 # Source block is passed directly to interactive python;
123 # value is value of _ at end.
124 #+begin_src python :session
125 def foo(x):
126   if x>0:
127     return x+1
128   else:
129     return x-1
130
131 foo(1)
132 #+end_src
133
134 #+RESULTS:
135 : 2
136 #+end_example
137
138  - Non-session mode:
139 #+begin_example
140 # blank lines OK in indented blocks, and use return()
141 # Entire source block will get indented and used as the body of main()
142 #+begin_src python
143 def foo(x):
144   if x>0:
145     return x+1
146
147   else:
148     return x-1
149
150 return foo(5)
151 #+end_src
152
153 #+RESULTS:
154 : 6
155 #+end_example
156
157 Finally, if you are using matplotlib for graphics, matplotlib uses an
158 "interactive" backend when started from an interactive python (as you
159 might expect).  So you have to set the backend explicitly to a PDF or
160 PNG or other file-exporting backend when using session mode.  See the
161 example at
162
163 #+begin_example
164 #+begin_src python :session :results file
165 import matplotlib
166 matplotlib.use('Agg')
167 import matplotlib.pyplot as plt
168 fig=plt.figure(figsize=(3,2))
169 plt.plot([1,3,2])
170 fig.tight_layout()
171 plt.savefig('images/myfig.pdf')
172 'images/myfig.pdf' # return this to org-mode
173 #+end_src
174
175 #+RESULTS:
176 [[file:images/myfig.pdf]]
177 #+end_example
178
179 ** Result Types
180    * =value=: Value results are the value of the last expression
181      evaluated in the code block.  This is found in session mode using
182      using the "_" special python interpreter variable.
183
184    * =output=: Output results come from whatever the python code prints on stdout.
185
186 * Examples of Use
187   - Hello World!
188 #+begin_example
189 #+begin_src python :results output
190 print "Hello, world!"
191 #+end_src python
192
193 #+RESULTS:
194 : Hello, world!
195
196 #+end_example
197
198   - Inline calling:
199 #+begin_example
200 Two plus two equals src_python{return(2+2)}
201 #+end_example
202 when exported, e.g. to HTML or LaTeX/PDF, becomes:
203 #+begin_example
204 Two plus two equals 4
205 #+end_example
206
207
208   - Extracting data from an org-mode table
209 #+begin_example
210 #+tblname: data_table
211 | a | 1 |
212 | b | 2 |
213 | c | 3 |
214 #+begin_src python :var val=1 :var data=data_table
215 # Return row specified by val.
216 # In non-session mode, use return to return results.
217 return(data[val])
218 #+end_src
219
220 #+RESULTS:
221 | b | 2 |
222
223 #+end_example
224
225   - Plotting
226 #+begin_example
227 #+begin_src python :results file
228 import matplotlib, numpy
229 matplotlib.use('Agg')
230 import matplotlib.pyplot as plt
231 fig=plt.figure(figsize=(4,2))
232 x=numpy.linspace(-15,15)
233 plt.plot(numpy.sin(x)/x)
234 fig.tight_layout()
235 plt.savefig('images/python-matplot-fig.png')
236 return 'images/python-matplot-fig.png' # return filename to org-mode
237 #+end_src
238
239 #+RESULTS:
240 [[file:images/python-matplot-fig.png]]
241
242 #+end_example
243 [[file:images/python-matplot-fig.png]]