Feedback erwünscht zu "meinem ersten GitHub Projekt" :-)

[hemmerling]

Hallo,

a)
nach 2 Jahren Python-Lernens+Übens und trotz meines Alters und IT-Erfahrung...
habe ich erst erst jetzt "mein erstes GitHub Projekt" veröffentlicht, mit englischsprachiger Dokumentation
Ergebnis meiner Einarbeitung wie man den mit den Distutils eine Anwendung installierbar macht, Schwerpunkt war u.a. wie man die Module bei der Distribution umbenennt und dann doch sowohl für die Entwicklungsumgebung als auch für den installierenden Kunden richtig importiert:

"distutils_foo - Python demo application prepared for distribution by distutils"
http://github.com/hemmerling/distutils_foo
http://hemmerling.github.com/distutils_foo
http://www.github.com/hemmerling/distutils_foo/wiki

Tja... Begeisterungsstürme über den "tollen Code" erwarte ich nicht, ich hätte lieber als Feedback, ob ich alles formal richtig gemacht habe, denn natürlich ist das ja nur der Vorgeschmack auf mein erstes "richtiges" sinnvolle kleine Projekt das ich in Arbeit habe.

Also sind die Copyright-Hinweise so ok, fehlen wichtige Dateien, ist die Dokumentation zum Installieren verständlich, kann ich an setup.py noch was verbessern... ?
Sprich was sollte ich hieran noch verbessern bzw. bei meinem späteren ersten richtigen Projekt doch anders machen?
Es geht mir also mehr um das Formale...

b)
Bei "anderen" Programmiersprachen und deren typischen IDEs ist es sinnvoll und notwendig, die Projekt-Datei der IDE mit zu sichern.
Tja wie ist das bei der Pycharme IDE, sollte ich die Projektdatei mit hochladen ? Ich meine NEIN.
Es würde auch eine extra-Verzeichnisebene "kosten" .
Ansonsten nutze ich i.A. die Pyscripter IDE, die hat gar keine Projektdateien..

c)
Wie deinstalliere ich eigentlich Python-Pakete sauber, und was muss ich dazu als Programm-Autor tun bzw. zur Verfügung stellen ?!

Viele Grüße
Rolf

[BlackJack]

@hemmerling: In `Scripts/distutils_foo-script.py` steht komischer Code am Ende. Die `main()` macht nichts weiter als die
`distutils_foo_module.main()` aufzurufen — dafür braucht man keine Funktion schreiben.

Das ``if __name__ == …``-Idiom ist keine Funktion wie der Kommentar darüber behauptet. Die Dokumentation von Funktionen gehört auch in den Doctstring und nicht in Kommentare vor der Funktion. Gleiches gilt natürlich für Module, Klassen, und Methoden.

Das Umbennen von Packages und/oder Modulen beim Installieren um Installiertes von Entwicklung zu trennen ist schräg. So etwas sehe ich zum ersten mal. Dafür benutzt man normalerweise virtualenv und/oder einen ”dev-Install” mit ``pip`` oder man setzt beim Entwickeln einen PYTHON_PATH in dem die Entwicklungsversion vor einer eventuell installierten stabilen Version steht.

[hemmerling]

Hallo Blackjack,
Danke für's Feedback.

Meine Erläuterungen:
a) "`Scripts/distutils_foo-script.py` steht komischer Code am Ende"
Das ist nur wie in den anderen Modul-Dateien um zu prüfen, ob die Datei von Python "durchlaufen" wird, insbesondere bei den inkludierten Modulen als Check ob ich sowohl bei Entwicklungs-Umgebung als auch bei Installation die include-Anweisungen richtig gesetzt habe ( also tatsächlich eher "überflüssiger" Code bei `Scripts/distutils_foo-script.py`, der Code dient(e) zum Erkunden, ist kein Produktivcode )

b) "Die `main()` macht nichts weiter als die `distutils_foo_module.main()` aufzurufen — dafür braucht man keine Funktion schreiben."
Ich will aus einer simplen kurzen Skript-Datei das "Hauptprogramm" aufrufen, hier Modul "distutils_foo_module", mangels weiterer Funktionaliät. Und ich wollte lernen wie man Module und Pakete unterschiedlich zu inkludieren hat...
Ich benötige die Konstruktion "ein Script ruft ein Modul auf, das Modul ruft je nach Parameter (hier nicht realisiert!) verschiedene Pakete auf" für mein nächstes Projekt.. das hab ich hier geübt.
Ich habe durch die Beschäftigung damit gelernt, daß in einem Verzeichnis man besser KEIN namensgleiches Modul und Paket ablegt - es wird immer das Paket geladen - Stackoverflow hat mich auch dann darin bestätigt

c) "Das ``if __name__ == …``-Idiom ist keine Funktion wie der Kommentar darüber behauptet. Die Dokumentation von Funktionen gehört auch in den Doctstring und nicht in Kommentare vor der Funktion. Gleiches gilt natürlich für Module, Klassen, und Methoden."
1. Ich nutzte Doxygen
http://de.wikipedia.org/wiki/Doxygen
zum Dokumentieren, da ich den Dokumentations-Stil aus Java und eben "allen" Windows-Programmiersprachen "dank" Doxygen gewohnt bin - man erhält ein schönes RTF oder HTML Handbuch. Python wird explizit unterstützt.
Ich notiere also durch Dein Feedback, daß die Python-Gemeinde gerne das LaTex/Tex-lastige Dokumentationstool
http://sphinx-doc.org/
verwendet, das die Docstrings unterstützt,
ich möchte aber einstweilen nicht mit LaTex/Tex...
Gibts Alternativen ?!
Mir ist noch
http://crunchy.sourceforge.net/
aufgefallen...
2. Beim Inkludieren eines Moduls Python "durchläuft"das Modul und führt den globalen Code aus. Durch die if-Abfrage verhindert man das - ausser man ruft die Datei selber explizit aus. Man "ist" also irgendwie in einer Art Funktion - bei C wäre das main().
3. Ich hatte den Eindruck dass es vorteilhaft ist, allen globalen Code in main() zu packen. Weil wenn ich ein Modul inkludiere,
3a) der globale Code ungefragt von Python ausgeführt wird ( siehe 2 )- will ich ja vielleicht gar nicht dass da viel passiert in dem Augenblick -
3b) wenn ich ein anderes Modul gezielt - auch wiederholt! - ausführen will, kann ich das so mit modulname.main() tun, während es modulname.__main__() offensichtlich nicht gibt... in dem Sinne ist der globale Code keine Funktion, auch wenn er einen "Namen" hat...
4."Das Umbennen von Packages und/oder Modulen beim Installieren um Installiertes von Entwicklung zu trennen ist schräg" - schön zu hören, dass das ein exotisches Feature ist, ich hab aber nun erarbeitet wie's geht . Danke für die Tipps es mit anderen Bordmitteln zu vermeiden.

Viele Grüße
Rolf

[BlackJack]

@hemmerling: Zu b) Da bist Du nicht wirklich auf meinen Kritikpunkt eingegangen: Die `main()`-Funktion die einfach nur die andere `main()`-Funktion aufruft ist überflüssig. Du könntest da gleich, ohne diesen sinnlosen Umweg die endgültige Funktion aufrufen.

Zu c) 1. Ich sehe nicht wo Sphinx LaTeX-Lastig ist. Nur wenn man PDF via LaTeX erstellen will. Um damit HTML zu erstellen braucht man kein LaTeX. Und wenn Python von Doxygen unterstützt wird, dann sollte das auch Docstrings unterstützen. Sonst wäre das ziemlich mau, denn Docstrings sind der vorgesehene und ja auch zur Laufzeit unterstützte Weg bei Python, die sind Teil der Sprache, sowohl der Spezifikation als auch der zur Laufzeit existierenden Objekte.

Es gibt noch Epydoc, das eher JavaDoc-ähnliche Dokumentation erzeugt. Aber ob das noch weiterentwickelt wird… Sphinx ist da recht ”alternativlos”. Ich finde den Ansatz auch besser als JavaDoc was leider die Leute zu oft dazu verleitet zwar alles mit einer Dokumentation zu versehen, die dann aber so dämlich trivial ausfällt, das sie oft für die Tonne ist.

Zu c) 2. Das ist Code auf Modulebene und keine Funktion. Und das ist im Grunde auch nicht `main()` in C sondern so etwas wie ``__attribute__((constructor))`` beim GCC für Bibliotheken. Letztlich macht es aber wenig Sinn so einen Vergleich aufzuzwingen der massiv hinkt. Das ist schlicht keine Funktion, wenn es eine wäre, dann müsste es dafür ja ein Funktionsobjekt geben.

Zu c) 3a) und 3b) Äh ja das stimmt alles, ich sehe nicht was das mit meiner Kritik zu tun hat.

[hemmerling]

Hallo

a)
Comment blocks in Python
http://www.stack.nl/~dimitri/doxygen/ma ... locks.html

"For Python there is a standard way of documenting the code using so called documentation strings. Such strings are stored in doc and can be retrieved at runtime. Doxygen will extract such comments and assume they have to be represented in a preformatted way.

Note that in this case none of doxygen's special commands are supported"

Damit ist erfüllt Dokumentation (nur) mit Docstrings nicht wirklich die Anforderungen... die Dokumentations-Qualität in Sinne von "Javadocs" zu bieten.

b)
Wie uninstalliert man Module und Pakete ( automatisch )?
Zumindest bei den Distutils habe ich nichts entdeckt, dass das unterstützt.
Gibts andere Python-Installer die das unterstützen, und wenn ja wie?

Viele Grüße
Rolf

[cofi]

Ad a) Dann ist doxygen wohl kein brauchbares Tool, um Python-API Dokumente zu erstellen. Ich erwarte schon, dass `help(your_object)` funktioniert, und dafuer braucht es Docstrings.
Bei Sphinx heisst das autodoc: http://sphinx-doc.org/ext/autodoc.html
Die Syntax ist ein wenig anders als bei Doxygen passt dafuer aber zur ReST Syntax.

Ad b) `pip` kann Pakete deinstallieren.

[BlackJack]

Ist IMHO ein wenig unverständlich warum Doxygen zwar Docstrings extrahieren und 1:1 in die generierte Dokumentation einbauen kann, aber nicht in der Lage sein sollte den Inhalt als Doxygen-Markup auszuwerten. Das wäre technisch doch eigentlich gar kein Problem‽

[Leonidas]

Außerdem sollte die README.txt README.md heißen, dann greift auch der GitHub-Parser das auf und rendert da schickeres HTML.