Control de versiones, entornos reproducibles y estructura profesional.

Has llegado a un punto en el que tus programas ya tienen funciones, clases, pruebas y documentación. Pero un proyecto no es solo código: es un conjunto de archivos organizados, con dependencias que deben instalarse, un historial de cambios que permita volver atrás y un entorno reproducible que garantice que el programa funciona igual en tu ordenador y en el de otra persona. Este módulo cubre las herramientas que convierten un conjunto de scripts en un proyecto profesional: la terminal, Git para el control de versiones, los entornos virtuales para aislar dependencias y pyproject.toml como configuración única del proyecto.

El objetivo no es que memorices decenas de comandos, sino que entiendas por qué cada herramienta existe y cuándo usarla. La terminal, Git y los entornos virtuales son el entorno de trabajo diario de cualquier desarrollador, y dominarlos desde el principio te ahorrará horas de confusión y errores difíciles de rastrear.

Título: Terminal, Git y gestión de proyectos: control de versiones, entornos reproducibles y estructura profesional.

Alcance: Usar la terminal con soltura en Windows y Linux; pasar argumentos a un script con argparse; inicializar un repositorio Git, hacer commits, gestionar ramas y escribir un .gitignore; crear y activar entornos virtuales con venv (y conocer la alternativa moderna uv); instalar dependencias con pip o uv; declarar dependencias en requirements.txt o pyproject.toml; estructurar un proyecto con el diseño src/; y garantizar la reproducibilidad y portabilidad entre sistemas. Se presupone todo el curso hasta el Módulo 18, en particular módulos (Módulo 12), archivos (Módulo 13) y tipado/documentación (Módulo 18). No se profundiza en publicación en PyPI ni en integración continua avanzada (se mencionan conceptualmente).

Al terminar este módulo serás capaz de:

1. Navegar por el sistema de archivos y ejecutar comandos básicos en terminales de Windows (PowerShell) y Linux (Bash). 2. Pasar argumentos y opciones a un script de Python usando argparse. 3. Inicializar un repositorio Git, hacer commits significativos y consultar el historial. 4. Crear y fusionar ramas para trabajar en funcionalidades aisladas. 5. Escribir un .gitignore que excluya archivos generados, entornos virtuales y credenciales. 6. Crear un entorno virtual con venv, activarlo y desactivarlo. 7. Instalar dependencias con pip y congelarlas en requirements.txt; conocer uv como alternativa moderna. 8. Declarar metadatos y dependencias en pyproject.toml. 9. Estructurar un proyecto con el diseño src/ y justificar sus ventajas frente al diseño plano. 10. Explicar qué hace que un proyecto sea reproducible y portable entre Windows y Linux.

- Del Módulo 12: Módulos, paquetes e importaciones (necesario para entender src/ y pyproject.toml). - Del Módulo 13: Archivos y rutas con pathlib (necesario para .gitignore y estructura de proyecto). - Del Módulo 16: Ruff y calidad de código (contexto para la configuración del proyecto). - Del Módulo 17: Pruebas con pytest (se ejecutarán desde la terminal). - Ningún conocimiento de Git, entornos virtuales ni pyproject.toml.

Imagina que compartes tu proyecto con un compañero. Le pasas la carpeta con los archivos .py. Al ejecutarlo, le falla: le falta una biblioteca que instalaste hace meses y no recuerdas cuál. Le pasas una lista de dependencias, pero las versiones han cambiado y el comportamiento ya no es el mismo. Intentas volver a una versión anterior de tu código, pero no tienes copia. Ese es el problema que resuelven las herramientas de este módulo: Git guarda el historial, los entornos virtuales aíslan las dependencias y pyproject.toml declara la configuración de forma que cualquiera pueda reproducir el entorno.

Un proyecto profesional no es solo código que funciona: es código que otra persona puede ejecutar, que puede evolucionar sin miedo y que se puede reconstruir en cualquier máquina. Ese es el estándar que este módulo te ayuda a alcanzar.

La terminal (o shell) es una interfaz de texto para interactuar con el sistema operativo. Aunque los IDE modernos ofrecen terminales integradas, entender los comandos básicos es esencial para usar Git, crear entornos virtuales y ejecutar pruebas.

Comandos esenciales (equivalentes en Windows y Linux):

[WINDOWS / LINUX] PowerShell acepta alias como ls, cd y mkdir, pero los flags (opciones que empiezan por -) no son idénticos. Por ejemplo, ls -l funciona en Linux pero no en PowerShell. Para los comandos de este módulo, usa los equivalentes indicados en cada caso.

[BUENA PRÁCTICA] Usa pwd con frecuencia para saber dónde estás. La terminal ejecuta los comandos relativos al directorio de trabajo actual; un cd equivocado es la causa de la mayoría de los errores de “archivo no encontrado”.

Un script de Python puede recibir argumentos desde la terminal. La forma básica es sys.argv, pero el módulo argparse de la biblioteca estándar ofrece una interfaz más robusta: genera mensajes de ayuda, valida tipos y gestiona errores automáticamente.

# archivo: saludo.py
import argparse
 
parser = argparse.ArgumentParser(description="Saluda a una persona.")
parser.add_argument("nombre", help="Nombre de la persona a saludar")
parser.add_argument("--veces", type=int, default=1, help="Número de saludos")
 
args = parser.parse_args()
 
for _ in range(args.veces):
    print(f"Hola, {args.nombre}")

Ejecución:

- Linux: python3 saludo.py Ana --veces 3 - Windows: py saludo.py Ana --veces 3

argparse también genera ayuda automática con --help y muestra errores si falta un argumento obligatorio o el tipo no es correcto.

[PYTHON] argparse es el módulo recomendado por la documentación oficial para interfaces de línea de comandos en la biblioteca estándar. Es más verboso que otras alternativas (click, typer), pero no requiere dependencias externas y es suficiente para la mayoría de scripts.

[BUENA PRÁCTICA] Documenta cada argumento con help=. Un --help claro es la mejor documentación para quien usa tu script desde la terminal.

Git es un sistema de control de versiones distribuido. Registra los cambios en tus archivos a lo largo del tiempo, permite volver a versiones anteriores y facilita el trabajo en equipo. Los conceptos fundamentales son:

- Repositorio: la carpeta del proyecto, con un historial oculto en .git/. - Commit: una instantánea del estado del proyecto en un momento dado, con un mensaje que describe el cambio. - Rama (branch) : una línea de desarrollo independiente. La rama principal suele llamarse main. - Área de preparación (staging area) : los cambios que se incluirán en el próximo commit.

Flujo básico:

# 1. Inicializar un repositorio en la carpeta del proyecto
git init
 
# 2. Configurar identidad (solo la primera vez)
git config --global user.name "Tu Nombre"
git config --global user.email "tu@email.com"
 
# 3. Ver el estado de los archivos
git status
 
# 4. Añadir archivos al área de preparación
git add archivo.py
git add .          # Todos los archivos no ignorados
 
# 5. Crear un commit con un mensaje descriptivo
git commit -m "Añade función de cálculo de media"
 
# 6. Ver el historial
git log --oneline

[BUENA PRÁCTICA] Escribe mensajes de commit en imperativo y que describan qué cambia y por qué: "Corrige validación de edad negativa" es mejor que "cambios". Un historial legible es una herramienta de diagnóstico.

[ERROR HABITUAL] Hacer un git add . sin revisar antes git status. Puedes añadir archivos que no deberías (credenciales, entornos virtuales, archivos generados). Revisa siempre qué vas a incluir.

Las ramas permiten trabajar en una funcionalidad o corrección sin afectar a la rama principal. El flujo típico es:

git checkout -b feature/nueva-funcionalidad   # Crear y cambiar a una rama
# ... trabajar ...
git add .
git commit -m "Implementa nueva funcionalidad"
git checkout main                              # Volver a la rama principal
git merge feature/nueva-funcionalidad          # Fusionar los cambios

El archivo .gitignore indica a Git qué archivos o carpetas no debe rastrear. Debe incluir, como mínimo:

# Entornos virtuales
.venv/
venv/

# Archivos generados por Python
__pycache__/
*.pyc

# Archivos de configuración local
.env
*.local

# Archivos de cobertura y pruebas
.coverage
htmlcov/

# Archivos del sistema operativo
.DS_Store
Thumbs.db

[BUENA PRÁCTICA] Configura el .gitignore antes del primer commit. Un archivo que se ha añadido al historial de Git permanece allí para siempre, incluso si luego lo eliminas. Corregirlo después requiere reescribir el historial, lo que es complicado y arriesgado.

Un entorno virtual es un directorio aislado que contiene su propio intérprete de Python y sus propias dependencias. Sin él, todas las bibliotecas que instalas se acumulan en el Python global del sistema, lo que provoca conflictos de versiones entre proyectos.

Crear y activar un entorno virtual:

# Crear el entorno en una carpeta llamada .venv
python3 -m venv .venv          # Linux
py -m venv .venv               # Windows
 
# Activar
source .venv/bin/activate      # Linux
.venv\Scripts\activate         # Windows
 
# Desactivar
deactivate

Cuando el entorno está activo, el prompt de la terminal muestra su nombre (por ejemplo, (.venv)), y los comandos python y pip apuntan al intérprete y a las bibliotecas del entorno, no a los del sistema.

[BUENA PRÁCTICA] Nombra el entorno .venv (con punto) y añádelo al .gitignore. La carpeta del entorno virtual nunca debe subirse a Git: contiene binarios específicos de tu sistema operativo y no es portable.

[WINDOWS / LINUX] La activación es diferente: source .venv/bin/activate en Linux, .venv\Scripts\activate en Windows. La estructura interna del entorno también difiere (bin/ frente a Scripts/), pero el flujo de trabajo es el mismo.

pip es el instalador de paquetes de Python. Dentro de un entorno virtual activo, instala bibliotecas solo en ese entorno.

pip install requests
pip install pytest ruff

Para guardar las dependencias de un proyecto, puedes congelarlas en requirements.txt:

pip freeze > requirements.txt

Y para instalarlas en otro entorno:

pip install -r requirements.txt

[BUENA PRÁCTICA] pip freeze incluye todas las dependencias instaladas, incluidas las transitivas (las que instalan otras bibliotecas). Para un control más preciso, declara las dependencias directas en pyproject.toml y usa una herramienta que genere un lockfile con las versiones exactas.

uv es un gestor de paquetes y proyectos escrito en Rust, extremadamente rápido (10-100 veces más que pip). En 2026 se ha consolidado como la herramienta de referencia para proyectos nuevos: reemplaza a pip, venv y pip-tools en un solo comando.

Flujo con uv:

# Crear un proyecto nuevo
uv init mi-proyecto
cd mi-proyecto
 
# Añadir una dependencia (actualiza pyproject.toml y uv.lock)
uv add requests
 
# Sincronizar el entorno con las dependencias declaradas
uv sync
 
# Ejecutar un script o un comando dentro del entorno
uv run python main.py
uv run pytest

uv crea automáticamente el entorno virtual (.venv), resuelve las dependencias, genera un lockfile (uv.lock) con las versiones exactas y garantiza que la instalación sea reproducible.

[PYTHON] uv no forma parte de la biblioteca estándar, pero se ha convertido en el estándar de facto para proyectos nuevos en 2026. venv y pip siguen siendo válidos y son la base sobre la que uv construye, pero uv ofrece una experiencia más integrada y mucho más rápida. Para este curso, aprender ambos te da flexibilidad: venv/pip para entender los fundamentos, uv para la práctica profesional.

[AMPLIACIÓN] pipx es otra herramienta del ecosistema moderno: instala aplicaciones de línea de comandos (como ruff, black o httpie) en entornos aislados, sin contaminar el entorno del proyecto. Es útil para herramientas globales que no forman parte de las dependencias de un proyecto concreto.

pyproject.toml es el archivo de configuración estándar de un proyecto Python moderno (PEP 518, PEP 621). Declara los metadatos del proyecto, las dependencias, el backend de construcción y la configuración de herramientas como Ruff, pytest o mypy.

[project]
name = "mi-proyecto"
version = "0.1.0"
description = "Una herramienta para procesar gastos"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.31",
]
 
[project.optional-dependencies]
dev = [
    "pytest>=8.0",
    "ruff>=0.6",
    "mypy>=1.10",
]
 
[project.scripts]
mi-proyecto = "mi_proyecto.cli:main"
 
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
 
[tool.ruff]
line-length = 88
 
[tool.pytest.ini_options]
testpaths = ["tests"]
 
[tool.mypy]
strict = true

[PYTHON] pyproject.toml es la fuente única de verdad del proyecto. Sustituye a setup.py, setup.cfg y, en muchos casos, a requirements.txt. Las herramientas modernas (uv, pip, hatch, poetry) lo leen y respetan.

[BUENA PRÁCTICA] Declara las dependencias directas en dependencies y las de desarrollo en optional-dependencies. No mezcles dependencias de producción con herramientas de pruebas o documentación.

El diseño src/ coloca el código importable dentro de una subcarpeta src/, separada de los archivos de configuración y documentación.

mi-proyecto/
├── pyproject.toml
├── README.md
├── .gitignore
├── src/
│   └── mi_proyecto/
│       ├── __init__.py
│       ├── main.py
│       └── cli.py
├── tests/
│   └── test_main.py
└── docs/
    └── index.rst

Ventajas del diseño src/:

- Evita importaciones accidentales: sin src/, el intérprete incluye el directorio actual en sys.path, y un import mi_proyecto podría importar la copia en desarrollo en lugar de la instalada. Con src/, el código debe instalarse (aunque sea en modo editable) para poder importarse. - Garantiza que las pruebas se ejecutan contra el paquete instalado, no contra una copia local que podría estar desactualizada. - Refleja la estructura real del paquete que se distribuirá.

[BUENA PRÁCTICA] La guía oficial de empaquetado de Python recomienda el diseño src/ para proyectos que se van a distribuir o que tienen pruebas automatizadas. El diseño plano es aceptable para scripts pequeños, pero src/ escala mejor.

Un proyecto es reproducible si cualquier persona puede reconstruir el mismo entorno y obtener el mismo comportamiento. Es portable si funciona igual en Windows y Linux.

Claves para la reproducibilidad:

- Declarar las dependencias con versiones compatibles en pyproject.toml. - Fijar las versiones exactas en un lockfile (uv.lock, requirements.txt con versiones fijadas). - Documentar la versión de Python requerida (requires-python). - Evitar dependencias del sistema no declaradas.

Claves para la portabilidad:

- Usar pathlib para rutas (Módulo 13). - Evitar rutas absolutas codificadas. - Usar UTF-8 explícitamente al abrir archivos (Módulo 13). - Probar en ambos sistemas (o al menos en CI con una matriz de sistemas operativos).

[BUENA PRÁCTICA] Un proyecto reproducible no depende de lo que “ya estaba instalado” en la máquina. Si una dependencia no está declarada, no existe. uv sync o pip install -r requirements.txt deben ser suficientes para reconstruir el entorno desde cero.

Paso 1: Crear el proyecto.

uv init analizador-gastos
cd analizador-gastos

uv init genera pyproject.toml, README.md, src/ y .gitignore.

Paso 2: Añadir dependencias y herramientas de desarrollo.

uv add requests
uv add --dev pytest ruff mypy

Paso 3: Escribir el código en src/analizador_gastos/main.py.

def calcular_total(gastos: list[dict]) -> float:
    """Devuelve la suma de los importes de una lista de gastos."""
    return sum(g["importe"] for g in gastos)

Paso 4: Escribir una prueba en tests/test_main.py.

from analizador_gastos.main import calcular_total
 
def test_calcular_total():
    gastos = [{"importe": 10}, {"importe": 20}]
    assert calcular_total(gastos) == 30

Paso 5: Ejecutar las pruebas y el linter.

uv run pytest
uv run ruff check .

Paso 6: Inicializar Git y hacer el primer commit.

git init
git add .
git commit -m "Estructura inicial del proyecto con uv y pruebas"

Seguimiento: uv run ejecuta el comando dentro del entorno virtual del proyecto, sin necesidad de activarlo manualmente. uv sync garantiza que el entorno coincida con pyproject.toml y uv.lock. Git registra la estructura inicial; el .gitignore generado por uv excluye .venv/ y __pycache__/.

Cuando ejecutas git commit, Git:

1. Toma una instantánea de los archivos en el área de preparación. 2. Calcula un hash único (SHA-1 o SHA-256) que identifica el commit. 3. Almacena la instantánea en el repositorio local (.git/objects/). 4. Actualiza la rama actual para apuntar al nuevo commit. 5. Registra el autor, la fecha y el mensaje.

El historial de Git es una cadena de commits: cada commit apunta a su predecesor. Por eso puedes volver a cualquier estado anterior con git checkout <hash> o git revert.

Cuando ejecutas uv sync, uv compara pyproject.toml y uv.lock con el estado del entorno virtual, resuelve las dependencias y descarga solo lo que falta. El resultado es un entorno idéntico al declarado, independientemente de la máquina.

[ERROR HABITUAL] Ejecutar pip install sin un entorno virtual activo. Las bibliotecas se instalan en el Python global, pueden entrar en conflicto con otras y no quedan registradas en el proyecto. Siempre dentro de un entorno virtual (o con uv, que lo gestiona automáticamente).

- venv en la biblioteca estándar: a diferencia de Node.js (node_modules por proyecto) o Ruby (Bundler), Python requiere crear y activar explícitamente un entorno virtual. uv simplifica esto, pero el concepto sigue siendo fundamental. - pyproject.toml como estándar: otros ecosistemas usan archivos específicos (package.json en Node.js, Cargo.toml en Rust, pom.xml en Java). Python ha convergido en pyproject.toml para metadatos, dependencias y configuración de herramientas. - Git es universal: no es específico de Python, pero su integración con el ecosistema (.gitignore para .venv/, __pycache__/) es parte del flujo de trabajo diario. - argparse en la biblioteca estándar: otros lenguajes requieren bibliotecas externas para interfaces de línea de comandos. Python incluye argparse, lo que reduce dependencias en scripts pequeños.

Incorrecto (sin entorno virtual, dependencias globales, .gitignore tardío):

pip install requests
git add .
git commit -m "inicio"

Mejor (entorno aislado, dependencias declaradas, .gitignore desde el principio):

uv init mi-proyecto
cd mi-proyecto
uv add requests
git init
git add .
git commit -m "Estructura inicial con uv y dependencias declaradas"

[BUENA PRÁCTICA] Un proyecto debe poder reconstruirse con un solo comando (uv sync o pip install -r requirements.txt) a partir de los archivos versionados. Si necesitas pasos manuales no documentados, el proyecto no es reproducible. Documenta el flujo en el README (Módulo 18).

- Comandos de terminal: la mayoría son equivalentes (cd, mkdir, ls), pero algunos difieren (source frente a .venv\Scripts\activate). - Entornos virtuales: la estructura interna difiere (bin/ en Linux, Scripts/ en Windows), pero el flujo es el mismo. - Git: funciona igual en ambos sistemas. La configuración de finales de línea (core.autocrlf) puede necesitar ajuste si colaboras entre sistemas, pero para un proyecto individual no suele ser necesario. - uv: funciona en Windows y Linux. Los comandos son idénticos. - Rutas en pyproject.toml: usa / en la configuración; las herramientas lo interpretan correctamente en ambos sistemas.

[WINDOWS / LINUX] Si un proyecto funciona en Linux pero falla en Windows, revisa mayúsculas en nombres de archivo (Windows no distingue, Linux sí), finales de línea (\n vs. \r\n) y rutas codificadas manualmente. pathlib y uv ayudan a evitarlo.

Ejercicio guiado 1: Script con argparse.

Escribe un script contar.py que reciba una ruta de archivo y una palabra, y cuente cuántas veces aparece la palabra en el archivo. Usa argparse para definir los dos argumentos y muestra un mensaje de ayuda con --help.

Ejercicio guiado 2: Repositorio Git básico.

1. Crea una carpeta proyecto-git y entra en ella. 2. Inicializa un repositorio con git init. 3. Crea un archivo hola.py con un print("Hola"). 4. Crea un .gitignore que excluya __pycache__/ y .venv/. 5. Haz un commit con el mensaje "Añade script inicial". 6. Modifica el archivo, haz un segundo commit y consulta el historial con git log --oneline.

Ejercicio guiado 3: Proyecto con uv y src/.

1. Crea un proyecto con uv init mi-libreria. 2. Añade una función en src/mi_libreria/__init__.py. 3. Añade una prueba en tests/test_mi_libreria.py. 4. Ejecuta uv run pytest y comprueba que pasa. 5. Examina el pyproject.toml generado e identifica las secciones [project], [build-system] y [tool.pytest.ini_options].

1. Predicción: ¿Qué hace git status después de crear un archivo nuevo sin añadirlo? ¿Y después de git add? Ejecútalo y comprueba. 2. Ramas: Crea una rama feature/saludo, añade una función de saludo, haz un commit, vuelve a main y fusiona. Consulta el historial con git log --graph --oneline. 3. pyproject.toml: Añade una sección [project.optional-dependencies] con un grupo dev que incluya pytest, ruff y mypy. Instálalo con uv sync --extra dev. 4. Reproducibilidad: Borra la carpeta .venv de un proyecto, ejecuta uv sync y comprueba que las pruebas siguen pasando. Explica qué ha ocurrido. 5. Reto opcional: Investiga el comando uv pip compile y genera un requirements.txt con versiones fijadas a partir de un pyproject.toml. Compara el resultado con pip freeze.

Solución al ejercicio guiado 1:

import argparse
from pathlib import Path
 
def contar_palabra(ruta, palabra):
    texto = Path(ruta).read_text(encoding="utf-8")
    return texto.lower().count(palabra.lower())
 
parser = argparse.ArgumentParser(description="Cuenta apariciones de una palabra.")
parser.add_argument("ruta", help="Ruta del archivo de texto")
parser.add_argument("palabra", help="Palabra a buscar")
args = parser.parse_args()
 
print(contar_palabra(args.ruta, args.palabra))

argparse valida que ambos argumentos estén presentes y genera ayuda automática.

Solución al ejercicio guiado 2: El flujo es el descrito en los pasos. git log --oneline muestra algo como:

a1b2c3d Modifica el saludo
e4f5g6h Añade script inicial

Solución al ejercicio 3: uv init genera pyproject.toml con [project] y [build-system]. uv add pytest añade la dependencia y actualiza pyproject.toml y uv.lock. uv run pytest ejecuta las pruebas dentro del entorno.

Solución al ejercicio 1 (predicción): git status muestra el archivo como untracked (no rastreado). Después de git add, aparece como staged (preparado para el commit).

- La terminal es la interfaz para ejecutar comandos, scripts y herramientas; los comandos básicos son similares en Windows y Linux. - argparse permite crear interfaces de línea de comandos robustas con ayuda automática y validación de tipos. - Git registra el historial: init, add, commit, branch, merge. El .gitignore debe configurarse antes del primer commit. - Los entornos virtuales (venv) aíslan las dependencias de cada proyecto; uv los gestiona automáticamente y añade un lockfile reproducible. - pyproject.toml es la fuente única de verdad del proyecto: metadatos, dependencias y configuración de herramientas. - El diseño src/ evita importaciones accidentales y refleja la estructura real del paquete. - Un proyecto reproducible se reconstruye con un comando (uv sync o pip install -r requirements.txt); uno portable funciona igual en Windows y Linux.

1. ¿Qué diferencia hay entre git add y git commit? ¿Qué contiene el área de preparación? 2. ¿Por qué es importante configurar .gitignore antes del primer commit? 3. ¿Qué hace un entorno virtual y por qué no debes instalarlo todo globalmente? 4. ¿Qué ventaja aporta el diseño src/ frente al diseño plano? 5. Reto: Sin ejecutar, predice qué archivos incluiría git add . en un proyecto con .venv/, __pycache__/, main.py y pyproject.toml si el .gitignore no existe. Luego explica cómo lo corregirías.