¿Cuál es la mejor estructura de proyecto para una aplicación Python?[cerrado]

StackOverflow https://stackoverflow.com/questions/193161

Pregunta

Imagine que usted desea desarrollar un no-trivial de escritorio para usuario final (no web) aplicación en Python.¿Cuál es la mejor manera de estructurar el proyecto de la jerarquía de carpetas?

Características deseables son la facilidad de mantenimiento, IDE-la amistad, la idoneidad para el control de la fuente de derivación/fusión, y la fácil generación de paquetes de instalación.

En particular:

  1. ¿Dónde poner la fuente?
  2. ¿Dónde se coloca la aplicación de secuencias de comandos de inicio?
  3. ¿Dónde se sitúa el proyecto IDE resto?
  4. ¿Dónde se coloca la unidad/pruebas de aceptación?
  5. ¿Dónde se coloca la no-Python datos, tales como archivos de configuración?
  6. ¿Dónde se coloca la no-Python fuentes, tales como C++ para pyd/modo binario módulos de extensión?
¿Fue útil?

Solución

No se mucho de la materia.Lo que te hace feliz va a trabajar.No hay una gran cantidad de reglas tontas porque Python proyectos pueden ser simples.

  • /scripts o /bin para ese tipo de interfaz de línea de comandos cosas
  • /tests para sus pruebas
  • /lib para el C-las bibliotecas de idioma
  • /doc para la mayoría de la documentación
  • /apidoc para el Epydoc generado por la API de google docs.

Y el directorio de nivel superior puede contener el README, configuración y demás.

La difícil elección es si usar o no un /src árbol.Python no tiene una distinción entre /src, /lib, y /bin como Java o C ha.

Desde un nivel superior /src directorio es visto por algunos como carente de sentido, su directorio de nivel superior puede ser el nivel superior de la arquitectura de la aplicación.

  • /foo
  • /bar
  • /baz

Les recomiendo poner todo esto bajo el "nombre-de-mi-producto de directorio".Por lo tanto, si usted está escribiendo una aplicación denominada quux, el directorio que contiene todo este material se denomina /quux.

Otro proyecto PYTHONPATH, entonces , puede incluir /path/to/quux/foo la reutilización de la QUUX.foo el módulo.

En mi caso, desde que tengo uso de Komodo Edit, mi IDE cuft es una sola .KPF archivo.De hecho, me puso que en el nivel superior /quux directorio y omite agregar a SVN.

Otros consejos

De acuerdo con la Estructura del sistema de archivos de Jean-Paul Calderone Proyecto Python : 

Project/
|-- bin/
|   |-- project
|
|-- project/
|   |-- test/
|   |   |-- __init__.py
|   |   |-- test_main.py
|   |   
|   |-- __init__.py
|   |-- main.py
|
|-- setup.py
|-- README

Este entrada de blog por Jean-Paul Calderone comúnmente se da como una respuesta en #python en Freenode.

Estructura de archivos de un proyecto de Python

Hacer:

  • el nombre del directorio en algo relacionado a su proyecto.Por ejemplo, si el proyecto se denomina "Torcido", el nombre del directorio de nivel superior para sus archivos de origen Twisted.Al hacer comunicados, usted debe incluir un número de versión de sufijo: Twisted-2.5.
  • crear un directorio Twisted/bin y poner sus ejecutables no, si tiene alguna.No les .py extensión, incluso si son de Python archivos de origen.No poner el código en ellos a menos de una importación de y llamada a una función principal definido en alguna otra parte en sus proyectos.(Leve arruga:desde que en Windows, el intérprete es seleccionado por la extensión del archivo, su Windows a los usuarios que realmente desean el .py extensión.Así, cuando el paquete de Windows, puede que desee agregar.Lamentablemente, no hay fácil distutils truco que yo conozco para automatizar este proceso.Teniendo en cuenta que en POSIX el .py extensión es sólo una verruga, mientras que en Windows la falta es en realidad un bug, si su base de usuarios incluye a los usuarios de Windows, puede que desee optar a tener .py extensión en todas partes.)
  • Si su proyecto es expressable como una sola fuente de Python archivo, a continuación, poner en el directorio y el nombre de algo relacionado con su proyecto.Por ejemplo, Twisted/twisted.py.Si necesita varios archivos de código fuente, crear un paquete en lugar de (Twisted/twisted/, con un vacío Twisted/twisted/__init__.py) y coloque los archivos de origen en ella.Por ejemplo, Twisted/twisted/internet.py.
  • pon tu unidad de pruebas en un sub-paquete de su paquete (nota - esto significa que la única fuente de Python opción de archivo de arriba era un truco que siempre necesita al menos otro archivo para su unidad de pruebas).Por ejemplo, Twisted/twisted/test/.Por supuesto, hacer un paquete con Twisted/twisted/test/__init__.py.Lugar de las pruebas en archivos como Twisted/twisted/test/test_internet.py.
  • agregar Twisted/README y Twisted/setup.py para explicar e instalar el software, respectivamente, si se siente agradable.

No:

  • poner la fuente en un directorio llamado src o lib.Esto hace que sea difícil de ejecutar sin necesidad de instalación.
  • pon tu pruebas fuera de su paquete de Python.Esto hace que sea difícil para ejecutar las pruebas en contra de una versión instalada.
  • crear un paquete que sólo tiene un __init__.py y, a continuación, poner todo el código en __init__.py.Acaba de hacer un módulo en lugar de un paquete, es más sencillo.
  • intentar llegar a la mágica hacks para hacer que Python capaz de importar el módulo o paquete sin necesidad de que el usuario agregue el directorio que contiene a su ruta de importación (ya sea a través de PYTHONPATH o algún otro mecanismo).Usted no manejar correctamente todos los casos, y se enoja cuando el software no funciona en su entorno.

Echa un vistazo a Open Sourcing a Python Proyectar de la manera correcta .

Permítanme extraer el diseño del proyecto parte de ese excelente artículo:

  

Al configurar un proyecto, el diseño (o la estructura del directorio) es importante para hacerlo bien. Una disposición sensata significa que los contribuyentes potenciales no tienen que pasar una eternidad buscando un código; Las ubicaciones de los archivos son intuitivas. Dado que estamos lidiando con un proyecto existente, significa que probablemente necesites mover algunas cosas.

     

Comencemos por la parte superior. La mayoría de los proyectos tienen una cantidad de archivos de nivel superior (como setup.py, README.md, required.txt, etc.). Hay tres directorios que cada proyecto debería tener:

     
      
  • Un directorio de documentos que contiene documentación del proyecto
    •   
  • Un directorio nombrado con el nombre del proyecto que almacena el paquete Python real
    •   
  • Un directorio de prueba en uno de dos lugares   
        
    • En el directorio del paquete que contiene código de prueba y recursos
      •   
    • Como un directorio de nivel superior independiente   Para tener una mejor idea de cómo deben organizarse sus archivos, aquí hay una instantánea simplificada del diseño de uno de mis proyectos, sandman:
      •   
    •   
$ pwd
~/code/sandman
$ tree
.
|- LICENSE
|- README.md
|- TODO.md
|- docs
|   |-- conf.py
|   |-- generated
|   |-- index.rst
|   |-- installation.rst
|   |-- modules.rst
|   |-- quickstart.rst
|   |-- sandman.rst
|- requirements.txt
|- sandman
|   |-- __init__.py
|   |-- exception.py
|   |-- model.py
|   |-- sandman.py
|   |-- test
|       |-- models.py
|       |-- test_sandman.py
|- setup.py
  

Como puede ver, hay algunos archivos de nivel superior, un directorio de documentos (generado es un directorio vacío donde sphinx colocará la documentación generada), un directorio sandman y un directorio de prueba debajo de sandman.

La " Python Packaging Authority " tiene un proyecto de muestra:

https://github.com/pypa/sampleproject

Es un proyecto de muestra que existe como ayuda para el Tutorial de la Guía del usuario de Python Packaging sobre Empaquetado y Distribución de Proyectos.

Pruebe a iniciar el proyecto con el python_boilerplate de la plantilla.Sigue en gran parte de las mejores prácticas (por ejemplo, los que están aquí), pero se adapta mejor en caso de que se encuentre dispuesto a dividir el proyecto en más de un óvulo en algún momento (y créanme, con cualquier cosa, pero el más sencillo de los proyectos, lo hará.Una situación común es donde usted tiene que utilizar un localmente versión modificada de alguien más, de la biblioteca).

  • ¿Dónde poner la fuente?

    • Para decentemente los grandes proyectos que tiene sentido dividir el código fuente en varios huevos.Cada huevo iba a ir como independiente setuptools-diseño de bajo PROJECT_ROOT/src/<egg_name>.

  • ¿Dónde se coloca la aplicación de secuencias de comandos de inicio?

    • La opción ideal es tener la aplicación de comandos de inicio registrarse como un entry_point en uno de los huevos.

  • ¿Dónde se sitúa el proyecto IDE resto?

    • Depende de la IDE.Muchos de ellos mantienen sus cosas en PROJECT_ROOT/.<something> en la raíz del proyecto, y esto está bien.

  • ¿Dónde se coloca la unidad/pruebas de aceptación?

    • Cada huevo tiene un conjunto independiente de pruebas, se mantuvo en su PROJECT_ROOT/src/<egg_name>/tests directorio.Yo personalmente prefiero utilizar py.test para ejecutar las mismas.

  • ¿Dónde se coloca la no-Python datos, tales como archivos de configuración?

    • Depende.Puede haber diferentes tipos de datos de Python.
      • "Los recursos", es decir,los datos que deben ser envasados dentro de un huevo.Esta información va en el correspondiente huevo directorio, en algún lugar dentro del paquete de espacio de nombres.Puede ser utilizado a través de pkg_resources paquete.
      • "Config-files", es decir,no los archivos de Python que deben ser considerados como externos a los archivos de origen del proyecto, pero tiene que ser inicializado con algunos valores cuando la aplicación empieza a ejecutarse.Durante el desarrollo prefiero mantener este tipo de archivos en PROJECT_ROOT/config.Para la implementación puede haber varias opciones.En Windows se puede utilizar %APP_DATA%/<app-name>/config, en Linux, /etc/<app-name> o /opt/<app-name>/config.
      • Los archivos generados, es decir,los archivos que pueden ser creados o modificados por la aplicación durante la ejecución.Yo prefiero mantenerlos en PROJECT_ROOT/var durante el desarrollo, y en virtud de /var durante el despliegue del Linux.
  • ¿Dónde se coloca la no-Python fuentes, tales como C++ para pyd/modo binario módulos de extensión?
    • En PROJECT_ROOT/src/<egg_name>/native

Documentación suele ir en PROJECT_ROOT/doc o PROJECT_ROOT/src/<egg_name>/doc (esto depende de si usted considera que algunos de los huevos para ser un grande separada de los proyectos).Alguna configuración adicional será en archivos como PROJECT_ROOT/buildout.cfg y PROJECT_ROOT/setup.cfg.

En mi experiencia, es solo una cuestión de iteración. Ponga sus datos y código donde quiera que vaya. Lo más probable es que te equivoques de todos modos. Pero una vez que tenga una mejor idea de cómo se van a arreglar las cosas, estará en una posición mucho mejor para hacer este tipo de conjeturas.

En cuanto a las fuentes de extensión, tenemos un directorio de Código debajo del tronco que contiene un directorio para python y un directorio para varios otros idiomas. Personalmente, estoy más inclinado a intentar poner cualquier código de extensión en su propio repositorio la próxima vez.

Dicho esto, vuelvo a mi punto inicial: no hagas un gran problema. Ponlo en un lugar que parezca funcionar para ti. Si encuentra algo que no funciona, puede (y debería) cambiarse.

No de datos de python mejor es incluido dentro de sus módulos de Python utilizando el package_data apoyo en setuptools.Una cosa que recomiendo es el uso de espacio de nombres de paquetes para crear compartido espacios de nombres que varios proyectos se puede utilizar, igual que la convención de Java de poner los paquetes en com.yourcompany.yourproject (y ser capaz de tener una compartido com.yourcompany.utils espacio de nombres).

Volver a la ramificación y la fusión, si se utiliza un buen sistema de control de fuentes que se manejan fusiona incluso a través cambia el nombre; Bazar es particularmente bueno en esto.

Contrariamente a algunas otras respuestas aquí, yo estoy +1 en tener una src directorio de nivel superior (con doc y test directorios de lado).Convenciones específicas para la documentación de los árboles de directorios variará dependiendo de lo que estés usando; Esfinge, por ejemplo, tiene sus propias convenciones que su inicio rápido de la herramienta de soporte.

Por favor, por favor apalancamiento setuptools and pkg_resources;esto hace que sea mucho más fácil para otros proyectos se basan en versiones específicas de su código (y varias versiones para ser instalados simultáneamente con diferentes no los archivos de código, si usted está utilizando package_data).

Licenciado bajo: CC-BY-SA con atribución
No afiliado a StackOverflow
scroll top