Cómo crear un paquete con Python y subirlo a PYPI
Muy buenas, en el tutorial de esta semana vamos a ver como crear un paquete en Python para posteriormente subirlo a un gestor de paquetes como es PYPI en el que una vez subido, podremos instalarlo en cualquier proyecto con el comando PIP.
Antes de empezar con el tutorial, quiero definir un par de puntos y es la diferencia entre módulo y paquete, ya que puede llevar a la confusión.
¿Qué es un módulo?
Un módulo es un archivo de Python el cual puede englobar funciones, clases y constantes.
¿Qué es un paquete?
Un paquete engloba uno o varios módulos que siguen una lógica general. Por ejemplo, en un paquete, podemos crear un módulo que tenga funciones matemáticas y un segundo módulo donde guardar las constantes que necesitemos, como podría ser el número PI.
Como nombrar módulos y paquetes
Como ya expliqué en este tutorial, por convención tanto en los módulos como en los paquetes deben ir en formato snake_case, tener nombres cortos en minúsculas y solo usar los guiones bajos si mejora la legibilidad. En el caso de los paquetes, se desaconseja utilizar los guiones bajos.
Cómo crear un paquete
Antes de seguir, te recomiendo que uses una versión de Python superior a la 3.3 para evitar problemas, yo voy a emplear la versión 3.9.
Crear repositorio
Como primer paso, lo que he hecho es crearme un repositorio público en GitHub, de esta forma, ya podemos autogenerar una licencia (yo escogí tipo MIT), el archivo README.md y el archivo .gitignore con la plantilla de Python.
Una vez hecho esto, debes clonar el proyecto en tu máquina y ahora sí, empezamos 🚀
Crear el proyecto que queremos convertir en paquete
El primer paso es definir que queremos hacer. Para este ejemplo yo voy a crear el caso que comenté anteriormente, que tendrá dos archivos, uno con funciones matemáticas y otro para guardar constantes que nos pueden ser útiles para algunas funciones matemáticas.
Para ello, voy a crear una carpeta en el directorio raíz del proyecto y para evitar conflictos con nombres de paquetes ya existentes y, ya que es un ejemplo, me voy a saltar un poquito la convención y voy a utilizar un nombre un poco más largo de lo normal, así que he nombrado la carpeta como "alber_package_calc".
Dentro de ella, voy a crear dos archivos, el primero se llamará consts.py y el segundo calc.py.
El archivo const.py tendrá el siguiente contenido:
PI=3.1416
Como puedes observar, solo vamos a almacenar una constante con el número PI.
El archivo calc.py contendrá el siguiente código:
from alber_package_calc.consts import PI
def sum(num1: float, num2: float) -> float:
return num1 + num2
def area_circle(radio: float) -> float:
return radio * radio * PI
Como ves, son dos simples funciones, una para realizar sumas y otra para calcular el área de un círculo. Fíjate que también estoy importando la constante PI para usarla en el cálculo del área del círculo. Esto lo he hecho para que puedas ver que dentro del paquete podemos acceder a los distintos módulos.
Antes de la versión 3.3 de Python, debíamos crear el archivo __init__.py dentro del paquete para que funcione correctamente, así que si tienes que utilizar una versión anterior, debes añadir ese archivo (no necesita tener ningún contenido).
Ya que es un ejemplo, el paquete no va a tener más funcionalidades, así que pasamos a ver los pasos para subir el paquete.
Subir el paquete a PYPI
Una vez tenemos listo el paquete, es hora de subirlo a PYPI. Para ello, lo primero que necesitaremos es tener una cuenta en esta plataforma, así que accedemos a su web y nos registramos:
https://pypi.org/account/register/
Una vez registrados, debemos acceder a la administración de nuestra cuenta y en la sección de API TOKEN, crear un token para posteriormente poder subir nuestro paquete.
https://pypi.org/manage/account/
Ahora que ya tenemos el token, debemos volver a nuestro proyecto y en la raíz (fuera de la carpeta alber_package_calc), crear un archivo llamado pyproject.toml que se encargará de almacenar la configuración del proyecto y deberá tener el siguiente contenido:
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "alber-package-calc"
version = "0.0.1"
authors = [
{ name="xxx", email="xxx@gmail.com" },
]
description = "Ejemplo de como crear un paquete"
readme = "README.md"
license = { file="LICENSE" }
requires-python = ">=3.9"
classifiers = [
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
]
[project.urls]
"Homepage" = "https://github.com/albertorc87/subir-paquete-pypi"
"Bug Tracker" = "https://github.com/albertorc87/subir-paquete-pypi/issues"
En general se entiende bastante bien que hace cada clave, así que solo voy a explicar los más importantes.
En name, debes sustituir el nombre del paquete por el que quieras, en authors.name, debes poner tu username de PYPI.
En version, indicamos la versión del paquete, en mi caso la 0.0.1.
En el campo requires-python indicaremos la versión o rango de versiones de Python con el que es compatible nuestro proyecto.
En classifiers podemos categorizar el proyecto, yo he añadido tres básicas, si queréis ver los classifiers existentes, os dejo en enlace:
Por último, en la sección "project.urls" tengo el enlace al repositorio en GitHub y a la de issues.
Una vez hecho esto, podemos subir todos los cambios a nuestro repositorio, ya que no necesitaremos realizar más modificaciones.
Ahora que ya tenemos el proyecto listo, vamos a subirlo a PYPI. Para ello, primero nos aseguramos que tenemos la última versión de PIP para generar los archivos de distribuición. Lo comprobaremos lanzando el siguiente comando, si no está actualizado, lo actualizará:
pip install --upgrade build
Una vez hecho esto, si no lo estamos, vamos a la raíz de nuestro proyecto y lanzamos el siguiente comando:
python -m build
Este comando generará una carpeta llamada dist con dos archivos.
El archivo con la extensión tar.gz es una distribución fuente, mientras que el archivo .whl es una distribución integrada. Estos serán los dos archivos que se suban a PYPI.
Ahora vamos a instalar el paquete twine de Python que se emplea para publicar paquetes en PYPI:
pip install --upgrade twine
Una vez instalado, lanzamos el siguiente comando para subir el paquete:
python -m twine upload --repository pypi dist/*
Nos pedirá el username y ahí NO DEBES escribir tu username de PYPI sino el siguiente nombre:
__token__
Una vez pulsemos enter nos pedirá el password y ahí debes insertar el token que creaste anteriormente, debe empezar por pypi-....
Y listo, si todo ha ido bien, deberías ver algo como esto:
Como puedes ver, recibiremos la URL a nuestro paquete, en mi caso:
https://pypi.org/project/alber-package-calc/
Probar nuestro paquete
Ahora que ya hemos subido el paquete solo queda probarlo. Para ello, he creado un nuevo proyecto y he instalado el paquete con PIP. Una vez hecho esto, he podido utilizarlo sin problemas 💪.
pip install alber-package-calc
Una vez instalada la librería en un entorno virtual, os dejo un ejemplo del uso de mi paquete en un archivo Python.
from alber_package_calc import consts
from alber_package_calc.calc import sum, area_circle
print(consts.PI)
print(sum(4, 5))
print(area_circle(17))
Si quieres más información acerca de este proceso, te dejo el enlace a la documentación oficial, también te dejo el enlace a mi repositorio por si necesitas echarle un vistazo.
Espero que este post te ayude y como siempre, te recomiendo seguirme en Twitter para estar al tanto de los nuevo contenido. Ahora también puedes seguirme en Instagram donde estoy subiendo tips, tutoriales en vídeo e información sobre herramientas para developers.
Por último os dejo mi guía para aprender a trabajar con APIs donde explico todo el funcionamiento de una API, el protocolo HTTP y veremos como construir una API con arquitectura REST.
Nos leemos 👋.