Python: Aprendiendo desde cero VII – Estructura proyecto

Raul Unzue Pulido 1 enero, 2021 Python 1 Comentario 6,143 Vistas

Python: Aprendiendo desde cero VII – Estructura proyecto

Como ya he comentado varias veces, yo no soy programador, pero he hecho mis pinitos durante estos años. Y una de las cosas que más me interesa cuando gestiono un proyecto, es intentar hacer un diseño lo más limpio posible, y que a la larga no me de problemas ni a mí ni a mi equipo.

Como nuestro objetivo final es aprender Python y generar un pequeño programa, vamos a empezar con conceptos de cómo estructurar las carpetas de nuestro futuro programa. Sé que nos quedan muchos más conceptos por descubrir, pero es interesante descubrir otros temas relacionados.

Así que me pongo manos a la obra, espero que os parezca interesante…

Para empezar vamos a hablar de cómo estructurar los repositorios de nuestro proyecto, e intentaremos, más adelante, hablar un poco de scripting y otros conceptos relacionados.

Decir que me he documentado antes de escribir este post (bueno como casi siempre, pocas cosas son de cosecha propia), con profesionales que saben mucho más de Python o desarrollo que yo (que tampoco es complicado ;P ). Dicho esto, la estructura a seguir, sería más o menos ésta, y ahora la vamos explicando poco a poco:

README.rst
LICENSE
setup.py
requirements.txt
sample/__init__.py
sample/core.py
sample/helpers.py
docs/conf.py
docs/index.rst
tests/test_basic.py
tests/test_advanced.py

README.rst

LICENSE

setup.py

requirements.txt

sample/__init__.py

sample/core.py

sample/helpers.py

docs/conf.py

docs/index.rst

tests/test_basic.py

tests/test_advanced.py

Datos y ficheros que deberemos recopilar:

Nombre del proyecto
Descripción del proyecto
Ficheros y estructura:
- README.rst:
  - Un fichero README permite a un usuario que no conozca el proyecto identificar cual es el objetivo del mismo, su descripción e incluso indica cómo hacer la instalación o ejecución de los ficheros.
  - Es importante, sobre todo si vas a compartir el proyecto en plataformas donde quieres que se contribuya, o tienes compañeros de desarrollo que van a utilizarlo.
  - Se sitúa normalmente en el raíz de la estructura, ya que si lo subes por ejemplo, a Github u otra plataforma, será utilizado para recopilar información.
  - Se puede escribir en casi cualquier formato de texto, pero en desarrollo normalmente se usa Markdown
  - Os dejo un ejemplo:

- LICENSE:
  - Si estáis generando un proyecto para vuestra empresa, uso personal o incluso para compartirlo, es importante definir el tipo de licencia que se va usar en el proyecto. Eso se hace en este fichero.
  - Para definir el tipo de licencia podéis usar la web: https://choosealicense.com/
  - Podéis no colocar ninguna licencia, pero creo que es importante definir el objetivo, aunque lo entregues a la comunidad, para que sea un proyecto serio.
  - Os dejo un ejemplo:

Copyright (c) 2021, El Blog de Negu

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

- CARPETA SAMPLE:
  - Donde se definen los módulos del proyecto, de los que hablaremos en otro apartado.
  - Aunque lo comentamos en otra entrada, un módulo se podría definir cómo un fichero que se puede reutilizar de forma recurrente en un programa. Ya que hasta ahora, sólo hemos hecho ejemplos con variables y funciones que se ejecutan en el momento, pero cuando termina la ejecución se pierden. Un módulo es un fichero que contiene definiciones y declaraciones de Python, que podemos usar luego en un script.
- REQUERIMENTS.TXT:
  - Si nuestro proyecto tiene dependencias, sería el fichero donde definirlas.
- SETUP.PY:
  - Es el script de configuración. Nos permite la gestión de los paquetes y librerías
  - Su propósito es la correcta instalación del software. Sería como el lanzador del programa
- CARPETA DOCS:
  - Carpeta que contiene toda la documentación del proyecto
- CARPETA TEST:
  - Esta carpeta contiene nuestro entorno de test, para realizar las pruebas de nuevas compilaciones