Lección 37 de 47 · Un proyecto real✦ WebMCP implementado
Módulos, paquetes, pip, venv y uv: Composer en Python
10 min de lectura3 retos
Un programa de verdad no cabe en un solo fichero ni usa solo lo que trae Python. En esta lección ves cómo se parten el código en módulos y paquetes (el namespace y el autoload de PHP, pero explícitos), cómo aislas las dependencias de cada proyecto con venv, cómo se instalan con pip y uv (el Composer de Python) y qué hacen pyproject.toml y el fichero de versiones fijadas.
¿De dónde vienen los nombres?
módulo = del latín modulus (medida pequeña)
Una pieza de un programa. En Python, un módulo es simplemente un fichero .py: tareas.py es el módulo tareas.
El fichero que Python ejecuta al importar una carpeta. Marca la carpeta como paquete y es su «puerta de entrada».
venv = virtual environment (entorno virtual)
Una carpeta con su propio Python y sus propias bibliotecas, aislada del resto del ordenador. Es como tener un vendor/ por proyecto, pero también para el intérprete.
pip = se suele explicar como «Pip Installs Packages» (un acrónimo recursivo)
El instalador de paquetes que viene con Python. Es el composer require de Python.
PyPI = Python Package Index (índice de paquetes de Python)
La tienda pública de paquetes, en pypi.org. Es el Packagist de Python.
TOML = Tom's Obvious Minimal Language (el lenguaje mínimo y obvio de Tom)
El formato de pyproject.toml: texto con [secciones] y clave = valor, más fácil de escribir a mano que JSON. Lo creó Tom Preston-Werner.
En 4 ideas
1/4
Un módulo es un fichero .py y un paquete es una carpeta con __init__.py. Se usan con import y from … import …, siempre de forma explícita: no hay autoload de Composer que los busque por ti.
venv crea un entorno aislado por proyecto: python -m venv .venv. En PHP, vendor/ ya es por proyecto; en Python, sin venv, pip instala en el Python global y los proyectos se pisan entre sí.
pyproject.toml es el composer.json de Python (nombre, versión de Python y dependencias) y un fichero de versiones fijadas (uv.lock o requirements.txt) es el composer.lock.
pip instala lo que pidas; uv es el gestor moderno que hace de pip, venv y lock a la vez, mucho más rápido: es lo más parecido a Composer que tiene Python.
1 · Un módulo es un fichero
En PHP partes el código en ficheros y los juntas con require o con el autoload de Composer. En Python cada fichero .py ya es un módulo y lo traes con import. Piensa en una caja de herramientas: import math te da la caja entera y from math import ceil saca solo el martillo.
Pythonmain.py
import math
from datetime import date
import json as j
# En PHP: echo ceil(7 / 3) . PHP_EOL;print(math.ceil(7 / 3))
# En PHP: echo (new DateTimeImmutable('2026-11-19'))->format('Y-m-d');print(date(2026, 11, 19).isoformat())
# En PHP: echo json_encode(['titulo' => 'Comprar pan']);print(j.dumps({"titulo": "Comprar pan"}))
# Todo módulo sabe su propio nombreprint(math.__name__, j.__name__)
PHP 8.5index.php
<?phpdeclare(strict_types=1);
use DateTimeImmutable as Fecha;
$hoy = newFecha('2026-11-19');
echo$hoy->format('Y-m-d') . PHP_EOL;
Pythonmain.py
# En PHP: use DateTimeImmutable as Fecha;from datetime import date asFecha
hoy = Fecha(2026, 11, 19)
print(hoy.isoformat())
Quiero…
En PHP
En Python
Traer un módulo entero
require 'tareas.php';
import tareas
Traer solo una cosa
use App\Tareas\Tarea;
from tareas import Tarea
Ponerle otro nombre
use App\Tareas\Tarea as T;
from tareas import Tarea as T
Traer todo a lo bruto
require de un fichero con funciones
from tareas import * (mejor evitarlo: no sabes qué entra)
2 · Paquetes: carpetas con __init__.py
Cuando tienes muchos módulos los metes en una carpeta. Si esa carpeta lleva un fichero __init__.py, Python la trata como un paquete: se importa como si fuera un módulo, con el nombre de la carpeta.
El punto delante de .modelo significa «el hermano modelo de este mismo paquete» (un import relativo). Y __all__ es la lista de nombres públicos del paquete: lo que verá quien haga from tareas import *.
Un módulo no es magia: es un objeto como los demás. Este ejemplo fabrica uno en memoria, lo registra y lo importa. Fíjate en que su código se ejecuta una sola vez, aunque lo importes dos veces.
sys.modules es el diccionario donde Python guarda todo lo que ya ha importado. Si el nombre está, import solo te devuelve ese objeto y no vuelve a ejecutar nada. Es el require_once de PHP, pero sin elegirlo: siempre es así.
Equivalencia POO · PHP → Python
Lo de namespace y use de PHP, traducido. La columna de la derecha dice dónde manda cada cosa.
PHP
Python
Quién lo ve
namespace App\Tareas; al principio del fichero
No se declara: el nombre sale de la ruta (tareas/modelo.py es tareas.modelo)
Quien importe el módulo
use App\Tareas\Tarea;
from tareas.modelo import Tarea
Solo ese fichero
Autoload PSR-4 de Composer
No existe: import busca en las carpetas de sys.path
Todo el programa
require_once
import (siempre una sola vez)
Todo el programa
private / public en una clase
Nada a nivel de módulo: _nombre avisa de que es interno y __all__ lista lo público
Convención, nadie lo impide
¿Por qué? · En PHP no existe
¿Por qué hay que escribir import en cada fichero? En PHP el autoload lo hace solo
Con el autoload de PHP puedes usar new Tarea() en cualquier sitio y Composer encuentra la clase. Cómodo, pero al leer el fichero no sabes de dónde sale Tarea.
Python lo hace al revés: arriba de cada fichero ves, línea a línea, de qué módulos depende. Si falta uno, falla enseguida con ModuleNotFoundError. Es la filosofía del Zen de Python: «explícito es mejor que implícito».
3 · venv y pip: un entorno por proyecto
Composer instala en la carpeta vendor/del proyecto: dos proyectos pueden usar versiones distintas de la misma biblioteca sin enterarse. pip, en cambio, instala por defecto en el Python del ordenador. Si el proyecto A necesita fastapi 0.100 y el B fastapi 0.165, se pisan.
La solución es el entorno virtual: una carpeta con una copia mínima de Python y su propio sitio para instalar paquetes. Se crea con el módulo venv, que viene con Python:
$ python -m venv .venv
$ ls .venv
bin include lib pyvenv.cfg
$ source .venv/bin/activate
(.venv) $ pip install fastapi
(.venv) $ pip freeze > requirements.txt
python -m venv .venv crea la carpeta .venv (la -m es «ejecuta este módulo como programa»). En Windows, activar es .venv\Scripts\activate en vez de source .venv/bin/activate.
Activar el entorno hace que python y pip apunten a los de .venv. El prompt lo avisa con (.venv).
pip install fastapi instala dentro de .venv, no en el ordenador. Borrar .venv y volver a crearlo es siempre seguro.
pip freeze lista lo instalado con su versión exacta. Redirigido con > se guarda en requirements.txt.
Un entorno recién creado está casi vacío. Esto es lo que sale de verdad al ejecutarlo en una imagen de Python 3.15:
$ .venv/bin/pip list
Package Version
------- -------
pip 26.2.2
$ .venv/bin/pip freeze
(pip freeze no imprime nada porque no cuenta a pip mismo.) Desde dentro de Python puedes saber si estás en un venv: sys.prefix apunta a la carpeta del entorno y sys.base_prefix al Python original.
Pythonmain.py
import sys
# Fuera de un venv las dos rutas coincidenprint("¿Estoy en un venv?", sys.prefix != sys.base_prefix)
¿Por qué Python necesita venv y PHP no? En PHP no existe
PHP tiene un solo intérprete por servidor y Composer ya mete las bibliotecas en el vendor/ del proyecto. El aislamiento viene de la carpeta.
Python guarda las bibliotecas en una carpeta común del intérprete (site-packages) y ahí caben una versión de cada paquete. Con dos proyectos sería una pelea. El venv le da a cada proyecto su propiosite-packages, y además evita el clásico «funciona en mi ordenador» porque cualquiera puede recrear el mismo entorno.
4 · pyproject.toml: el composer.json de Python
Hoy un proyecto Python declara lo que es y lo que necesita en un único fichero, pyproject.toml. Está escrito en TOML y Python 3.11 trajo tomllib para leerlo sin instalar nada:
Las versiones se escriben como en Composer, con otros símbolos:
Se escribe
Significa
En Composer
fastapi==0.165.0
exactamente esa
0.165.0
fastapi>=0.115
esa o una más nueva
>=0.115
fastapi>=0.115,<1
entre las dos
>=0.115 <1
fastapi~=0.115
compatible: sube de parche, no de versión menor ni mayor
~0.115.0
5 · uv y las versiones fijadas
Con pip tienes que hacer a mano tres cosas: crear el venv, activarlo y mantener requirements.txt. uv (de la empresa Astral, escrito en Rust) las hace todas con un solo programa y es mucho más rápido. Es lo más parecido a Composer que tiene Python.
uv add fastapi lo añade a dependencies, crea el .venv si no existe y lo instala. Es el composer require.
uv run pytest ejecuta un comando dentro del entorno, sin activarlo a mano.
uv sync deja el .venv exactamente como dicen pyproject.toml y uv.lock. Es el composer install.
Y aquí está la pieza que más importa en equipo: el lock (de bloqueo). pyproject.toml dice lo que quieres (fastapi>=0.115) y el lock lo que has obtenido (0.165.0, con todas las dependencias de las dependencias). Si el servidor instala desde el lock, instala lo mismo que tú probaste.
Aspecto
requirements.txt
uv.lock
Quién lo escribe
pip freeze o tú a mano
uv, solo
Qué contiene
Lista plana de versiones
Versiones, de dónde vienen y su huella para comprobar que no han cambiado (hashes)
Separa lo de desarrollo
No (hace falta otro fichero)
Sí, en el mismo fichero
Equivalente en Composer
composer.lock, hecho a mano
composer.lock
Pythonmain.py
requisitos = """fastapi==0.165.0uvicorn>=0.54# solo para los testspytest==9.2.0"""for linea in requisitos.splitlines():
linea = linea.strip()
ifnot linea or linea.startswith("#"):
continue
fijada = "=="in linea
print(f"{linea:<18} fijada: {fijada}")
¿Por qué? · En PHP no existe
¿Por qué dos ficheros, pyproject.toml y un lock? En PHP ya lo hace Composer
Es la misma idea de composer.json y composer.lock. Si solo hubiera «lo que quiero», cada install podría traer una versión nueva y la app que funcionaba el lunes se rompería el viernes sin que tocases nada.
El lock congela el resultado. Quien clona el repo y ejecuta uv sync (o pip install -r requirements.txt) obtiene el mismo árbol de bibliotecas que tú. Súbelo siempre a git.
La pregunta que te vas a hacer
Vale, pero… ¿cómo instalo las dependencias en el servidor?
Igual que haces con Composer en un despliegue: copias pyproject.toml y el lock, creas el entorno y lo sincronizas. En un Dockerfile son dos líneas: copiar los ficheros y ejecutar uv sync --frozen (o pip install -r requirements.txt). El frozen de uv es el --no-update de Composer: instala el lock tal cual, sin recalcular.
Tienes 7 tareas y las muestras de 3 en 3. Importa math e imprime cuántas páginas hacen falta (3). Es el ceil() de PHP.
Al pulsar Comprobar, unos tests ocultos prueban tu código en tu navegador, con Python 3.14.
Pythonmain.py · editable
Pista. Añade import math arriba y usa math.ceil(...) con una división normal (/), no con //.
Reto 2 de 3 · ✓ Resuelto
Lee el requirements.txt
Escribe lee_requisitos(texto): recibe el contenido de un requirements.txt (una línea nombre==version por paquete) y devuelve un diccionario {nombre: version}. Ignora las líneas vacías y las que empiezan por #. Es el require de composer.json, leído a mano.
Al pulsar Comprobar, unos tests ocultos prueban tu código en tu navegador, con Python 3.14.
Pythonmain.py · editable
Pista. Recorre texto.splitlines(), haz strip() a cada línea, sáltate las vacías y las que empiezan por # y parte el resto con linea.split("==").
Reto 3 de 3 · ✓ Resuelto
Los nombres del pyproject
Escribe nombres_de_dependencias(texto): recibe el contenido de un pyproject.toml (como texto) y devuelve la lista con solo los nombres de [project] dependencies, sin versión ni extras: de "uvicorn[standard]>=0.30" sale "uvicorn". Si no hay dependencies, una lista vacía. Usa tomllib.
Al pulsar Comprobar, unos tests ocultos prueban tu código en tu navegador, con Python 3.14.
Pythonmain.py · editable
Pista. El nombre acaba en el primer carácter de [, <, >, =, !, ~, ; o espacio. re.split(r"[\[<>=!~; ]", dep, maxsplit=1)[0] se queda con lo de antes.
Resumen
Lo que te llevas de esta lección
Un módulo es un fichero .py y un paquete una carpeta con __init__.py; todo se trae con import explícito (en PHP, use más el autoload de Composer).
Un módulo se ejecuta una sola vez y queda guardado en sys.modules (el require_once de PHP, pero obligatorio).
Un venv por proyecto: python -m venv .venv, activar e instalar dentro. El nombre lo eliges tú y va en el .gitignore (en PHP, vendor/ ya es por proyecto).
pyproject.toml declara el proyecto y sus dependencias (el composer.json) y el lock fija las versiones exactas (el composer.lock).
uv une pip, venv y lock: uv add (composer require), uv sync (composer install), uv run (ejecutar dentro del entorno).
Para recordarlo: «Crea, Activa, Instala, Fija»
CCrea python -m venv .venv
AActiva source .venv/bin/activate
IInstala pip install fastapi
FFija pip freeze > requirements.txt
Los cuatro pasos de todo proyecto nuevo: Crea el entorno, Actívalo, Instala lo que necesitas y Fija las versiones. Con uv se resumen en uv add y uv sync.