Make your code consistent through style conventions. For interactive reading and executing code blocks 
and find b08-pystyle.ipynb, or install Python and JupyterLab locally.
Watch this section as a video
Watch this section as a video on the @Hydro-Morphodynamics channel on YouTube.
Atmen Sie tief ein, nehmen Sie aus und schauen Sie sich an, was Sie bisher aus einer neuen Perspektive gelernt haben. Nach diesem Kapitel lohnt es sich, einen weiteren Blick auf Ihren alten Code zu werfen und ihn robust zu formatieren. Die hier vorgestellten Style-Richtlinien gehen über visuelle Ästhetik und Hilfe beim Schreiben effektiver Code.
Hintergrund und PEP¶
Dieser Stilführer zeigt Teile des PEP 8 - Style Guide for Python Code von Guido van Rossum, Barry Warsaw und Nick Coghlan. Das vollständige Dokument ist unter python.org erhältlich und in diesem Kapitel sind nur Aspekte mit Relevanz für die in diesem eBook gezeigten Anwendungen aufgeführt.
Was ist ein PEP? PEP steht für Python Enhancement Proposal*. Ein PEP ist ein Designdokument, das der Python-Community Informationen zur Verfügung stellt oder eine vorgeschlagene Funktion, Prozess oder damit verbundene Änderung beschreibt. Es gibt viele PEPs, darunter Standards-Track-, Informations- und Prozessvorschläge. Dieses Kapitel zeigt Empfehlungen von PEP 8, der Stilführer für Python-Code, von Guido van Rossum, Barry Warsaw und Alyssa Coghlan.
Viele IDEs, einschließlich PyCharm oder VS-Code, bieten Auto-Vervollständigung und Tooltips mit PEP-Stil Anleitung, um konsequente Programmierung zu unterstützen. So, wenn Ihre IDE unterstreicht alles in Ihrem Skript, überprüfen Sie den Grund dafür und prüfen, den Code entsprechend zu ändern.
Das Zen von Python¶
Werden wir spirituell? Weit davon. Das Zen von Python ist ein Informationsblatt PEP (20) von Tim Peters, um Programmierer zu leiten. Es ist ein paar Linien, die gute Praxis bei der Codierung zusammenfassen. Python’s Easter Egg import this druckt das Zen von Python in jedem Python Dolmetscher:
import thisThe Zen of Python, by Tim Peters
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!
Code Layout¶
Maximale Linienlänge¶
PEP 8 empfiehlt, Codezeilen auf 79 Zeichen zu begrenzen. Der Text in Kommentaren und docstrings sollte auf 72 Zeichen beschränkt sein. Ein Team kann sich auf eine Codezeilengrenze von bis zu 99 Zeichen einigen, sofern Kommentare und Zeichen auf 72 Zeichen beschränkt bleiben.
Identifizierung¶
Indentation groups statements into suites controlled by constructs such as for, if, while, try, with, def, and class. PEP 8 recommends four spaces per indentation level. Indentation does not by itself create a new variable scope: names assigned in an if or for suite remain in the surrounding scope. Functions, classes, modules, and some comprehensions have their own scoping rules.
for i in range(1, 2):
print("I'm one level indented.")
if i == 1:
print("I'm two levels indented.")I'm one level indented.
I'm two levels indented.
Weil lange Zeilen von Code schlechte Praxis sind, müssen wir manchmal Zeilenumbrüche verwenden, wenn wir beispielsweise eine list zuweisen oder eine Funktion anrufen. In diesen Fällen wird auch die nächste, weiterführende Linie eingerückt und es gibt verschiedene Optionen, um Multi-Line-Beträge zu identifizieren. Hier möchten wir den Stilcode der Verwendung eines Öffnungsbegrenzers für die Einbuchtung verwenden:
a_too_long_word_list = ["Do", "not", "hard-code", "something", "like", "this.",
"There", "are", "better", "ways."]
a_better_indented_list = [
"Do",
"not",
"hard-code",
"something",
"like",
"this.",
"...",
]*Recall: PyCharm, VS-Code und viele andere IDEs automatisch Layout-Einbuchtung.
Line Breaks of Expressions mit binären Operatoren¶
Wenn binäre Operatoren Teil eines Ausdrucks sind, der die maximale Zeilenlänge von 79 Zeichen überschreitet, sollte der Zeilenbruch vor den binären Operatoren sein.
import pandas as pd
dummy_df = pd.get_dummies(
pd.Series(["variable1", "parameter2", "sensor3"]),
dtype=int,
)
print(dummy_df.head(3))
dum_sum = (
dummy_df["variable1"]
+ dummy_df["parameter2"]
- dummy_df["sensor3"]
)
parameter2 sensor3 variable1
0 0 0 1
1 1 0 0
2 0 1 0
Leere Linien¶
Um Code-Blöcke zu trennen, schlagen Sie den Enter Schlüssel oft ist eine sehr einladende Option. Die zufällige und stimmungsgesteuerte Verwendung von leeren Linien führt jedoch zu unstrukturiertem Code. Deshalb bieten PEP 8 Autoren auch Hinweise auf die Verwendung von Leerzeilen:
Surround-Klassendefinitionen und Top-Level-Funktionen (d.h. Funktionen, bei denen die
def-line nicht eingezeichnet ist) mit zwei Leerzeilen.Umgebungsmethoden (z.B. Funktionen innerhalb einer Klasse) mit einer leeren Linie.
Verwenden Sie leere Zeilen sparsam in allen anderen Code, um logische Abschnitte anzuzeigen.
# blank 1 before top-level function
# blank 2 before top-level function
def top_level_function():
pass
# blank 1 after top-level function
# blank 2 after top-level functionLeere (Weißräume)¶
Vermeiden Sie unnötigen Weißraum unmittelbar innerhalb von Klammern, Klammern oder Klammern; vor Kommas, Semikolonen und gewöhnlichen Kolonen; oder zwischen einem Funktionsnamen und seiner Argumentliste. Schreiben Sie function(e1, e2), (1,),a_dict = {a_key: a_value} und def fun(arg=0.0):.
Verwenden Sie Leerzeichen um Zuordnung, Vergleich und Boolean Operatoren. Für arithmetische Ausdrücke fügen Sie Leerzeichen um die niedrigsten Vorgänger und nutzen Sie das Urteil, um die Vorhergehende klar zu machen; zum Beispiel hypot2 = x*x + y*y.
Pakete und Module¶
Einfuhr¶
Importe erscheinen normalerweise nach dem Modul-Docstring und vor Modul global. Gruppen Sie sie in dieser Reihenfolge mit einer leeren Linie zwischen Gruppen: Standard-Bibliothek, verwandte Drittpakete, lokale Anwendung oder Bibliothek Importe. Normale Einfuhren auf getrennte Linien setzen und Wildcard-Importe vermeiden. Jeder Import sollte eine eigene Linie haben und die Verwendung des Kommazeichens für mehrere Importe vermeiden:
import os
import sys
import numpy as np
from my_package import my_moduleNamenspakete und Skript¶
Neue, benutzerdefinierte Pakete oder Module sollten kurze und All-Lowercase-Namen haben, wo Unterpunkte verwendet werden können, um die Lesbarkeit zu verbessern (für Pakete entmutigt).
Bemerkungen¶
Block und Inline Kommentare¶
Blockkommentare werden auf die gleiche Ebene wie der Code, den sie beschreiben, und jede Zeile beginnt mit # . Verwenden Sie Inline-Kommentare sparsam. Ein inline Kommentar erscheint auf der gleichen Zeile wie ein Statement, wird von ihm durch mindestens zwei Leerzeichen getrennt und beginnt mit # .
Ärzte¶
Ein Docstring ist ein String-Literal, das als erste Aussage in einem Modul, Funktion, Klasse oder Verfahren auftritt. Es wird über das Attribut __doc__ des Objekts verfügbar. PEP 257 empfiehlt dreifache doppelte Zitate. Zum Beispiel:
a_list = [1, 2]
print(a_list.__doc__)Built-in mutable sequence.
If no argument is given, the constructor creates a new empty list.
The argument must be an iterable if specified.
Beim Schreiben einer Python-Funktion werden die Docstrings unmittelbar nach der def ...-Linie mit dreifachen Doppelquoten eingeführt:
def let_there_be_light(*args, **kwargs):
"""Print a sunrise message and return `True`.
Args:
*args: Positional arguments accepted but not used.
**kwargs: Keyword arguments accepted but not used.
Returns:
`True` in all cases.
"""
print("Sunrise")
return True
print(let_there_be_light.__doc__)
Bright function accepting any input argument with indifferent behavior.
:param an_input_argument: STR or anything else
:param another_input_argument: FLOAT or anything else
:return: True (in all cases)
Beachten Sie, dass die Empfehlungen zu Docstrings mit PEP 257 anstatt PEP 8.
Bezeichnung Konventionen¶
Definition von Name Styles¶
Die Namenskonventionen verwenden die folgenden Stile (Quelle: python.org):
Klassen verwenden normalerweise CapWords, zum Beispiel
MyClass.Benutzerdefinierte Ausnahmeklassen folgen dem Klassen-naming-Übereinkommen und verwenden normalerweise den suffix
Error, wenn sie einen Fehler darstellen, z.B.ConfigurationError.Funktionen, Methoden und Variablen verwenden bei Bedarf kleinere Wörter, die durch Unterstriche getrennt werden.
Konstanten verwenden normalerweise Großbuchstaben, die durch Unterstriche getrennt werden, z.B.
WATER_DENSITY = 1000.
Einige variable Namensformate lösen ein bestimmtes Verhalten von Python aus:
_single_leading_underscoreVariablen geben einen schwachen internen Gebrauch an und werden nicht mitfrom module import *__double_leading_underscoreVariablen rufen den Namen mangling in den Klassen an (z.B. eine Methode namens__dluder KlasseMyClasswird in_MyClass__dlueingebunden)__double_leading_and_trailing_underscore__Variablen sind magic Objekte oder Attribute in benutzergesteuerten Namespaces (z.B.__init__oder__call__in Klassen)
Verwenden Sie nur dokumentierte magische Attribute und erfinden sie nie. Lesen Sie mehr über magische Methoden im Kapitel unter Python classes.single_trailing_underscore_Variablen werden verwendet, um Konflikte mit Python Keywords zu vermeiden (z.B.MyClass(class_='AnotherClass'))
Objektbezeichnungen¶
Verwenden Sie die oben definierten Stile für die Benennung von Python-Elementen wie folgt:
Klassen:
CamelCase(CapWords) nur Buchstaben wieMyClassKonstanten: Nur
UPPERCASEBuchstaben, bei denen Unterstriche die Lesbarkeit verbessern können (z.B. auf Modulebene verwenden, um WasserdichteRHO = 1000) zuzuweisen.Ausnahmen:
CamelCase(CapWords) Buchstaben nur (Ausnahmen sollten vordefiniert Error-Kurse sein; typischerweise verwenden Sie die suffixError(z.B.TypeError)Funktionen: Nur
lowercaseBuchstaben, bei denen Unterpunkte die Lesbarkeit verbessern können; manchmal giltmixedCase, um eine rückständige Kompatibilität der vorherrschenden Stile sicherzustellenMethoden (Klassenfunktion, nichtöffentlich):
_lowercaseBuchstaben nur mit einem führenden Unterpunkt, wo Unterpunkte die Lesbarkeit verbessern könnenMethoden (Klassenfunktion, öffentlich): Nur
lowercaseBuchstaben, bei denen Unterpunkte die Lesbarkeit verbessern könnenModule: Nur
lowercaseBuchstaben, wo Unterpunkte die Lesbarkeit verbessern könnenPakete: Nur
lowercaseBuchstaben, bei denen Unterstriche entmutigt werdenVariablen: Nur
lowercaseBuchstaben, wo Unterpunkte die Lesbarkeit verbessern könnenVariablen (global): Nur
lowercaseBuchstaben, bei denen Unterpunkte die Lesbarkeit verbessern können; beachten Sie, dass “global” nur innerhalb eines Moduls auf eine variable Nutzung beschränken sollte.
Mehr Code Style Empfehlungen¶
Um die Code-Kompatibilität und Programmeffizienz zu gewährleisten, bietet der PEP 8 Style Guide weitere allgemeine Empfehlungen (weitere Informationen in der Python docs):
Geben Sie bei der Erstellung einer benannten Funktion eine
def-Anweisung vor; geben Sie keinen Lambda-Ausdruck direkt einem Namen zu. Eine kurze Lambda kann bei direkter Weitergabe als Argument geeignet sein, z.B.items.sort(key=lambda item: item.name).Wenn Ausnahmen erwartet werden, verwenden Sie
try-exceptklauseln (siehe Abschnitt errors and exceptions).Stellen Sie sicher, dass Methoden und Funktionen Objekte konsequent zurückgeben, zum Beispiel:
import numpy as np
def a_function_with_return(x):
if x > 0:
return np.sqrt(x)
return np.nan