Funktionen

Funktion definieren

Die Programmierung wäre ein mühsames Geschäft, wenn man nur Anweisungen und Kontrollstrukturen zur Verfügung hätte, weil man so das Rad immer wieder neu erfinden müsste. So wie wir in der Mathematik vorgefertigte Berechnungen in Form von Funktionen (z. B. sin() oder cos()) benutzen, möchten wir in einem Programm wiederkehrende Aufgaben und Algorithmen zusammenfassen und beliebig oft nutzen können.

• Gewisse Berechnungen oder Aktionen benötigt man immer wieder
• Funktionen (functions) erlauben es, wiederverwendbare Folgen von Anweisungen zu schreiben

import math # Mathematische Funktionen laden

radius = 2.5
umfang = 2 * math.pi * radius

## Später im Programm
radius = 3.7
umfang = 2 * math.pi * radius

Das Beispiel zeigt das Problem deutlich: Die Berechnung des Umfangs erfolgt immer wieder nach demselben Muster. Hat man einen Fehler gemacht, muss man ihn an allen Stellen finden und beheben.

Die Bedeutung des import am Anfang des Programms wird im Kapitel zu Modulen erläutert. Hier sei nur erwähnt, dass es dafür sorgt, dass man auf die Konstante math.pi für π zugreifen kann.

In Python können wir mit einer Funktion eine beliebige Anzahl von Anweisungen zusammenfassen und wiederverwenden. Dazu hat eine Funktion

• einen Namen,
• eine Argumentliste und
• eine Rückgabe.

Der Name dient dazu, die Funktion später aufzurufen, d. h. wir sprechen Funktionen über ihren Namen an, so wie Sie in der Mathematik die Sinus-Funktion über den Namen sin ansprechen.

Die Argumentliste benutzen wir, damit Funktionen mit unterschiedlichen Eingabewerten arbeiten können. Auch das ist keine Überraschung, denn auch in der Mathematik nutzt uns eine Funktion wenig, wenn wir keine Werte übergeben können, z.b. sin(2π). Ein anderes Wort für Argument ist Parameter. Im Unterschied zu mathematischen Funktionen haben wir es bei der Programmierung oft mit Funktionen zu tun, die mehr als einen Parameter bekommen (z. B. range) oder gar keine Parameter haben.

Wenn eine Funktion mit ihrer Arbeit fertig ist, kann sie etwas zurückgeben, also eine Rückgabe machen. Python hat hier die Besonderheit (siehe unten), dass eine Funktion mehr als einen Wert zurückgeben kann. Die Rückgabe erfolgt mit dem Schlüsselwort return.

• Eine Funktionsdefinition wird mit dem Schlüsselwort def eingeleitet,
• gefolgt von einem Namen,
• einer Argumentliste (0–n Parameter)
• und einem Doppelpunkt :

def <NAME>(<ARG1>, <ARG2> ...):
    <ANWEISUNGEN>

def umfang(r):
    ergebnis = 2 * r * math.pi
    return ergebnis

Das Beispiel zeigt, wie die Berechnung des Umfangs in eine Funktion ausgelagert werden kann. Diese Funktion kann man dann überall verwenden, wo eine solche Berechnung benötigt wird:

r = 2.5
u = umfang(r)

# Später im Programm
r = 3.7
u = umfang(r)

Rückgabewerte

Das Schlüsselwort return dient dazu, eine Rückgabe aus der Funktion zu machen. Der Wert, den die Funktion zurückgeben möchte, wird nach dem return angegeben. So gibt z. B. return 5 den Wert 5 zurück oder return n den Wert, der aktuell in der Variable n steht.

• Mit return wird angegeben, was die Funktion zurückgeben soll
• Ohne return hat die Funktion den Rückgabewert None
• return beendet die Funktion

def wurzel(z):
    for n in range(0, 100):
        if n**2 == z:
            return n

    return -1

Eine Funktion kann beliebig viele (auch kein) return enthalten. Wenn das return-Statement ausgeführt wird, wird die Funktion sofort beendet und der Wert hinter dem return wird als Rückgabewert der Funktion an den Aufrufer geliefert.

def abs(x):
    if x >= 0:
        return x
    else:
        return -x

print(abs(-23)) # 23
print(abs(42)) # 42

Eine Verwendung mehrerer return in einer Funktion gilt bei manchen Programmierern als schlechter Stil. Sie folgen der "single-entry-single-exit"-Philosophie: Funktionen haben einen Einstiegspunkt (am Anfang) und einen Ausstiegspunkt (am Ende). Eine so gestaltete Funktion gilt bei ihnen als besser verständlich. Die abs-Funktion sähe nach dieser Schule wie folgt aus:

def abs(x):
    if x >= 0:
        result = x
    else:
        result = -x
    return result

print(abs(-23)) # 23
print(abs(42)) # 42

Funktionen müssen kein return enthalten. In diesem Fall geben sie auch keinen (echten) Wert zurück, sondern liefern None. None zeigt in Python das Fehlen eines Wertes an, so wie null in Java oder nil in Ruby.

def empty():
    pass

a = empty()
print(a) # -> None

Es gibt bei Funktionen eine Asymmetrie: Wieso kann eine Funktion beliebig viele Parameter (Argumente) bekommen, aber nur einen Rückgabewert haben. Das ist doch irgendwie unfair…

Glücklicherweise kann man in Python über einen kleinen Umweg Funktionen auch beliebig viele Werte zurückgeben lassen. Dazu verwendet man das automatische Auspacken von Werten aus Listen (zu Listen, siehe unten).

• Über das Packing/Unpacking (siehe Listen) kann eine Funktion auch mehrere Rückgabewerte zurückgeben

def multi_return():
    return (42, 23)

a, b = multi_return()
print(a) # -> 42
print(b) # -> 23

Die Funktion multi_return gibt zwar auch in diesem Beispiel nur einen Wert zurück, dieser ist aber vom Typ einer Liste, die mehrere Werte enthalten kann. Der Aufrufer kann dann die Elemente der Liste in einer Mehrfachzuweisung an die Variablen a und b zuweisen. Damit fühlt es sich für den Verwender der Funktion so an, als ob sie mehr als einen Wert zurückgeben könnte.

Der Verwender einer Funktion muss wissen, wie viele Werte sie zurückgibt, da es andernfalls zu einem Fehler kommt. Die Funktion sollte die Anzahl der Werte als in einer Weise dokumentieren, die für die Verwender unmissverständlich ist.

def multi_return():
    return (42, 23)

a, b, c = multi_return()

ValueError: not enough values to unpack (expected 3, got 2)

Funktionen aufrufen

In den Beispielen sieht man bereits, wie eine Funktion aufgerufen wird: Man verwendet den Namen der Funktion und gibt die Argumente in Klammern, durch Komma getrennt an.

• Eine Funktion wird über ihren Namen aufgerufen und den Parametern (entsprechend der Reihenfolge)

a = wurzel(2)
print(a) # -> -1

b = wurzel(4)
print(b) # -> 2

Dieses Beispiel ist relativ klar und sollte niemanden überraschen, der schon einmal mit mathematischen Funktionen zu tun hatte. Bei den Argumenten (Parametern) einer Funktion muss man allerdings etwas spitzfindig sein, und noch zwei Begriffe einführen, die für das Verständnis wichtig sind.

• Formalparameter Parameter bei der Definition der Funktion (Variablen)
• sind innerhalb der Funktion Variablen
• werden ein Mal definiert
• Aktualparameter aktueller Wert beim Aufruf der Funkion (Wert)
• Anzahl entspricht Formalparametern
• Belegen die Variablen mit Werten
• können von Aufruf zu Aufruf der Funktion variieren

Was bedeuten die beiden Begriffe Formal- und Aktualparameter genau? Nehmen wir eine Funktion als Beispiel:

def f(a, b, c):
    print(a, b, c)

Bei der Funktion f sehen wir drei Parameter: a, b, c. Diese sind die Formalparameter der Funktion. Wir kennen den Wert dieser Parameter nicht, da sie ihren Wert erst beim Aufruf der Funktion bekommen. Wir wissen nur, dass es beim Aufruf der Funktion drei Werte geben wird, die wir in den drei Parametern finden können. Die Parameter sind für uns also einfach nur Variablen, mit denen wir, wie mit jeder anderen Variable auch, hantieren können; die Werte interessieren uns nicht. Die Formalparameter legen also fest, wie viele Werte einer Funktion in der Parameterliste übergeben werden können.

Wenn wir die Funktion f aufrufen, z. B. mit f(1, 2, 3), dann legen wir die Werte fest, die innerhalb der Funktion in den Variablen a, b, c zu finden sind, nämlich 1, 2 und 3. Wir könnten die Funktion auch mit f("x", "y", "z") aufrufen und somit die Variablen a, b, c mit "x", "y", "z" belegen. Die konkreten Werte beim Aufruf der Funktion bezeichnen wir als Aktualparameter, weil sie die aktuelle Belegung der Variablen beim Funktionsaufruf bestimmen.

Eine Funktion hat nur einen Satz von Formalparametern, die bei der Definition der Funktion bestimmt werden. Sie kann aber beliebig viele Aktualparameter haben – nämlich jedes Mal, wenn sie aufgerufen wird.

Was passiert in folgendem Beispiel?

def f(a, b, c):
    print(a, b, c)

a = 1
b = 2
c = 3
f(a, b, c)

Hier hilft uns die strenge Unterscheidung zwischen Formal- und Aktualparametern weiter: Die Funktion f hat die drei Formalparameter a, b, c. Beim Aufruf tauchen auch wieder a, b und c auf. Dies sind aber die Aktualparameter und dass die Namen identisch sind ist Zufall – genaugenommen ist es kein Zufall, sondern hier aus didaktischen Gründen extra so gemacht.

Es passiert folgendes: Die Werte der Aktualparameter werden in die Variablen kopiert, die als Formalparameter angegeben sind. Es wird also geschaut, welchen Wert hat das a im Aktualparameter und dieser Wert (1) wird in den Parameter a der Funktion geschrieben. Dasselbe dann mit b und c.

Das Programm ist damit identisch mit einem Programm, das wie folgt aussieht:

def f(a, b, c):
    print(a, b, c)

x = 1
y = 2
z = 3
f(x, y, z)

Da die Werte der Aktualparameter in die Variablen der Formalparameter kopiert werden, ist es egal, wie die Aktualparameter heißen.

Übergabe von Daten an Funktionen erfolgt per Wertübergabe (pass by value) (im Gegensatz zu Referenzübergabe (pass by reference))

• Wert des Aktualparameters wird kopiert
• Methode arbeitet auf einer Kopie
• Wert beim Aufrufer bleibt unverändert

Dies gilt auch für Referenzvariablen

Die Wertübergabe hat zur Konsequenz, dass eine Funktion den Wert der Variablen, die beim Aufrufer als Aktualparameter benutzt wurden, nicht verändern kann.

def change(a):
    a = a + 1

a = 3
change(a)
print(a) # -> 3

Vararg-Funktion

Funktionen können beliebig viele Parameter bekommen aber wir müssen bei der Definition der Funktion angeben, welche Formalparameter sie hat. Wir müssen also wissen, wie viele Parameter diese eine konkrete Funktion bekommen soll.

Wieso ist es dann möglich, die print-Funktion mal mit einem print("Hello") und mal mit mehr Parametern aufzurufen print(1, 2, 3)? Die Antwort ist, dass man Funktionen schreiben kann, bei denen man die Anzahl der Formalparameter nicht kennt.

• Wenn die Funktion beliebig viele Parameter annehmen soll, kann man einen *-Parameter definieren
• Die Werte werden dann als Liste (siehe unten) übergeben

def max(*a):
    result = a[0]
    for i in a:
        if result < i:
            result = i
    return result

max(3) # -> 3
max(4, 3) # -> 4
max(4, 3, 5) # -> 5

Eine Funktion, die man mit beliebig vielen Argumenten aufrufen kann, bezeichnet man als Vararg-Funktion, für variable arguments. Will man ein solches Verhalten, muss man einen Formalparameter am Ende der Parameterliste mit einem * kennzeichnen. Alle verbliebenen Aktualparameter werden dann in eine Liste verpackt und diesem Parameter zugewiesen.

def f(a, *b):
    print(a, b)

f(1)
f(1, 2)
f(1, 2, 3)
f(1, 2, 3, 4)

1 ()
1 (2,)
1 (2, 3)
1 (2, 3, 4)

Man sieht, dass alle Aktualparameter (außer dem ersten) als Liste im Parameter b zu finden sind.

Die einzelnen Elemente der Liste kann man mit der entsprechenden Syntax (siehe unten) aus der Liste extrahieren.

Named Arguments

Bei Skriptsprachen findet keine Überprüfung der Typen von Aktualparametern beim Aufruf einer Funktion statt. Wenn die Typen nicht zu dem passen, was im Inneren der Funktion passiert, dann kommt es erst zur Laufzeit zu einem Fehler. Der Aufrufer muss also wissen, welche Typen eine Funktion bei den jeweiligen Parametern verarbeiten kann.

def printer(text, wert):
    print(text.format(wert, wert**2))

printer("{}^2 = {}", 8) # -> 8^2 = 64
printer("8, {}^2 = {}") # Fehler
# TypeError: printer() missing 1 required positional argument: 'wert'

Ein weiteres Problem ist, dass Funktionen mit langen Parameterlisten schnell unübersichtlich werden. Leicht vertauscht man einen Parameter oder vergisst ihn beim Aufruf.

Die genannten Probleme lassen sich vermeiden, wenn man die Parameter nicht über ihre Position, sondern über ihren Namen adressiert.

• Es ist möglich anstatt der Reihenfolge auch die Namen der Parameter im Aufruf zu verwenden: Benannte Argumente (named arguments)

def potenz(basis, exponent):
    return basis ** exponent

# Positionale Parameter
a = potenz(2, 4) # -> 16

# Benannte Parameter
b = potenz(exponent = 4, basis = 2) # -> 16

Das Beispiel zeigt, dass man eine Python-Funktion sowohl aufrufen kann, indem man die Aktualparameter der Reihe nach angibt als auch die Parameter explizit über ihren Namen anspricht. Verwendet man den Namen, spielt die Reihenfolge keine Rolle mehr.

Default Argumente

Wenn ein Formalparameter definiert ist, dann muss er beim Aufrufen mit einem Wert belegt werden. Das ist aber nicht immer komfortable, weil es Funktionen gibt, bei denen man Standardwerte hat, die man nur ab und zu übersteuern möchte.

Ein solches Beispiel wäre eine Logarithmus-Funktion, die normalerweise den Logarithmus zur Basis e bestimmen soll, es sei denn, der Verwender gibt eine andere Basis an. Dieses Problem könnte man lösen, indem man zwei Funktionen anbietet:

def log_e(x):
    # ...

def log(basis, x):
    # ...

Dieser Ansatz ist aber nicht sehr elegant.

Python bietet als Lösung an, dass man Parameter mit Standardwerten belegen kann. Wird ein Parameter nicht belegt, hat er den Standardwert.

• Parameter von Methoden können mit Standardwerten (default values) belegt werden
• Gibt der Aufrufer keinen Wert an, wird der Standardwert verwendet
• Über benannte Argumente kann jeder Parameter ausgewählt werden

def potenz(basis = 2, exponent = 1):
    return basis ** exponent

# Positionale Parameter
a = potenz() # -> 2
b = potenz(4) # -> 4
c = potenz(2, 4) # -> 16

# Benannte Parameter
d = potenz(exponent = 8) # -> 256

Das Beispiel zeigt, wie man die Funktion potenz mit keinem, einem oder zwei Parametern aufrufen kann. Wird der Parameter nicht belegt, dann wird einfach der Standardwert (2 für basis bzw. 1 für exponent) verwendet.

Die Standardwerte funktionieren auch, wenn man benannte Argumente verwendet, wie die letzte Zeile im Beispiel zeigt.

Funktionen sind Objekte

Ein komplexeres Feature von Python ist, dass Funktionen selbst wieder Objekte sind; der Objektbegriff wird später noch erläutert. Man kann Funktionen also in Variablen speichern und an andere Funktionen übergeben.

def p(x):
    print(x)

f = p
print(f) # -> <function p at 0x7f0842a78dc0>
p("Hallo") # -> Hallo

Das Beispiel definiert eine Funktion p und weist diese dann der Variable f zu. Die Funktion, auf welche die Variable f zeigt, kann man mit dem ()-Operator aufrufen. () wird auch als Aufrufoperator bezeichnet.

• Alles in Python ist ein Objekt, auch Funktionen
• Man kann Funktionen an Funktionen übergeben (später mehr dazu)

def twice(f, x):
    return f(f(x))

def quadriere(x):
    return x*x

print(twice(quadriere, 2))

16

Im Beispiel ruft die Funktion twice einfach die ihr übergebene Funktion f zweimal mit dem Parameter x auf. Hierbei wird das Ergebnis des ersten Aufrufs an den zweiten übergeben (f(f(x))). twice ist es hierbei egal, was die übergebene Funktion macht.

Man kann sie mit jeder anderen Funktion aufrufen, die einen Wert nimmt:

def hello(name):
    return "Hallo {}".format(name)

print(twice(hello, "Thomas"))

Hallo Hallo Thomas

Gültigkeitsbereich

Wenn wir in einem Programm (außerhalb von Funktionen) mit Variablen arbeiten, dann ist die Variable von ihrer ersten Zuweisung (Definition) bis zum Ende des Programms sichtbar und kann benutzt werden. Der Gültigkeitsbereich der Variable recht also von der Definition bis zum Ende des Programms.

Wenn jetzt Funktionen ins Spiel kommen, verändert sich die Situation. Es wäre sehr unpraktisch, wenn Variablen innerhalb von Funktionen genauso behandelt würden, wie die außerhalb. Sehr schnell hätten wir das Problem, dass uns keine neuen Namen mehr einfallen und der Speicher voller unnützer Variablen wäre. Deswegen werden Funktionen besonders behandelt.

• Der Gültigkeitsbereich (scope) einer Variable gibt an, wo sie sichtbar und verwendbar ist
• Variablen in Funktionen sind nur in diesen sichtbar und gültig
• Können denselben Namen wie Variablen außerhalb der Funktion haben

x = 1

def add_one(x):
    x = x + 1 # lokales x
    return x

y = add_one(x)
# x = 1, y = 2

In diesem Beispiel sehen wir eine Variable x, die außerhalb der Funktion definiert wurde. Die Funktion selbst hat einen Parameter, der ebenfalls x heißt und der innerhalb der Funktion wie eine Variable benutzt werden kann. Die Namensgleichheit ist hier egal, es handelt sich um zwei vollkommen unterschiedliche Variablen. Schreiben wir das Programm um, um das deutlicher zu machen:

g = 1

def add_one(l):
    l = l + 1
    return l

y = add_one(g)
# g = 1, y = 2

Die Variable g ist global und ihr Gültigkeitsbereich erstreckt sich von der Zeile g = 1 bis zum Ende des Programms, es handelt sich um eine globale Variable. Die Variable l ist nur innerhalb der Funktion add_one gültig. Nachdem die Funktion beendet wurde, wird die Variable verworfen. Dasselbe gilt für alle weiteren Variablen, die in einer Funktion definiert werden. Schreiben wir add_one um zu

def add_one(l):
    k = l + 1
    return k

dann hat die Funktion jetzt zwei lokale Variablen, nämlich l und k, die nur in der Funktion gelten. Es gilt als schlechter Programmierstil, die Parameter einer Funktion innerhalb der Funktion zu verändern, sodass das obige Beispiel von vielen Entwicklerinnen als das bessere angesehen würde.

Jeder Versuch, auf die lokalen Variablen einer Funktion außerhalb dieser zuzugreifen, führt zu einer Fehlermeldung:

def f():
  l = 3

f()
print(l) # Error
# NameError: name 'l' is not defined

Schlüsselwort global

Globale Variablen sind überall im Programm sichtbar, also auch in den Funktionen.

g = "global"

def f():
  print(g)

f() #-> global

Python verbietet aber standardmäßig, dass eine Funktion den Wert einer globalen Variable ändert, weil dies eine häufige Quelle von schwer zu findenden Fehlern ist. Ein Schreibzugriff erzeugt einfach eine neue, lokale Variable mit demselben Namen, wie das folgende Beispiel zeigt.

g = "global"

def f():
  g = "lokal"

f()
print(g) #-> global

• Globale Variablen sind in Funktionen sichtbar, können aber nicht verändert werden → Zuweisung legt eine neue lokale Variable an
• Mit dem Schlüsselwort global können globale Variablen in Funktionen zugewiesen werden (Vorsicht!)

x = 0

def incr_x():
    x = x + 1 # Fehler

def incr_x2():
    global x
    x = x + 1 # funktioniert

Die Funktion incr_x() kann man nicht aufrufen, weil Python einen Fehler meldet ("UnboundLocalError: local variable 'x' referenced before assignment"). Das Problem ist, dass die Zuweisung x = eine neue lokale Variable x erzeugt, die dann aber rechts der Zuweisung auftaucht, bevor sie einen Wert hatte.

Der Ausweg aus dem Problem ist, die globale Variable mit dem Schlüsselwort global in der Funktion zu kennzeichnen. Damit wird sie schreibbar und eine Zuweisung legt keinen neue, lokale Variable mit demselben Namen an, sondern verwendet wirklich die globale Variable.

g = "global"

def f():
  global g
  g = "lokal"

f()
print(g) #-> lokal

Funktionen in Funktionen

Variablen können sowohl global, als auch lokal sein. Lokale Variablen sind nur in der jeweiligen Funktion sichtbar, in der sie definiert wurden.

Analog kann man auch Funktionen in Funktionen definieren. Diese sind dann ebenfalls nur innerhalb der jeweiligen Funktion sichtbar und können auch nur dort aufgerufen werden.

• Funktionen können Funktionen enthalten (analog zu Variablen)

def function1(x):
    def function2(y):
        print(y + 2)
        return y + 2
    return 3 * function2(x)

a = function1(2) # 4
print(a) # 12

b = function2(2.5) # error: undefined name

Die Funktion function2 ist innerhalb von function1 definiert und nur dort sichtbar. Der Versuch, sie von außerhalb mit b = function2(2.5) aufzurufen führt deswegen zu einem Fehler. Innerhalb von function1 kann man sie aber problemlos nutzen.

Lambda

Die Syntax, um Funktionen in Python zu definieren ist relativ kompakt. Trotzdem braucht man selbst für eine einfache Additionsfunktion zwei Zeilen und die Schlüsselwörter def und return. Für kurze, einfache Funktionen, gibt es deswegen die Möglichkeit, ein sogenanntes Lambda zu verwenden.

• Für kurze Funktionen (mit nur einem Ausdruck) steht mit dem Lambda eine verkürzte Schreibweise zur Verfügung

# Klassische Funktionsdefinition
def add(a, b):
    return a + b

## Definition über Lambda
add2 = lambda a, b: a + b

print(add(1, 2)) # -> 3
print(add2(2, 3)) # -> 5

Die Syntax für ein Lambda ist:

lambda <ARGUMENTLISTE>: <AUSDRUCK>

Es ist kein return notwendig, weil das Ergebnis des Ausdrucks <AUSDRUCK> als Rückgabewert aus dem Lambda geliefert wird.

Präzise muss man sagen, dass lambda ein namenloses Funktionsobjekt erzeugt, das man dann über eine Zuweisung an eine Variable zuweist. Der Ausdruck add2 = lambda a, b: a + b besteht somit aus zwei Teilen

• erzeugen eines Funktionsobjektes mit lambda a, b: a + b
• zuweisen des Objektes an eine Variable add2 = ...

Die vielfältigen Anwendungen von Lambdas sprengen den Rahmen dieser Vorlesung. Sie sind aber ein wichtiges Element für die funktionale Programmierung in Python, die wir bei den Listen noch einmal sehen werden. Dort findet sich das folgende Beispiel:

filme = [ 'Pulp Fiction', 'Kill Bill', 'Reservoir Dogs' ]
filme_gross = list(map(lambda f: f.upper(), filme))

print(filme_gross)
# -> ['PULP FICTION', 'KILL BILL', 'RESERVOIR DOGS']

Hier sieht man, wie ein Lambda benutzt wird, um eine Funktion auf die Elemente einer Liste anzuwenden.

Docstring

Wir haben schon an einigen Stellen gesehen, dass die Verwenderin einer Funktion wissen muss, was die Funktion genau macht, welche Bedeutung die Parameter haben und welche(n) Rückgabewert(e) die Funktion haben wird. Da es viel zu mühselig wäre, dies immer aus dem Quelltext der Funktion zu schließen, werden Funktionen in Python mit einer entsprechenden Dokumentation versehen, dem Docstring.

Funktionen sollten dokumentiert werden, damit

• andere sie korrekt benutzen können
• Sie sich nach drei Monaten noch erinnern können, was sie machen

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    ...

Der Docstring wird durch drei Anführungszeichen (""") eingeleitet und durch dieselbe Markierung wieder beendet. Zwischen den Markierungen beschreibt man, das die Funktion macht, welche Parameter mit welcher Bedeutung sie hat und was sie zurückgeben wird.

• Die Informationen aus dem Docstring können über help(FUNKTIONSNAME) ausgegeben werden

>>> help(complex)

Help on function complex in module __main__:

complex(real=0.0, imag=0.0)
    Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

Ein Beispiel aus der Python-Bibliothek für die print-Funktion:

>>> help(print)

Help on built-in function print in module builtins:

print(...)
    print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)

    Prints the values to a stream, or to sys.stdout by default.
    Optional keyword arguments:
    file:  a file-like object (stream); defaults to the current sys.stdout.
    sep:   string inserted between values, default a space.
    end:   string appended after the last value, default a newline.
    flush: whether to forcibly flush the stream.