La estructura de un proyecto: ejemplo Encuentro

Python — Jueves 23 de Mayo de 2013, 18:43


Un tema que se ha visto varias veces, tanto en la lista de PyAr como en la vida real, es que los desarrolladores que no estuvieron involucrados en proyectos grandes, o que sólo estuvieron metidos en uno o dos sistemas (más allá el tamaño), no saben muy bien qué estructura, o qué forma, darle a un proyecto nuevo.

Es totalmente comprensible. La estructura a tener depende de muchos factores: de la complejidad del proyecto, de cuan listo lo deja uno para empaquetarlo, de la prolijidad del desarrollador, etc.

Lo notable es que (en mi experiencia) el proyecto aunque nazca pequeño, siempre conviene que esté ordenado. Y que la forma de ordenarlo, qué estructura darle, cambia en función de las necesidades (como decía arriba) pero que siempre es bueno tener alguna.

En función de todo esto es que paso a contarles qué estructura tiene hoy Encuentro. No es la mejor del mundo, pero es la que a mí me funciona en este y otros proyectos. Y es una buena base como para que alguien que no tiene idea sepa para qué lado ir ordenando los tantos.

El código en sí lo pueden ver acá o si tienen instalado bazaar pueden hacer bzr branch lp:encuentro y exploran el código de forma local.

Bueno, a los bifes.


El código "útil" en sí

Tenemos dos archivos y varios directorios...

- test: Este es un script que básicamente ejecuta todas las comprobaciones que necesitamos para asegurarnos que el proyecto está "verde". En el caso de encuentro, corre las pruebas de unidad (las que están en el directorio tests, ver abajo), luego corre un verificador estático de código genérico (pylint) y finalmente otro verificador puntual para pep 8.

- version.txt: La versión del programa. La tengo separada sólo por consistencia: me gusta que esté en un sólo lado así es la misma para todos los que la necesitan (setup.py, para mostrarlo al arrancar, o cuando el usuario pide info del programa, etc).

- bin/: Aquí (normalmente) hay un sólo archivo, con el nombre del proyecto: encuentro. Este es el script de inicio, el que arranca todo el sistema ya sea cuando lo ejecutamos desde el proyecto mismo, desde un tarball descomprimido, e incluso es el que va a parar a /usr/bin cuando se instala. Este es el único que es ejecutable, el resto del sistema son sólo módulos.

- encuentro/: Es el directorio principal del proyecto (por eso el nombre). Acá tenemos todo el código "de producción" del proyecto, con su estructura interna. Por lo pronto, en este mismo directorio están todos los módulos que tienen que ver con el funcionamiento interno de Encuentro.

- encuentro/ui/: Aquí tenemos todo el código que necesitamos para armar la Interfaz del Usuario del programa. También tiene que ver con el funcionamiento interno de Encuentro, pero es sólo el manejo de la interfaz. La separación de qué va aquí o qué va directamente en encuentro/ a veces es complicada.

- encuentro/ui/media/: Todas las imágenes, audios, etc, que necesitamos para que funcione la UI en sí.

- encuentro/logos/: También imágenes, pero que se usan como identificación del programa en sí. Aunque algunas se usan en la parte de UI, están todas acá porque también se usan en otros contextos (por ejemplo, en la instalación del paquete).

- tests/: Los tests de unidad del proyecto, normalmente un montón de archivos cuyo nombre arranca con "test_" pero también pueden haber otros (módulos o no) para dar soporte a las pruebas.


Otros directorios

Estos son directorios puntuales que tengo para Encuentro. Algunos se repiten con otros proyectos, otros no.

- qtreactor: El módulo de integración entre Qt (el framework de interfaz gráfica que estoy usando) y Twisted (una biblioteca asincrónica que uso para trabajar con la red).

- server: Cuando le decimos al programa "local" de Encuentro que actualice los episodios, se baja algunos archivos comprimidos de mi server, con toda la metadata. Estos archivos comprimidos se generan una vez al día a partir de los sitios webs de Encuentro, Conectate, BACUA, etc. El código para realizar todo esto está en este directorio.

- web: Todos los archivos necesarios para montar el sitio web del proyecto.

- windows: Imágenes, configuraciones, y explicaciones necesarias para armar el .exe en Windows y luego armar con eso el instalador final que se distribuye.


Otros archivos

Estos son otros archivos que no tienen demasiada relación entre sí, pero que son importantes en distintos momentos de la vida del proyecto:

- AUTHORS, COPYING: Info legal: cuales son las personas que participaron del proyecto, y la licencia del mismo.

- LEEME.txt, README.txt, AYUDA.txt: Textos de ayuda para la persona que llega por primera vez al proyecto (viéndolo desde los archivos fuente). Está en dos idiomas, pero como Encuentro es inherentemente para personas que hablan castellano, el LEEME es el que tiene la info posta.

- anuncio.txt, pasos_release.txt: Recordatorios y textos preparados para mí (o para el que haga la release del proyecto... que vengo siendo siempre yo, :p).

- pylintrc: Un archivo de configuración para el verificador estático de código que mencionaba arriba.

- setup.py, MANIFEST.in: Script principal de empaquetamiento e instalación, más un archivo que podríamos decir de configuración del mismo.

- encuentro.desktop, source_encuentro.py: Dos archivitos necesarios en sistemas Debian/Ubuntu (al menos). El primero le pasa al sistema info para poner el programa en el menú del usuario, y el otro es usado en caso de que el programa crashee, para informar automáticamente del problema.


Python Argentina

comentarios

  1. Yo usaba una organización parecida pero en los últimos proyectos que encaré cambié algunas cosas.

    En primer lugar no tengo un directorio `bin`, sino que incluyo un entry_point (o más) en `setup.py`. Esto me permite reusar funciones de modulos, y (en windows/Mac) llamar a python o pythonw (segun la aplicacion sea de linea de comando o de ventana).

    También inclui los tests dentro del directorio del proyecto. De esta forma están disponibles en el proyecto instalado. Los tests están declarados también en `setup.py`.

    Uso tox para probarlo en multiples versiones y travis para hacer CI/

    Finalmente estoy usando zest_releaser para facilitar el proceso de release. Automatiza un monton de cosas y me salva de errores. Entre esas cosas está el versionado, el manejo de release notes, la subidad a PyPI y la posibilidad de poner hooks que se ejecutan antes/durante/despues del release. Por ejemplo yo lo tengo de forma tal que se corren los tests antes de empezar el proceso.

    Escrito por Hernán — 23 May 2013, 20:48

  2. Gran post Facu! Hace unos días venía pensando justamente esto: Tengo que reorganizar la estructura de TOMy... así que ya tengo por donde empezar en PyCamp :D

    Escrito por Jose — 24 May 2013, 10:50


Añadir comentario

authimage






Powered by LifeType