Einrückung

Verwenden Sie 4 Leerzeichen pro Einrückungsebene.

Fortsetzungszeilen sollten entweder vertikal ausgerichtet sein, indem die implizite Zeilenfortsetzung von Python innerhalb von Klammern, eckigen Klammern und geschweiften Klammern verwendet wird, oder durch eine *hängende Einrückung* [1]. Bei der Verwendung einer hängenden Einrückung sollten folgende Punkte beachtet werden: Es sollten keine Argumente in der ersten Zeile stehen und eine weitere Einrückung sollte verwendet werden, um sie klar als Fortsetzungszeile zu kennzeichnen.

# Correct:

# Aligned with opening delimiter.
foo = long_function_name(var_one, var_two,
                         var_three, var_four)

# Add 4 spaces (an extra level of indentation) to distinguish arguments from the rest.
def long_function_name(
        var_one, var_two, var_three,
        var_four):
    print(var_one)

# Hanging indents should add a level.
foo = long_function_name(
    var_one, var_two,
    var_three, var_four)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

Die 4-Leerzeichen-Regel ist für Fortsetzungszeilen optional.

Optional

# Hanging indents *may* be indented to other than 4 spaces.
foo = long_function_name(
  var_one, var_two,
  var_three, var_four)

Wenn der bedingte Teil einer if-Anweisung lang genug ist, um über mehrere Zeilen geschrieben werden zu müssen, ist es erwähnenswert, dass die Kombination aus einem zweistelligen Schlüsselwort (d. h. if), plus einem Leerzeichen, plus einer öffnenden Klammer eine natürliche 4-Leerzeichen-Einrückung für die nachfolgenden Zeilen der mehrzeiligen Bedingung erzeugt. Dies kann zu einem visuellen Konflikt mit der eingerückten Code-Suite führen, die in die if-Anweisung verschachtelt ist, die ebenfalls natürlich auf 4 Leerzeichen eingerückt wäre. Dieses PEP nimmt keine explizite Stellung dazu, wie (oder ob) solche bedingten Zeilen visuell von der verschachtelten Suite innerhalb der if-Anweisung unterschieden werden sollen. Akzeptable Optionen in dieser Situation sind unter anderem:

# No extra indentation.
if (this_is_one_thing and
    that_is_another_thing):
    do_something()

# Add a comment, which will provide some distinction in editors
# supporting syntax highlighting.
if (this_is_one_thing and
    that_is_another_thing):
    # Since both conditions are true, we can frobnicate.
    do_something()

# Add some extra indentation on the conditional continuation line.
if (this_is_one_thing
        and that_is_another_thing):
    do_something()

(Siehe auch die Diskussion, ob vor oder nach binären Operatoren umgebrochen werden soll.)

Die schließende geschweifte Klammer/eckige Klammer/runde Klammer bei mehrzeiligen Konstrukten kann entweder unter dem ersten Nicht-Leerzeichen-Zeichen der letzten Zeile der Liste ausgerichtet werden, wie in

my_list = [
    1, 2, 3,
    4, 5, 6,
    ]
result = some_function_that_takes_arguments(
    'a', 'b', 'c',
    'd', 'e', 'f',
    )

oder sie kann unter dem ersten Zeichen der Zeile ausgerichtet werden, die den mehrzeiligen Konstrukt beginnt, wie in

my_list = [
    1, 2, 3,
    4, 5, 6,
]
result = some_function_that_takes_arguments(
    'a', 'b', 'c',
    'd', 'e', 'f',
)

Tabs oder Leerzeichen?

Leerzeichen sind die bevorzugte Einrückungsmethode.

Tabs sollten ausschließlich verwendet werden, um mit bereits mit Tabs eingerücktem Code konsistent zu bleiben.

Python verbietet das Mischen von Tabs und Leerzeichen für die Einrückung.

Maximale Zeilenlänge

Beschränken Sie alle Zeilen auf maximal 79 Zeichen.

Für fließende lange Textblöcke mit weniger strukturellen Einschränkungen (Docstrings oder Kommentare) sollte die Zeilenlänge auf 72 Zeichen beschränkt werden.

Die Begrenzung der erforderlichen Editorfensterbreite ermöglicht es, mehrere Dateien nebeneinander zu öffnen, und funktioniert gut bei der Verwendung von Code-Review-Tools, die die beiden Versionen in benachbarten Spalten darstellen.

Die Standard-Zeilenumbrüche in den meisten Tools stören die visuelle Struktur des Codes und erschweren dessen Verständnis. Die Limits sind so gewählt, dass sie bei einer Fensterbreite von 80 keine Umbrüche verursachen, selbst wenn das Tool beim Umbrechen von Zeilen ein Markierungszeichen in der letzten Spalte platziert. Einige webbasierte Tools bieten möglicherweise überhaupt keine dynamischen Zeilenumbrüche.

Einige Teams bevorzugen eine längere Zeilenlänge. Für Code, der ausschließlich oder hauptsächlich von einem Team gepflegt wird, das sich bei diesem Thema einigen kann, ist es in Ordnung, die Zeilenlängenbegrenzung auf bis zu 99 Zeichen zu erhöhen, vorausgesetzt, Kommentare und Docstrings werden weiterhin bei 72 Zeichen umbrochen.

Die Python-Standardbibliothek ist konservativ und verlangt die Begrenzung von Zeilen auf 79 Zeichen (und Docstrings/Kommentare auf 72).

Die bevorzugte Methode zum Umbrechen langer Zeilen ist die Verwendung der impliziten Zeilenfortsetzung von Python innerhalb von Klammern, eckigen Klammern und geschweiften Klammern. Lange Zeilen können über mehrere Zeilen umbrochen werden, indem Ausdrücke in Klammern gesetzt werden. Diese sollten der Verwendung eines Backslashs zur Zeilenfortsetzung vorgezogen werden.

Backslashes können immer noch angebracht sein. Beispielsweise konnten lange, mehrfache with-Anweisungen vor Python 3.10 keine implizite Fortsetzung verwenden, daher waren Backslashes für diesen Fall akzeptabel.

with open('/path/to/some/file/you/want/to/read') as file_1, \
     open('/path/to/some/file/being/written', 'w') as file_2:
    file_2.write(file_1.read())

(Siehe die vorherige Diskussion über mehrzeilige if-Anweisungen für weitere Gedanken zur Einrückung solcher mehrzeiliger with-Anweisungen.)

Ein weiterer solcher Fall sind assert-Anweisungen.

Stellen Sie sicher, dass die fortgesetzte Zeile entsprechend eingerückt ist.

Soll eine Zeile vor oder nach einem binären Operator umgebrochen werden?

Jahrzehntelang war der empfohlene Stil, nach binären Operatoren umzubrechen. Dies kann jedoch die Lesbarkeit auf zwei Arten beeinträchtigen: Die Operatoren werden tendenziell über verschiedene Spalten auf dem Bildschirm verstreut und jeder Operator wird von seinem Operanden weg und auf die vorhergehende Zeile verschoben. Hier muss das Auge zusätzliche Arbeit leisten, um zu erkennen, welche Elemente addiert und welche subtrahiert werden.

# Wrong:
# operators sit far away from their operands
income = (gross_wages +
          taxable_interest +
          (dividends - qualified_dividends) -
          ira_deduction -
          student_loan_interest)

Um dieses Lesbarkeitsproblem zu lösen, folgen Mathematiker und ihre Verleger der entgegengesetzten Konvention. Donald Knuth erklärt die traditionelle Regel in seiner Serie Computers and Typesetting: „Während Formeln innerhalb eines Absatzes immer nach binären Operationen und Relationen umgebrochen werden, werden angezeigte Formeln immer vor binären Operationen umgebrochen“ [3].

Das Folgen der Tradition aus der Mathematik führt normalerweise zu lesbarerem Code.

# Correct:
# easy to match operators with operands
income = (gross_wages
          + taxable_interest
          + (dividends - qualified_dividends)
          - ira_deduction
          - student_loan_interest)

In Python-Code ist es zulässig, vor oder nach einem binären Operator umzubrechen, solange die Konvention lokal konsistent ist. Für neuen Code wird Knuths Stil vorgeschlagen.

Leerzeilen

Umschließen Sie Funktions- und Klassendefinitionen auf Top-Level-Ebene mit zwei Leerzeilen.

Methodendefinitionen innerhalb einer Klasse werden von einer einzelnen Leerzeile umgeben.

Zusätzliche Leerzeilen können (sparsam) verwendet werden, um Gruppen verwandter Funktionen zu trennen. Leerzeilen können zwischen einer Reihe verwandter Einzeiler (z. B. einer Reihe von Dummy-Implementierungen) weggelassen werden.

Verwenden Sie Leerzeilen in Funktionen, sparsam, um logische Abschnitte zu kennzeichnen.

Python akzeptiert das Control-L (d. h. ^L) Form-Feed-Zeichen als Whitespace; viele Tools behandeln diese Zeichen als Seitenunterbrecher, sodass Sie sie verwenden können, um Seiten zusammengehöriger Abschnitte Ihrer Datei zu trennen. Beachten Sie, dass einige Editoren und webbasierte Code-Viewer Control-L möglicherweise nicht als Form-Feed erkennen und stattdessen ein anderes Glyphen anzeigen.

Quellcodedatei-Kodierung

Code in der Kern-Python-Distribution sollte immer UTF-8 verwenden und keine Kodierungsdeklaration haben.

In der Standardbibliothek sollten Nicht-UTF-8-Kodierungen nur zu Testzwecken verwendet werden. Verwenden Sie Nicht-ASCII-Zeichen sparsam, vorzugsweise nur zur Bezeichnung von Orten und menschlichen Namen. Wenn Sie Nicht-ASCII-Zeichen als Daten verwenden, vermeiden Sie laute Unicode-Zeichen wie z̯̯͡a̧͎̺l̡͓̫g̹̲o̡̼̘ und Byte Order Marks.

Alle Bezeichner in der Python-Standardbibliothek MÜSSEN ASCII-kompatible Bezeichner verwenden und SOLLTEN nach Möglichkeit englische Wörter verwenden (in vielen Fällen werden Abkürzungen und Fachbegriffe verwendet, die nicht englisch sind).

Open-Source-Projekte mit globaler Reichweite werden ermutigt, eine ähnliche Politik zu verfolgen.

Imports

• Imports sollten normalerweise in separaten Zeilen erfolgen.

  # Correct:
  import os
  import sys
  

  # Wrong:
  import sys, os
  

  Es ist in Ordnung, dies zu tun.

  # Correct:
  from subprocess import Popen, PIPE
  

• Imports werden immer am Anfang der Datei platziert, direkt nach allen Modulkommentaren und Docstrings und vor Modul-Globale und Konstanten.

  Imports sollten in folgender Reihenfolge gruppiert werden:

  1. Imports der Standardbibliothek.
  2. Zugehörige Drittanbieter-Imports.
  3. Lokale Anwendungs-/bibliothekspezifische Imports.

  Sie sollten eine Leerzeile zwischen jeder Gruppe von Imports einfügen.

• Absolute Imports werden empfohlen, da sie in der Regel lesbarer sind und sich tendenziell besser verhalten (oder zumindest bessere Fehlermeldungen liefern), wenn das Importsystem falsch konfiguriert ist (z. B. wenn ein Verzeichnis innerhalb eines Pakets auf sys.path landet).

  import mypkg.sibling
  from mypkg import sibling
  from mypkg.sibling import example
  

  Explizite relative Imports sind jedoch eine akzeptable Alternative zu absoluten Imports, insbesondere bei komplexen Paketlayouts, bei denen die Verwendung absoluter Imports unnötig ausführlich wäre.

  from . import sibling
  from .sibling import example
  

  Code der Standardbibliothek sollte komplexe Paketlayouts vermeiden und immer absolute Imports verwenden.

• Beim Importieren einer Klasse aus einem Modul, das Klassen enthält, ist es normalerweise in Ordnung, dies so zu schreiben:

  from myclass import MyClass
  from foo.bar.yourclass import YourClass
  

  Wenn diese Schreibweise lokale Namenskonflikte verursacht, schreiben Sie sie explizit:

  import myclass
  import foo.bar.yourclass
  

  und verwenden Sie myclass.MyClass und foo.bar.yourclass.YourClass.

• Wildcard-Imports (from <module> import *) sollten vermieden werden, da sie unklar machen, welche Namen im Namensraum vorhanden sind, was sowohl Leser als auch viele automatisierte Tools verwirrt. Es gibt einen einzigen vertretbaren Anwendungsfall für einen Wildcard-Import, nämlich die Wiederveröffentlichung einer internen Schnittstelle als Teil einer öffentlichen API (z. B. Überschreiben einer reinen Python-Implementierung einer Schnittstelle mit den Definitionen aus einem optionalen Beschleunigermodul, und genau welche Definitionen überschrieben werden, ist im Voraus nicht bekannt).

  Bei der Wiederveröffentlichung von Namen auf diese Weise gelten die untenstehenden Richtlinien bezüglich öffentlicher und interner Schnittstellen weiterhin.

Modul-Level Dunder-Namen

Modul-Level „Dunders“ (d. h. Namen mit zwei führenden und zwei nachgestellten Unterstrichen) wie __all__, __author__, __version__ usw. sollten nach dem Modul-Docstring, aber vor allen Import-Anweisungen platziert werden, *außer* from __future__-Imports. Python schreibt vor, dass Future-Imports in einem Modul vor jedem anderen Code außer Docstrings erscheinen müssen.

"""This is the example module.

This module does stuff.
"""

from __future__ import barry_as_FLUFL

__all__ = ['a', 'b', 'c']
__version__ = '0.1'
__author__ = 'Cardinal Biggles'

import os
import sys

Besondere Nervensägen

Vermeiden Sie überflüssige Leerzeichen in den folgenden Situationen:

• Unmittelbar innerhalb von Klammern, eckigen Klammern oder geschweiften Klammern.

  # Correct:
  spam(ham[1], {eggs: 2})
  

  # Wrong:
  spam( ham[ 1 ], { eggs: 2 } )
  

• Zwischen einem nachgestellten Komma und einer folgenden schließenden Klammer.

  # Correct:
  foo = (0,)
  

  # Wrong:
  bar = (0, )
  

• Unmittelbar vor einem Komma, Semikolon oder Doppelpunkt.

  # Correct:
  if x == 4: print(x, y); x, y = y, x
  

  # Wrong:
  if x == 4 : print(x , y) ; x , y = y , x
  

• Bei einem Slice fungiert der Doppelpunkt jedoch wie ein binärer Operator und sollte auf beiden Seiten gleich viel Platz haben (behandelt ihn als Operator mit der niedrigsten Priorität). Bei einem erweiterten Slice müssen beide Doppelpunkte den gleichen Abstand haben. Ausnahme: Wenn ein Slice-Parameter weggelassen wird, wird der Abstand weggelassen.

  # Correct:
  ham[1:9], ham[1:9:3], ham[:9:3], ham[1::3], ham[1:9:]
  ham[lower:upper], ham[lower:upper:], ham[lower::step]
  ham[lower+offset : upper+offset]
  ham[: upper_fn(x) : step_fn(x)], ham[:: step_fn(x)]
  ham[lower + offset : upper + offset]
  

  # Wrong:
  ham[lower + offset:upper + offset]
  ham[1: 9], ham[1 :9], ham[1:9 :3]
  ham[lower : : step]
  ham[ : upper]
  

• Unmittelbar vor der öffnenden Klammer, die die Argumentenliste eines Funktionsaufrufs beginnt.

  # Correct:
  spam(1)
  

  # Wrong:
  spam (1)
  

• Unmittelbar vor der öffnenden Klammer, die eine Indizierung oder ein Slicing beginnt.

  # Correct:
  dct['key'] = lst[index]
  

  # Wrong:
  dct ['key'] = lst [index]
  

• Mehr als ein Leerzeichen um einen Zuweisungsoperator (oder einen anderen Operator), um ihn mit einem anderen auszurichten.

  # Correct:
  x = 1
  y = 2
  long_variable = 3
  

  # Wrong:
  x             = 1
  y             = 2
  long_variable = 3
  

Andere Empfehlungen

• Vermeiden Sie nachgestellte Leerzeichen überall. Da sie meist unsichtbar sind, können sie verwirrend sein: z. B. zählt ein Backslash gefolgt von einem Leerzeichen und einem Zeilenumbruch nicht als Zeilenfortsetzungszeichen. Einige Editoren behalten sie nicht bei, und viele Projekte (wie CPython selbst) haben Pre-Commit-Hooks, die sie ablehnen.
• Umschließen Sie diese binären Operatoren immer mit einem einzelnen Leerzeichen auf beiden Seiten: Zuweisung (=), erweiterte Zuweisung (+=, -= etc.), Vergleiche (==, <, >, !=, <=, >=, in, not in, is, is not), Boole'sche Werte (and, or, not).
• Wenn Operatoren mit unterschiedlichen Prioritäten verwendet werden, sollten Sie erwägen, um die Operatoren mit der niedrigsten Priorität Leerzeichen hinzuzufügen. Nutzen Sie Ihr eigenes Urteilsvermögen; verwenden Sie jedoch niemals mehr als ein Leerzeichen und haben Sie immer die gleiche Menge an Leerzeichen auf beiden Seiten eines binären Operators.

  # Correct:
  i = i + 1
  submitted += 1
  x = x*2 - 1
  hypot2 = x*x + y*y
  c = (a+b) * (a-b)
  

  # Wrong:
  i=i+1
  submitted +=1
  x = x * 2 - 1
  hypot2 = x * x + y * y
  c = (a + b) * (a - b)
  

• Funktionsannotationen sollten die normalen Regeln für Doppelpunkte verwenden und immer Leerzeichen um den ->-Pfeil haben, falls vorhanden. (Siehe Funktionsannotationen unten für weitere Informationen zu Funktionsannotationen.)

  # Correct:
  def munge(input: AnyStr): ...
  def munge() -> PosInt: ...
  

  # Wrong:
  def munge(input:AnyStr): ...
  def munge()->PosInt: ...
  

• Verwenden Sie keine Leerzeichen um das Gleichheitszeichen (=), wenn es zur Angabe eines Schlüsselwortarguments oder zur Angabe eines Standardwerts für einen *unannotierten* Funktionsparameter verwendet wird.

  # Correct:
  def complex(real, imag=0.0):
      return magic(r=real, i=imag)
  

  # Wrong:
  def complex(real, imag = 0.0):
      return magic(r = real, i = imag)
  

  Wenn Sie eine Argumentannotation mit einem Standardwert kombinieren, verwenden Sie jedoch Leerzeichen um das Gleichheitszeichen (=).

  # Correct:
  def munge(sep: AnyStr = None): ...
  def munge(input: AnyStr, sep: AnyStr = None, limit=1000): ...
  

  # Wrong:
  def munge(input: AnyStr=None): ...
  def munge(input: AnyStr, limit = 1000): ...
  

• Zusammengesetzte Anweisungen (mehrere Anweisungen in einer Zeile) werden generell nicht empfohlen.

  # Correct:
  if foo == 'blah':
      do_blah_thing()
  do_one()
  do_two()
  do_three()
  

  Besser nicht.

  # Wrong:
  if foo == 'blah': do_blah_thing()
  do_one(); do_two(); do_three()
  

• Obwohl es manchmal in Ordnung ist, eine if/for/while mit einem kleinen Körper in derselben Zeile zu belassen, tun Sie dies niemals für mehrteilige Anweisungen. Vermeiden Sie es auch, solche langen Zeilen umzubrechen!

  Besser nicht.

  # Wrong:
  if foo == 'blah': do_blah_thing()
  for x in lst: total += x
  while t < 10: t = delay()
  

  Definitiv nicht.

  # Wrong:
  if foo == 'blah': do_blah_thing()
  else: do_non_blah_thing()
  
  try: something()
  finally: cleanup()
  
  do_one(); do_two(); do_three(long, argument,
                               list, like, this)
  
  if foo == 'blah': one(); two(); three()
  

Blockkommentare

Blockkommentare beziehen sich im Allgemeinen auf einen Teil (oder den gesamten) folgenden Codes und sind auf der gleichen Ebene wie dieser Code eingerückt. Jede Zeile eines Blockkommentars beginnt mit einem # und einem einzelnen Leerzeichen (es sei denn, es handelt sich um eingerückten Text innerhalb des Kommentars).

Absätze innerhalb eines Blockkommentars werden durch eine Zeile mit einem einzelnen # getrennt.

Inline-Kommentare

Verwenden Sie Inline-Kommentare sparsam.

Ein Inline-Kommentar ist ein Kommentar in derselben Zeile wie eine Anweisung. Inline-Kommentare sollten mindestens zwei Leerzeichen von der Anweisung getrennt sein. Sie sollten mit einem # und einem einzelnen Leerzeichen beginnen.

Inline-Kommentare sind unnötig und tatsächlich ablenkend, wenn sie das Offensichtliche wiederholen. Tun Sie das nicht.

x = x + 1                 # Increment x

Aber manchmal ist das nützlich.

x = x + 1                 # Compensate for border

Docstrings

Konventionen zum Schreiben guter Dokumentationszeichenfolgen (auch „Docstrings“ genannt) sind in PEP 257 verewigt.

• Schreiben Sie Docstrings für alle öffentlichen Module, Funktionen, Klassen und Methoden. Docstrings sind für nicht-öffentliche Methoden nicht notwendig, aber Sie sollten einen Kommentar haben, der beschreibt, was die Methode tut. Dieser Kommentar sollte nach der def-Zeile erscheinen.
• PEP 257 beschreibt gute Docstring-Konventionen. Beachten Sie, dass am wichtigsten ist, dass die """, die einen mehrzeiligen Docstring beendet, auf einer eigenen Zeile steht.

  """Return a foobang
  
  Optional plotz says to frobnicate the bizbaz first.
  """
  

• Für einzeilige Docstrings, halten Sie bitte die schließende """ in derselben Zeile.

  """Return an ex-parrot."""
  

Oberstes Prinzip

Namen, die für den Benutzer als öffentliche Teile der API sichtbar sind, sollten Konventionen folgen, die die Verwendung und nicht die Implementierung widerspiegeln.

Beschreibend: Namensstile

Es gibt viele verschiedene Namensstile. Es hilft, erkennen zu können, welcher Namensstil verwendet wird, unabhängig davon, wofür er verwendet wird.

Die folgenden Namensstile werden üblicherweise unterschieden:

• b (einzelner Kleinbuchstabe)
• B (einzelner Großbuchstabe)
• kleingeschrieben
• kleingeschrieben_mit_unterstrichen
• GROSSGESCHRIEBEN
• GROSSGESCHRIEBEN_MIT_UNTERSTRICHEN
• CapitalizedWords (oder CapWords, oder CamelCase – so genannt wegen des holprigen Aussehens seiner Buchstaben [4]). Dies ist auch manchmal als StudlyCaps bekannt.

  Hinweis: Bei Verwendung von Akronymen in CapWords sollten alle Buchstaben des Akronyms großgeschrieben werden. Daher ist HTTPServerError besser als HttpServerError.

• mixedCase (unterscheidet sich von CapitalizedWords durch den anfänglichen Kleinbuchstaben!)
• Capitalized_Words_With_Underscores (hässlich!)

Es gibt auch den Stil, ein kurzes eindeutiges Präfix zu verwenden, um verwandte Namen zu gruppieren. Dies wird in Python nicht viel verwendet, ist aber der Vollständigkeit halber erwähnt. Zum Beispiel gibt die Funktion os.stat() ein Tupel zurück, dessen Elemente traditionell Namen wie st_mode, st_size, st_mtime usw. haben. (Dies geschieht, um die Entsprechung mit den Feldern des POSIX-Systemaufrufsstructs hervorzuheben, was Programmierern, die damit vertraut sind, hilft.)

Die X11-Bibliothek verwendet ein führendes X für alle ihre öffentlichen Funktionen. In Python wird dieser Stil im Allgemeinen als unnötig erachtet, da Attribut- und Methodennamen mit einem Objekt vorangestellt sind und Funktionsnamen mit einem Modulnamen vorangestellt sind.

Zusätzlich werden die folgenden Sonderformen mit führenden oder nachgestellten Unterstrichen erkannt (diese können im Allgemeinen mit jeder beliebigen Fallkonvention kombiniert werden):

• _single_leading_underscore: schwacher Indikator für „internen Gebrauch“. Z. B. importiert from M import * keine Objekte, deren Namen mit einem Unterstrich beginnen.
• single_trailing_underscore_: wird per Konvention verwendet, um Konflikte mit Python-Schlüsselwörtern zu vermeiden, z. B.:

  tkinter.Toplevel(master, class_='ClassName')
  

• __double_leading_underscore: beim Benennen eines Klassenattributs wird Namensvermaschung (Name Mangling) aufgerufen (innerhalb der Klasse FooBar wird __boo zu _FooBar__boo; siehe unten).
• __double_leading_and_trailing_underscore__: „magische“ Objekte oder Attribute, die in benutzerkontrollierten Namensräumen leben. Z. B. __init__, __import__ oder __file__. Erfinden Sie niemals solche Namen; verwenden Sie sie nur wie dokumentiert.

Vorschreibend: Namenskonventionen

from typing import TypeVar

VT_co = TypeVar('VT_co', covariant=True)
KT_contra = TypeVar('KT_contra', contravariant=True)

Öffentliche und interne Schnittstellen

Jegliche Garantien zur Abwärtskompatibilität gelten nur für öffentliche Schnittstellen. Daher ist es wichtig, dass Benutzer klar zwischen öffentlichen und internen Schnittstellen unterscheiden können.

Dokumentierte Schnittstellen gelten als öffentlich, es sei denn, die Dokumentation erklärt sie ausdrücklich als vorläufige oder interne Schnittstellen, die von den üblichen Garantien zur Abwärtskompatibilität ausgenommen sind. Alle undokumentierten Schnittstellen sollten als intern betrachtet werden.

Um die Introspektion besser zu unterstützen, sollten Module die Namen ihrer öffentlichen API explizit mit dem Attribut __all__ deklarieren. Das Setzen von __all__ auf eine leere Liste zeigt an, dass das Modul keine öffentliche API hat.

Selbst wenn __all__ korrekt gesetzt ist, sollten interne Schnittstellen (Pakete, Module, Klassen, Funktionen, Attribute oder andere Namen) weiterhin mit einem einzelnen führenden Unterstrich beginnen.

Eine Schnittstelle gilt ebenfalls als intern, wenn ein enthaltender Namensraum (Paket, Modul oder Klasse) als intern gilt.

Importierte Namen sollten immer als Implementierungsdetail betrachtet werden. Andere Module dürfen sich nicht auf indirekten Zugriff auf solche importierten Namen verlassen, es sei denn, sie sind explizit als Teil der API des enthaltenden Moduls dokumentiert, wie z. B. os.path oder ein __init__-Modul eines Pakets, das Funktionalität aus Untermodulen freilegt.

Function Annotations

Mit der Akzeptanz von PEP 484 haben sich die Stilregeln für Funktionsannotationen geändert.

• Funktionsannotationen sollten die PEP 484-Syntax verwenden (es gibt einige Formatierungsempfehlungen für Annotationen im vorherigen Abschnitt).
• Das Experimentieren mit Annotationsstilen, das zuvor in diesem PEP empfohlen wurde, wird nicht mehr gefördert.
• Außerhalb der Standardbibliothek werden nun Experimente innerhalb der Regeln von PEP 484 gefördert. Zum Beispiel das Markieren einer großen Drittanbieterbibliothek oder Anwendung mit PEP 484-Stil-Typannotationen, die Überprüfung, wie einfach es war, diese Annotationen hinzuzufügen, und die Beobachtung, ob ihre Anwesenheit die Verständlichkeit des Codes erhöht.
• Die Python-Standardbibliothek sollte konservativ bei der Übernahme solcher Annotationen sein, aber ihre Verwendung ist für neuen Code und für große Refactorings gestattet.
• Für Code, der eine andere Verwendung von Funktionsannotationen wünscht, wird empfohlen, einen Kommentar der Form einzufügen

  # type: ignore
  

  am Anfang der Datei; dies weist Typ-Checker an, alle Annotationen zu ignorieren. (Feingranularere Möglichkeiten, Beschwerden von Typ-Checkern zu deaktivieren, finden Sie in PEP 484.)

• Wie Linter sind Typ-Checker optionale, separate Werkzeuge. Python-Interpreter sollten standardmäßig keine Meldungen aufgrund von Typ-Checking ausgeben und ihr Verhalten nicht aufgrund von Annotationen ändern.
• Benutzer, die keine Typ-Checker verwenden möchten, können diese ignorieren. Es wird jedoch erwartet, dass Benutzer von Drittanbieter-Bibliothekspaketen Typ-Checker über diese Pakete ausführen möchten. Zu diesem Zweck empfiehlt PEP 484 die Verwendung von Stub-Dateien: .pyi-Dateien, die vom Typ-Checker bevorzugt vor den entsprechenden .py-Dateien gelesen werden. Stub-Dateien können mit einer Bibliothek verteilt werden oder separat (mit Erlaubnis des Bibliotheksautors) über das typeshed-Repository [5].

Variablenannotationen

PEP 526 hat Variablenannotationen eingeführt. Die Stil-Empfehlungen für sie ähneln denen für Funktionsannotationen, die oben beschrieben wurden.

• Annotationen für Modul-Level-Variablen, Klassen- und Instanzvariablen sowie lokale Variablen sollten einen einzelnen Leerschritt nach dem Doppelpunkt haben.
• Vor dem Doppelpunkt sollte kein Leerzeichen sein.
• Wenn eine Zuweisung eine rechte Seite hat, sollte das Gleichheitszeichen auf beiden Seiten genau einen Leerschritt haben.

  # Correct:
  
  code: int
  
  class Point:
      coords: Tuple[int, int]
      label: str = '<unknown>'
  

  # Wrong:
  
  code:int  # No space after colon
  code : int  # Space before colon
  
  class Test:
      result: int=0  # No spaces around equality sign
  

• Obwohl PEP 526 für Python 3.6 akzeptiert wurde, ist die Syntax für Variablenannotationen die bevorzugte Syntax für Stub-Dateien in allen Python-Versionen (siehe PEP 484 für Details).

Fußnoten