Guía de bibliotecas en Python

Enlaces rápidos

• ¿Qué son las bibliotecas de Python?

• Cómo instalar bibliotecas de Python

• Importar una biblioteca completa en Python

• Importar parte de una biblioteca (solo en sesiones interactivas)

• Crear e importar tus propias bibliotecas de Python

¿Qué son las bibliotecas de Python?

Las bibliotecas son colecciones de código reutilizable. En Python también se usan los términos módulo o paquete según la estructura. Una biblioteca agrupa funciones, clases y constantes que puedes invocar desde tus programas para no reescribir soluciones comunes.

Definición rápida: módulo = archivo .py con funciones; paquete = carpeta con init.py que agrupa módulos.

Ventajas principales

• Ahorro de tiempo: no reinventas soluciones comunes.
• Calidad: muchas bibliotecas populares están probadas y depuradas.
• Ecosistema: existen bibliotecas para gráficos, análisis de datos, redes, criptografía, etc.

Ejemplo de uso habitual: análisis de datos con NumPy, pandas y Matplotlib. Estas bibliotecas permiten operaciones vectorizadas, manipulación de tablas y visualización sin implementar todo desde cero.

Notas importantes

• Usar bibliotecas externas implica confiar en su mantenimiento y en su política de seguridad.
• Revisa la licencia si vas a redistribuir software que dependa de la biblioteca.

Cómo instalar bibliotecas de Python

Existen varias vías para instalar bibliotecas. La elección depende del sistema operativo, si tienes permisos de administrador, del flujo de trabajo del equipo y del tipo de paquete (rueda/wheel, sdist o binario del sistema).

Terminología breve

• PyPI: índice público de paquetes Python.
• wheel (.whl): formato empaquetado binario para distribuir paquetes.
• sdist: distribución en código fuente.

Métodos habituales

1. pip (desde PyPI)

• Comando básico para instalar un paquete desde PyPI:

pip install numpy

• Usar pip en entornos virtuales evita afectar al sistema global.

2. Entornos virtuales

• venv (incluido en Python moderno) y virtualenv permiten crear entornos aislados por proyecto. Recomendado para la mayoría de desarrollos.

• Crear y activar un entorno con venv:

python -m venv .venv
# En Linux/macOS
source .venv/bin/activate
# En Windows PowerShell
.venv\Scripts\Activate.ps1

3. Mamba / Conda

• Conda y su implementacón Mamba son populares en ciencia de datos. Permiten gestionar entornos y paquetes con dependencias binarios complejas.

• Activar un entorno Mamba:

mamba activate stats

• Mamba suele ser más rápido que conda y útil cuando necesitas dependencias no puramente Python (por ejemplo, bibliotecas C).

4. Instalación sin privilegios administrativos

• Si no tienes acceso root, usa entornos virtuales o pip con la opción –user para instalaciones por usuario:

pip install --user paquete

• Otra opción es pipx para instalar utilidades de línea de comandos en entornos aislados:

pipx install package-cli

5. Requisitos por proyecto

• Guarda dependencias reproducibles en un archivo requirements.txt:

pip freeze > requirements.txt

• Para instalar desde ese archivo:

pip install -r requirements.txt

6. Instalación editable durante desarrollo

• Para probar paquetes locales mientras los desarrollas:

pip install -e .

7. Buenas prácticas de instalación

• Prefiere entornos aislados por proyecto.
• Mantén requirements.txt o pyproject.toml con herramientas como poetry o pip-tools.
• Usa constraints para fijar versiones transitorias cuando sea necesario.
• Evita mezclar paquetes del sistema con pip en el sistema global.

Imagen: búsqueda del paquete numpy en PyPI

Importar una biblioteca completa en Python

Para usar una biblioteca en tu script o en modo interactivo, usa la sentencia import.

Ejemplo básico:

import numpy

Namespaces y alias

• Al importar, el módulo queda dentro de su propio espacio de nombres. Esto evita colisiones con funciones internas.
• Para abreviar, es común usar alias:

import numpy as np

• Buena práctica: usa alias estándar cuando existan (np, pd, plt). Esto mejora la legibilidad entre proyectos.

Acceder a funciones del módulo

• Las funciones se llaman como atributos del módulo:

np.mean(numbers)

• Si prefieres mantener el módulo completo, así evitas sobrescribir funciones built-in.

Imagen: uso de np.mean

Consejos

• Importa al inicio del archivo para claridad.
• Mantén el orden: imports de librerías estándar, luego de terceros, luego locales.
• Evita alias no convencionales.

Importar parte de una biblioteca

En sesiones interactivas es común importar funciones concretas para ahorrar escritura.

Ejemplo:

from numpy import mean

mean(numbers)

• También puedes importar varias funciones:

from numpy import mean, median

Riesgos y recomendaciones

• No uses “from module import *” en scripts: contamina el namespace y provoca conflictos sutiles.
• En scripts, prefiere importar el módulo completo o usar alias explícitos.
• Importar funciones concretas puede ser útil en notebooks y REPL para legibilidad rápida.

Imagen: importar mean y median desde NumPy

Crear e importar tus propias bibliotecas de Python

Un módulo Python es simplemente un archivo .py con funciones y clases. Un paquete es una carpeta con un archivo init.py.

Estructura mínima de paquete

mi_paquete/
    __init__.py
    utils.py
    procesamiento.py

• init.py puede estar vacío o exponer una API pública.

Permisos y ejecución

• No necesitas marcar un módulo con permisos de ejecución para importarlo. El ejemplo clásico muestra chmod, pero la ejecución como script es distinta al uso como módulo.

chmod +x my_library.py

• Marcar como ejecutable permite ejecutar el archivo directamente desde la terminal si contiene un shebang.

Ubicación y búsqueda de módulos

• Python busca módulos en sys.path. Para listar el path en una sesión:

import sys
sys.path

• Para añadir rutas temporales:

sys.path.append('/path/to/my/modules')

• Para entornos persistentes, configura la variable PYTHONPATH:

export PYTHONPATH="$PYTHONPATH:/path/to/my/modules"

• Uso típico: mantén módulos locales dentro del repositorio y usa imports relativos dentro de paquetes.

Entrar en modo script vs import

• Convención para permitir que un archivo funcione como módulo y script:

if __name__ == "__main__":
    main()

Imagen: script que llama a una función Hello, world desde main

Publicar y distribuir paquetes (panorama)

Resumen de rutas para compartir una biblioteca:

• Distribución local: pip install -e . o copiar carpeta.
• Repositorio privado: subir paquete a registro privado (Artifactory, Nexus, GitHub Packages).
• PyPI público: preparar pyproject.toml y publicar usando twine y build.

Herramientas comunes

• setuptools: antiguo estándar aún muy usado.
• poetry: maneja dependencias y empaquetado moderno con pyproject.toml.
• flit: empaquetado simple para librerías puras Python.

Buenas prácticas previas a publicar

• Añade pruebas automatizadas y CI.
• Define versiones semánticas claras.
• Incluye archivo README claro y LICENCIA.
• Firma o verifica paquetes binarios si la plataforma lo admite.

Seguridad y privacidad al usar bibliotecas

• Verifica la reputación del paquete y su mantenibilidad.
• Evita paquetes con pocas descargas o sin actualizaciones si el paquete es crítico.
• Usa pip-audit o herramientas similares para detectar vulnerabilidades conocidas.
• Revisa las dependencias transitivas: un paquete pequeño puede traer una cadena de dependencias.
• Si trabajas con datos personales, revisa la política de manejo de datos del paquete y evita enviar datos a servicios externos sin control.

Casos en los que el uso de bibliotecas falla o no es apropiado

• Requisitos de rendimiento extremo: en algunos casos un algoritmo personalizado y optimizado en C/C++ puede superar a la biblioteca general.
• Restricciones legales o de licencia: algunas licencias pueden ser incompatibles con tu producto.
• Dependencia de mantenimiento: una biblioteca abandonada puede introducir riesgos a largo plazo.

Modelos mentales y heurísticos

• Regla 80/20: inicialmente usa bibliotecas consolidadas para el 80% de las tareas. Optimiza el 20% que queda si hace falta.
• Mínima superficie de dependencia: añade solo las bibliotecas que realmente necesitas.
• Aislamiento por proyecto: cada proyecto debe poder construirse desde su descriptor de dependencias.

Flujo de decisión para elegir cómo instalar una biblioteca

flowchart TD
  A[¿Necesitas el paquete globalmente?] -->|Sí| B[¿Tienes privilegios de administrador?]
  A -->|No| C[Usar entorno virtual por proyecto]
  B -->|Sí| D[Instalar con gestor del sistema o pip global]
  B -->|No| E[Instalar con --user o crear venv]
  C --> F[Elegir entre pip, conda/mamba según dependencia]
  F --> G[Si requiere dependencias nativas: conda/mamba]
  F --> H[Si solo es Python puro: pip en venv]
  D --> I[Preferir gestor del sistema para librerías del sistema]
  E --> I

Lista de comprobación por rol

Desarrollador de software

• Crear venv por proyecto.
• Definir requirements.txt o pyproject.toml.
• Escribir pruebas unitarias.
• Evitar from module import * en scripts.

Científico de datos

• Usar conda/mamba si hay dependencias C.
• Mantener notebooks reproducibles con archivos de entorno.
• Registrar versiones de librerías en el proyecto.

DevOps / SRE

• Aislar entornos en CI.
• Escanear dependencias por vulnerabilidades.
• Mantener repositorios privados para paquetes internos.

Educador / Formador

• Enseñar buenas prácticas de importación y entornos.
• Mostrar diferencias entre importar en scripts y en la REPL.

Plantillas y fragmentos útiles

requirements.txt (ejemplo minimalista)

numpy==1.24.*
pandas>=1.5,<2.0
scipy

pyproject.toml (poetry minimal)

[tool.poetry]
name = "mi-paquete"
version = "0.1.0"
description = "Utilidades para análisis X"

[tool.poetry.dependencies]
python = "^3.10"
numpy = "^1.24"

Archivo de pruebas simple con pytest

def test_mean():
    from mi_paquete import stats
    assert stats.mean([1,2,3]) == 2

Criterios de aceptación para una biblioteca interna

• Documentación mínima: README con ejemplos de uso.
• Pruebas unitarias que cubran funcionalidades críticas.
• CI que ejecute pruebas en al menos una versión soportada de Python.
• Versionado semántico y changelog.

Mantenimiento y madurez de una biblioteca

Niveles sugeridos de madurez

• Nivel 1 (experimental): uso interno limitado, API puede cambiar.
• Nivel 2 (estable): API documentada, pruebas básicas, versión semántica.
• Nivel 3 (maduro): adopción amplia, pruebas completas, políticas de seguridad.

Compatibilidad y migraciones

• Revisa las notas de la versión al actualizar dependencias mayores.
• Prueba el proyecto en entornos separados antes de promover cambios a producción.
• Evita saltos mayores de versión sin fase de pruebas.

Playbook rápido: crear y usar un paquete local en desarrollo

1. Estructura tu paquete con init.py.
2. Añade pruebas en tests/.
3. Crea pyproject.toml o setup.cfg.
4. En el entorno del proyecto, instala en modo editable:

pip install -e .

5. Ejecuta pruebas y documenta la API.

Pruebas de aceptación y casos de prueba

• Instalar desde requirements.txt recrea el entorno sin errores.
• Importar y ejecutar funciones clave en CI pasa todas las pruebas.
• Empaquetar y desinstalar no deja archivos huérfanos.

Riesgos comunes y mitigaciones

• Riesgo: paquete abandonado. Mitigación: fork y mantener internamente o buscar alternativas.
• Riesgo: vulnerabilidades. Mitigación: escaneo periódico y actualización controlada.
• Riesgo: conflictos de versión. Mitigación: usar entornos aislados y cifrar constraints.

Últimos consejos y resumen

• Usa bibliotecas consolidadas para ahorrar tiempo, pero controla las dependencias y su seguridad.
• Mantén entornos reproducibles y documentados.
• Prefiere importaciones explícitas en scripts y utiliza atajos en sesiones interactivas.

Resumen final

Con módulos y paquetes puedes ampliar enormemente lo que haces con Python. Adoptar buenas prácticas en instalación, importación y mantenimiento te ahorrará errores y tiempo. Las bibliotecas son herramientas poderosas si las gestionas con disciplina.

Importante: cuando instales paquetes que manejen datos sensibles, revisa su política y evita exponer información en servicios externos.