Hola, reproducible

Objetivos

Al terminar este proyecto vas a haber hecho, con tus manos y sin ayuda de la IA:

• Crear un proyecto Python con estructura estándar (src/, tests/, pyproject.toml) y su entorno aislado con uv.
• Escribir un test que falla, luego la función que lo hace pasar.
• Ver el mismo test correr dentro de un contenedor Docker.
• Publicar el repo en GitHub y abrir un Pull Request que Rodrigo revisa.
• Poner un breakpoint y mirar una variable en el debugger de VS Code.

Temas que vas a usar

Léelos antes o consúltalos cuando aparezcan. Están en El libro de Python (en español, corto y bien explicado). Los de la derecha son de esta guía.

• Instalar PythonSolo para entender qué es un intérprete. Nosotros lo instalamos con uv.
• Funcionesdef, parámetros, return. Lo único que escribes hoy.
• Anotaciones de tiposeq: str y -> float: dicen qué entra y qué sale.
• Cadenas de texto.upper(), .count(), len().
• Excepcionesraise ValueError(...): fallar temprano y claro.
• Testing con pytestQué es un test, cómo se estructura, cómo se corre.
• Módulos · PaquetesPor qué from hola.core import gc_content funciona.
• Los 4 hábitos del día 0Git, tests, Docker, documentar. Este proyecto los estrena todos.
• Trabajar con IARegla 1: la primera vez, a mano. Este proyecto es esa primera vez.

Antes de empezar

Instala las herramientas y verifica cada una. Si un comando de verificación no responde como se indica, arréglalo antes de seguir; nada de lo que viene funciona sin esto.

1. Terminal

En macOS: la app Terminal (o iTerm2). En Windows: instala WSL2 con Ubuntu y trabaja siempre ahí; todo lo que sigue asume una terminal tipo Unix.

2. uv (instala Python y maneja proyectos)

# macOS (con Homebrew) o Linux
brew install uv          # macOS
curl -LsSf https://astral.sh/uv/install.sh | sh    # Linux / WSL

# instala Python 3.12 (uv lo descarga; no toca el Python del sistema)
uv python install 3.12

uv --version

uv 0.12.5 (o superior)

3. git y GitHub

git --version
git config --global user.name "Alexandra"
git config --global user.email "tu-correo@ejemplo.com"
git config --global init.defaultBranch main

Crea tu cuenta en github.com si no la tienes. Instala la CLI de GitHub e inicia sesión (te guía para crear la llave SSH):

brew install gh        # macOS · en Linux: https://cli.github.com
gh auth login          # elige GitHub.com → SSH → seguir las instrucciones
gh auth status

✓ Logged in to github.com account alexandra-… (keyring)

4. Docker Desktop

Descarga Docker Desktop, ábrelo y espera a que el ícono diga que está corriendo. Luego:

docker run --rm hello-world

Hello from Docker!
This message shows that your installation appears to be working correctly.

5. VS Code

Instala VS Code y, dentro, la extensión Python (de Microsoft). Con eso vienen el debugger y el panel de tests. Opcional pero recomendado: la extensión Ruff.

6. Claude Code

Instálalo siguiendo la documentación oficial. En este proyecto lo usas solo para preguntar, no para escribir. Ver Con Claude más abajo.

Construcción paso a paso

Escribe cada archivo tú misma (no copies y pegues bloques enteros: tipear es parte de aprender). Corre cada comando y compara con lo que "deberías ver". Si difiere, detente ahí y entiende por qué antes de avanzar.

mkdir hola-alexandra
cd hola-alexandra
git init
uv python pin 3.12
mkdir -p src/hola tests

[project]
name = "hola"
version = "0.1.0"
description = "Proyecto 0: validar la cadena de herramientas"
requires-python = ">=3.12"
dependencies = []

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/hola"]

[tool.pytest.ini_options]
testpaths = ["tests"]

[tool.ruff]
line-length = 100

touch src/hola/__init__.py

.venv/
__pycache__/
.pytest_cache/
.ruff_cache/
*.pyc
.env
dist/

uv add --dev pytest ruff

Resolved 6 packages in …
Installed 5 packages in …
 + hola==0.1.0 (from file:///…/hola-alexandra)
 + pytest==9.x
 + ruff==0.x
 …

ls -a

.  ..  .git  .gitignore  .python-version  .venv  pyproject.toml  src  tests  uv.lock

git status
git add .
git commit -m "Estructura inicial del proyecto con uv, pytest y ruff"
git log --oneline

a1b2c3d (HEAD -> main) Estructura inicial del proyecto con uv, pytest y ruff

import pytest

from hola.core import gc_content


def test_gc_content_mitad():
    assert gc_content("ATGC") == 0.5


def test_gc_content_todo_gc():
    assert gc_content("GGCC") == 1.0


def test_gc_content_ignora_minusculas():
    assert gc_content("atgc") == 0.5


def test_gc_content_secuencia_vacia_lanza_error():
    with pytest.raises(ValueError):
        gc_content("")

uv run pytest

==================================== ERRORS ====================================
_____________________ ERROR collecting tests/test_core.py ______________________
…
tests/test_core.py:3: in <module>
    from hola.core import gc_content
E   ModuleNotFoundError: No module named 'hola.core'
=========================== short test summary info ============================
ERROR tests/test_core.py
!!!!!!!!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!!!!!!!!

"""Funciones sobre secuencias de ADN. Solo cálculo: nada de archivos ni print."""


def gc_content(seq: str) -> float:
    """Fracción de bases G y C en la secuencia, entre 0.0 y 1.0.

    Ignora mayúsculas/minúsculas. Lanza ValueError si la secuencia está vacía.
    """
    if not seq:
        raise ValueError("la secuencia está vacía")
    seq = seq.upper()
    gc = seq.count("G") + seq.count("C")
    return gc / len(seq)

uv run pytest -v

tests/test_core.py::test_gc_content_mitad PASSED                         [ 25%]
tests/test_core.py::test_gc_content_todo_gc PASSED                       [ 50%]
tests/test_core.py::test_gc_content_ignora_minusculas PASSED             [ 75%]
tests/test_core.py::test_gc_content_secuencia_vacia_lanza_error PASSED   [100%]

============================== 4 passed in 0.01s ===============================

uv run ruff check .
uv run ruff format .

All checks passed!
3 files left unchanged   (o "1 file reformatted" si tenías algo distinto: mira el diff con git diff)

git add .
git commit -m "Agrega gc_content con sus tests"

.venv/
.git/
__pycache__/
.pytest_cache/
.ruff_cache/

# Imagen base: Python 3.12 mínimo, sobre Debian
FROM python:3.12-slim

# Copiamos el binario de uv desde su imagen oficial
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /app

# Primero las dependencias (cambian poco → la capa se cachea)
COPY pyproject.toml uv.lock ./
# Luego el código y los tests
COPY src ./src
COPY tests ./tests

# Instala exactamente lo que dice uv.lock, nada más
RUN uv sync --frozen

# Lo que corre el contenedor por defecto: los tests
CMD ["uv", "run", "pytest", "-v"]

docker build -t hola .
docker run --rm hola

…
tests/test_core.py::test_gc_content_mitad PASSED                         [ 25%]
tests/test_core.py::test_gc_content_todo_gc PASSED                       [ 50%]
tests/test_core.py::test_gc_content_ignora_minusculas PASSED             [ 75%]
tests/test_core.py::test_gc_content_secuencia_vacia_lanza_error PASSED   [100%]

============================== 4 passed in 0.01s ===============================

docker images hola

REPOSITORY   TAG       IMAGE ID       CREATED          SIZE
hola         latest    ba5ccbd2560c   1 minute ago     ~320MB

git add .
git commit -m "Dockerfile que corre los tests en un contenedor"

# hola-alexandra

Proyecto 0 del cuaderno: valida la cadena de herramientas con una sola
función (`gc_content`) y su test.

## Correr los tests

    uv sync
    uv run pytest

## Correr los tests en Docker

    docker build -t hola .
    docker run --rm hola

## Estructura

    src/hola/core.py      la función (solo cálculo, sin I/O)
    tests/test_core.py    sus controles
    Dockerfile            entorno reproducible
    pyproject.toml        descripción del proyecto y dependencias

## Decisiones

- `src/` layout: obliga a instalar el paquete para probarlo, igual que
  lo haría un usuario. Evita que "funcione en mi máquina" por accidente.
- Ver DECISIONES.md.

# Decisiones

## 2026-08-xx · uv en lugar de pip + venv
Una herramienta hace lo que antes eran cuatro. Alternativa: pip + venv +
pip-tools. Cambio si uv deja de mantenerse.

## 2026-08-xx · La imagen Docker corre los tests
En este proyecto no hay "programa" que correr; lo que quiero verificar es
que el entorno se reproduce. Los tests son la prueba de eso.

git add .
git commit -m "README y registro de decisiones"
gh repo create hola-alexandra --private --source . --push

✓ Created repository alexandra-…/hola-alexandra on GitHub
✓ Added remote git@github.com:alexandra-…/hola-alexandra.git
✓ Pushed commits to git@github.com:alexandra-…/hola-alexandra.git

{
  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": ["tests"]
}

git switch -c feat/reverse-complement

from hola.core import reverse_complement


def test_reverse_complement_basico():
    assert reverse_complement("ATGC") == "GCAT"


def test_reverse_complement_ignora_minusculas():
    assert reverse_complement("atgc") == "GCAT"


def test_reverse_complement_base_invalida_lanza_error():
    with pytest.raises(ValueError):
        reverse_complement("ATXG")

COMPLEMENTO = {"A": "T", "T": "A", "G": "C", "C": "G"}


def reverse_complement(seq: str) -> str:
    """Complemento reverso de una secuencia de ADN (5'→3')."""
    seq = seq.upper()
    invalidas = set(seq) - set(COMPLEMENTO)
    if invalidas:
        raise ValueError(f"bases inválidas: {sorted(invalidas)}")
    return "".join(COMPLEMENTO[base] for base in reversed(seq))

uv run pytest -q
uv run ruff check . && uv run ruff format .
docker build -t hola . && docker run --rm hola

7 passed in 0.01s   (y lo mismo dentro de Docker)

git add .
git commit -m "Agrega reverse_complement con validación de bases"
git push -u origin feat/reverse-complement
gh pr create --title "Agrega reverse_complement" --body "Segunda función del P0. Valida bases y devuelve el complemento reverso. Incluye 3 tests." --reviewer rotorrest

git switch main
git pull
git log --oneline

Entiende el código

No sigas al Proyecto 1 hasta poder explicar cada una de estas piezas con tus palabras.

Estructura

hola-alexandra/
├── .python-version      versión de Python del proyecto (la lee uv)
├── pyproject.toml       nombre, versión, dependencias, config de pytest y ruff
├── uv.lock              versiones exactas instaladas (se versiona)
├── .venv/               entorno virtual (NO se versiona; se regenera con uv sync)
├── src/hola/
│   ├── __init__.py      marca la carpeta como paquete
│   └── core.py          la lógica: funciones puras
├── tests/test_core.py   los controles
├── Dockerfile           receta de la imagen
├── .dockerignore        lo que no entra a la imagen
├── README.md            el protocolo
└── DECISIONES.md        el porqué de lo no obvio

pyproject.toml, sección por sección

• [project]: identidad del paquete. requires-python es una promesa: este código asume 3.12 o más.
• [build-system]: qué herramienta convierte tu carpeta en un paquete instalable (hatchling). Sin esto, uv add no instala tu propio paquete y el import hola.core falla desde tests/.
• [tool.hatch.build.targets.wheel]: dónde está el código (src/hola). Es lo que hace que from hola.core import … resuelva.
• [tool.pytest.ini_options]: dónde buscar tests. [tool.ruff]: largo de línea. Cada herramienta lee su sección de este mismo archivo: un solo lugar de configuración.
• [dependency-groups] dev (lo agregó uv add --dev): herramientas que necesitas para desarrollar, no para que el paquete funcione. Un usuario de hola no necesita pytest.

Por qué src/

Si el código estuviera en la raíz (hola/core.py al lado de tests/), Python lo encontraría "por casualidad" desde la carpeta actual, y los tests pasarían aunque el paquete estuviera mal instalado. Con src/, la única forma de importar hola es tenerlo instalado en el entorno, igual que lo tendría un usuario. Es una restricción que te protege de un "funciona en mi máquina".

Anatomía de un test

def test_gc_content_mitad():          # 1. nombre: empieza con test_, dice qué caso prueba
    assert gc_content("ATGC") == 0.5   # 2. arrange + act + assert en una línea: entrada conocida, salida esperada

def test_gc_content_secuencia_vacia_lanza_error():
    with pytest.raises(ValueError):    # 3. "dentro de este bloque DEBE saltar ValueError; si no salta, el test falla"
        gc_content("")

pytest descubre solo las funciones que empiezan con test_ en archivos que empiezan con test_. Un assert que da False = test fallido, y pytest te muestra los dos lados de la comparación. No hay más magia que esa.

La función

• seq: str) -> float: anotaciones. No cambian cómo corre, pero documentan el contrato y VS Code las usa para avisarte errores antes de correr.
• if not seq: raise ValueError(...): validar en el borde y fallar temprano con un mensaje que dice qué pasó. Sin esto, gc / len(seq) daría ZeroDivisionError: también falla, pero con un mensaje que no explica el problema real.
• La función no lee archivos, no imprime, no pide nada al usuario. Entra un str, sale un float. Por eso testearla es trivial. Esta separación entre lógica y entrada/salida es el concepto central del Proyecto 1.

El Dockerfile, línea por línea

• FROM python:3.12-slim: parto de una imagen que ya tiene Python 3.12 sobre un Debian mínimo. Nunca instalo Python a mano dentro de Docker.
• COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv: copio el ejecutable de uv desde su imagen oficial. Un solo archivo, sin pip.
• WORKDIR /app: de aquí en adelante todo pasa en /app dentro de la imagen.
• COPY pyproject.toml uv.lock ./ antes que COPY src: Docker cachea cada capa. Si solo cambias código, la capa de dependencias no se reconstruye. Es una optimización que verás en todos los Dockerfiles serios.
• RUN uv sync --frozen: instala exactamente lo que dice uv.lock. --frozen falla si el lock no coincide con pyproject.toml: mejor fallar en el build que instalar algo distinto en silencio.
• CMD [...]: qué corre el contenedor si no le dices otra cosa. Se puede sobreescribir: docker run --rm hola uv run python -c "from hola.core import gc_content; print(gc_content('GGGA'))".

Con Claude

Regla 1 de Trabajar con IA: la primera vez, a mano. Este proyecto entero es esa primera vez, así que Claude Code no escribe nada aquí. Sí lo usas para entender. Abre Claude Code en la carpeta del proyecto (claude) y crea primero el protocolo para él:

# hola-alexandra

Proyecto de aprendizaje. Estoy aprendiendo a programar con criterio; el
objetivo es que YO entienda cada línea.

## Reglas
- No escribas código a menos que te lo pida explícitamente. Por defecto,
  explica y pregunta.
- Si te pido código, propón el cambio más pequeño posible y explica cada línea.
- Nunca modifiques los tests para que pasen.
- No agregues dependencias sin preguntar y decir por qué.
- Antes de decir que algo está listo: `uv run pytest` y `uv run ruff check .`
  deben pasar.
- Responde en español.

Si algo falla

Los errores más comunes de este proyecto, cómo se ven y qué significan. Antes de buscar aquí: lee el traceback de abajo hacia arriba y formula una hipótesis.

Listo cuando

Las mismas casillas que en el índice; marcarlas aquí las marca allá. Sé honesta: "casi" no cuenta.

• Rodrigo clona el repo y con solo docker build + docker run ve los tests en verde.
• Hay al menos 3 commits con mensajes que explican por qué.
• Un test feliz y uno que verifica que una secuencia vacía lanza ValueError.
• Pusiste un breakpoint en la función y viste el valor de seq en el debugger.
• Puedes explicar la diferencia entre imagen y contenedor con tus palabras.

Siguiente

En el Proyecto 1 · seqtool conviertes estas dos funciones en un programa de línea de comandos que lee archivos FASTA de verdad, y aprendes la separación más importante de todas: la lógica en un lado, la entrada/salida en otro. Ahí también entra la integración continua (GitHub Actions corriendo tus tests en cada PR).

Si te quedaste con ganas: instala tu paquete como herramienta (uv build y luego uv tool install dist/hola-0.1.0-py3-none-any.whl) y entiende qué es un wheel. Es opcional; anótalo si lo haces.