Mis apuntes · Aprende Python desde PHP

Se guardan solos en este navegador mientras escribes. Puedes usar Markdown. Al descargarlos, la primera línea es tu enlace personal al curso.

Lección 37 de 47 · Un proyecto real ✦ WebMCP implementado

Módulos, paquetes, pip, venv y uv: Composer en Python

10 min de lectura 3 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.
__init__.py = inglés init = initialize (inicializar), con guiones bajos dobles
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.

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 nombre
print(math.__name__, j.__name__)
PHP 8.5index.php
<?php
declare(strict_types=1);

use DateTimeImmutable as Fecha;

$hoy = new Fecha('2026-11-19');
echo $hoy->format('Y-m-d') . PHP_EOL;
Pythonmain.py
# En PHP: use DateTimeImmutable as Fecha;
from datetime import date as Fecha

hoy = Fecha(2026, 11, 19)
print(hoy.isoformat())
Quiero…En PHPEn Python
Traer un módulo enterorequire 'tareas.php';import tareas
Traer solo una cosause App\Tareas\Tarea;from tareas import Tarea
Ponerle otro nombreuse App\Tareas\Tarea as T;from tareas import Tarea as T
Traer todo a lo brutorequire de un fichero con funcionesfrom 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.

main.py
tareas/
├── __init__.py
├── modelo.py
└── repositorio.py
Pythonmain.py
# tareas/__init__.py
from .modelo import Tarea
from .repositorio import RepositorioMemoria

__all__ = ["Tarea", "RepositorioMemoria"]
Pythonmain.py
# main.py
from tareas import Tarea, RepositorioMemoria

repo = RepositorioMemoria()
repo.guardar(Tarea(1, "Comprar pan"))

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.

Pythonmain.py
import sys
import types

codigo = """
def formatea(titulo, prioridad):
    return f"[P{prioridad}] {titulo}"

print("cargando tareas_demo")
"""

modulo = types.ModuleType("tareas_demo")
exec(codigo, modulo.__dict__)
sys.modules["tareas_demo"] = modulo

import tareas_demo
import tareas_demo as otra_vez

print(tareas_demo.formatea("Comprar pan", 2))
print(tareas_demo is otra_vez)
print("tareas_demo" in sys.modules)

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.

PHPPythonQuién lo ve
namespace App\Tareas; al principio del ficheroNo 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 TareaSolo ese fichero
Autoload PSR-4 de ComposerNo existe: import busca en las carpetas de sys.pathTodo el programa
require_onceimport (siempre una sola vez)Todo el programa
private / public en una claseNada a nivel de módulo: _nombre avisa de que es interno y __all__ lista lo públicoConvenció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 coinciden
print("¿Estoy en un venv?", sys.prefix != sys.base_prefix)
Composer (PHP)Python
composer require fastapi/fastapipip install fastapi
composer installpip install -r requirements.txt
vendor/.venv/lib/python3.x/site-packages/
PackagistPyPI
composer.jsonpyproject.toml (o requirements.txt)

¿Por qué? · En PHP no existe

¿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 propio site-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:

Pythonmain.py
import tomllib

texto = """
[project]
name = "tareas"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = [
    "fastapi>=0.115",
    "uvicorn>=0.30",
]

[dependency-groups]
dev = ["pytest>=8"]
"""

datos = tomllib.loads(texto)
print(datos["project"]["name"])
print(datos["project"]["dependencies"])
print(datos["dependency-groups"]["dev"])
Quiero decir…composer.jsonpyproject.toml
Nombre y versión"name", "version"name, version en [project]
Versión mínima del lenguaje"php": ">=8.5"requires-python = ">=3.14"
Dependencias del programa"require"dependencies
Dependencias solo de desarrollo"require-dev"[dependency-groups] (por ejemplo dev)

Las versiones se escriben como en Composer, con otros símbolos:

Se escribeSignificaEn Composer
fastapi==0.165.0exactamente esa0.165.0
fastapi>=0.115esa o una más nueva>=0.115
fastapi>=0.115,<1entre las dos>=0.115 <1
fastapi~=0.115compatible: 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 init tareas
$ cd tareas
$ uv add fastapi
$ uv add --dev pytest
$ uv run pytest
$ uv sync
  • uv init crea el proyecto con su pyproject.toml.
  • 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.

Aspectorequirements.txtuv.lock
Quién lo escribepip freeze o tú a manouv, solo
Qué contieneLista plana de versionesVersiones, de dónde vienen y su huella para comprobar que no han cambiado (hashes)
Separa lo de desarrolloNo (hace falta otro fichero)Sí, en el mismo fichero
Equivalente en Composercomposer.lock, hecho a manocomposer.lock
Pythonmain.py
requisitos = """
fastapi==0.165.0
uvicorn>=0.54
# solo para los tests
pytest==9.2.0
"""

for linea in requisitos.splitlines():
    linea = linea.strip()
    if not 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.

Hora de practicar

Retos · 0/3 resueltos

Reto 1 de 3

Páginas de tareas

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

Resumen

Lo que te llevas de esta lección

  1. 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).
  2. Un módulo se ejecuta una sola vez y queda guardado en sys.modules (el require_once de PHP, pero obligatorio).
  3. 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).
  4. pyproject.toml declara el proyecto y sus dependencias (el composer.json) y el lock fija las versiones exactas (el composer.lock).
  5. 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.