paquetes - modulos python 3
¿Cuál es el mejor código de esqueleto de módulo de biblioteca de Python? (8)
Muchos IDE de python te iniciarán con una plantilla como:
print ''hello world''
Eso no es suficiente ... Así que aquí está mi código de esqueleto para comenzar esta pregunta:
My Module Skeleton, versión corta:
#!/usr/bin/env python
"""
Module Docstring
"""
#
## Code goes here.
#
def test():
"""Testing Docstring"""
pass
if __name__==''__main__'':
test()
y,
My Module Skeleton, versión larga:
#!/usr/bin/env python
# -*- coding: ascii -*-
"""
Module Docstring
Docstrings: http://www.python.org/dev/peps/pep-0257/
"""
__author__ = ''Joe Author ([email protected])''
__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.
"""
Esqueleto alternativo, versión larga:
(Código adaptado 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 muchas 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?
Actualizar
Muéstrame cualquier tipo de "mejor" que prefieras. Cuéntanos qué métricas usaste para calificar "lo mejor".
A menudo es recomendable establecer
#coding=<coding>
en la segunda línea Me gusta
#coding=utf8
Por ejemplo. Esta es una alternativa a la verbosa
# -*- coding: <encoding name> -*-
Ver PEP-263 para 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 tengo
def main():
#code
pass
if __name__=="__main__":
main()
Si tengo la intención de publicar el código, agrego la documentación y los términos de licencia adecuados, así como la directiva de codificación mencionada.
El shebang ( #!/usr/bin/env python ) solo es necesario para el archivo que se supone que es el ejecutable.
Aún mejor, aquí está el diseño del paquete sugerido por el Dr. Titus Brown:
Dependiendo de la naturaleza del programa, podría considerar elegir una licencia y ponerla al comienzo del archivo.
Devolver algo también es una buena práctica (aquí con args llamados):
...
import sys
def main(args):
return 0
if __name__==''__main__'':
sys.exit(main(sys.argv))
Pero se está volviendo más complejo que un simple "mundo de hola".
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 se almacenan mejor en setup.py como parte de los metadatos del paquete. El uso de los atributos del módulo __(metadata)__ es una práctica obsoleta, 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.
Las características adicionales como test () o __main__ hack no utilizo lo suficiente para garantizar la inclusión en una plantilla de módulo.
Entonces, la única plantilla necesaria es:
# -*- coding: ascii -*-
"""
"""
Agradable y simple.
Qué tal si:
...
import sys
def main(*args):
return 0
if __name__==''__main__'':
sys.exit(main(*sys.argv[1:]))
Entonces, por supuesto, modifica ese esqueleto principal para reflejar los parámetros reales del programa (después del nombre del archivo):
def main(arg1, arg2, *args):
...
(Sorprendido, no podemos usar Markdown en los comentarios ...)
Yo diría que lo 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 parte
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.
#!/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 contener o no una función main , por lo que no forma parte de la plantilla.