¿Cuál es el mejor código de esqueleto de módulo de biblioteca de Python?

Question

Muchos Python IDE le comenzar con una plantilla como:

print 'hello world' 

eso no es suficiente ... Así que aquí está mi código esqueleto para obtener esta pregunta comenzó:

Mi Módulo esqueleto, versión corta:

#!/usr/bin/env python 

""" 
Module Docstring 
""" 

# 
## Code goes here. 
# 

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

if __name__=='__main__': 
    test() 

y,

Mi Módulo esqueleto, Versión larga:

#!/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() 

Notas (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. 

""" 

alternativo esqueleto, versión larga: (. Código adaptada de la respuesta 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() 

Hay un montón de PEP que presentan recomendaciones de estilo de codificación. ¿Me estoy perdiendo las mejores prácticas importantes? ¿Cuál es el mejor código de esqueleto de Python?

actualización

Muéstrame cualquier tipo de "mejor" que prefiera. Cuéntanos qué métricas usaste para calificar "lo mejor".

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 
""" 

El módulo puede o no contener una función main modo que no es parte de la plantilla.

Answer 2

Dependiendo de la naturaleza del programa, podría considerar elegir una licencia y ponerla al principio del archivo.

Answer 3

A menudo es aconsejable establecer

#coding=<coding> 

en la segunda línea. Como

#coding=utf8 

Por ejemplo. Esta alternativa a la verbosa

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

Ver PEP-263 para obtener más información.

---

Editar para una respuesta completa: Depende de la situación. Si es para algún proyecto interno, más simple es mejor. Pero casi siempre tienen

def main(): 
    #code 
    pass 

if __name__=="__main__": 
    main() 

Si tengo la intención de publicar el código, agrego términos de documentación y licencias apropiadas, así como la Directiva de codificación mencionada.

El shebang (#!/usr/bin/env python) solo es necesario para el archivo que se pretende que sea el ejecutable.

Answer 4

Volviendo algo es una buena práctica también (llamados aquí con args):

... 
import sys 

def main(args): 
    return 0 

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

Pero se está volviendo más compleja que un simple "hola mundo".

Answer 5

Aún mejor, aquí está la presentación de embalaje sugerido por el Dr. Tito Brown:

http://github.com/ctb/SomePackage

Answer 6

¿Qué tal:

... 
import sys 

def main(*args): 
    return 0 

if __name__=='__main__': 
    sys.exit(main(*sys.argv[1:])) 

Luego, por supuesto modificar el esqueleto principal para reflejar los parámetros actuales del programa (después del nombre de archivo):

def main(arg1, arg2, *args): 
    ... 

(Sorprendido no podemos usar el descuento en los comentarios ...)

Answer 7

Diría que el mejor es el más simple que satisface sus requisitos. Cuantos más datos ponga en el "esqueleto", más datos obsoletos, sin sentido o erróneos podrá obtener.

• La pieza if __name__=='__main__': no es necesaria en un módulo que es solo un módulo. Las pruebas pueden ser parte del módulo, pero incluso así podrían llamarse externamente. Llamar a un módulo directamente es a menudo inconveniente (o imposible, por ejemplo, cuando se utilizan importaciones relativas).
• El intérprete de Python suele decir que cuando se necesita la información de codificación, no todos los códigos de pieza necesitan caracteres que no sean ascii.

El mínimo razonable en mi humilde opinión es el docstring al comienzo del módulo. Otras piezas, mencionadas en su pregunta y otras respuestas también son a menudo útiles, pero de ninguna manera son obligatorias.

Answer 8

Los módulos no son ejecutables, por lo que no deberían tener un shebang.

Las cadenas de documentos son buenas.

La codificación es útil.

Metadatos como autor, derechos de autor, versión y licencia, como mejor se almacenan en setup.py como parte de los metadatos del paquete. El uso de los atributos del módulo __(metadata)__ es una práctica desactualizada, ya que es anterior al momento en que Python tenía los metadatos del paquete. Si el código es lo suficientemente efímero como para no garantizar el embalaje, es poco probable que necesite alguno de los metadatos.

Características adicionales como prueba() o un truco __main__ que no uso lo suficiente para garantizar la inclusión en una plantilla de módulo.

Así que la única plantilla necesaria es:

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

bonito y sencillo.