Ich schreibe eine Lightweight-Klasse, deren Attribute öffentlich zugänglich sein sollen und nur manchmal in bestimmten Instanziierungen überschrieben werden. In der Python-Sprache gibt es keine Möglichkeit, Dokumentzeichenfolgen für Klassenattribute oder andere Attribute zu erstellen. Was ist der erwartete und unterstützte Weg, um diese Attribute zu dokumentieren? Momentan mache ich so etwas:
class Albatross(object):
"""A bird with a flight speed exceeding that of an unladen swallow.
Attributes:
"""
flight_speed = 691
__doc__ += """
flight_speed (691)
The maximum speed that such a bird can attain.
"""
nesting_grounds = "Raymond Luxury-Yacht"
__doc__ += """
nesting_grounds ("Raymond Luxury-Yacht")
The locale where these birds congregate to reproduce.
"""
def __init__(self, **keyargs):
"""Initialize the Albatross from the keyword arguments."""
self.__dict__.update(keyargs)
Dies führt dazu, dass der Docstring der Klasse den anfänglichen Standard-Docstring-Abschnitt sowie die Zeilen enthält, die für jedes Attribut über eine erweiterte Zuordnung zu hinzugefügt wurden __doc__
.
Obwohl dieser Stil in der EU nicht ausdrücklich verboten zu sein scheint Richtlinien für Docstring-Stile , wird er auch nicht als Option erwähnt. Der Vorteil hierbei ist, dass es eine Möglichkeit bietet, Attribute neben ihren Definitionen zu dokumentieren, während gleichzeitig eine vorzeigbare Klassen-Dokumentzeichenfolge erstellt wird, und dass keine Kommentare geschrieben werden müssen, die die Informationen aus der Dokumentzeichenfolge wiederholen. Ich bin immer noch etwas verärgert, dass ich die Attribute tatsächlich zweimal schreiben muss; Ich denke darüber nach, die Zeichenfolgendarstellungen der Werte in der Dokumentzeichenfolge zu verwenden, um zumindest eine Verdoppelung der Standardwerte zu vermeiden.
Ist dies ein abscheulicher Verstoß gegen die Ad-hoc-Community-Konventionen? Ist es okay? Gibt es einen besseren Weg? Beispielsweise ist es möglich, ein Wörterbuch mit Werten und Dokumentzeichenfolgen für die Attribute zu erstellen und den Inhalt __dict__
gegen Ende der Klassendeklaration der Klasse und der Dokumentzeichenfolge hinzuzufügen . Dies würde die Notwendigkeit verringern, die Attributnamen und -werte zweimal einzugeben. edit : Diese letzte Idee ist meiner Meinung nach nicht wirklich möglich, zumindest nicht ohne das dynamische Erstellen der gesamten Klasse aus Daten, was eine wirklich schlechte Idee zu sein scheint, es sei denn, es gibt einen anderen Grund dafür.
Ich bin ziemlich neu in Python und arbeite immer noch an den Details des Codierungsstils, daher sind auch nicht verwandte Kritiken willkommen.
quelle
attribute doc string
in PEP 257 eine Erwähnung , die nicht gut bekannt ist und schwer zu finden scheint, um die Frage des OP zu beantworten, und die von einigen Quellwerkzeugen unterstützt wird. Dies ist keine Meinung. Es ist eine Tatsache und ein Teil der Sprache und ziemlich genau das, was das OP will.Antworten:
Um Verwirrung zu vermeiden: Der Begriff Eigenschaft hat in Python eine bestimmte Bedeutung . Sie sprechen von Klassenattributen . Da sie immer durch ihre Klasse behandelt werden, finde ich es sinnvoll, sie in der Dokumentzeichenfolge der Klasse zu dokumentieren. Etwas wie das:
Ich denke, das ist viel einfacher für die Augen als der Ansatz in Ihrem Beispiel. Wenn ich wirklich wollte, dass eine Kopie der Attributwerte in der Dokumentzeichenfolge angezeigt wird, würde ich sie neben oder unter die Beschreibung jedes Attributs setzen.
Beachten Sie, dass in Python Dokumentzeichenfolgen tatsächliche Elemente der von ihnen dokumentierten Objekte sind und nicht nur Anmerkungen zum Quellcode. Da Klassenattributvariablen keine Objekte selbst sind, sondern Verweise auf Objekte, können sie keine eigenen Dokumentzeichenfolgen enthalten. Ich denke, Sie könnten sich für Dokumentzeichenfolgen in Referenzen einsetzen, um vielleicht zu beschreiben, "was hier hingehen soll" anstatt "was eigentlich hier ist", aber ich finde es einfach genug, dies in der Dokumentzeichenfolge der enthaltenen Klasse zu tun.
quelle
flight_speed = 691; flight_speed.__doc__ = "blah blah"
. Ich denke, das ist es, was Sie in Ihrer Bearbeitung erwähnen . Leider funktioniert dies nicht für Instanziierungen von (den meisten?) Eingebauten Typen (wieint
in diesem Beispiel). Es funktioniert für Instanziierungen von benutzerdefinierten Typen. =========== Es gab tatsächlich einen PEP (Entschuldigung, vergessen Sie die Nummer), der das Hinzufügen von Dokumentzeichenfolgen für Klassen- / Modulattribute vorschlug, der jedoch abgelehnt wurde, weil sie keinen Weg fanden, dies klar zu machen ob die Dokumentzeichenfolgen für die vorhergehenden oder folgenden Attribute waren.Sie zitieren die PEP257: Docstring Konventionen im Abschnitt Was für ein docstring ist es heißt:
Dies wird in PEP 258: Attribute docstrings näher erläutert. Wie oben erklärt ʇsәɹoɈ. Ein Attribut ist kein Objekt, das ein __doc__ besitzen kann, daher werden sie nicht in
help()
oder pydoc angezeigt . Diese Dokumentzeichenfolgen können nur für die generierte Dokumentation verwendet werden.Sie werden in Sphinx mit der Direktive autoattribute verwendet
Sphinx kann Kommentare in einer Zeile vor einer Zuweisung oder einen speziellen Kommentar nach einer Zuweisung oder eine Dokumentzeichenfolge nach der Definition verwenden, die automatisch dokumentiert wird.
quelle
Sie könnten Eigenschaften zu diesem Zweck missbrauchen. Eigenschaften enthalten einen Getter, einen Setter, einen Deleter und einen Docstring . Naiv würde dies sehr ausführlich werden:
Dann haben Sie eine Dokumentzeichenfolge, die zu Cx gehört:
Dies für viele Attribute zu tun ist umständlich, aber Sie könnten sich eine Hilfsfunktion vorstellen, myprop:
Wenn Sie dann Pythons interaktiv aufrufen
help
, erhalten Sie:was ich denke, sollte so ziemlich das sein, wonach du suchst.
Edit : Mir ist jetzt klar, dass wir vielleicht vermeiden können, das erste Argument
myprop
überhaupt weitergeben zu müssen, weil der interne Name keine Rolle spielt. Wenn nachfolgende Aufrufe vonmyprop
irgendwie miteinander kommunizieren können, könnte es automatisch über einen langen und unwahrscheinlichen internen Attributnamen entscheiden. Ich bin mir sicher, dass es Möglichkeiten gibt, dies umzusetzen, aber ich bin mir nicht sicher, ob sie es wert sind.quelle