seqtool

[project]
name = "seqtool"
version = "0.1.0"
description = "Proyecto 1: CLI de secuencias de ADN, hecho a mano a propósito"
requires-python = ">=3.12"
dependencies = []

[project.scripts]
seqtool = "seqtool.cli:app"

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

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

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

[tool.ruff]
line-length = 100

import pytest

from seqtool.core import base_counts, find_motif, gc_content, reverse_complement


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


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("")


def test_gc_content_ignora_n_en_el_denominador():
    # ATGNNNGCC: 9 bases, 3 son N; de las 6 válidas, 4 son G/C
    assert gc_content("ATGNNNGCC") == pytest.approx(4 / 6)


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


def test_reverse_complement_conserva_n():
    assert reverse_complement("ATGN") == "NCAT"


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


def test_find_motif_devuelve_posiciones_0_based():
    assert find_motif("ATGGAATTCGGCC", "GAATTC") == [3]


def test_find_motif_varias_veces_y_solapadas():
    assert find_motif("AAAA", "AA") == [0, 1, 2]


def test_find_motif_sin_coincidencia_devuelve_lista_vacia():
    assert find_motif("ATGC", "GGG") == []


def test_find_motif_ignora_minusculas():
    assert find_motif("atggaattc", "GAATTC") == [3]


def test_find_motif_motivo_vacio_lanza_error():
    with pytest.raises(ValueError):
        find_motif("ATGC", "")


def test_base_counts():
    assert base_counts("ATGCNa") == {"A": 2, "C": 1, "G": 1, "T": 1, "N": 1}

"""Lógica sobre secuencias de ADN. Funciones puras: entra texto, sale un valor.

Aquí no se leen archivos, no se imprime nada y no se sabe qué es una terminal.
"""

from collections import Counter

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


def gc_content(seq: str) -> float:
    """Fracción de G y C entre las bases válidas (A, C, G, T). Las N no cuentan.

    Lanza ValueError si la secuencia está vacía o no tiene bases válidas.
    """
    if not seq:
        raise ValueError("la secuencia está vacía")
    seq = seq.upper()
    validas = sum(seq.count(b) for b in "ACGT")
    if validas == 0:
        raise ValueError("la secuencia no tiene bases A/C/G/T")
    return (seq.count("G") + seq.count("C")) / validas


def reverse_complement(seq: str) -> str:
    """Complemento reverso (5'→3'). Acepta N. Lanza ValueError ante otras bases."""
    seq = seq.upper()
    invalidas = set(seq) - set(COMPLEMENTO)
    if invalidas:
        raise ValueError(f"bases inválidas: {sorted(invalidas)}")
    return "".join(COMPLEMENTO[b] for b in reversed(seq))


def find_motif(seq: str, motif: str) -> list[int]:
    """Posiciones (0-based) donde empieza el motivo, incluyendo solapadas."""
    if not motif:
        raise ValueError("el motivo está vacío")
    seq, motif = seq.upper(), motif.upper()
    posiciones = []
    for i in range(len(seq) - len(motif) + 1):
        if seq[i : i + len(motif)] == motif:
            posiciones.append(i)
    return posiciones


def base_counts(seq: str) -> dict[str, int]:
    """Cuántas veces aparece cada base, en mayúsculas."""
    return dict(Counter(seq.upper()))

>seq1 fragmento con sitio EcoRI
ATGGAATTCGGCC
>seq2 en minusculas y partida en dos lineas
atgcatgc
gaattc
>seq3 con bases indeterminadas
ATGNNNGCC

from pathlib import Path

import pytest

from seqtool.fasta import Record, iter_fasta, parse_fasta

DATA = Path(__file__).parent / "data"


def test_parse_fasta_lee_tres_registros():
    registros = parse_fasta(DATA / "ejemplo.fasta")
    assert len(registros) == 3
    assert registros[0] == Record(id="seq1", seq="ATGGAATTCGGCC")


def test_parse_fasta_une_lineas_y_pasa_a_mayusculas():
    registros = parse_fasta(DATA / "ejemplo.fasta")
    assert registros[1].id == "seq2"
    assert registros[1].seq == "ATGCATGCGAATTC"


def test_iter_fasta_es_un_generador():
    gen = iter_fasta(DATA / "ejemplo.fasta")
    primero = next(gen)
    assert primero.id == "seq1"


def test_parse_fasta_archivo_inexistente_lanza_error():
    with pytest.raises(FileNotFoundError):
        parse_fasta(DATA / "no_existe.fasta")


def test_parse_fasta_sin_cabecera_lanza_error(tmp_path):
    malo = tmp_path / "malo.fasta"
    malo.write_text("ATGC\nGGCC\n")
    with pytest.raises(ValueError, match="cabecera"):
        parse_fasta(malo)


def test_parse_fasta_vacio_devuelve_lista_vacia(tmp_path):
    vacio = tmp_path / "vacio.fasta"
    vacio.write_text("")
    assert parse_fasta(vacio) == []

"""Leer archivos FASTA. Aquí sí hay archivos, pero todavía nada de terminal."""

from collections.abc import Iterator
from dataclasses import dataclass
from pathlib import Path


@dataclass(frozen=True)
class Record:
    id: str
    seq: str


def iter_fasta(path: Path) -> Iterator[Record]:
    """Recorre un FASTA registro por registro sin cargar el archivo entero en memoria."""
    id_actual: str | None = None
    partes: list[str] = []
    with open(path, encoding="utf-8") as f:
        for numero, linea in enumerate(f, start=1):
            linea = linea.strip()
            if not linea:
                continue
            if linea.startswith(">"):
                if id_actual is not None:
                    yield Record(id_actual, "".join(partes))
                id_actual = linea[1:].split()[0]
                partes = []
            elif id_actual is None:
                raise ValueError(f"línea {numero}: secuencia sin cabecera '>' antes")
            else:
                partes.append(linea.upper())
    if id_actual is not None:
        yield Record(id_actual, "".join(partes))


def parse_fasta(path: Path) -> list[Record]:
    """Lee un FASTA completo a una lista. Cómodo para archivos chicos."""
    return list(iter_fasta(path))

"""Entrada/salida: argumentos, archivos, pantalla. La capa delgada y aburrida."""

from pathlib import Path

import typer

from seqtool import core, fasta

app = typer.Typer(
    help="Herramientas simples para secuencias de ADN en FASTA.", no_args_is_help=True
)


def _leer(archivo: Path) -> list[fasta.Record]:
    """Lee el FASTA o termina el programa con un mensaje claro y código de salida 1."""
    try:
        return fasta.parse_fasta(archivo)
    except FileNotFoundError:
        typer.echo(f"error: no existe el archivo {archivo}", err=True)
        raise typer.Exit(code=1)
    except ValueError as e:
        typer.echo(f"error: FASTA malformado ({e})", err=True)
        raise typer.Exit(code=1)


@app.command()
def stats(archivo: Path) -> None:
    """Longitud, %GC y conteo por base de cada secuencia."""
    for r in _leer(archivo):
        try:
            gc = f"{core.gc_content(r.seq):.1%}"
        except ValueError:
            gc = "n/a"
        conteo = " ".join(f"{b}={n}" for b, n in sorted(core.base_counts(r.seq).items()))
        typer.echo(f"{r.id}\tlen={len(r.seq)}\tGC={gc}\t{conteo}")


@app.command()
def revcomp(archivo: Path) -> None:
    """Complemento reverso de cada secuencia, en formato FASTA."""
    for r in _leer(archivo):
        try:
            typer.echo(f">{r.id}_rc\n{core.reverse_complement(r.seq)}")
        except ValueError as e:
            typer.echo(f"error: {r.id}: {e}", err=True)
            raise typer.Exit(code=1)


@app.command()
def find(
    archivo: Path,
    motif: str = typer.Option(..., "--motif", "-m", help="Motivo a buscar, ej. GAATTC"),
) -> None:
    """Posiciones (0-based) donde aparece el motivo en cada secuencia."""
    if not motif:
        typer.echo("error: el motivo no puede estar vacío", err=True)
        raise typer.Exit(code=2)
    for r in _leer(archivo):
        pos = core.find_motif(r.seq, motif)
        typer.echo(f"{r.id}\t{len(pos)}\t{','.join(map(str, pos)) or '-'}")

from pathlib import Path

from typer.testing import CliRunner

from seqtool.cli import app

DATA = Path(__file__).parent / "data"
runner = CliRunner()


def test_stats_imprime_una_linea_por_secuencia():
    resultado = runner.invoke(app, ["stats", str(DATA / "ejemplo.fasta")])
    assert resultado.exit_code == 0
    lineas = resultado.stdout.strip().splitlines()
    assert len(lineas) == 3
    assert lineas[0].startswith("seq1\tlen=13\tGC=53.8%")


def test_find_encuentra_ecori():
    resultado = runner.invoke(app, ["find", str(DATA / "ejemplo.fasta"), "--motif", "GAATTC"])
    assert resultado.exit_code == 0
    assert "seq1\t1\t3" in resultado.stdout
    assert "seq3\t0\t-" in resultado.stdout


def test_revcomp_devuelve_fasta():
    resultado = runner.invoke(app, ["revcomp", str(DATA / "ejemplo.fasta")])
    assert resultado.exit_code == 0
    assert ">seq1_rc\nGGCCGAATTCCAT" in resultado.stdout


def test_archivo_inexistente_sale_con_codigo_1():
    resultado = runner.invoke(app, ["stats", "no_existe.fasta"])
    assert resultado.exit_code == 1
    assert "no existe el archivo" in resultado.output


def test_motivo_vacio_sale_con_codigo_2():
    resultado = runner.invoke(app, ["find", str(DATA / "ejemplo.fasta"), "--motif", ""])
    assert resultado.exit_code == 2

"""Control externo: nuestra implementación contra una librería madura."""

from Bio.Seq import Seq
from Bio.SeqUtils import gc_fraction

from seqtool.core import gc_content, reverse_complement


def test_gc_content_coincide_con_biopython():
    for seq in ["ATGC", "GGCC", "ATATAT", "atggaattcggcc"]:
        assert gc_content(seq) == gc_fraction(seq)


def test_reverse_complement_coincide_con_biopython():
    for seq in ["ATGC", "GGAATTCC", "atgn"]:
        assert reverse_complement(seq) == str(Seq(seq).reverse_complement()).upper()

"""¿Cuánto crece el tiempo de find_motif si la secuencia crece 10x? Medirlo, no adivinarlo."""

import random
import time

from seqtool.core import find_motif

random.seed(1)
for n in (100_000, 1_000_000, 10_000_000):
    seq = "".join(random.choice("ACGT") for _ in range(n))
    inicio = time.perf_counter()
    hallazgos = find_motif(seq, "GAATTC")
    segundos = time.perf_counter() - inicio
    print(f"n={n:>10,}  hallazgos={len(hallazgos):>6,}  tiempo={segundos:.3f}s")

name: CI
on:
  push:
    branches: [main]
  pull_request:
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v6
        with:
          python-version: "3.12"
      - run: uv sync
      - run: uv run ruff check .
      - run: uv run ruff format --check .
      - run: uv run pytest

FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
WORKDIR /app
COPY pyproject.toml uv.lock ./
COPY src ./src
# Solo lo que necesita el programa (sin pytest, ruff ni biopython)
RUN uv sync --frozen --no-dev
# El script `seqtool` quedó instalado en el entorno virtual de la imagen
ENV PATH="/app/.venv/bin:$PATH"
# Carpeta donde el usuario monta sus archivos con -v
WORKDIR /data
ENTRYPOINT ["seqtool"]
CMD ["--help"]

## 2026-08-xx · Parser FASTA propio, Biopython solo como control
Reinventé el parser para aprender qué hay dentro (cabeceras, líneas
partidas, mayúsculas, errores de formato). En un proyecto real usaría
Bio.SeqIO: está mantenido, cubre variantes que el mío no (FASTQ,
alineamientos, archivos comprimidos) y lo conocen más personas.
Regla que me llevo: reinventar para aprender, sí; en producción, la
librería madura. Los tests contra gc_fraction se quedan como control.