¡Aprenda a crear su primera biblioteca de Python! En esta serie de publicaciones, lo guiaremos a través del proceso de creación y publicación de una biblioteca de Python usando Poetry. Comencemos por crear una pequeña aplicación de calculadora, que cubra todo, desde la configuración inicial hasta la implementación y prueba de funciones básicas. Al final de esta serie, tendrá su biblioteca lista para compartir con el mundo en PyPI.

¿Qué es la poesía?

Poetry es una herramienta de empaquetado y gestión de dependencias para proyectos de Python. Simplifica el proceso de creación y mantenimiento de bibliotecas y aplicaciones al automatizar muchas tareas que tradicionalmente requieren múltiples herramientas. Poetry viene con todas las herramientas que puedas necesitar para gestionar tus proyectos de forma determinista. Estas son algunas de las principales ventajas de la Poesía:

• Crear proyectos: crea y empaqueta tus proyectos fácilmente con un solo comando.
• Comparte tu trabajo: Da a conocer tu trabajo publicándolo en PyPI.
• Comprueba el estado de tus dependencias: obtén una vista de las dependencias de tu proyecto con un solo comando.
• Resolución de dependencias: Poetry viene con un solucionador de dependencias exhaustivo, que siempre encontrará una solución, si existe.
• Aislamiento: Poetry utiliza entornos virtuales configurados o crea los suyos propios para estar siempre aislado de su sistema.
• CLI intuitiva: los comandos de poesía son intuitivos y fáciles de usar, sensibles a los valores predeterminados pero configurables.

Con estas ventajas, Poetry se destaca como una herramienta poderosa y eficiente para desarrollar proyectos Python.

¿Qué necesitamos antes de iniciar nuestra biblioteca Python?

Antes de comenzar a escribir código, debemos configurar nuestro entorno de desarrollo. Estos son los pasos para asegurarte de tener todo listo:

Verifique la versión de Python

Primero, debemos asegurarnos de tener instalada la última versión de Python. Para verificar la versión de Python instalada en su sistema, ejecute el siguiente comando en la terminal:

python --version

Si aún no tienes Python instalado o necesitas actualizarlo, puedes descargarlo e instalarlo desde el sitio web oficial de Python.

Instalando poesía

Después de asegurarse de tener instalada la última versión de Python, el siguiente paso es instalar Poetry. Puede instalar Poetry siguiendo las instrucciones detalladas en la documentación oficial. Aquí hay un comando rápido para la instalación:

curl -sSL https://install.python-poetry.org | python3 -

Iniciar su biblioteca: los primeros pasos

Paso 1: Creando el proyecto con Poetry

Ahora que tenemos Python y Poetry instalados, es hora de comenzar nuestro proyecto de calculadora. Poetry facilita la creación de un nuevo proyecto con un simple comando.

Navega hasta el directorio donde deseas crear tu proyecto y ejecuta el siguiente comando en la terminal:

poetry new calculator
cd calculator

Este comando crea una nueva estructura de proyecto para usted, que incluye carpetas y archivos esenciales.

calculator/
├── README.md
├── calculator
│   └── __init__.py
├── pyproject.toml
└── tests
    └── __init__.py

Entendamos la estructura generada:

• README.md: Un archivo de documentación para describir su proyecto.
• calculadora/: Una carpeta que contiene el código fuente de tu aplicación.
• tests/: Una carpeta para tus pruebas unitarias.
• pyproject.toml: el archivo de configuración principal de Poetry.

Paso 2: implementar las funciones de la calculadora

Ahora creemos las funciones de la calculadora dentro del archivo calculadora/calculadora.py.

calculator/
├── calculator.py
├── __init__.py

Abra el archivo calculadora.py e implemente las funciones básicas de la calculadora:

def add(a, b):
    return a   b

def subtract(a, b):
    return a - b

def multiply(a, b):
    return a * b

def divide(a, b):
    if b == 0:
        raise ValueError("Não é possível dividir por zero")
    return a / b

Paso 3: Probar las funciones de la calculadora

Las pruebas son esenciales para garantizar la calidad del software, brindando confiabilidad en la corrección de errores y la evolución del código. En este ejemplo, usaremos pruebas unitarias para validar las funciones de nuestra calculadora. Configuremos el entorno de prueba y escribamos algunos casos de prueba para garantizar que las operaciones matemáticas funcionen correctamente.

Configurar el entorno de prueba

Comience a agregar pytest como dependencia de desarrollo:

poetry add --dev pytest

Ahora, crea un archivo llamado test_calculator.py dentro de la carpeta de pruebas:

import pytest
from calculator.calculator import add, subtract, multiply, divide

def test_add():
    assert add(2, 3) == 5
    assert add(-1, 1) == 0
    assert add(0, 0) == 0
    assert add(-1, -1) == -2

def test_subtract():
    assert subtract(5, 2) == 3
    assert subtract(0, 0) == 0
    assert subtract(-1, 1) == -2
    assert subtract(-1, -1) == 0

def test_multiply():
    assert multiply(2, 3) == 6
    assert multiply(5, 0) == 0
    assert multiply(-1, 1) == -1
    assert multiply(-2, -3) == 6

def test_divide():
    assert divide(6, 2) == 3
    assert divide(5, 2) == 2.5
    assert divide(-10, 2) == -5
    with pytest.raises(ValueError):
        divide(4, 0)

Finalmente, simplemente ejecuta las pruebas con el siguiente comando:

poetry run pytest

Paso 4: Publicar en GitHub

Ahora que nuestra aplicación está cubierta de pruebas, preparémosla para compartirla en GitHub. Siga los pasos a continuación para agregar su proyecto a GitHub:

1. Crea un repositorio en GitHub: ve a GitHub y crea un nuevo repositorio para tu calculadora.

2. Agrega tu proyecto al repositorio:

• Inicialice el repositorio Git dentro del directorio de su proyecto si aún no está inicializado:

git init

• Agregue todos los archivos a Git y realice la primera confirmación:

git add .
git commit -m "Initial commit"

• Conecta tu repositorio local al repositorio remoto en GitHub:

git remote add origin 

• Sube tus archivos a GitHub:

git push -u origin main

Ahora tu proyecto está en GitHub y listo para compartirlo y colaborar con otros desarrolladores.

Paso 5: Instalación mediante Pip o Poetry

Para instalar su biblioteca directamente, simplemente use los siguientes comandos:

• Vía Pip:

pip install git https://github.com/seu_usuario/seu_repositorio.git

• Vía Poesía:

poetry add git https://github.com/seu_usuario/seu_repositorio.git

¿Que viene despues?

En esta primera parte del tutorial, cubrimos los fundamentos esenciales para crear una biblioteca de Python usando Poetry. Comenzamos configurando el entorno de desarrollo, implementamos una calculadora básica con pruebas unitarias usando pytest y compartimos el proyecto en GitHub para colaborar.

En la siguiente parte de este tutorial, exploraremos cómo publicar su biblioteca en PyPI, el repositorio de paquetes estándar de Python, y aprenderemos cómo instalarla usando Poetry o pip directamente desde PyPI. Esto no solo hará que su biblioteca sea más fácil de usar para otros desarrolladores, sino que también lo ayudará a integrarse con la comunidad Python.

¡Felicitaciones por llegar tan lejos! Espero que estés disfrutando creando tu biblioteca Python. No dude en compartir preguntas o sugerencias en los comentarios. Pasemos ahora a la Parte II y continuemos nuestro viaje de colaboración con la comunidad Python.

Referencias

• Canal Eduardo Mendes (@Dunossauro) Creando un paquete Python desde cero: desde los requisitos hasta el despliegue
• Documentación de poesía
• Poesía: crear paquetes de Python de forma sencilla