Creación de paquetes de Python

Hoy voy a iniciar una serie de entradas en las que explicaré el proceso de creación de paquetes de Python. Además de explicar diferentes opciones para su distribución, incluyendo subirlos a PyPI. La serie consta de las siguiente siete entradas:

1. Creación de paquetes de Python
2. Pruebas unitarias en Python
3. Probar en múltiples versiones de Python
4. Cobertura de las pruebas unitarias en Python
5. Gestionar las dependencias de paquetes Python
6. Documentar paquetes de Python
7. Distribuir paquetes de Python

Durante las entradas crearemos un paquete de ejemplo, al que llamaremos pylane, con el que ver los diferentes pasos a seguir. Este paquete lo podéis encontrar en nuestra cuenta GitHub.

El código utilizado en esta serie se publicará en el repositorio pylane en la cuenta de GitHub de Analytics Lane.

Creación de un paquete de Python

Poder estructurar el código en paquetes es algo de gran ayuda para no solo para reutilizar el trabajo, sino que para mantener este, evolucionarlo y distribuirlo de una forma estándar. En una serie anterior hemos visto cómo distribuir el código en JavaScript, pero nunca lo habíamos tratado en Python.

Una de las mejores soluciones para la creación de paquetes en Python es Cookiecutter, ya que ofrece múltiples plantillas a partir de las cuales comenzar nuestro trabajo. Permitiendo así comenzar tener con una estructura básica sobre la que trabajar.

Cookiecutter se distribuye como un paquete más de Python, por lo que en primer lugar será necesario instalarlo en el ordenador. Lo que haremos, como siempre, mediante el comando pip.

pip install cookiecutter

Plantillas para Cookiecutter

Una vez instalado Cookiecutter es necesario descargar una plantilla. Una de las más sencillas es “cookiecutter-pypackage-minimal”, que, tal como su nombre indica, es una plantilla mínima para creación de paquetes de Python. La plantilla se encuentra en un repositorio de GitHub que debemos clonar mediante el siguiente comando.

git clone https://github.com/kragniz/cookiecutter-pypackage-minimal.git

Al finalizar el proceso aparecerá una carpeta con el nombre cookiecutter-pypackage-minimal en la ruta donde se hubiese ejecutado el comando. La carpeta que contiene la plantilla que usara Cookiecutter para crear la estructura de nuestro paquete.

Iniciar el proyecto a partir de la plantilla

Para crear la plantilla de nuestro proyecto solamente tendremos que llamar a Cookiecutter indicando la plantilla que deseamos utilizar, es decir:

cookiecutter cookiecutter-pypackage-minimal

En este momento un asistente nos preguntará la información básica del proyecto como son el nombre, el autor y el repositorio donde se almacenará. Valores que son importantes, pero podremos cambiar en un futuro sin problemas.

Si no queremos descargar la plantilla, es posible indicar a Cookiecutter el repositorio para que sea él quien descargue la plantilla. Para la plantilla que estamos utilizando podemos utilizar el comando:

cookiecutter https://github.com/kragniz/cookiecutter-pypackage-minimal.git

Estructura del proyecto

Una vez finalizado el asistente se creará una carpeta con el nombre de nuestro proyecto. En nuestro caso lo hemos llamado pylane. Una carpeta que tendrá la siguiente estructura

• pylane : carpeta en la que se encuentra todo el código de paquete, en cada caso proyecto tendrá un nombre diferente.
• tests:  carpeta donde se encuentran las pruebas unitarias (se verá en la segunda entrega).
• tox.ini: se utiliza junto con Pytest para pruebas de múltiples entornos (se verá en la tercera entrega).
• LICENSE.txt: archivo de licencia para distribución del código
• README.rst – donde se encuentra la documentación en formato rst (se verá en la sexta entrega).
• setup.py – se utiliza para especificar los detalles del paquete (se verá en la quinta entrega).

En el interior de la carpeta con el nombre del proyecto solamente tendremos un archivo __init__.py en la que se han de incluir o importar el código del proyecto. En este momento solamente incluirá la descripción del paquete, la versión y el autor.

Subpaquetes

En el caso de que necesitemos incluir un subpaquete dentro del propio paquete se tiene que crear una carpeta con el nombre de este. Dentro de la cual se incluirá un archivo __init__.py y el resto de los archivos del subpaquete u otros subpaquetes.

Función “¡Hola Mundo!”

Simplemente para ver que podemos crear un paquete e instalarlo en nuestra máquina vamos a crear una función que imprima por pantalla el texto “¡Hola mundo!”. Algo que solamente es una prueba, lo que se puede hacer añadiendo el siguiente código al archivo __init__.py

def hola_mundo():<br>
    print("¡Hola mundo!")

Instalación y ejecución del paquete

Ahora podemos instalar el paquete en nuestro ordenador para probar su funcionamiento. Para lo que nos situaremos en la carpeta del proyecto e invocamos el siguiente comando pip:

pip install -e .

La opción -e indica que el paquete es editable y el punto es la ruta al proyecto. Una vez hecho esto ya podemos importar el paquete y llamar a la función que hemos creado. Lo que haremos como cualquier otro paquete descargado de PyPI, escribiendo las siguientes líneas en un archivo:

from pylane import hola_mundo

hola_mundo()

Al ejecutar este archivo deberá aparecer por pantalla el mensaje “¡Hola mundo!”.

Conclusiones

En esta primera entrega de la serie “Creación de paquetes de Python” hemos visto cómo usar Cookiecutter para crear la plantilla de nuestro proyecto y añadir una primera función de prueba. Además, hemos visto cómo instalar el paquete en desarrollo en nuestro ordenador, lo que nos permite probar el funcionamiento de este en un entorno trabajo real.

La semana que viene vamos a ver una de las partes más importantes para garantizar que el proyecto pueda evolucionar con garantías. La escritura y ejecución de pruebas unitarias.

Imagen de seth0s en Pixabay