Zusammenfassung

Die Python C-API verfügt derzeit über keinen Mechanismus zur Spezifikation und automatischen Generierung von Funktionssignaturen, Annotationen oder benutzerdefinierten Argumentkonvertern.

Es gibt mehrere mögliche Ansätze für das Problem. Cython verwendet cdef-Definitionen in .pyx-Dateien zur Generierung der erforderlichen Informationen. Die C-API-Funktionen von CPython erfordern jedoch oft zusätzliche Initialisierungs- und Aufräumschnipsel, die in einem cdef schwer zu spezifizieren wären.

PEP 436 schlägt eine domänenspezifische Sprache (DSL) vor, die in C-Kommentaren eingeschlossen ist und weitgehend einer Konfigurationsdatei pro Parameter ähnelt. Ein Präprozessor liest den Kommentar und gibt eine Argument-Parsing-Funktion, Docstrings und einen Header für die Funktion aus, die die Ergebnisse des Parsing-Schritts verwendet.

Letztere Funktion wird im Folgenden als Implementierungsfunktion bezeichnet.

Ablehnungsbescheid

Diese PEP wurde von Guido van Rossum auf der PyCon US 2013 abgelehnt. Mehrere der spezifischen Probleme, die von dieser PEP aufgeworfen wurden, wurden jedoch bei der Gestaltung der zweiten Iteration der PEP 436 DSL berücksichtigt.

Begründung

Die Meinungen gehen auseinander, was die Eignung der PEP 436 DSL im Kontext einer C-Datei betrifft. Diese PEP schlägt eine alternative DSL vor. Die spezifischen Probleme mit PEP 436, die den Gegenentwurf ausgelöst haben, werden im letzten Abschnitt dieser PEP erläutert.

Umfang

Die PEP konzentriert sich ausschließlich auf die DSL. Themen wie die Ausgabeorte von Docstrings oder der generierte Code liegen außerhalb des Geltungsbereichs dieser PEP.

Es ist jedoch unerlässlich, dass die DSL zur Generierung benutzerdefinierter Argument-Parser geeignet ist, einer Funktion, die bereits in Cython implementiert ist. Daher ist eines der Ziele dieser PEP, die DSL nahe an bestehenden Lösungen zu halten und so eine mögliche Aufnahme der relevanten Teile von Cython in den CPython-Quellbaum zu erleichtern.

DSL-Übersicht

/*[converter]
##### Default converters #####
"s":  str                                -> const char *res;
"s*": [str, bytes, bytearray, rw_buffer] -> Py_buffer &res;
[...]
"es#": str -> (const char *res_encoding, char **res, Py_ssize_t *res_length);
[...]
##### Custom converters #####
path_converter:           [str, bytes, int]  -> path_t &res;
OS_STAT_DIR_FD_CONVERTER: [int, None]        -> int res;
[converter_end]*/

/*[define posix_stat]
def os.stat(path: path_converter, *, dir_fd: OS_STAT_DIR_FD_CONVERTER = None,
            follow_symlinks: "p" = True) -> os.stat_result: pass
%%
path_t path = PATH_T_INITIALIZE("stat", 0, 1);
int dir_fd = DEFAULT_DIR_FD;
int follow_symlinks = 1;
%%
path_cleanup(&path);
[define_end]*/

<literal C output>

/*[define_output_end]*/

/*[define stat_float_times]
def os.stat_float_times(/, newval: "i") -> os.stat_result: pass
%%
int newval = -1;
[define_end]*/

/*[define]
def curses.window.addch(y: "i", x: "i", ch: "O", attr: "l") -> None: pass
where groups = [[ch], [ch, attr], [y, x, ch], [y, x, ch, attr]]
[define_end]*/

Flexibilität bei der Formatierung

Wenn das obige os.stat-Beispiel als zu kompakt betrachtet wird, kann es einfach so formatiert werden

/*[define posix_stat]
def os.stat(path: path_converter,
            *,
            dir_fd: OS_STAT_DIR_FD_CONVERTER = None,
            follow_symlinks: "p" = True)
-> os.stat_result: pass
%%
path_t path = PATH_T_INITIALIZE("stat", 0, 1);
int dir_fd = DEFAULT_DIR_FD;
int follow_symlinks = 1;
%%
path_cleanup(&path);
[define_end]*/

<literal C output>

/*[define_output_end]*/

Vorteile einer kompakten Notation

Die Vorteile einer prägnanten Notation sind besonders offensichtlich, wenn eine große Anzahl von Parametern beteiligt ist. Der Argument-Parsing-Teil von _posixsubprocess.fork_exec wird vollständig durch diese Definition spezifiziert

/*[define subprocess_fork_exec]
def _posixsubprocess.fork_exec(
    process_args: "O", executable_list: "O",
    close_fds: "p", py_fds_to_keep: "O",
    cwd_obj: "O", env_list: "O",
    p2cread: "i", p2cwrite: "i", c2pread: "i", c2pwrite: "i",
    errread: "i", errwrite: "i", errpipe_read: "i", errpipe_write: "i",
    restore_signals: "i", call_setsid: "i", preexec_fn: "i", /) -> int: pass
[define_end]*/

Beachten Sie, dass das preprocess-Tool derzeit einen redundanten C-Deklarationsabschnitt für dieses Beispiel ausgibt, sodass die Ausgabe länger ist als nötig.

Einfache Validierung der Definition

Wie kann ein unerfahrener Benutzer eine Definition wie os.stat validieren? Einfach, indem er os.stat in os_stat ändert, fehlende Konverter definiert und die Definition in den interaktiven Python-Interpreter einfügt!

Tatsächlich könnte ein converters.py-Modul aus converters.h generiert werden.

Referenzimplementierung

Eine Referenzimplementierung ist unter issue 16612 verfügbar. Da diese PEP unter Zeitdruck geschrieben wurde und der Autor mit der PLY-Toolchain nicht vertraut ist, ist die Software in Standard ML geschrieben und verwendet die ml-yacc/ml-lex-Toolchain.

Die Grammatik ist konfliktfrei und in ml-yacc lesbarer BNF-Form verfügbar.

Zwei Werkzeuge sind verfügbar

• printsemant liest einen Konverter-Header und eine .c-Datei und gibt den semantisch geprüften Parse-Baum auf stdout aus.
• preprocess liest einen Konverter-Header und eine .c-Datei und gibt die vorverarbeitete .c-Datei auf stdout aus.

Bekannte Mängel

• Der Python-‚test‘-Ausdruck wird nicht semantisch geprüft. Die Syntax wird jedoch geprüft, da sie Teil der Grammatik ist.
• Der Lexer verarbeitet keine dreifach zitierten Zeichenketten.
• C-Deklarationen werden primitiv geparst. Die endgültige Implementierung sollte ‚declarator‘ und ‚init-declarator‘ aus der C-Grammatik verwenden.
• Das preprocess-Tool gibt keinen Code für den Fall der linken und rechten optionalen Argumente aus. Das printsemant-Tool kann mit diesem Fall umgehen.
• Da das preprocess-Tool die Ausgabe aus dem Parse-Baum generiert, geht die ursprüngliche Einrückung des define-Blocks verloren.

Grammatik

TBD: Die Grammatik existiert in ml-yacc lesbarer Form, sollte aber wahrscheinlich hier in EBNF-Notation aufgenommen werden.

Vergleich mit PEP 436

Der Autor dieser PEP hat folgende Bedenken bezüglich der in PEP 436 vorgeschlagenen DSL

• Die Whitespace-empfindliche Konfigurationsdatei-ähnliche Syntax wirkt fehl am Platz in einer C-Datei.
• Die Struktur der Funktionsdefinition geht in den pro Parameter spezifizierten Angaben verloren. Schlüsselwörter wie positionsgebunden, erforderlich und nur-Schlüsselwort sind über zu viele verschiedene Stellen verstreut.

  Im Gegensatz dazu kann in der alternativen DSL die Struktur der Funktionsdefinition auf einen Blick erfasst werden.

• Die PEP 436 DSL hat 14 dokumentierte Flags und mindestens ein undokumentiertes (allow_fd) Flag. Die Ermittlung, welche der 2**15 möglichen Kombinationen gültig sind, stellt eine unnötige Belastung für den Benutzer dar.

  Erfahrungen mit den PEP 3118 Buffer-Flags haben gezeigt, dass das Sortieren (und erschöpfende Testen!) gültiger Kombinationen eine äußerst mühsame Aufgabe ist. Die PEP 3118 Flags sind immer noch nicht gut verstanden von vielen Leuten.

  Im Gegensatz dazu gibt es bei der alternativen DSL eine zentrale Datei Include/converters.h, die schnell nach dem gewünschten Konverter durchsucht werden kann. Viele der Konverter sind bereits bekannt, vielleicht sogar auswendig gelernt von Leuten (aufgrund häufiger Nutzung).

• Die PEP 436 DSL lässt zu viel Freiheit. Typen können anscheinend weggelassen werden, der Präprozessor akzeptiert (und ignoriert) unbekannte Schlüsselwörter, und das Hinzufügen von Leerzeichen nach einem Docstring führt manchmal zu einem Assertionsfehler.

  Die alternative DSL hingegen lässt keine solchen Freiheiten zu. Das Weglassen von Konverter- oder Rückgabewert-Annotationen ist eindeutig ein Syntaxfehler. Die LALR(1)-Grammatik ist eindeutig und für die vollständige Übersetzungseinheit spezifiziert.

Urheberrecht

Dieses Dokument unterliegt der Open Publication License.