Bibliotecas de Python: módulos, paquetes y pip

Las bibliotecas de Python son colecciones de código reutilizable que resuelven problemas comunes. En lugar de programar desde cero cada función para fechas, archivos, peticiones web, análisis de datos o gráficos, puedes importar herramientas ya probadas y concentrarte en el objetivo específico de tu proyecto.

En esta guía aprenderás la diferencia entre módulo, paquete, biblioteca y framework; conocerás la biblioteca estándar; instalarás paquetes externos con pip y entornos virtuales; y revisarás criterios prácticos para elegir dependencias confiables.

Por qué son importantes

Imagina un programa que debe leer CSV, convertir fechas, consultar una API, procesar estadísticas y crear un gráfico. Implementar cada componente desde el principio consumiría mucho tiempo y aumentaría la posibilidad de errores. Las bibliotecas proporcionan bloques reutilizables con interfaces documentadas.

También crean un vocabulario compartido. Un equipo que conoce Pandas, Requests o Pytest puede comprender un proyecto más rápidamente porque esas herramientas siguen patrones conocidos.

Módulo, paquete, biblioteca y framework

• Módulo: normalmente un archivo Python con variables, funciones o clases.
• Paquete: una estructura de directorios que agrupa módulos importables.
• Biblioteca: término general para código reutilizable distribuido como uno o varios paquetes.
• Framework: estructura mayor que controla parte del flujo de la aplicación y espera que el código siga determinadas convenciones.

El tutorial oficial de módulos de Python explica imports, paquetes, rutas de búsqueda y ejecución de módulos.

La biblioteca estándar

Python incluye una biblioteca estándar amplia. Estos módulos normalmente no requieren pip:

• pathlib para rutas y archivos;
• json para codificar y decodificar JSON;
• csv para archivos CSV;
• datetime para fechas y horas;
• statistics para cálculos estadísticos;
• sqlite3 para bases de datos SQLite;
• logging para registros;
• unittest para pruebas.

La referencia oficial de la biblioteca estándar documenta todos los módulos incluidos.

Importar un módulo

import statistics

notas = [72, 85, 91, 68, 84]
print(statistics.mean(notas))
print(statistics.median(notas))

El nombre del módulo queda disponible y sus funciones se acceden con punto. Esta forma deja claro el origen de cada herramienta.

Importar un nombre concreto

from pathlib import Path

informe = Path("informes") / "ventas.csv"
print(informe)

Importar una clase o función concreta es útil cuando se utiliza con frecuencia. La guía de pathlib en Python amplía el trabajo con rutas.

Usar alias

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt

Los alias convencionales reducen repetición sin ocultar la biblioteca. Sigue nombres conocidos para facilitar la lectura.

Evitar imports con asterisco

from math import *  # Evitar

Un import con asterisco añade muchos nombres al espacio actual, puede sobrescribir variables y dificulta saber de dónde viene una función. Prefiere import math o importa únicamente lo necesario.

Bibliotecas externas y PyPI

Los paquetes de terceros suelen publicarse en el Python Package Index. Ejemplos habituales son:

• Requests para HTTP;
• Pandas para datos tabulares;
• NumPy para arrays numéricos;
• Matplotlib para gráficos estáticos;
• Plotly para gráficos interactivos;
• Pytest para pruebas.

Crear un entorno virtual

Instalar todos los paquetes globalmente provoca conflictos. Aísla el proyecto:

python -m venv .venv

Después de activarlo, las instalaciones pertenecen a ese entorno. La guía de entornos virtuales en Python explica Windows, macOS y Linux.

Instalar con pip

python -m pip install requests

Usar python -m pip relaciona pip con un intérprete concreto. Esto evita que el editor ejecute un Python diferente al utilizado para instalar el paquete.

Comprobar una instalación

import requests
import sys

print(requests.__version__)
print(sys.executable)

Cuando el import falla, compara la ruta del intérprete con el entorno activo. También verifica que tu archivo no se llame requests.py, json.py o igual que otra biblioteca.

Leer documentación oficial

Una biblioteca confiable debería ofrecer:

• instrucciones de instalación;
• guía de inicio;
• referencia de API;
• versiones de Python compatibles;
• notas de cambios y migración;
• licencia;
• canal de seguridad.

No copies código sin comprobar la versión. Una respuesta antigua puede utilizar métodos eliminados.

Guardar dependencias

python -m pip freeze > requirements.txt

Otra persona puede instalarlas con:

python -m pip install -r requirements.txt

pip freeze registra dependencias directas e indirectas. En proyectos duraderos, puede ser útil una herramienta que distinga requisitos principales de versiones bloqueadas.

Cómo elegir una biblioteca confiable

• Necesidad: resuelve un problema real del proyecto.
• Documentación: los ejemplos y referencias son claros.
• Mantenimiento: existen versiones, incidencias y actualizaciones recientes.
• Compatibilidad: funciona con tu Python y sistema operativo.
• Licencia: permite el uso previsto.
• Dependencias: el árbol añadido es razonable.
• Gobernanza: el proyecto tiene responsables y código fuente identificables.

Las cifras de descargas no garantizan calidad ni seguridad.

Evitar errores con nombres de paquetes

Existen paquetes maliciosos con nombres parecidos a proyectos populares. Copia el nombre exacto desde la documentación oficial, revisa la página de PyPI y evita comandos provenientes de comentarios anónimos.

El nombre usado con pip puede ser diferente al utilizado en import. Comprueba siempre ambos en la documentación.

Fijar versiones con criterio

python -m pip install requests==2.32.3

Una versión exacta mejora la reproducción, pero mantener un pin antiguo indefinidamente puede excluir correcciones de seguridad. Prueba actualizaciones de manera periódica y revisa cambios mayores.

Actualizar, eliminar e inspeccionar

python -m pip install --upgrade requests
python -m pip uninstall requests
python -m pip list
python -m pip show requests
python -m pip check

pip check informa requisitos incompatibles después de cambiar versiones.

Crear tu propio módulo

Crea calculos.py:

def calcular_descuento(
    precio: float,
    porcentaje: float,
) -> float:
    if precio < 0:
        raise ValueError("El precio no puede ser negativo")
    if not 0 <= porcentaje <= 100:
        raise ValueError("Porcentaje fuera de rango")

    return precio * (1 - porcentaje / 100)

Después impórtalo:

from calculos import calcular_descuento

print(calcular_descuento(200, 15))

Añadir type hints, docstrings y pruebas hace que el módulo sea más reutilizable. Consulta la guía de docstrings en Python.

Patrón if __name__

def saludar(nombre: str) -> str:
    return f"Hola, {nombre}."


if __name__ == "__main__":
    print(saludar("Ana"))

Al importar el módulo, la demostración no se ejecuta automáticamente.

Cuándo no añadir una dependencia

Una dependencia tiene coste de mantenimiento. Evítala cuando una función breve resuelve el problema con claridad, el proyecto está abandonado, la licencia no es adecuada o el entorno no puede aceptar sus requisitos.

Sin embargo, no reinventes criptografía, protocolos, analizadores o controladores de bases de datos sin una razón excepcional. Una biblioteca estable y revisada suele ser más segura que una implementación improvisada.

Errores frecuentes

• Nombrar un archivo igual que una biblioteca.
• Instalar en el intérprete equivocado.
• Copiar sintaxis desactualizada.
• Subir .venv al repositorio.
• Ignorar el traceback de un ImportError.
• Añadir una dependencia grande para una tarea mínima.
• No revisar licencia ni mantenimiento.

Conclusión

Las bibliotecas de Python convierten código reutilizable en bloques prácticos. Comienza con la biblioteca estándar, aísla dependencias externas en un entorno virtual, instala nombres exactos desde fuentes confiables y lee documentación oficial. Evalúa mantenimiento, compatibilidad, licencia y seguridad antes de añadir un paquete, y registra el entorno para poder reproducir el proyecto.