Wie kann ich *args und **kwargs durch die echte Signatur in der Dokumentation dekorierter Funktionen ersetzen?
Nehmen wir an, ich habe die folgende Dekoration und dekorierte Funktion:
%Vor% Entsprechend ruft uns print(myfunc(3, 4)) auf:
So weit, so gut. Ich möchte auch, dass meine Bibliothek, die myfunc enthält, ordnungsgemäß mit Sphinx dokumentiert wird.
Wenn ich jedoch meine Funktion in meine Sphinx-HTML-Seite über:
Es wird tatsächlich angezeigt als:
Unscharfe Addition
Wie kann ich den generischen myfunc(*args, **kwargs) im Titel loswerden? Dies sollte durch myfunc (foo = 42, bar = 43) ersetzt werden. Wie kann ich Sphinx oder meinen Dekorator mywrapper so ändern, dass die Standardschlüsselwortargumente in der Dokumentation beibehalten werden?
BEARBEITEN :
Wie schon gesagt, wurde diese Frage schon einmal gestellt, aber die Antworten sind nicht so hilfreich.
Allerdings hatte ich eine Idee und frage mich, ob das möglich ist. Setzt Sphinx eine Umgebungsvariable, die meinem Modul mitteilt, dass es tatsächlich von Sphinx importiert wird? Wenn das der Fall ist, könnte ich einfach meine eigenen Wrapper patchern. Wenn mein Modul von Sphinx importiert wird, geben meine Wrapper die ursprünglichen Funktionen zurück, anstatt sie zu umhüllen. Somit wird die Signatur erhalten.
Ich habe einen Affen-Patch für functools.wraps gefunden.
Dementsprechend habe ich das einfach zum Skript conf.py im Ordner sphinx source meiner Projektdokumentation hinzugefügt:
Beim Erstellen der HTML-Seite über make html wird also functools.wraps durch diesen Dekorator no_op_wraps ersetzt, der absolut nichts anderes tut, als einfach die ursprüngliche Funktion zurückzugeben.
Normalerweise können Sie nicht. Das liegt daran, dass die Variablennamen, die als Parameter in der Wrapped-Funktion verwendet werden, nicht einmal in der Wrapped-Funktion vorhanden sind - also weiß Sphinx nichts über sie.
Das ist ein bekanntes kompliziertes Problem in Python - so sehr, dass neuere Versionen - darunter nicht nur Python 3, sondern auch Python 2.7 - ein __wrapped__ -Attribut für die Klasse enthalten haben, die die richtige Verwendung von functools.wraps machen -
Auf diese Weise kann man sich bei der Überprüfung der dekorierten Funktion über die tatsächliche Wrapped-Funktion informieren, indem man __wrapped__ betrachtet. Unglücklicherweise ignoriert Sphinx das __wrapped__ und zeigt stattdessen die Info über die Wrapper-Funktion an.
SO ist es eine Sache, dies dem Sphinx-Projekt selbst als Fehler zu melden - es sollte __wrapped__ berücksichtigen.
Eine Umgehungslösung dafür wäre, die Wrapperfunktion so zu ändern, dass sie mehr Informationen über das Wrapped enthält - wie seine Signatur. Sie könnten also eine andere Funktion schreiben, die anstelle von "functools.wraps" für Ihr Projekt aufgerufen wird, was genau das macht: Funktionssignatur zu seinem Docstring, falls vorhanden. Leider ist das Abrufen der Funktionssignaturen in Python älter als 3.3 schwierig - (für 3.3 und neuer, überprüfen Sie Ссылка ) - aber für eine naive Form könnte man trotzdem eine andere Version von "Wraps" schreiben:
%Vor%Und benutze das anstelle von "functools.wraps". Es würde zumindest eine Zeile mit den Parameternamen (aber nicht den Defalt-Werten) als erste Zeile in den Dokumenten hinzufügen.
--- Hmm ... Vielleicht wäre es einfacher, Sphinx zu benutzen, um __wrapped__ zu benutzen, bevor es richtig gemacht wird.
Tags und Links python python-sphinx decorator documentation python-decorators