¡Hola! Bienvenidos a este tutorial para crear la estructura de directorios de nuestros proyectos en Python.

Este tutorial te guiará en el uso de Pyscaffold, una librería de Python para organizar proyectos desde cero en este lenguaje de programación, para crear el esqueleto de directorios y archivos que necesitarás para comenzar un proyecto en Python.

Al final de este tutorial serás capaz de usar esta herramienta para crear un proyecto con los elementos básicos y modificarlos según los requerimientos del enunciado o del proyecto en el que estés trabajando.

Objetivos

  1. Comprender la estructura de directorios que hace parte de un proyecto de Python.
  2. Utilizar PyScaffold para crear el esqueleto de un nuevo proyecto en Python.
  3. Personalizar la estructura de directorios de un nuevo proyecto en Python para comenzar a trabajar en él.

Requerimientos Técnicos

Para el siguiente tutorial es necesario tener Python 3 y pip instalado.

Es importante entender la estructura de proyectos que utilizaremos para trabajar en Python. En su nivel más básico, la estructura de carpetas responde a la siguiente jerarquización:

Vemos entonces que tenemos tres carpetas en nuestro directorio principal. La carpeta docs que contendrá la documentación relacionada con nuestro proyecto, la carpeta src que contendrá todo el código fuente en Python y la carpeta tests que contendrá el código de las pruebas.

Al utilizar PyScaffold, obtendremos adicionalmente varios esqueletos de archivos que podemos completar y cuya ubicación es la siguiente:

En la tabla a continuación encontrará una breve descripción de cada archivo generado automáticamente:

Directorio

Archivo

Descripción

raíz

.coveragerc

Este es el archivo de cubrimiento o coverage que indica qué proporción del código está cubierto por pruebas automatizadas.

raíz

.gitignore

Este archivo contiene el nombre de archivos y extensiones que no serán considerados para un commit en GIT.

raíz

AUTHORS.rst

Archivo de texto con el nombre de los programadores que contribuyen al código.

raíz

CHANGELOG.rst

Archivo de texto con la lista de cambios realizados.

raíz

LICENSE.txt

Archivo de texto que contiene el tipo de licencia del desarrollo.

raíz

README.rst

Archivo de texto con la descripción del proyecto. Sirve como página principal en los repositorios de Github.

raíz

requirements.txt

Archivo que contiene las librerías y dependencias que se deben instalar para poder correr el programa, a través de la instrucción

pip install -r requirements.txt

raíz

setup.cfg

Archivo de configuración del proyecto con los parámetros para setup.py

raíz

setup.py

Archivo de configuración del proyecto en Python.

docs

authors.rst

Archivo de texto para la documentación que contiene la lista de los programadores que contribuyen al código.

docs

changelog.rst

Archivo de texto para la documentación con la lista de cambios realizados.

docs

conf.py

Archivo de configuración de la documentación en Sphinx.

docs

index.rst

Página principal de la documentación para ser generada en Sphinx.

docs

license.rst

Archivo de texto para la documentación que contiene el tipo de licencia del desarrollo.

docs

Makefile

Archivo para la generación automática de la documentación en Sphinx.

docs/_static

.gitignore

Este archivo contiene el nombre de archivos y extensiones a ignorar a nivel de la página estática de la documentación.

src/mi_proyecto

__init__.py

Archivo principal desde donde corre el proyecto en Python.

tests

conftest.py

Archivo de configuración base de tests para Python

Con relación a la documentación, por defecto PyScaffold crea un directorio para generar una página estática en Sphinx. Por el momento no nos ocuparemos de la documentación y volveremos sobre ella en un tutorial posterior.

Configuración en ambiente virtual

Antes de comenzar a trabajar, es necesario configurar un ambiente virtual de desarrollo asociado a nuestro proyecto. Para esto primero debemos instalar la herramienta virtualenv haciendo:

pip install virtualenv

Posteriormente podemos ir al directorio en donde crearemos nuestro proyecto y crear la carpeta en donde guardaremos el ambiente virtual asociado a nuestro desarrollo. Sólo debemos escribir la instrucción:

virtualenv venv

En esta instrucción, venv es el nombre de nuestro ambiente virtual. El resultado de invocar esta instrucción es la creación de una carpeta con dicho nombre, en donde estará guarda la configuración de nuestro ambiente virtual. Si tienes problemas corriendo la instrucción virtualenv, verifica que las carpetas que contienen los ejecutables y las librerías de tu instalación de base de Python estén en el Path de tu sistema operativo.

Finalmente, para activar nuestro ambiente virtual sólo debemos ejecutar el script en la siguiente ruta:

venv\Scripts\activate

Si estás usando windows puedes hacerlo usando la instrucción &. Si estás usando linux, basta con usar la instrucción source. En tu consola, debe aparecer antes de cada instrucción entre paréntesis el nombre del ambiente que acabas de activar. En nuestro ejemplo, debe estar antecedido por (venv).

Instalación de librerías iniciales

Ahora debemos instalar PyScaffolding. Para esto, y habiendo activado previamente nuestro ambiente virtual, sólo debemos usar la instrucción:

pip install pyscaffold

Una vez instalada, estamos listos para generar la estructura de nuestro proyecto, en el siguiente paso de nuestro tutorial.

Una vez hemos instalado la librería PyScaffold, podemos entonces crear nuestro esqueleto inicial usando la instrucción:

putup mi_proyecto --no-skeleton

El flag --no-skeleton nos permite crear la estructura inicial sin generar archivos de ejemplo que PyScaffold crea por defecto. Con esto, ya deberíamos poder ver la estructura de directorios base de nuestro proyecto. Si estás utilizando Visual Studio Code u algún otro editor de código similar, el resultado debería parecerse a la siguiente imagen:

¡Y listo! Tenemos todo lo necesario para comenzar en nuestro proyecto, e incluso podemos subirlo a un repositorio usando GIT.

A continuación una lista de enlaces útiles que te llevarán a la documentación de las tecnologías empleadas en este tutorial.