Allgemein

Zeilen sollten normalerweise nicht über Spalte 79 hinausragen, mit Ausnahme von URLs und ähnlichen Umständen. Tabulatorzeichen dürfen niemals im Dokument vorkommen.

Abschnittsüberschriften

PEP-Überschriften müssen in Spalte Null beginnen und der erste Buchstabe jedes Wortes muss großgeschrieben werden, wie in Buchtiteln. Akronyme sollten in Großbuchstaben geschrieben werden. Abschnittstitel müssen mit einer Unterstreichung, einem einzeln wiederholten Satzzeichen, versehen sein, die in Spalte Null beginnt und sich mindestens bis zum rechten Rand des Titeltextes erstreckt (mindestens 4 Zeichen). Erstklassige Abschnittsüberschriften werden mit „=“ (Gleichheitszeichen), zweitklassige mit „-“ (Bindestriche) und drittklassige mit „’“ (einfache Anführungszeichen oder Apostrophe) unterstrichen. Zum Beispiel:

First-Level Title
=================

Second-Level Title
------------------

Third-Level Title
'''''''''''''''''

Wenn es mehr als drei Ebenen von Abschnitten in Ihrer PEP gibt, können Sie über- und unterstrichene Titel für die erste und zweite Ebene wie folgt einfügen:

============================
First-Level Title (optional)
============================

-----------------------------
Second-Level Title (optional)
-----------------------------

Third-Level Title
=================

Fourth-Level Title
------------------

Fifth-Level Title
'''''''''''''''''

Sie sollten nicht mehr als fünf Ebenen von Abschnitten in Ihrer PEP haben. Wenn doch, sollten Sie überlegen, sie neu zu schreiben.

Sie müssen zwei Leerzeilen zwischen der letzten Zeile des Abschnittskörpers und der nächsten Abschnittsüberschrift verwenden. Wenn eine Unterabschnittsüberschrift unmittelbar auf eine Abschnittsüberschrift folgt, ist eine einzige Leerzeile dazwischen ausreichend.

Der Text jedes Abschnitts wird normalerweise nicht eingerückt, obwohl einige Konstrukte Einrückungen verwenden, wie unten beschrieben. Leerzeilen werden verwendet, um Konstrukte zu trennen.

Absätze

Absätze sind linksbündige Textblöcke, die durch Leerzeilen getrennt sind. Absätze sind nicht eingerückt, es sei denn, sie sind Teil eines eingerückten Konstrukts (wie z. B. eines Blockzitats oder eines Listenelements).

Inline-Markup

Textteile innerhalb von Absätzen und anderen Textblöcken können formatiert werden. Zum Beispiel:

Text may be marked as *emphasized* (single asterisk markup,
typically shown in italics) or **strongly emphasized** (double
asterisks, typically boldface).  ``Inline literals`` (using double
backquotes) are typically rendered in a monospaced typeface.  No
further markup recognition is done within the double backquotes,
so they're safe for any kind of code snippets.

Blockzitate

Blockzitate bestehen aus eingerückten Bodenelementen. Zum Beispiel:

This is a paragraph.

    This is a block quote.

    A block quote may contain many paragraphs.

Blockzitate werden verwendet, um erweiterte Passagen aus anderen Quellen zu zitieren. Blockzitate können in andere Bodenelemente verschachtelt werden. Verwenden Sie 4 Leerzeichen pro Einrückungsebene.

Literalblöcke

Literalblöcke werden für Codebeispiele und andere vorformatierte Texte verwendet. Um einen Literalblock anzuzeigen, stellen Sie den eingerückten Textblock mit „::“ (zwei Doppelpunkte) voran oder verwenden Sie die Direktive .. code-block::. Rücken Sie den Textblock um 4 Leerzeichen ein; der Literalblock dauert bis zum Ende der Einrückung. Zum Beispiel:

This is a typical paragraph.  A literal block follows.

::

    for a in [5, 4, 3, 2, 1]:  # this is program code, shown as-is
        print(a)
    print("it's...")

„::“ wird auch am Ende jedes Absatzes erkannt; wenn er nicht unmittelbar von Leerzeichen vorangestellt wird, bleibt ein Doppelpunkt in der endgültigen Ausgabe sichtbar

This is an example::

    Literal block

Standardmäßig werden Literalblöcke als Python-Code mit Syntax-Hervorhebung versehen. Für bestimmte Blöcke, die Code oder Daten in anderen Sprachen/Formaten enthalten, verwenden Sie die Direktive .. code-block:: language und ersetzen Sie „language“ durch den „Kurznamen“ des entsprechenden Pygments Lexers (oder text, um die Hervorhebung zu deaktivieren). Zum Beispiel:

.. code-block:: rst

    An example of the ``rst`` lexer (i.e. *reStructuredText*).

Für PEPs, die hauptsächlich Literalblöcke einer bestimmten Sprache enthalten, verwenden Sie die Direktive .. highlight:: language mit der entsprechenden language am Anfang des PEP-Textes (unter den Kopfzeilen und über dem Abstract). Alle Literalblöcke werden dann als diese Sprache behandelt, es sei denn, sie werden in der spezifischen .. code-block-Direktive anders angegeben. Zum Beispiel:

.. highlight:: c

Abstract
========

Here's some C code::

    printf("Hello, World!\n");

Listen

Aufzählungspunkte beginnen mit einem der Zeichen „-“, „*“ oder „+“ (Bindestrich, Sternchen oder Pluszeichen), gefolgt von Leerzeichen und dem Listenelementtext. Der Text von Listenelementen muss linksbündig und relativ zum Aufzählungspunkt eingerückt sein; der Text unmittelbar nach dem Aufzählungspunkt bestimmt die Einrückung. Zum Beispiel:

This paragraph is followed by a list.

* This is the first bullet list item.  The blank line above the
  first list item is required; blank lines between list items
  (such as below this paragraph) are optional.

* This is the first paragraph in the second item in the list.

  This is the second paragraph in the second item in the list.
  The blank line above this paragraph is required.  The left edge
  of this paragraph lines up with the paragraph above, both
  indented relative to the bullet.

  - This is a sublist.  The bullet lines up with the left edge of
    the text blocks above.  A sublist is a new list so requires a
    blank line above and below.

* This is the third item of the main list.

This paragraph is not part of the list.

Aufgezählte (nummerierte) Listenelemente sind ähnlich, verwenden aber einen Aufzähler anstelle eines Aufzählungspunkts. Aufzähler sind Zahlen (1, 2, 3, …), Buchstaben (A, B, C, …; groß oder klein) oder römische Ziffern (i, ii, iii, iv, …; groß oder klein), formatiert mit einem Punkt-Suffix („1.“, „2.“), Klammern („(1)“, „(2)“) oder einem rechten Klammer-Suffix („1)“, „2)“). Zum Beispiel:

1. As with bullet list items, the left edge of paragraphs must
   align.

2. Each list item may contain multiple paragraphs, sublists, etc.

   This is the second paragraph of the second list item.

   a) Enumerated lists may be nested.
   b) Blank lines may be omitted between list items.

Definitionslisten werden wie folgt geschrieben:

what
    Definition lists associate a term with a definition.

how
    The term is a one-line phrase, and the definition is one
    or more paragraphs or body elements, indented relative to
    the term.

Tabellen

Einfache Tabellen sind einfach und kompakt

=====  =====  =======
  A      B    A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

Eine Tabelle muss mindestens zwei Spalten haben (um sie von Abschnittsüberschriften zu unterscheiden). Spaltenspanns werden mit Bindestrich-Unterstreichungen angezeigt („Inputs“ überspannt die ersten beiden Spalten)

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

Text in einer Zelle der ersten Spalte beginnt eine neue Zeile. Kein Text in der ersten Spalte bedeutet eine Fortsetzungszeile; die restlichen Zellen können mehrere Zeilen umfassen. Zum Beispiel:

=====  =========================
col 1  col 2
=====  =========================
1      Second column of row 1.
2      Second column of row 2.
       Second line of paragraph.
3      - Second column of row 3.

       - Second item in bullet
         list (row 3, column 2).
=====  =========================

Hyperlinks

Wenn Sie in einem PEP-Text auf eine externe Webseite verweisen, sollten Sie den Titel der Seite oder eine geeignete Beschreibung im Text angeben, entweder mit einem Inline-Hyperlink oder einem separaten expliziten Ziel mit der URL. Fügen Sie keine bloßen URLs in den Text der PEP ein und verwenden Sie, wo immer möglich, HTTPS-Links.

Hyperlink-Referenzen verwenden Rückwärtszeichen (Backticks) und einen nachgestellten Unterstrich, um den Referenztext zu markieren; Rückwärtszeichen sind optional, wenn der Referenztext ein einzelnes Wort ist. Um beispielsweise auf ein Hyperlink-Ziel namens Python website zu verweisen, würden Sie schreiben:

In this paragraph, we refer to the `Python website`_.

Wenn Sie einen Link nur einmal verwenden möchten und ihn inline mit dem Text definieren möchten, fügen Sie den Link in spitze Klammern (<>) nach dem zu verlinkenden Text, aber vor dem schließenden Rückwärtszeichen ein, mit einem Leerzeichen zwischen dem Text und dem öffnenden Rückwärtszeichen. Sie sollten auch einen doppelten Unterstrich nach dem schließenden Rückwärtszeichen anstelle eines einzelnen verwenden, was ihn zu einer anonymen Referenz macht, um Konflikte mit anderen Zielnamen zu vermeiden. Zum Beispiel:

Visit the `website <https://pythonlang.de/>`__ for more.

Wenn Sie einen Link an mehreren Stellen mit unterschiedlichem Linktext verwenden möchten oder sicherstellen möchten, dass Sie Ihre Link-Zielnamen nicht ändern müssen, wenn Sie den Linktext ändern, fügen Sie den Zielnamen in spitze Klammern hinter dem zu verlinkenden Text ein, mit einem Unterstrich nach dem Zielnamen, aber vor der schließenden spitzen Klammer (andernfalls funktioniert der Link nicht). Zum Beispiel:

For further examples, see the `documentation <pydocs_>`_.

Ein explizites Ziel liefert die URL. Platzieren Sie Ziele im Abschnitt Fußnoten am Ende der PEP oder unmittelbar nach dem Absatz mit der Referenz. Hyperlink-Ziele beginnen mit zwei Punkten und einem Leerzeichen (dem „explicit markup start“), gefolgt von einem führenden Unterstrich, dem Referenztext, einem Doppelpunkt und der URL.

.. _Python web site: https://pythonlang.de/
.. _pydocs: https://docs.pythonlang.de/

Der Referenztext und der Zieltext müssen übereinstimmen (obwohl der Abgleich Groß- und Kleinschreibung ignoriert und Unterschiede in Leerzeichen ignoriert). Beachten Sie, dass der Unterstrich dem Referenztext folgt, aber dem Zieltext vorausgeht. Wenn Sie sich den Unterstrich als Pfeil nach rechts vorstellen, zeigt er vom Referenz und zum Ziel.

Interne und PEP/RFC-Links

Derselbe Mechanismus wie für Hyperlinks kann für interne Referenzen verwendet werden. Jeder eindeutige Abschnittstitel definiert implizit ein internes Hyperlink-Ziel. Wir können wie folgt auf den Abstract-Abschnitt verweisen:

Here is a hyperlink reference to the `Abstract`_ section.  The
backquotes are optional since the reference text is a single word;
we can also just write: Abstract_.

Um auf PEPs oder RFCs zu verweisen, verwenden Sie immer die Rollen :pep: und :rfc:, niemals fest codierte URLs. Zum Beispiel:

See :pep:`1` for more information on how to write a PEP,
and :pep:`the Hyperlink section of PEP 12 <12#hyperlinks>` for how to link.

Dies wird wie folgt gerendert:

Siehe PEP 1 für weitere Informationen zum Verfassen einer PEP und den Abschnitt Hyperlinks in PEP 12 für die Verlinkung.

PEP-Nummern im Text werden niemals aufgefüllt, und es gibt ein Leerzeichen (kein Bindestrich) zwischen „PEP“ oder „RFC“ und der Nummer; die obigen Rollen kümmern sich darum für Sie.

Fußnoten

Fußnotenreferenzen bestehen aus einer linken eckigen Klammer, einem Label, einer rechten eckigen Klammer und einem nachgestellten Unterstrich. Anstelle einer Nummer verwenden Sie ein Label der Form „#word“, wobei „word“ eine mnemotechnische Bezeichnung aus alphanumerischen Zeichen plus internen Bindestrichen, Unterstrichen und Punkten ist (keine Leerzeichen oder andere Zeichen sind erlaubt). Zum Beispiel:

Refer to The TeXbook [#TeXbook]_ for more information.

was wie folgt gerendert wird:

Beachten Sie The TeXbook [1] für weitere Informationen.

Leerzeichen müssen der Fußnotenreferenz vorangestellt werden. Lassen Sie ein Leerzeichen zwischen der Fußnotenreferenz und dem vorhergehenden Wort.

Verwenden Sie Fußnoten für zusätzliche Anmerkungen, Erklärungen und Vorbehalte sowie für Verweise auf Bücher und andere Online-nicht ohne weiteres verfügbare Quellen. Native reST-Hyperlink-Ziele oder Inline-Hyperlinks im Text sollten Fußnoten für die Einbindung von URLs zu Online-Ressourcen vorgezogen werden.

Fußnoten beginnen mit „.. “ (dem explicit markup start), gefolgt vom Fußnotenmarker (keine Unterstriche), gefolgt vom Fußnotentext. Zum Beispiel:

.. [#TeXbook] Donald Knuth's *The TeXbook*, pages 195 and 196.

was wie folgt gerendert wird:

Fußnoten und Fußnotenreferenzen werden automatisch nummeriert, und die Nummern werden immer übereinstimmen.

Bilder

Wenn Ihre PEP eine Grafik oder eine andere Grafik enthält, können Sie sie mit der Direktive image in der verarbeiteten Ausgabe einfügen:

.. image:: diagram.png

Jedes browserfreundliche Grafikformat ist möglich; PNG sollte für Grafiken, JPEG für Fotos und GIF für Animationen bevorzugt werden. Derzeit müssen SVG aufgrund von Kompatibilitätsproblemen mit dem PEP-Build-System vermieden werden.

Für Barrierefreiheit und Leser des Quelltextes sollten Sie eine Beschreibung des Bildes und alle darin enthaltenen wichtigen Informationen mit der Option :alt: zur Direktive image aufnehmen:

.. image:: dataflow.png
   :alt: Data flows from the input module, through the "black box"
         module, and finally into (and through) the output module.

Kommentare

Ein Kommentar ist ein eingerückter Block beliebigen Textes, der unmittelbar auf einen expliziten Markup-Start folgt: zwei Punkte und Leerzeichen. Lassen Sie die „..“ in einer eigenen Zeile, um sicherzustellen, dass der Kommentar nicht falsch als ein anderer expliziter Markup-Konstrukt interpretiert wird. Kommentare sind im verarbeiteten Dokument nicht sichtbar. Zum Beispiel:

..
   This section should be updated in the final PEP.
   Ensure the date is accurate.

Maskierungsmechanismus

reStructuredText verwendet Backslashes (”\“), um die besondere Bedeutung von Markup-Zeichen zu überschreiben und die tatsächlichen Zeichen selbst zu erhalten. Um einen wörtlichen Backslash zu erhalten, verwenden Sie einen maskierten Backslash (”\\“). Es gibt zwei Kontexte, in denen Backslashes keine besondere Bedeutung haben: Literalblöcke und Inline-Literale (siehe Inline-Markup oben). In diesen Kontexten findet keine Markup-Erkennung statt, und ein einzelner Backslash stellt einen wörtlichen Backslash dar, ohne dass er verdoppelt werden muss.

Wenn Sie feststellen, dass Sie einen Backslash in Ihrem Text verwenden müssen, erwägen Sie stattdessen die Verwendung von Inline-Literalen oder eines Literalblocks.

Intersphinx

Sie können Intersphinx-Referenzen zu anderen Sphinx-Seiten wie der Python-Dokumentation packaging.python.org und typing.python.org verwenden, um Seiten, Abschnitte und Python/C-Objekte einfach zu verknüpfen.

Um beispielsweise einen Link zu einem Abschnitt der Typing-Dokumentation zu erstellen, würden Sie Folgendes schreiben:

:ref:`type expression <typing:type-expression>`

Kanonische Dokumentation

Wie in PEP 1 beschrieben, gelten PEPs nach der Kennzeichnung als „Final“ als historische Dokumente, und ihre kanonische Dokumentation/Spezifikation sollte woanders hin verschoben werden. Um dies anzuzeigen, verwenden Sie die Direktive canonical-doc oder eine geeignete Unterklasse

• canonical-pypa-spec für Packaging-Standards
• canonical-typing-spec für Typing-Standards

Fügen Sie die Direktive zwischen den Kopfzeilen und dem ersten Abschnitt der PEP ein (typischerweise der Abstract) und übergeben Sie als Argument eine Intersphinx-Referenz der kanonischen Doku/Spezifikation (oder, wenn das Ziel nicht auf einer Sphinx-Seite ist, einen reST-Hyperlink).

Um beispielsweise ein Banner zu erstellen, das auf die sqlite3-Dokumentation verweist, würden Sie Folgendes schreiben:

.. canonical-doc:: :mod:`python:sqlite3`

Dies würde das Banner generieren:

Wichtig

Diese PEP ist ein historisches Dokument. Die aktuelle, kanonische Dokumentation finden Sie nun unter sqlite3.

×

Siehe PEP 1, um Änderungen vorzuschlagen.

Oder für eine PyPA-Spezifikation, wie die Core-Metadaten-Spezifikationen, würden Sie verwenden:

.. canonical-pypa-spec:: :ref:`packaging:core-metadata`

was wie folgt gerendert wird:

Wichtig

Dieses PEP ist ein historisches Dokument. Die aktuelle, kanonische Spezifikation, Kernmetadatenspezifikationen, wird auf der PyPA Specs-Seite gepflegt.

×

Siehe den PyPA-Spezifikations-Update-Prozess, um Änderungen vorzuschlagen.

Für eine Typing-PEP, die keine neuen Laufzeitobjekte einführt, könnten Sie etwas wie das erste dieser verwenden; für eine Typing-PEP, die ein neues Objekt zum Typing-Modul zur Laufzeit einführt, könnten Sie das zweite verwenden:

.. canonical-typing-spec:: :ref:`typing:packaging-typed-libraries`
.. canonical-typing-spec:: :ref:`typing:literal-types` and
                           :py:data:`typing.Literal`

Die beiden werden wie folgt gerendert:

Wichtig

Diese PEP ist ein historisches Dokument: siehe Typinformationen in Bibliotheken für aktuelle Spezifikationen und Dokumentation. Kanonische Typing-Spezifikationen werden auf der Seite typing specs site gepflegt; das Laufzeit-Typing-Verhalten wird in der CPython-Dokumentation beschrieben.

×

Siehe den Prozess zur Aktualisierung der Typ-Spezifikation, um Änderungen an der Typ-Spezifikation vorzuschlagen.

Wichtig

Diese PEP ist ein historisches Dokument: siehe Literaltypen und typing.Literal für aktuelle Spezifikationen und Dokumentation. Kanonische Typing-Spezifikationen werden auf der Seite typing specs site gepflegt; das Laufzeit-Typing-Verhalten wird in der CPython-Dokumentation beschrieben.

×

Siehe den Prozess zur Aktualisierung der Typ-Spezifikation, um Änderungen an der Typ-Spezifikation vorzuschlagen.

Das Argument akzeptiert beliebiges reST, sodass Sie mehrere verknüpfte Dokumente/Spezifikationen einfügen und ihnen beliebige Namen geben können, und Sie können auch Direktiveninhalte einfügen, die in den Text eingefügt werden. Das folgende fortgeschrittene Beispiel:

.. canonical-doc:: the :ref:`python:sqlite3-connection-objects` and :exc:`python:~sqlite3.DataError` docs

    Also, see the :ref:`Data Persistence docs <persistence>` for other examples.

würde wie folgt gerendert werden:

Wichtig

Diese PEP ist ein historisches Dokument. Die aktuelle, kanonische Dokumentation finden Sie nun unter den Connection-Objekten und sqlite3.DataError Docs.

×

Siehe auch die Data Persistence Docs für weitere Beispiele.

Siehe PEP 1, um Änderungen vorzuschlagen.