Das deutsche Python-Forum

Ich bin gerade dabei mich in Python 3 ein zu arbeiten, bis jetzt habe ich teils sehr umfangreiche Programme in Java und PHP (+ zugehörige Sprachen). Nun bin ich bei der Objektorientierung mit Python angekommen und Frage mich nun wie es bei Python Üblich ist Funktionen und Klassen zu Dokumentieren. Durch die SPrache selbst werden ja die Docstrings unterstützt, aber das scheint ja kein praktikapler weg zu sein Parameter von Funktionen zu Dokumentieren. In Java wird das ja mit JavaDoc gemacht und in PHP mit PHP Doc (welches weitestgehend von Java übernommen wurde, aber für Python hab ich nichts ähniches gefunden?

Fuer Python gibt es mit Sphinx ein vergleichbares Tool welches mittels dem autodoc-Plugin die Dokumentation aus den Docstrings zieht. Die eine durchaus praktikable Art sind, Funktionen und Klassen zu dokumentieren.

Der Standard sind Docstrings, seine Parameter kann man da durchaus praktikabel dokumentieren.
Du meinst wohl aber, dass du Dokumente daraus generieren willst. Dafuer gibt es Sphinx: http://sphinx-doc.org/ mit Autodoc: http://sphinx-doc.org/tutorial.html#autodoc

Effektiv laeuft es auf etwas aehnliches wie Javadoc heraus.

@agent47: Man kann in DocStrings auch Parameter mit Syntax kennzeichnen, die von externen Werkzeugen extrahiert und verstanden werden können. In Richtung JavaDoc gibt es zum Beispiel Epydoc. Ich weiss nicht ob es das schon für Python 3 gibt (oder je geben wird), aber von Python 3 würde ich sowieso noch die Finger lassen, solange es für den Einsatz keinen zwingenden Grund gibt. Und nein, „Ich will aber unbedingt die höchste Versionsnummer” ist kein Grund wenn Python 2.7 auch eine aktuelle Version ist.

Allerdings finden viele Pythonistas JavaDoc-Stil nicht besonders toll, weil man dort sehr oft verleitet wird, triviale und damit im Grunde sinnlose Dokumentation zu schreiben, wo man denkt wenn man nur jede Klasse, jede Methode und Funktion, jedes Attribut, und jeden Parameter abgedeckt hat, dann hätte man eine gute Dokumentation. Besser wäre eine Dokumentation, welche mehr in Freitextform, natürlich nicht ohne sinnvolle Struktur, die API und ihre Verwendung zu beschreiben. Ähnlich der Dokumentation von Python und der Standardbibliothek selbst. Das Werkzeug für diese Dokumentation heisst Sphinx und kann natürlich auch für eigene Projekte verwendet werden.

Danke für die schnellen Antworten, ich werde mir Sphinx mal genauer anschauen.

@BlackJack

was gefällt dir an Python 3 nicht? Soweit ich mitbekommen habe ich Python 2 zu 3 nicht 100% kompatibel und damit denke ich ist es doch sinnvoll auf die aktuellste Version zu setzen?

Python 2 und 3 sind mit voller Absicht inkompatibel. Nur leider bietet Python 3 keinen sooo grossen Vorteil, so dass es noch unportierte Bibliotheken gibt.

Python2.7 ist nicht viel weniger aktuell als Python3.3.

@agent47: Python 2.7 und Python 3.3 sind *beide* aktuelle Versionen. An Python 3 gefällt mir nicht, dass es für mich praktisch nicht verwendbar ist, weil vieles von dem was ich benutze, einfach noch nicht mit Python 3 zusammen arbeitet. Und wie cofi schon sagte, gibt es bei 3.x auch keine grossen Vorteile die mich irgendwie motivieren würden die Nachteile auszuhalten, also zum Beispiel viel Arbeit in Lösungen zu stecken wie ich ohne Bibliotheken auskomme, die noch nicht für 3.x zur Verfügung stehen. Ich hätte damit nur Probleme ohne einen wirklichen Mehrwert.

hmm, mein schwerpunkt und auch der Grund warum ich überhaupt mit Python angefangen habe ist Programme für den Raspberry Pi zu schreiben da dies mit Java und co. nicht so der renner ist. Da der Raspberry Pi recht neu ist gibt es alle Module für Python 2 und 3, vor allem wichtig isr da ja das RPi.GPIO und das gibt es für beide Versionen.

@agent47: Da läuft in der Regel ein Debian Wheezy drauf, und da solltest Du mal die Anzahl der verfügbaren Pakete für Python 2 und die für 3 vergleichen. Da gibt es bei weitem nicht jedes Paket auch für Python 3. Pygame, womit die vorinstallierten Beispielspiele umgesetzt sind, gibt es zum Beispiel nicht für Python 3 als Paket.

Wenn man auf dem Gerät eine Webanwendung mit Django laufen lassen möchte, braucht man auch Python 2.

erstmal danke für eure Hilfe, ich werde mir das nochmal genauer anschauen, wie gesagt momentan bezieht sich eigentlich alles auf den Raspberry Pi und die Zentrale Bibliotehk RPI.GPIO gibt er für beide versionen.

Hallo,

wie gesagt momentan bezieht sich eigentlich alles auf den Raspberry Pi und die Zentrale Bibliotehk RPI.GPIO gibt er für beide versionen.

Richtig.

Bevor du einen falschen Eindruck bekommst: Python3 ist die Zukunft. Das streitet auch keiner ab. Nur, ehe alle Python-Programmierer P3 verwenden, wird es noch ein paar Jahre dauern. Grund - wie bereits gesagt - es sind noch lange nicht alle (populären) Programme und Module portiert.
Wenn es für deinen Zweck alle Module bereits in einer P3 Version gibt, dann spricht rein gar nichts gegen P3.

Gruß, noisefloor