Literate Programming mit Python und Emacs org-mode

Inhaltsverzeichnis

1. Einleitung
2. Ziele
3. Links
4. Pakete und Einstellungen
- 4.1. Python
- 4.2. Emacs und Python
5. org-mode
6. Python Skripte

1 Einleitung

Ich teste und untersuche hier, inwieweit mit Emacs org-mode und Python das „Literate Programming“ (nach Donald Knuth) möglich ist.

Weiterführenden Notizen zu Emacs und org-mode finden sich unter Emacs Notizen.

2 Ziele

Im Dokument einzelne Code-Stücke unabhängig ausführen, und eventuell das Ergebnis unter dem Code-Stück einfügen.
Einzelne Code-Stücke vom Ausführen beim Exportieren ausschließen.
Exportieren des Dokuments in verschiedene Formate.
Beim Exportieren
1. mit Code und Ergebnissen
2. mit Code ohne Ergebnisse
3. ohne Code mit Ergebnissen
4. ohne Code und ohne Ergebnissen
Exportieren und Ausführen als Code-Datei.

3 Links

Literate Programming
- https://de.wikipedia.org/wiki/Literate_programming
Python und Emacs org-mode
- http://orgmode.org/worg/org-contrib/babel/languages/ob-doc-python.html
- http://home.fnal.gov/~neilsen/notebook/orgExamples/org-examples.html
Python lernen
Andere IDEs für Python
- IDLE http://www.python.org/download/
- Geany http://www.geany.org/
- Netbeans http://www.netbeans.org/downloads
- Eclipse http://www.eclipse.org/downloads/
- Komodo Edit http://www.activestate.com/komodo-edit/downloads
- EricDE http://eric-ide.python-projects.org/eric-download.html

4 Pakete und Einstellungen

4.1 Python

Die Version von Python bei mir ist:

python --version

Python 3.5.2

Bei IPython ist es

ipython --version

5.1.0

4.2 Emacs und Python

Bei mir installiert ist Emacs in der Version

(emacs-version)

GNU Emacs 25.1.1 (x86_64-unknown-linux-gnu, GTK+ Version 3.20.9)
 of 2016-09-18

In Emacs habe ich die folgenden Pakete für die Arbeit mit Python geladen.

anaconda-mode: Code navigation, documentation lookup and completion for Python
auto-virtualenv: Auto activate python virtualenvs
company-jedi: company-mode completion back-end for Python JEDI
ein: Emacs IPython Notebook
elpy: Emacs Python Development Environment
flymake-python-…: A flymake handler for python-mode files using pyflakes (or flake8)
jedi: a Python auto-completion for Emacs
jedi-direx: Tree style source code viewer for Python buffer
nose: Easy Python test running in Emacs
ob-ipython: org-babel functions for IPython evaluation
pungi: Integrates jedi with virtualenv and buildout python environments
py-autopep8: Use autopep8 to beautify a Python buffer
py-import-check: Finds the unused python imports using importchecker
py-isort: Use isort to sort the imports in a Python buffer
py-smart-operator: smart-operator for python-mode
pydoc-info: Better Python support for info-lookup-symbol.
pyenv-mode: Integrate pyenv with python-mode
pyenv-mode-auto: Automatically activates pyenv version if .python-version file exists.
python: Python’s flying circus support for Emacs
python-docstring: Smart Python docstring formatting
python-info: Python info manual for Emacs
python-mode: Python major mode
python3-info: Python 3 info manual for Emacs
pythonic: Utility functions for writing pythonic emacs package.
pyvenv: Python virtual environment interface
virtualenv: Virtualenv for Python
python: Python’s flying circus support for Emacs

5 org-mode

5.1 Code Blöcke

Code Blöcke werden zwischen „Source Blocks“ eingeschlossen.

#+BEGIN_SRC python -n -r -k :var an_arg="Hallo" :exports both
  def testfunction(an_arg):
      """Eine Testfunktion.  Das Ergebnis wird unter dem Code-Block als
  \"RESULT\" ausgegeben.

      """
      return format("Das Argument \"%s\" wurde übergeben." % an_arg)


  return testfunction(an_arg)
#+END_SRC

#+RESULTS:
: Das Argument "Hallo" wurde übergeben.

Hier das Ergebnis, wenn es nicht in #+BEGIN_EXAMPLE und #+END_EXAMPLE eingerahmt wird.

1:   def testfunction(an_arg):
2:       """Eine Testfunktion.  Das Ergebnis wird unter dem Code-Block als
3:   \"RESULT\" ausgegeben.
4: 
5:       """
6:       return format("Das Argument \"%s\" wurde übergeben." % an_arg)
7: 
8: 
9:   return testfunction(an_arg)

Das Argument "Hallo" wurde übergeben.

Hinweis: Um den Code zu bearbeiten, ist es angenehm mit C-c ' in den Python-Editier-Modus zu wechseln. Dies erleichtert das Schreiben des Codes, insbesondere die Einrückung, doch sehr.

5.2 BEGIN_SRC Optionen

Der #+BEGIN_SRC Code-Block kennt meherere Optionen, die je nach Sprache variieren können. Da es hier um Python geht, beschränke ich mich darauf.

#+BEGIN_SRC <Sprache> <Optionen>
    Hier kommt der Code rein.
#+END_SRC

-n: Zur Nummerierung der Codezeilen.
-r: Damit auf die Codezeilen referenziert werden kann. !Funktioniert nur für HTML Export!.
-k: Zeigt die Referenzen im Code an.
:eval: Code-Block Evaluierung. Möglich sind never oder no für nie, query für eine Abfrage, never-export oder no-export falls die Evaluierung mit C-c C-c weiter möglich sein soll, query-export für eine Abfrage während des Exports.
org-confirm-babel-evaluate: Wenn in den org-mode Einstellungen org-confirm-babel-evaluate auf t (default) gesetzt ist, wird beim Exportieren abgefragt. Mit nil wird gar nicht mehr gefragt, sondern blind evaluiert.
:var: Die Variable wird an den Code weitergeleitet, und kann dort genutzt werden. (:var arg0="Hallo)
:exports: Der Code und das Ergebnis werden in das Dokument exportiert. Möglich sind none, code, results und both.
:tangle: Für das exportieren des Code-Blocks in die Code-Datei. Möglich sind no, yes und filename. Der Default-Wert ist no.
:session: Diese Code-Blöcke gehören zu einer „Session“ in dem Dokument. Somit muss nicht jeder Code-Block für sich alleine funktionsfähig sein.

5.3 Inline src Blöcke

Code-Blöcke können auch inline, d.h. innerhalb einer Zeile gesetzt werden. Ihr Ergebnis wird beim Exportieren dann direkt in das Ergebnis umgeandelt. Die Syntax dafür ist

src_<language>{<code>}

oder Optional mit Argumenten

src_<language>[<Argumente>]{<code>}

Dies ist ein Beispiel für inline Code-Blöcke.  
Das Ergebnis ist src_emacs-lisp[:var arg=2]{(/ 100.0 pi arg)}.

Dies ist ein Beispiel für inline Code-Blöcke. Das Ergebnis ist 15.915494309189533.

Das Ergebnis wird dabei verbatim ausgegeben.

5.4 Code-Block Namen nutzen

Code-Blöcke können mit Namen versehen werden. Anhand des Namens kann das Ergebnis eines Code-Blocks an ein anderen Code-Block weitergegeben werden.

!!! 
Da die Namen einzigartig (unique) sein müssen, sind im Beispiel drei
Unterstriche.  Die "echten" Namen haben zwei Unterstriche.
!!!

#+NAME: ___DieWahrheitIst
#+BEGIN_SRC emacs-lisp :exports none :eval no-exports
(* 21 2)
#+END_SRC

#+NAME: ___DieGanzeWahrheit
#+BEGIN_SRC emacs-lisp :var wahrheit=___DieWahrheitIst :exports none :eval no-exports
(print wahrheit)
#+END_SRC

Wenn man das inline macht, wird so das Ergebnis eines Code-Blocks in den Text eingefügt.

Die Wahrheit ist src_emacs-lisp[:var wahr=__DieWahrheitIst]{(print wahr)}.

Die Wahrheit ist 42.

Noch einfacher geht das ganze dann mit der Call-Funktion.

#+CALL: <name>(<Argumente>)
#+CALL: __DieGanzeWahrheit()

Die Ausgabe als #+RESULTS:

Und das ganze dann auch noch inline.

Die Wahrheit ist eine Zahl, und ihr Wert ist call___DieGanzeWahrheit().

Die Wahrheit ist eine Zahl, und ihr Wert ist 42.

5.5 Code Block in Tabelle nutzen

Erzeugen wir erst einmal einen Source Code Block.

#+NAME: py4tblformula
#+BEGIN_SRC python -n -r -k :var arg1=0 arg2=0 :exports none :eval no-export
return (arg1 * (arg2**2))**(1/2)
#+END_SRC

| Wert 1 | Wert 2 | Ergebnis |
|--------+--------+----------|
|      1 |      2 |          |
|      2 |      4 |          |
|      3 |      6 |          |
|      4 |      8 |          |
|      5 |     10 |          |
#+TBLFM: $3='(org-sbe "py4tblformula" (arg1 $1) (arg2 $2));%.2f

Das Ergebnis sieht dann so aus.

Wert 1	Wert 2	Ergebnis
1	2	2.00
2	4	5.66
3	6	10.39
4	8	16.00
5	10	22.36

5.6 Exportieren in ein Dokument

Um das Dokument als PDF, ODT, HTML u.ä. zu exportieren, gibt man das Kommando C-c C-e ein, um im dann auftauchenden Menü das gewünschte zu wählen.

5.7 Den Code als Python Datei exportieren

Mit dem Kommando org-babel-tangle (C-c C-v t) wird aus dem Dokument der getanglete Code in eine Python-Datei kopiert. Dafür werden nur die Code-Blöcke benutzt, bei denen tangle auf yes oder einen Dateinamen stehen.

5.8 org-confirm-babel-evaluate

Wenn ein Source Code Block evaluiert werden soll, muss das bestätigt werden (default). Das ein- und ausschalten kann über die Funktion erledigt werden. Mit M-x babel-confirm wird der Status zurückgegeben. Mit C-u M-x babel-confirm die Einstellung getoggelt.

(defun babel-confirm (flag)
  "Report the setting of org-confirm-babel-evaluate.  If invoked with
C-u, toggle the setting"
  (interactive "P")
  (if (equal flag '(4))
      (setq org-confirm-babel-evaluate (not org-confirm-babel-evaluate)))
  (message "Babel evaluation confirmation is %s"
           (if org-confirm-babel-evaluate "on" "off")))

6 Python Skripte

Hier einige Python-Skripte, die beim tanglen in verschiedene Code-Dateien exportiert werden.

6.1 klasse.py

Die Klasse wird mit

1: import klasse as mk

importiert.

6.1.1 Header

2:   #!/usr/bin/env python
3:   # coding: utf-8
4:   # python-n-org-mode.org[*Org Src python-n-org-mode.org[ python ]*]
5:   # 25.03.2016 Andreas Kruse

6.1.2 Imports

Es werden keine imports benötigt.

6:

6.1.3 class meineklasse

Hier wird die Klasse „meineklasse“ angelegt. Sie erbt nur von „object“, womit sie die grundlegenden Fähigkeiten einer Klasse besitzt.

 7:   class meineklasse(object):
 8:       """Documentation for meineklasse
 9:     
10:       """

6.1.3.1 def `init`

Bei der Initialisierung werden die beiden privaten Variabeln

__meinpfad (Zeile 12) und
__meinedaten (Zeile_13)

angelegt.

11:   def __init__(self):
12:       self.__meinpfad = ""
13:       self.__meinedaten = ""

6.1.3.2 def set_args

Mit dieser Funktion werden die beiden Variabeln __meinpfad und __meinedaten gesetzt.

14:   def set_args(self, pfad, daten):
15:       self.__meinpfad = pfad
16:       self.__meinedaten = daten

6.1.3.3 def get_args

Diese Funktion gibt die beiden Variabeln __meinpfad und __meinedaten zurück.

17:   def get_args(self):
18:       """Some not so useful comment to fill this space with words.
19:       """
20:       print(self.__meinpfad, ":", self.__meinedaten)
21:       return self.__meinedaten, self.__meinpfad

6.2 matplot-exercises.py

6.2.1 Header

1:   #!/usr/bin/env python
2:   # coding: utf-8
3:   # matplot-exercises.py
4:   # 24.03.2016 Andreas Kruse

6.2.2 Imports

1:   import numpy as np
2:   import matplotlib.pyplot as plt

6.2.3 Code

 1:   x = np.linspace(0, 10)
 2:   line,= plt.plot(x, np.sin(x), '--', linewidth=2)
 3: 
 4:   dashes = [10, 5, 100, 5]  # 10 points on, 5 off, 100 on, 5 off
 5:   line.set_dashes(dashes)
 6: 
 7:   # plt.show()
 8:   plt.savefig("./matplot-exercises.png")
 9:   plt.savefig("./matplot-exercises.pdf")
10:   print("matplot-exercises saved!")

6.2.4 Das Ergebnis

Hier das Ergebnis als Bild. Einmal als PNG, und einmal als PDF.

./code/matplot-exercises.pdf

6.3 parsen.py

Hier geht es um Python-Funktionen zum Parsen von Dateien.

6.3.1 Header

1: #!/usr/bin/env python
2: # coding: utf-8
3: # parsen.py
4: # 04.03.2016 Andreas Kruse

6.3.2 Imports

5:   import re

6.3.3 Code

Regular Expression (regexp) vorkompiliert, um die Zahlen aus folgendem String zu lesen.

6:   # dashes = [10, 5, 100, 5]  # 10 points on, 5 off, 100 on, 5 off
7:   reg = re.compile(r'\d+\s+(.*?)[,$]')

Hier das Suchen mit search().

 8:   print("\n---- reg.search ----\n")
 9:   for line in open('matplot-exercises.py', 'r'):
10:       mo = reg.search(line)
11:       if mo is not None:
12:           print(mo.group(1))

Als nächstes wird finditer() probiert.

13:   print("\n---- reg.finditer ----\n")
14:   for line in open('matplot-exercises.py', 'r'):
15:       moiter = reg.finditer(line)
16:       for mo in moiter:
17:           print(mo.group(0), mo.span())

Diesmal findall() auf ein etwas komplizierteren String angesetzt.

18:   print("\n---- Teststring ----\n")
19:   teststring = "Irgendwas vorher[Plot Name&String&[123456:irgendwastolles];Was auch immer noch kommt.;"
20:   teststring += "Irgendwas vorher[Plot Name&String&[123487:nochwastolles];Was auch immer noch kommt.;"
21:   teststring += "Irgendwas vorher[Plot Name&String&[213487:onchwastolles];Was auch immer noch kommt.;"
22:   teststring += "Irgendwas vorher[Plot Name&String&[132487:ncohwastolles];Was auch immer noch kommt.;"
23:   print(teststring, "\n")
24:   testreg = re.compile(r'Name&String&\[(.*?)\];')
25:   moall  = testreg.findall(teststring)
26:   print("FINDALL = ", moall)
27:   for found in moall:
28:       print(" - ", found)

Das Ergebnis der Tests.

---- reg.search ----

points on

---- reg.finditer ----

10 points on, (28, 41)
5 off, (42, 48)
100 on, (49, 56)

---- Teststring ----

Irgendwas vorher[Plot Name&String&[123456:irgendwastolles];Was auch immer noch kommt.;Irgendwas vorher[Plot Name&String&[123487:nochwastolles];Was auch immer noch kommt.;Irgendwas vorher[Plot Name&String&[213487:onchwastolles];Was auch immer noch kommt.;Irgendwas vorher[Plot Name&String&[132487:ncohwastolles];Was auch immer noch kommt.; 

FINDALL =  ['123456:irgendwastolles', '123487:nochwastolles', '213487:onchwastolles', '132487:ncohwastolles']
 -  123456:irgendwastolles
 -  123487:nochwastolles
 -  213487:onchwastolles
 -  132487:ncohwastolles

6.4 stringsearch.py

In Strings mit String-Methoden suchen.

6.4.1 Header

1:   #!/usr/bin/env python
2:   # stringsearch.py -- searching in strings with string methods
3:   # 07.02.2016 Andreas Kruse

6.4.2 Imports

Keine Imports.

6.4.3 Code

Als erstes benötigen wir die Eingabe des Nutzers von dem zu durchsuchenden String und dem String, der dort gesucht werden soll.

4:   s = raw_input('Enter source string: ')
5:   sub = raw_input('Enter substring: ')

Schnell mal schauen, ob der Suchstring im Quellstring vorhanden ist.

 6:   # The operator returns TRUE or FALSE
 7:   if sub in s:
 8:       print "´%s´ is a substring of ´%s´" % (sub, s)
 9:   else:
10:       print "´%s´ is NOT a substring of ´%s´" % (sub, s)

Die String-Funktion index gibt schon mehr Information her.

11:   # index, rindex return index (0-based), or raise ValueError:
12:   try:
13:       idx = s.index(sub)
14:       ridx = s.rindex(sub)
15:       print "´%s´.index(´%s´) == %d" % (s, sub, idx)
16:       print "´%s´.rindex(´%s´) == %d" % (s, sub, ridx)
17:   except ValueError:
18:       print "´%s´ doesn´t occur in ´%s´" (sub, s)

Bei der String-Funktion find gibt es kein ValueError.

19:   # find, rfind return index (0-based), or -1 if not found
20:   pos = s.find(sub)
21:   rpos = s.rfind(sub)
22:   print "´%s´.find(´%s´) == %d" % (s, sub, pos)
23:   print "´%s´.rfind(´%s´) == %d" % (s, sub, rpos)

Mit den String-Funktionen startswith und endswith testet man nur, ob der Suchstring am Anfang oder am Ende des Quellstrings vorkommt.

24:   # startswith, endswith return TRUE or FALSE
25:   print "´%s.startswith(´%s´) == " % (s, sub), s.startswith(sub)
26:   print "´%s.endswith(´%s´) == " % (s, sub), s.endswith(sub)

Die Funktion count gibt aus, wie oft der Suchstring im Quellstring vorkommt.

27:   # count returns number of non-overlapping occurences:
28:   print "´%s´ occurs %d times in ´%s´" % (sub, s.count(sub), s)

6.5 String split

Andere String-Methoden.

6.5.1 Header

1:   #!/usr/bin/env python
2:   # stringsplit.py -- searching in strings with string methods
3:   # 27.02.2017 Andreas Kruse

6.5.2 Imports