Apuntes BD II

Instalación de Paquetes y Gestión de Proyectos

Se lee en 8 min

Paquetes de Python

Python posee un ecosistema con una gran cantidad de paquetes que proveen funcionalidades adicionales para muchos propósitos, los cuales son creados por la comunidad de Python. Estos paquetes pueden instalarse desde el repositorio Python Package Index (PyPI).

Algunos de los paquetes más destacables son:

Instalador de paquetes Pip

Pip es el administrador de paquetes estándar en Python, utilizado para instalar y gestionar librerías y dependencias adicionales. Aunque suele instalarse automáticamente con Python, en algunas distribuciones de Linux puede ser necesario instalarlo manualmente mediante el gestor de paquetes de sistema.

El uso básico de pip es el siguiente:

# instalar un paquete
pip install nombre_del_paquete
# instalar un paquete indicando una versión específica
pip install nombre_del_paquete==versión
# listar paquetes instalados
pip list
# desinstalar un paquete
pip uninstall nombre_del_paquete

¿Dónde se instalan los paquetes?

Los paquetes instalados por Pip pueden almacenarse en diferentes ubicaciones dependiendo del entorno y del tipo de instalación:

  • Instalación a Nivel de Sistema: Los paquetes instalados a nivel de sistema se gestionan típicamente a través del gestor de paquetes del sistema (APT, DNF, Pacman, etc.) y están disponibles para todos los usuarios. Estos paquetes suelen encontrarse en /usr/lib/pythonX.Y/dist-packages. Aunque es posible instalar paquetes globales usando sudo pip install ..., no es recomendable ya que podría causar conflictos con otros paquetes gestionados por el sistema.
  • Instalación para un Usuario Específico: Cuando se instalan paquetes sin privilegios de superusuario (sudo), Pip los coloca en el directorio de paquetes del usuario (~/.local/lib/pythonX.Y/site-packages). Esta es la opción predeterminada en la mayoría de los casos cuando se ejecuta pip install sin permisos elevados.
  • Instalación en Entornos Virtuales (Virtualenv): Los entornos virtuales permiten aislar dependencias y paquetes específicos para un proyecto. Dentro de un entorno virtual, los paquetes se instalan en lib/pythonX.Y/site-packages dentro de la carpeta del entorno, asegurando que no interfieran con el resto del sistema o con otros proyectos.

Entornos virtuales

Los entornos virtuales son fundamentales para gestionar proyectos sin afectar el sistema o causar conflictos con otros proyectos. Un entorno virtual es esencialmente un directorio con una estructura que permite almacenar paquetes. Para crear uno ejecuta:

python -m venv mi_entorno

INFO

En algunas distribuciones de linux será necesario instalar venv como paquete de sistema. En Debian, Ubuntu y derivadas:

sudo apt install python3-venv

Activa un entorno virtual con:

source mi_entorno/bin/activate
# ahora puededes instalar paquetes en este entorno
pip install httpx

Después de activar el entorno, puedes usar Pip para instalar y gestionar paquetes dentro del entorno virtual. Cada vez que abras una nueva terminal, tendrás que activar el entorno nuevamente para trabajar dentro de él.

Para desactivar el entorno virtual y regresar al entorno global del sistema :

deactivate

Gestor de paquetes uv

uv es una alternativa unificada y moderna a herramientas populares del ecosistema de Python, como Pip, virtualenv, poetry, pdm, pipx, entre otras. Con uv puedes:

  • Instalar paquetes de manera similar a Pip
  • Gestionar entornos virtuales
  • Instalar herramientas creadas en Python
  • Gestionar proyectos de Python
  • Instalar y manejar versiones del intérprete de Python

ruff

uv es la segunda herramienta desarrollada por Astral, quienes ya habían revolucionado el ecosistema Python con ruff, una solución eficiente que unifica varias herramientas de análisis y formateo código.

Instalación de uv

Para instalar uv, sigue las instrucciones de instalación (https://docs.astral.sh/uv/getting-started/installation/). Para Linux, se debe ejecutar el siguiente comando:

curl -LsSf https://astral.sh/uv/install.sh | sh

Luego, cierra y vuelve a abrir tu terminal para poder utilizar el comando uv --help.

Instalación de paquetes y gestión de entornos virtuales con uv

uv ofrece los subcomandos uv pip y uv venv, que funcionan de manera equivalente a sus contrapartes tradicionales:

# crea un entorno virtual env .venv
uv venv .venv
# activa el entorno virtual
source .venv/bin/activate
# instala un paquete
uv pip install httpx

Instalación de herramientas con uv

Muchos paquetes de Python son herramientas que pueden ejecutarse desde la línea de comandos. Algunos ejemplos son:

  • ruff, un herramienta de verificación y formateo de código de Python
  • visidata, una herramienta para visualizar y manipular datos desde la terminal
  • harlequin, un cliente de bases de datos SQL basado en terminal
  • posting, un cliente de APIs REST basado en terminal

Para instalar este tipo de herramientas, utiliza el subcomando uv tool. uv instalará cada herramienta y sus dependencias en un entorno virtual, evitando conflictos de versiones entre ellas. Después de hacer esto, los comandos deberían estar disponibles (posiblemente después de abrir una nueva terminal).

Gestión de proyectos con uv

En la actualidad, existen herramientas avanzadas para gestionar de manera integral los proyectos en Python y sus dependencias. uv es una de estas herramientas.

Como gestor de proyectos, uv permite entre otras cosas:

  • Registro de metadatos: Permite mantener un control detallado de la información esencial del proyecto, como el nombre, la versión, y la descripción.
  • Gestión de dependencias: Facilita la instalación, registro y actualización de todas las dependencias necesarias para tu proyecto.
  • Entorno virtual automatizado: Crea y administra automáticamente entornos virtuales para aislar las dependencias de tu proyecto, asegurando que no interfieran con otros proyectos en tu sistema.
  • Automatización de tareas: Mediante la creación de scripts y comandos personalizados, puedes sistematizar tareas repetitivas o críticas del proyecto.
  • Control de versiones de Python: Permite instalar y usar versiones específicas de Python en tu entorno, asegurando la compatibilidad de tu proyecto.

¿Qué ventajas tiene gestionar con uv o herramientas similares?

  • Aislamiento de entornos: Al mantener las dependencias en un entorno virtual, se evita que estas afecten a otros proyectos o sean afectadas por ellos, garantizando un entorno de trabajo limpio y predecible.
  • Reproducibilidad: la gestión de dependencias y entornos asegura que el proyecto pueda ser replicado de manera consistente en cualquier máquina, minimizando problemas de incompatibilidad.
  • Simplicidad: consolidar las configuraciones y dependencias en un sistema de gestión facilita la administración del proyecto, reduciendo la complejidad y el riesgo de errores.

Inicialización de un proyecto con uv

Para empezar un nuevo proyecto con uv, crea un directorio y dentro de él ejecuta:

uv init

Este comando genera automáticamente un archivo pyproject.toml, que es el núcleo de la configuración de tu proyecto, donde se almacenan los metadatos del proyecto, incluidas las dependencias. Un archivo típico pyproject.toml podría verse así:

[project]
name = "my_project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

Adicionalmente, uv creará un archivo README.md y un script de ejemplo hello.py.

Descripción de los campos en pyproject.toml

  • name: el nombre del proyecto. Este nombre se usará para identificar tu proyecto en sistemas de gestión de paquetes.
  • version: la versión actual del proyecto, siguiendo la convención de versiones semánticas.
  • description: una breve descripción del propósito o funcionalidad del proyecto.
  • readme: el archivo que contiene la documentación del proyecto, típicamente README.md.
  • requires-python: la versión mínima de Python requerida para ejecutar el proyecto.
  • dependencies: lista de paquetes necesarios para que el proyecto funcione correctamente. Puedes encontrar más detalles de cómo usar pyproject.toml en la este enlace.

Gestionar dependencias de nuestro proyecto

Una vez que hayas inicializado tu proyecto, puedes comenzar a agregar o eliminar dependencias fácilmente utilizando uv. Los comandos principales son uv add para agregar dependencias y uv remove para eliminarlas.

# agregar SQLAlchemy
uv add httpx
# agregar SQLAlchemy, específicamente la versión 2.0.22
uv add sqlalchemy==2.0.22
# agregar Pandas con soporte para archivos Excel
uv add 'pandas[excel]'
# eliminar Pandas
uv remove pandas

¿Qué ocurre al modificar dependencias?

  • Actualización del pyproject.toml: al agregar o eliminar una dependencia, uv actualizará automáticamente la sección dependencies del archivo pyproject.toml.
  • Creación/Actualización del uv.lock: la primera vez que se agrega una dependencia, se genera un archivo uv.lock, que contiene un registro exacto de las dependencias y subdependencias del proyecto, incluyendo sus sumas de verificación. Esto asegura que cualquier persona trabajando en el proyecto tenga un entorno idéntico al tuyo.
  • Gestión del Entorno Virtual: uv instalará o desinstalará el paquete en el entorno virtual asociado al proyecto. Si el entorno virtual no existe, uv lo creará automáticamente en .venv.

Edición manual de dependencias en pyproject.toml

Si editas manualmente el archivo pyproject.toml para agregar o eliminar dependencias, estos cambios no se reflejarán automáticamente en el entorno virtual. Para sincronizar los cambios con el entorno, ejecuta:

uv sync

Este comando también actualizará el lockfile (uv.lock) si es necesario.

Sincronización y migración de proyectos

Si descargas o copias un proyecto gestionado con uv en otro equipo, puedes recrear el entorno de desarrollo de manera sencilla ejecutando uv sync. Este comando se encargará de descargar la versión adecuada de Python (si es necesario), crear el entorno virtual e instalar todas las dependencias necesarias, asegurando que el proyecto funcione de manera consistente en diferentes entornos.

Dependencias “ejecutables”

Al agregar dependencias que incluyen programas ejecutables (como ruff o alembic), estos se instalan correctamente en el proyecto, pero al intentar ejecutar uno de estos comandos directamente, es posible que la terminal no los encuentre. Esto ocurre porque los archivos ejecutables se instalan dentro del entorno virtual del proyecto, el cual no se carga automáticamente en la sesión actual de la terminal.

Para ejecutar estos programas, tienes dos opciones:

  • Activar el entorno virtual, lo que cargará todas las dependencias y programas ejecutables en la sesión actual de la terminal: 
    source .venv/bin/activate
ruff --version             # ahora debería funcionar
  • Usar uv run, que ejecuta comandos dentro del entorno virtual sin necesidad de activarlo manualmente. Esta opción es conveniente para ejecutar comandos de dependencias sin modificar tu sesión de shell: 
    uv run ruff --version      # funciona sin activar el entorno virtual

Vista Gráfica

Retroenlaces