Proyectos Python con Poetry y VSCode Parte 1 - Hoja de Trucos Python
Un Entorno Virtual es una instalación de Python aislada diseñada para evitar llenar nuestra instalación base con librerías que podríamos usar solo para un proyecto. También nos permite gestionar múltiples versiones de la misma librería en diferentes proyectos. Podríamos, por ejemplo, necesitar Django 4.1 para uno y 1.9 para el otro.
Python Poetry
Poetry es una herramienta para manejar la instalación de dependencias, así como la construcción y empaquetado de paquetes de Python. Solo necesita un archivo para hacer todo eso: el nuevo pyproject.toml, estandarizado. En otras palabras, poetry usa pyproject.toml para reemplazar setup.py, requirements.txt, setup.cfg, MANIFEST.in y el recién añadido Pipfile.
En esta serie de artículos, usaremos Poetry para gestionar nuestras dependencias, construir un proyecto simple y, con un solo comando, publicarlo en PyPI.
En esta primera parte, haremos lo siguiente:
- Iniciar un nuevo proyecto.
- Crear un Entorno Virtual.
- Gestionar dependencias.
En el segundo artículo, haremos lo siguiente:
- Añadir nuestro Entorno Virtual a VSCode.
- Integrar nuestras dependencias de desarrollo:
- Flake8
- Black
- Pytest
Y finalmente, en un tercer artículo haremos lo siguiente:
- Escribir una librería de ejemplo.
- Construir nuestro proyecto con Poetry.
- Publicarlo en PyPI.
Instalación de Poetry
La forma más fácil es usar pip:
pip install poetry
Pero usaremos el instalador propio de Poetry para aislarlo del resto del sistema al virtualizar sus dependencias. Esta es la forma recomendada de instalar poetry:
curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
De esta manera, más tarde podremos actualizar poetry a la última versión estable con el comando poetry self update.
Inicio de un nuevo proyecto
Ahora podemos iniciar un nuevo proyecto de Python usando el comando poetry new [nombre_del_proyecto]. Lo llamaré how-long y será una librería simple para medir el tiempo de ejecución de una función:
poetry new how-long
Nota: Para proyectos existentes, puedes usar el comando
poetry inity crear interactivamente un pyproject.toml.
Se crea el directorio how-long y dentro hay una estructura de proyecto básica:
how-long
├── README.rst
├── how_long
│ └── __init__.py
├── pyproject.toml
└── tests
├── __init__.py
└── test_how_long.py
Para una guía completa sobre el manejo de rutas de archivos y directorios, lo cual es esencial para gestionar estructuras de proyectos, consulta la página de Rutas de Archivos y Directorios.
Nota: Para poder publicar tu proyecto, necesitas un nombre disponible. Usa la búsqueda de PyPI para esto.
El archivo pyproject.toml
El archivo pyproject.toml gestionará los detalles y dependencias del proyecto:
[tool.poetry]
name = "how-long"
version = "0.1.0"
description = "A simple decorator to measure a function execution time."
authors = ["wilfredinni <carlos.w.montecinos@gmail.com>"]
[tool.poetry.dependencies]
python = "^3.7"
[tool.poetry.dev-dependencies]
pytest = "^3.0"
[build-system]
requires = ["poetry>=0.12"]
build-backend = "poetry.masonry.api"
[tool.poetry]
Los detalles. Añadir una licencia y un README podría ser una buena idea:
[tool.poetry]
...
license = "MIT"
readme = "README.rst"
[tool.poetry.dependencies]
Primero está la versión de Python. Básicamente, este proyecto será compatible con Python 3.7 en adelante. Además, a partir de ahora, cada paquete que instalemos destinado a ser usado en producción se listará aquí.
[tool.poetry.dev-dependencies]
Estos paquetes son solo para desarrollo y no se incluirán cuando publiquemos nuestro proyecto. Por defecto, Poetry incluye Pytest, así que lo usaremos para probar nuestro proyecto más adelante.
Creación de un Entorno Virtual
Para crear un Entorno Virtual e instalar Pytest, usaremos el comando poetry install:
poetry install
Después de que termine, se creará un nuevo archivo, poetry.lock.
Cuando Poetry termina de instalar, escribe todos los paquetes y las versiones exactas de ellos que descargó en el archivo poetry.lock, bloqueando el proyecto a esas versiones específicas. Debes incluir el archivo poetry.lock en el repositorio de tu proyecto para que todas las personas que trabajan en el proyecto queden bloqueadas a las mismas versiones de las dependencias.
Gestión de Dependencias
Una forma de añadir o eliminar dependencias es editar directamente pyproject.toml y luego ejecutar poetry install para aplicar los cambios. En su lugar, usaremos los comandos add y remove para evitar modificaciones manuales.
Añadir dependencias
Añadamos dos paquetes al proyecto, pendulum y coo:
poetry add pendulum coo
Abre pyproject.toml y poetry.lock y observa cómo se han actualizado.
Añadir dependencias de desarrollo
Estas dependencias solo estarán disponibles durante el desarrollo; Poetry no las incluirá al construir y publicar el proyecto.
Ya instalamos Pytest, pero también usaremos flake8 para linting y mypy para tipado estático:
poetry add -D flake8 mypy
Ahora que lo pienso, olvidé añadir un formateador. Usaremos black:
poetry add -D black
[ValueError]
Could not find a matching version of package black
add [-D|--dev] [--git GIT] [--path PATH] [-E|--extras EXTRAS] [--optional] [--python PYTHON] [--platform PLATFORM] [--allow-prereleases] [--dry-run] [--] <name> (<name>)...
Este error ocurre porque black está en estado de prelanzamiento, por lo que Poetry no puede encontrar ninguna versión estable para nosotros. Pero realmente lo quiero, así que lo instalaré de todos modos con el flag --allow-prereleases:
poetry add -D black --allow-prereleases
Eliminar dependencias
Sabes qué, cambié de opinión, este proyecto no usará ni coo ni mypy. Empecemos eliminando coo, una dependencia normal de nuestro proyecto:
poetry remove coo
Ahora mypy, que es una dependencia de desarrollo:
poetry remove -D mypy
Conclusión
En esta primera parte, hemos iniciado un nuevo proyecto, creado un Entorno Virtual y añadido y eliminado dependencias usando los siguientes comandos:
| Comando | Descripción |
|---|---|
poetry new [nombre-paquete] | Iniciar un nuevo Proyecto de Python. |
poetry init | Crear un archivo pyproject.toml interactivamente. |
poetry install | Instalar los paquetes dentro del archivo pyproject.toml. |
poetry add [nombre-paquete] | Añadir un paquete a un Entorno Virtual. |
poetry add -D [nombre-paquete] | Añadir un paquete de desarrollo a un Entorno Virtual. |
poetry remove [nombre-paquete] | Eliminar un paquete de un Entorno Virtual. |
poetry remove -D [nombre-paquete] | Eliminar un paquete de desarrollo de un Entorno Virtual. |
poetry self:update | Actualizar poetry a la última versión estable. |
En un segundo artículo, veremos más comandos de Poetry, añadiremos nuestro Entorno Virtual a VSCode y usaremos los paquetes de desarrollo que instalamos para hacer linting (Flake8), formateo (Black) y pruebas (Pytest) de nuestro código dentro del editor. Finalmente, en un tercero, escribiremos y publicaremos una librería de ejemplo en PyPI.
¿Alguna duda o sugerencia? Por favor, deja un comentario.