Wie Doku-Head in .py dateien aufbauen...

[jens]

Ich möchte meine PyLucid Sourcedateien etwas aufräumen... Ich hab z.B. immer __history__ und __version__ drin, pflege diese aber nicht wirklich gut... Somit will ich mal die Header aufräumen...

Aber wie gestalten???

Es gibt das verschiedene Variante:

http://trac.edgewall.org/browser/trunk/ ... achment.py

Code: Alles auswählen

# -*- coding: utf-8 -*-
#
# Copyright (C) 2003-2005 Edgewall Software
# Copyright (C) 2003-2005 Jonas Borgström <jonas@edgewall.com>
# Copyright (C) 2005 Christopher Lenz <cmlenz@gmx.de>
# All rights reserved.
#
# This software is licensed as described in the file COPYING, which
# you should have received as part of this distribution. The terms
# are also available at http://trac.edgewall.org/wiki/TracLicense.
#
# This software consists of voluntary contributions made by many
# individuals. For the exact contribution history, see the revision
# history and logs, available at http://trac.edgewall.org/log/.
#
# Author: Jonas Borgström <jonas@edgewall.com>
#         Christopher Lenz <cmlenz@gmx.de>

from datetime import datetime
...

http://pysvn.tigris.org/source/browse/p ... _dialog.py

Code: Alles auswählen

'''
 ====================================================================
 Copyright (c) 2003-2006 Barry A Scott.  All rights reserved.

 This software is licensed as described in the file LICENSE.txt,
 which you should have received as part of this distribution.

 ====================================================================

    wb_subversion_properties_dialog.py

'''
import os

http://trac.pocoo.org/browser/pocoo/trunk/pocoo/db.py

Code: Alles auswählen

# -*- coding: utf-8 -*-
"""
    pocoo.db
    ~~~~~~~~

    Database support, a thin layer on top of SQLAlchemy.


    How to use the database layer
    =============================

    TODO: this needs to be written.


    :copyright: 2006 by Georg Brandl, Armin Ronacher.
    :license: GNU GPL, see LICENSE for more details.
"""

import os
...

http://pylucid.net/trac/browser/trunk/PyLucid_app.py

Code: Alles auswählen

#!/usr/bin/python
# -*- coding: UTF-8 -*-

# copyleft: jensdiemer.de (GPL v2 or above)

__author__  = "Jens Diemer (www.jensdiemer.de)"
__license__ = """GNU General Public License v2 or above -
 http://www.opensource.org/licenses/gpl-license.php"""
__url__     = "http://www.PyLucid.org"

__version__ = "0.7.1beta"
__info__ = """<a href="%s" title="\
PyLucid - A OpenSource CMS in pure Python CGI by Jens Diemer">PyLucid</a> \
v%s""" % (__url__, __version__)

http://gelb.bcom.at/trac/misc/browser/s ... dressdb.py

Code: Alles auswählen

#!/usr/bin/env python
# -*- coding: iso-8859-1 -*-
"""
Kleine Adressdatenbank mit einfacher Kommandozeilenoberfläche.
Diese Adressdatenbank soll die Verwendung von pysqlite demonstrieren.

Das besondere Format der Docstrings ist für die Verwendung von
epydoc_ optimiert.

.. _epydoc: http://epydoc.sourceforge.net/

Created:       2006-07-10 by Gerold
Requirements:  Python: http://www.python.org
               pysqlite: http://initd.org/tracker/pysqlite
"""

import os
...

Ich glaube die Liste kann man endlos lange führen Wenn man sich die Python Lib selber anschaut gibt es da auch nichts einheitliches...

An für sich, finde ich es nicht schlecht __author__, __license__ und __url__ zu nutzten... Aber was ist wenn mehrere Leute daran gearbeitet haben??? Bei __author__ eine Liste machen?
Außerdem werden diese Angaben bei jedem einlesen auch als echte Python Objekte gepast... Ein großer Dok-String wird im Optimize Modus einfach ignoriert... Mag sich da nur um ein paar MiliSek. handeln, aber wenn es in jeder Datei geparst werden muß?

Also was machen???

[CM]

Hoi Jens,

An für sich, finde ich es nicht schlecht __author__, __license__ und __url__ zu nutzten... Aber was ist wenn mehrere Leute daran gearbeitet haben??? Bei __author__ eine Liste machen?

Den Autor __maintainer__ nennen, ggf. __author__ = __maintainer__ setzen, und in jedem Funktionsdocstring die Autoren nennen - sofern es nicht zu viele sind.

Außerdem werden diese Angaben bei jedem einlesen auch als echte Python Objekte gepast... Ein großer Dok-String wird im Optimize Modus einfach ignoriert... Mag sich da nur um ein paar MiliSek. handeln, aber wenn es in jeder Datei geparst werden muß?

Also was machen???

Meine bescheidene Meinung: Unbedingt die Docstrings für die Entwicklungs drin lassen - allenfalls bei Anwendungen bei denen der Endnutzer niemals (mit 120 %iger Sicherheit) den Interpreter nicht starten und Deine Module importieren wird, die Docstrings weglassen. Begründung: Die Zeiteinsparung kompensiert bei weitem nicht die Zeit, die Du aufwenden mußt, um dumme Fragen zu beantworten. Je größer und ausführlicher die Docstrings, desto einfacher ist es nach geraumer Zeit wieder als Entwickler einzusteigen.

Zwei Beispiele aus Headers von meinen Skripten / Programmen (gekürzt):

Aus einem größeren GUI:

Code: Alles auswählen

#! /usr/bin/python
"""
    SPlot is a programm to visualize SAXS data
    it can cope with ASA, gnom output, and itp77 output files
    for further information see the help-html files.
"""

__author__ = "..."
__mail__ = "...@..."
__revision__ = """...
0.2.9.11\t17. Nov. 06\tstatic lines introduced in the colum chooser dialog
0.2.9.12\t17. Nov. 06\tdisplaying version history now with scrolled panel
0.2.9.13\t17. Nov. 06\tthe fit display can be checked and unchecked"""
__version__ = __revision__.splitlines()[-1].split()[0]
__date__ = __revision__.splitlines()[-1].split('\t')[1]


und aus einer Skriptsammlung:

Code: Alles auswählen

#! /usr/bin/python
# -*- coding: iso-8859-1 -*-

# header information for script2html.py:

# SPIDER comments for script2html.py starting with ';~'
# keywords for script2html.py starting with '#~ [keyword]'
#~ [topic] SAXS
#~ [description] preparing surface for dammin model representation in DINO
#~ [requirements] msms
#~ [version] 0.1
#~ [author] ....
#~ [date] 17. March 2006

#... und dann noch ein paar __metadaten__
# alles hinter #~ kann ich mit einem Parser auslesen und ein html-Dokument
# integrieren, was Nutzern auf einer internen web-Seite zur Verfügung steht.
# Ziemlich einfach, aber es funktioniert.


HTH
Christian

[jens]

Unbedingt die Docstrings für die Entwicklungs drin lassen

Ich glaube da hast du mich falsch verstanden... Ich will die DocStrings nicht per Hand löschen, sondern das kann Python automatisch machen, siehe:
http://www.python-forum.de/post-47042.html#47042

[Leonidas]

Darüber hinaus kannst du dir die Revision automatisch von deiner VC-Software einsetzen lassen.

[CM]

@Jens: Ich habe Dich richtig verstanden und meine Du solltest die Docstrings nicht rausnehmen, bevor Du es einen Nutzer damit werkeln läßt - es sei denn eine der oben genannten Ausnahmen trifft zu. D. h. auch, daß Dein setup.py - oder was immer Du nutzt - das nicht tun sollte. Es ist meine Meinung, Du kannst natürlich eine andere haben.

@Leonidas: Stimmt - aber ich mache es trotzdem per Hand. Allerdins könnte ich das auch __histrory__ oder sonstswie nennen.

Gruß,
Christian

[jens]

@Leonidas: Hab mir mal die svn:keywords angeschaut:
http://svnbook.red-bean.com/nightly/en/ ... l.keywords
Muß ich mal probieren

@CM: Also in PyLucid ist das nur abhängig vom Handler... Also der User kann selber entscheiden ob er einen Handler mit -OO nimmt oder nicht

[jens]

@Leonidas: Hab mir mal die svn:keywords angeschaut: ... Muß ich mal probieren

Hab ich mal Probiert:
https://pylucid.net/trac/browser/trunk/ ... py?rev=617
[code=]Last commit info:
----------------------------------
LastChangedDate: $LastChangedDate$
Revision.......: $Rev$
Author.........: $Author$
date...........: $Date$[/code]
Geht so aber nicht...

Weiß jemand wie man die svn:keywords benutzt???

[BlackJack]

Hast Du auch das Property für die Quelltext-Dateien gesetzt? Schlüssel ist svn:keywords und Wert eine Liste der gewünschten "Variablen".

Edit: Ich hätte ja mal den Link anklicken können.

Wie sieht's aus, wenn Du die Datei "auscheckst"? Im Repository selbst werden diese Zeichenketten nicht ersetzt, die Werte werden erst beim auschecken eingesetzt.

[jens]

Ja, das stimmt. Das habe ich nicht. Aber da blick ich auch nicht ganz durch. Was soll ich als value für svn:keywords angeben? Einfach eine Liste wie "Rev, Author, Date, LastChangeDate" ???

[BlackJack]

Also ich gebe die Werte immer als ein Keyword pro Zeile an.

[jens]

Aha... Es geht ja irgendwie doch... Hab beim Update meine Info's drin:
[code=]Last commit info:
----------------------------------
LastChangedDate: $LastChangedDate: 2006-12-01 18:47:53 +0100 (Fr, 01 Dez 2006) $
Revision.......: $Rev: 617 $
Author.........: $Author$
date...........: $Date: 2006-12-01 18:47:53 +0100 (Fr, 01 Dez 2006) $[/code]

Nur Author fehlt... Aber das ist auch nicht in den keyword drin...

Was ich jetzt aber nicht ganz verstehe, warum muß ich überhaupt ein 'svn:keywords' setzten?

Und vor allem: Wie kann ich das für alle Dateien setzten? Denn ich kann es wohl nicht auf das Hauptverzeichnis setzten und fertig...

[birkenfeld]

Was ich jetzt aber nicht ganz verstehe, warum muß ich überhaupt ein 'svn:keywords' setzten?

Damit SVN weiß, dass du diese Ersetzungen willst. Die sind nämlich nicht immer sinnvoll oder gewollt.

Und vor allem: Wie kann ich das für alle Dateien setzten? Denn ich kann es wohl nicht auf das Hauptverzeichnis setzten und fertig...

svn propset -R

[jens]

OK, das hab ich nun mal gemacht: https://pylucid.net/trac/changeset/631

Irgendwie erscheint es mit aber als nicht so Praktisch... Ich meine warum ist das nicht so:

Ein 'svn:keywords' setzt man nur auf ein Verzeichnis und gibt dabei die Dateiendungen an, z.B. *.py. Es wirkt sich dann rekursiv auf alle Dateien und Unterverzeichnisse aus.
Man kann aber gezielt zu jeder Datei sagen, das die keywords nicht ersetzt werden sollen.

[BlackJack]

Du kannst mit `propset` auch bei mehreren Dateien die Properties setzen, also z.B. ``*.py`` angeben.

Ausserdem kannst Du in der Konfigurationsdatei unter `~/.subversion` (k.A. wo das unter Windows liegt) folgendes Eintragen:

Code: Alles auswählen

enable-auto-props = yes

[auto-props]
*.py = svn:keywords=Date Rev

Achtung: Da würde ich dringend von abraten, weil das für den Benutzeraccount gilt, also auch Zugriffe auf fremde Repositories betrifft. Ausserdem wirken sich solche Automatiken natürlich auch auf Quelltext aus, der nicht von Dir ist. Wenn Du also ein kleines Modul aus den Codesnippets hier in Dein Repository übernimmst, in dem eine Revision und ein Author steht, auch wenn die Angaben aus einem anderen VCS stammen wie zum Beispiel CVS, dann ändert sich das in Deinem Repository plötzlich auf Deinen Namen und eine SVN-Revisionsnummer. Nicht unbedingt das was man möchte.

Der Autor von meinem Lieblingsbuch über Subversion rät sogar ganz von solchen automatischen Ersetzungen ab. Er schreibt, er hatte damit schon mehr Ärger als ihm lieb war. Betrifft Python zwar nicht so stark, aber bei Sprachen in denen ``$`` ganz "natürlich" im Quelltext vorkommen, ergeben sich gerne mal Ersetzungen an falscher Stelle. Zum Beispiel in Perl, Bash, PHP oder LaTeX kann das Muster ``$keyword irgendwas $`` schon mal irgendwo "aus versehen" im Quelltext vorkommen.

In LaTeX hat's mich sogar schonmal erwischt, da hatte ich eine Identitätsfunktion in Haskell im Text beschrieben und die als Formel gesetzt: $id x = x$. CVS hat mir damals eine nette Ersetzung dafür gemacht.

[jens]

Hab jetzt ein Skript zum automatischen setzten der svn:keywords gemacht:

http://www.python-forum.de/topic-9243.html