Quel est le meilleur code squelette de module de bibliothèque Python ?

Question

De nombreux IDE python vous feront démarrer avec un modèle comme celui-ci :

print 'hello world'

Ce n'est pas suffisant... Voici donc mon code squelette pour commencer cette question :

Le squelette de mon module, version courte :

#!/usr/bin/env python

"""
Module Docstring
"""

#
## Code goes here.
#

def test():
    """Testing Docstring"""
    pass

if __name__=='__main__':
    test()

et,

Mon module squelette, version longue :

#!/usr/bin/env python
# -*- coding: ascii -*-

"""
Module Docstring
Docstrings: http://www.python.org/dev/peps/pep-0257/
"""

__author__ = 'Joe Author (joe.author@website.org)'
__copyright__ = 'Copyright (c) 2009-2010 Joe Author'
__license__ = 'New-style BSD'
__vcs_id__ = '$Id$'
__version__ = '1.2.3' #Versioning: http://www.python.org/dev/peps/pep-0386/

#
## Code goes here.
#

def test():
    """ Testing Docstring"""
    pass

if __name__=='__main__':
    test()

Notes ( PEP 8 , UTF-8 ):

"""
===MODULE TYPE===
Since the vast majority of my modules are "library" types, I have constructed
this example skeleton as such. For modules that act as the main entry for
running the full application, you would make changes such as running a main()
function instead of the test() function in __main__.

===VERSIONING===
The following practice, specified in PEP 8, no longer makes sense:

   __version__ = '$Revision: 1.2.3 $'

For two reasons:
    (1) Distributed version control systems make it neccessary to include more
        than just a revision number. E.g. author name and revision number.
    (2) It's a revision number not a version number.

Instead, the __vcs_id__ variable is being adopted. This expands to, for
example:
    __vcs_id__ = '$Id: example.py,v 1.1.1.1 2001/07/21 22:14:04 goodger Exp $'

===VCS DATE===
Likewise, the date variable has been removed:

    __date__ = '$Date: 2009/01/02 20:19:18 $'

===CHARACTER ENCODING===
If the coding is explicitly specified, then it should be set to the default
setting of ASCII. This can be modified if necessary (rarely in practice).
Defaulting to UTF-8 can cause anomalies with editors that have poor unicode
support.

"""

Squelette alternatif, version longue :

(Code adapté de la réponse de DasIch).

#!/usr/bin/env python
# -*- coding: ascii -*-

"""
package.module
~~~~~~~~~~~~~

A description which can be long and explain the complete
functionality of this module even with indented code examples.
Class/Function however should not be documented here.

:copyright: year by my name, see AUTHORS for more details
:license: license_name, see LICENSE for more details
"""

#
## Code goes here.
#

def test():
    """ """
    pass

if __name__=='__main__':
    test()

Il existe de nombreux PEP qui proposent des recommandations de style de codage. Est-ce que je manque des bonnes pratiques importantes ? Quel est le meilleur squelette de code pour un module Python ?

Mise à jour

Montrez-moi n'importe quel type de "meilleur" que vous préférez. Dites-nous quels paramètres vous avez utilisés pour qualifier le "meilleur".

Answer 1

#!/usr/bin/env python
# coding: utf-8
"""
    package.module
    ~~~~~~~~~~~~~

    A description which can be long and explain the complete
    functionality of this module even with indented code examples.
    Class/Function however should not be documented here.

    :copyright: year by my name, see AUTHORS for more details
    :license: license_name, see LICENSE for more details
"""

Le module peut ou non contenir un main donc cela ne fait pas partie du modèle.

Answer 2

Il est souvent conseillé de définir

#coding=<coding>

à la deuxième ligne. Comme

#coding=utf8

Par exemple. C'est une alternative à la méthode verbeuse

# -*- coding: <encoding name> -*-

Voir PEP-263 pour plus d'informations.

---

Editer pour la réponse complète : Cela dépend de la situation. Si c'est pour un projet interne, le plus simple est le mieux. Mais j'ai presque toujours

def main():
    #code
    pass

if __name__=="__main__":
    main()

Si j'ai l'intention de publier le code, j'ajoute la documentation et les conditions de licence appropriées ainsi que la directive d'encodage mentionnée.

Le shebang ( #!/usr/bin/env python ) n'est nécessaire que pour le fichier qui est censé être l'exécutable.

Answer 3

Mieux encore, voici la disposition suggérée par le Dr Titus Brown :

http://github.com/ctb/SomePackage

Answer 4

Renvoyer quelque chose est également une bonne pratique (ici avec des args appelés) :

...
import sys

def main(args):
    return 0

if __name__=='__main__':
    sys.exit(main(sys.argv))

Mais cela devient plus complexe qu'un simple "hello world".

Answer 5

Les modules ne sont pas exécutables, donc ils ne devraient pas avoir de shebang.

Les docstrings sont bien.

Le codage est utile.

Les métadonnées telles que l'auteur, le droit d'auteur, la version et la licence sont stockées de manière optimale dans la base de données. setup.py dans le cadre des métadonnées de l'emballage. L'utilisation de __(metadata)__ Les attributs de module sont une pratique dépassée, car elle est antérieure à l'époque où Python disposait de métadonnées de packaging. Si le code est d'une nature suffisamment éphémère pour ne pas justifier un packaging, il est peu probable que vous ayez besoin des métadonnées.

Des fonctionnalités supplémentaires telles que test() ou un __main__ Je n'utilise pas assez le hack pour justifier son inclusion dans un modèle de module.

Donc le seul modèle nécessaire est :

# -*- coding: ascii -*-
"""
"""

Sympathique et simple.