uydatos 0.2.1__py3-none-any.whl

uydatos/__init__.py

@@ -0,0 +1,24 @@
+"""uydatos — lectores estrictos de datos públicos de Uruguay y la región.
+
+Cada módulo lee una fuente y **rechaza en vez de arreglar**: una respuesta mala, una columna
+cambiada o un hueco en la serie levantan una excepción con el motivo, en lugar de devolver una
+serie creíble pero falsa. La única función de cada módulo que sale a internet se llama
+`descargar*()`; todo lo demás trabaja sobre archivos en disco.
+
+Módulos:
+
+- `bcu`          — cotizaciones del Banco Central del Uruguay (dólar, UI, peso argentino, real).
+- `ancap`        — precios máximos de combustibles fijados por el Poder Ejecutivo.
+- `inia`         — clima diario de INIA Salto Grande, con normales y anomalías.
+- `salto_grande` — estaciones hidrometeorológicas de la CTM de Salto Grande.
+- `indec`        — IPC nacional de Argentina (API de series de datos.gob.ar).
+- `ibge`         — IPCA de Brasil (API SIDRA del IBGE).
+- `ideuy`        — geocodificación de direcciones uruguayas con IDE.uy.
+- `rut`          — dígito verificador de RUT y cédula uruguaya.
+- `semanas`      — semanas ISO 8601 (W1, W2...) con los bordes de año resueltos.
+- `catalogo`     — recursos del catálogo de datos abiertos de Uruguay (CKAN).
+"""
+
+__version__ = "0.2.1"
+
+USER_AGENT = f"uydatos/{__version__} (lectura de datos abiertos)"

uydatos/ancap.py

@@ -0,0 +1,200 @@
+"""Precios máximos de combustibles de ANCAP, aprobados por decreto del Poder Ejecutivo.
+
+Dataset `ancap-precio-combustible-pe` del catálogo de datos abiertos: **precio máximo al
+público, IVA incluido**. **No es** `ancap-precio-combustible-ex-planta`, que es el precio
+deducidos flete, tasas y margen. Los dos se citan como "los precios de ANCAP" y no son el mismo
+número.
+
+Las trampas (medidas en octubre de 2026)
+---------------------------------------
+1. **Las columnas vienen invertidas.** El encabezado dice `Unidad` y `Valor`, pero `Unidad`
+   trae el **número** y `Valor` la **unidad de medida**. Quien sume "Valor" suma `'$/lt'`.
+   Si la fuente las vuelve a dar vuelta, el lector lo rechaza.
+2. **El archivo no es una serie: es un log de publicaciones acumulativas.** Cada mes ANCAP
+   republica el año entero hasta ese mes y el archivo **apila** las publicaciones: un mismo mes
+   aparece decenas de veces. Contar o promediar filas mide publicaciones, no precios: usar
+   `serie_mensual()`.
+3. **El BOM viene doble**: abrir con `utf-8-sig` no alcanza, queda un `\\ufeff` pegado al
+   nombre de la primera columna.
+4. **`S/C`** es *sin cotización*: un nulo, no un cero.
+5. **Coma decimal y punto de miles** (`1.234,50`): un `float()` pelado no sirve.
+
+Uso:
+    python -m uydatos.ancap bajar precios.csv
+    python -m uydatos.ancap serie precios.csv "GASOIL 50-S *"
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import Optional, Sequence
+
+DATASET = "ancap-precio-combustible-pe"
+URL_CSV = (
+    "https://catalogodatos.gub.uy/dataset/556beb30-02fc-4d06-909a-f42083c89ef7/resource/"
+    "1a37fc4a-44fd-4842-bcb4-b5845dc8eced/download/datos-de-precios-de-combustibles.csv"
+)
+
+COLUMNAS_ESPERADAS = ["Año", "Mes", "Producto", "Unidad", "Valor"]
+SIN_COTIZACION = "S/C"
+
+
+class AncapInvalido(ValueError):
+    """La serie no cumple el contrato de la fuente."""
+
+
+def numero_europeo(texto: str) -> Optional[float]:
+    """`'1.234,50'` -> 1234.5. `None` si no se puede leer: nunca un cero inventado."""
+    t = texto.replace("\xa0", " ").strip().replace(".", "").replace(",", ".")
+    if not t:
+        return None
+    try:
+        return float(t)
+    except ValueError:
+        return None
+
+
+def _limpiar_encabezado(campos: list[str]) -> list[str]:
+    return [c.replace("", "").strip() for c in campos]
+
+
+def leer_publicaciones(ruta: Path) -> list[dict]:
+    """Lee el archivo **crudo**: una fila por publicación, sin deduplicar.
+
+    Devuelve, por fila, `anio`, `mes`, `producto`, `precio` (float | None) y `unidad`.
+    Para el precio de un mes usar `serie_mensual()`, no esto.
+    """
+    ruta = Path(ruta)
+    if not ruta.is_file():
+        raise AncapInvalido(f"{ruta}: el archivo no está en el disco")
+    with ruta.open(encoding="utf-8-sig", newline="") as f:
+        lector = csv.reader(f, delimiter=";")
+        try:
+            encabezado = _limpiar_encabezado(next(lector))
+        except StopIteration:
+            raise AncapInvalido(f"{ruta}: archivo vacío") from None
+        if encabezado != COLUMNAS_ESPERADAS:
+            raise AncapInvalido(f"{ruta}: columnas inesperadas {encabezado}, se esperaban {COLUMNAS_ESPERADAS}")
+        publicaciones = []
+        for n, campos in enumerate(lector, start=2):
+            if not any(c.strip() for c in campos):
+                continue
+            if len(campos) != len(COLUMNAS_ESPERADAS):
+                raise AncapInvalido(f"{ruta} fila {n}: {len(campos)} columnas")
+            anio_crudo, mes_crudo, producto, precio_crudo, unidad = (c.strip() for c in campos)
+            # `Valor` tiene que traer la UNIDAD. Si trae un número, la fuente invirtió las columnas.
+            if unidad and unidad != SIN_COTIZACION and not unidad.startswith("$"):
+                raise AncapInvalido(
+                    f"{ruta} fila {n}: la columna `Valor` debería traer la unidad y trae {unidad!r}. "
+                    f"¿La fuente invirtió las columnas?"
+                )
+            try:
+                anio, mes = int(anio_crudo), int(mes_crudo)
+            except ValueError:
+                raise AncapInvalido(f"{ruta} fila {n}: año/mes ilegible {campos[:2]!r}") from None
+            if precio_crudo == SIN_COTIZACION:
+                precio = None
+            else:
+                precio = numero_europeo(precio_crudo)
+                if precio is None:
+                    raise AncapInvalido(f"{ruta} fila {n}: precio ilegible {precio_crudo!r}")
+            publicaciones.append(
+                {
+                    "anio": anio,
+                    "mes": mes,
+                    "producto": producto,
+                    "precio": precio,
+                    "unidad": "" if unidad == SIN_COTIZACION else unidad,
+                }
+            )
+    if not publicaciones:
+        raise AncapInvalido(f"{ruta}: archivo sin filas de datos")
+    return publicaciones
+
+
+def serie_mensual(publicaciones: list[dict]) -> list[dict]:
+    """Deduplica el log apilado: **una fila por (producto, año, mes)**.
+
+    Desempate declarado: **el valor manda sobre el `S/C`**. Un mes que alguna vez tuvo precio no
+    se pierde porque una publicación posterior diga `S/C`; entre dos precios distintos gana el
+    de la publicación más reciente (la que aparece después en el archivo).
+    """
+    orden: list[tuple] = []
+    estado: dict[tuple, dict] = {}
+    for p in publicaciones:
+        clave = (p["producto"], p["anio"], p["mes"])
+        if clave not in estado:
+            orden.append(clave)
+            estado[clave] = {
+                "anio": p["anio"],
+                "mes": p["mes"],
+                "producto": p["producto"],
+                "precio": None,
+                "unidad": "",
+            }
+        if p["precio"] is not None:
+            estado[clave]["precio"] = p["precio"]
+            estado[clave]["unidad"] = p["unidad"]
+    return [estado[k] for k in orden]
+
+
+def precio_del_mes(serie: list[dict], producto: str, anio: int, mes: int) -> Optional[float]:
+    """El precio de ese producto en ese mes, o `None` si nunca tuvo cotización.
+
+    Espera la salida de `serie_mensual()`, no la de `leer_publicaciones()`.
+    """
+    for s in serie:
+        if s["producto"] == producto and s["anio"] == anio and s["mes"] == mes:
+            return s["precio"]
+    return None
+
+
+def descargar(destino: Path, url: str = URL_CSV) -> Path:
+    """Baja el CSV del catálogo a `destino`. **Única función que sale a la red.**
+
+    Si la URL del recurso cambia, `uydatos.catalogo.recursos(DATASET)` da la vigente.
+    """
+    import urllib.request
+
+    from uydatos import USER_AGENT
+
+    destino = Path(destino)
+    destino.parent.mkdir(parents=True, exist_ok=True)
+    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+    with urllib.request.urlopen(req, timeout=90) as r:  # noqa: S310 — host fijo
+        destino.write_bytes(r.read())
+    return destino
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    ap = argparse.ArgumentParser(prog="python -m uydatos.ancap", description=__doc__.splitlines()[0])
+    sub = ap.add_subparsers(dest="orden", required=True)
+    b = sub.add_parser("bajar")
+    b.add_argument("archivo", type=Path)
+    s = sub.add_parser("serie", help="precio por mes de un producto (sin argumento: lista los productos)")
+    s.add_argument("archivo", type=Path)
+    s.add_argument("producto", nargs="?")
+    args = ap.parse_args(argv)
+
+    if args.orden == "bajar":
+        print(f"bajado {descargar(args.archivo)}")
+        return 0
+    publicaciones = leer_publicaciones(args.archivo)
+    serie = serie_mensual(publicaciones)
+    print(f"{len(publicaciones)} publicaciones, {len(serie)} meses distintos (producto x año x mes)")
+    if not args.producto:
+        for p in sorted({s["producto"] for s in serie}):
+            print(f"  {p}")
+        return 0
+    print("anio;mes;precio;unidad")
+    for s in serie:
+        if s["producto"] == args.producto:
+            print(f"{s['anio']};{s['mes']:02d};{'' if s['precio'] is None else s['precio']};{s['unidad']}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

uydatos/bcu.py

@@ -0,0 +1,233 @@
+"""Cotizaciones del Banco Central del Uruguay, desde su web service SOAP público.
+
+Monedas declaradas (códigos y nombres tal como los devuelve `awsbcumonedas`):
+
+- **2225, DLS. USA BILLETE**.
+- **9800, UNIDAD INDEXADA**: sigue al IPC de Uruguay día a día. Sirve de deflactor para comparar
+  pesos de dos fechas sin bajar el IPC del INE aparte (`a_pesos_de`).
+- **501, PESO ARG.BILLETE** y **1001, REAL BILLETE**: las monedas de las dos fronteras. Con el
+  IPC de cada país (`uydatos.indec`, `uydatos.ibge`) arman el tipo de cambio real bilateral.
+
+Las trampas, y por qué el lector las corta
+-----------------------------------------
+1. **Una respuesta mala igual se guarda.** `status 0` o `codigoerror` distinto de 0 se rechaza:
+   no es "un mes sin cotización".
+2. **Un archivo, una moneda.** La UI (~6,3) leída como dólar (~40) no da error, da un cálculo
+   absurdo. Se rechaza el archivo que trae otra moneda o dos.
+3. **Fines de semana y feriados no vienen.** `cotizacion_del_dia` devuelve `None` salvo que se
+   pida `hacia_atras=True`, y aun así no salta más de `MAX_DIAS_ATRAS` días: un hueco de un mes
+   es un archivo que falta, no un fin de semana.
+4. **El mes en curso viene parcial.** `promedio_mensual` declara los días de cada mes.
+5. **El servicio rechaza rangos largos** (`codigoerror 104`): `descargar` baja un mes por archivo.
+
+Qué cotización corresponde para un fin fiscal (la del día, la del día hábil anterior, compra o
+venta) **no lo decide este lector**. `TCC` y `TCV` vienen iguales en todo lo observado; se usa
+`TCV` y se rechaza un día donde difieran, para que nadie elija en silencio.
+
+Uso:
+    python -m uydatos.bcu bajar DIRECTORIO 9800 2024-01 2026-09
+    python -m uydatos.bcu serie DIRECTORIO 9800
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+import xml.etree.ElementTree as ET
+from collections import defaultdict
+from datetime import date, timedelta
+from pathlib import Path
+from typing import Optional, Sequence
+
+URL = "https://cotizaciones.bcu.gub.uy/wscotizaciones/servlet/awsbcucotizaciones"
+
+MONEDAS = {
+    2225: "DLS. USA BILLETE",
+    9800: "UNIDAD INDEXADA",
+    501: "PESO ARG.BILLETE",
+    1001: "REAL BILLETE",
+}
+
+MAX_DIAS_ATRAS = 7
+
+_NS = "{Cotiza}"
+
+
+class BcuInvalido(ValueError):
+    """El archivo no cumple el contrato de la fuente."""
+
+
+def _texto(nodo: ET.Element, etiqueta: str) -> str:
+    hijo = nodo.find(f"{_NS}{etiqueta}")
+    return (hijo.text or "").strip() if hijo is not None else ""
+
+
+def leer_crudo(ruta: Path, moneda: int) -> dict[date, float]:
+    """Lee una respuesta SOAP guardada y devuelve {fecha: TCV}. Rechaza en vez de arreglar."""
+    ruta = Path(ruta)
+    try:
+        raiz = ET.parse(ruta).getroot()
+    except ET.ParseError as e:
+        raise BcuInvalido(f"{ruta.name}: no es XML ({e})") from e
+
+    status = raiz.find(f".//{_NS}respuestastatus")
+    if status is None:
+        raise BcuInvalido(f"{ruta.name}: sin respuestastatus (no es una respuesta de cotizaciones)")
+    st, cod = _texto(status, "status"), _texto(status, "codigoerror")
+    if st != "1" or cod != "0":
+        raise BcuInvalido(
+            f"{ruta.name}: respuesta mala del BCU (status {st}, codigoerror {cod}: "
+            f"{_texto(status, 'mensaje')!r}). No se lee como mes sin cotización."
+        )
+
+    serie: dict[date, float] = {}
+    for dato in raiz.iter(f"{_NS}datoscotizaciones.dato"):
+        m = _texto(dato, "Moneda")
+        if m != str(moneda):
+            raise BcuInvalido(f"{ruta.name}: trae la moneda {m}, se pidió {moneda} ({MONEDAS.get(moneda, '?')})")
+        fecha = date.fromisoformat(_texto(dato, "Fecha"))
+        tcc, tcv = float(_texto(dato, "TCC")), float(_texto(dato, "TCV"))
+        if tcc != tcv:
+            raise BcuInvalido(f"{ruta.name}: {fecha} trae TCC {tcc} != TCV {tcv}. Elegir una no es tarea del lector.")
+        if fecha in serie:
+            raise BcuInvalido(f"{ruta.name}: {fecha} repetido")
+        serie[fecha] = tcv
+    if not serie:
+        raise BcuInvalido(f"{ruta.name}: respuesta buena sin datos")
+    return serie
+
+
+def leer_serie(directorio: Path, moneda: int) -> dict[date, float]:
+    """Une los archivos `<moneda>_AAAA-MM.xml` de un directorio. Un día en dos archivos es error."""
+    serie: dict[date, float] = {}
+    patron = re.compile(rf"^{moneda}_\d{{4}}-\d{{2}}\.xml$")
+    archivos = sorted(p for p in Path(directorio).iterdir() if patron.match(p.name))
+    if not archivos:
+        raise BcuInvalido(f"{directorio}: no hay archivos de la moneda {moneda}")
+    for p in archivos:
+        parte = leer_crudo(p, moneda)
+        repetidos = serie.keys() & parte.keys()
+        if repetidos:
+            raise BcuInvalido(f"{p.name}: días ya leídos en otro archivo: {sorted(repetidos)[:3]}")
+        serie.update(parte)
+    return dict(sorted(serie.items()))
+
+
+def cotizacion_del_dia(serie: dict[date, float], dia: date, hacia_atras: bool = False) -> Optional[float]:
+    """La cotización de `dia`. Sin publicación: None, o la del último día previo si se pide."""
+    if dia in serie:
+        return serie[dia]
+    if not hacia_atras:
+        return None
+    for atras in range(1, MAX_DIAS_ATRAS + 1):
+        previo = dia - timedelta(days=atras)
+        if previo in serie:
+            return serie[previo]
+    return None
+
+
+def promedio_mensual(serie: dict[date, float]) -> list[dict]:
+    """Promedio simple por mes calendario, con la cantidad de días publicados que lo forman."""
+    por_mes: dict[str, list[float]] = defaultdict(list)
+    for f, v in serie.items():
+        por_mes[f"{f.year:04d}-{f.month:02d}"].append(v)
+    return [
+        {"mes": mes, "promedio": round(sum(vs) / len(vs), 6), "dias": len(vs)} for mes, vs in sorted(por_mes.items())
+    ]
+
+
+def a_pesos_de(montos: dict[str, float], base: str, ui: dict[str, float]) -> dict[str, float]:
+    """Lleva montos mensuales ('AAAA-MM' -> pesos corrientes) a pesos del mes `base`.
+
+    `ui` es {'AAAA-MM': UI promedio del mes}, por ejemplo
+    `{f["mes"]: f["promedio"] for f in promedio_mensual(leer_serie(dir, 9800))}`.
+    Un mes sin UI **se rechaza**: dejarlo nominal mezclaría pesos de dos fechas sin avisar.
+    """
+    faltan = sorted(m for m in [*montos, base] if m not in ui)
+    if faltan:
+        raise BcuInvalido(f"sin UI para {faltan}: bajar la serie 9800 de esos meses")
+    return {m: v * ui[base] / ui[m] for m, v in montos.items()}
+
+
+def _sobre(moneda: int, desde: date, hasta: date) -> bytes:
+    return (
+        '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cot="Cotiza">'
+        "<soapenv:Header/><soapenv:Body><cot:wsbcucotizaciones.Execute><cot:Entrada>"
+        f"<cot:Moneda><cot:item>{moneda}</cot:item></cot:Moneda>"
+        f"<cot:FechaDesde>{desde.isoformat()}</cot:FechaDesde><cot:FechaHasta>{hasta.isoformat()}</cot:FechaHasta>"
+        "<cot:Grupo>0</cot:Grupo></cot:Entrada></cot:wsbcucotizaciones.Execute></soapenv:Body></soapenv:Envelope>"
+    ).encode("utf-8")
+
+
+def _meses(desde: str, hasta: str) -> list[tuple[date, date]]:
+    a, m = map(int, desde.split("-"))
+    fa, fm = map(int, hasta.split("-"))
+    out = []
+    while (a, m) <= (fa, fm):
+        ini = date(a, m, 1)
+        sig = date(a + (m == 12), m % 12 + 1, 1)
+        out.append((ini, sig - timedelta(days=1)))
+        a, m = sig.year, sig.month
+    return out
+
+
+def descargar(moneda: int, desde: str, hasta: str, destino: Path) -> list[Path]:
+    """Baja un archivo por mes (`desde` y `hasta` en 'AAAA-MM') a `destino`.
+
+    **Única función que sale a la red.** No pisa un archivo que ya existe: un mes cerrado no
+    debería cambiar, y si cambia conviene verlo comparando, no sobreescribiendo. El mes en
+    curso queda parcial: para completarlo, borrar ese archivo y volver a bajarlo.
+    """
+    import urllib.request
+
+    if moneda not in MONEDAS:
+        raise BcuInvalido(f"moneda {moneda} no declarada en MONEDAS")
+    destino = Path(destino)
+    destino.mkdir(parents=True, exist_ok=True)
+    escritos = []
+    for ini, fin in _meses(desde, hasta):
+        p = destino / f"{moneda}_{ini:%Y-%m}.xml"
+        if p.exists():
+            continue
+        pedido = urllib.request.Request(
+            URL,
+            data=_sobre(moneda, ini, fin),
+            headers={
+                "Content-Type": "text/xml; charset=utf-8",
+                "SOAPAction": "Cotizaaction/AWSBCUCOTIZACIONES.Execute",
+            },
+        )
+        with urllib.request.urlopen(pedido, timeout=60) as r:  # noqa: S310 — host fijo
+            p.write_bytes(r.read())
+        escritos.append(p)
+    return escritos
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    ap = argparse.ArgumentParser(prog="python -m uydatos.bcu", description=__doc__.splitlines()[0])
+    sub = ap.add_subparsers(dest="orden", required=True)
+    b = sub.add_parser("bajar", help="baja un archivo por mes")
+    b.add_argument("directorio", type=Path)
+    b.add_argument("moneda", type=int, choices=sorted(MONEDAS))
+    b.add_argument("desde", help="AAAA-MM")
+    b.add_argument("hasta", help="AAAA-MM")
+    s = sub.add_parser("serie", help="promedio mensual de lo bajado")
+    s.add_argument("directorio", type=Path)
+    s.add_argument("moneda", type=int, choices=sorted(MONEDAS))
+    args = ap.parse_args(argv)
+
+    if args.orden == "bajar":
+        for p in descargar(args.moneda, args.desde, args.hasta, args.directorio):
+            print(f"bajado {p.name}")
+        return 0
+    serie = leer_serie(args.directorio, args.moneda)
+    print(f"# {MONEDAS[args.moneda]} ({args.moneda}): {len(serie)} días, {min(serie)} a {max(serie)}")
+    print("mes;promedio;dias")
+    for fila in promedio_mensual(serie):
+        print(f"{fila['mes']};{fila['promedio']};{fila['dias']}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

uydatos/catalogo.py

@@ -0,0 +1,81 @@
+"""Recursos del catálogo de datos abiertos de Uruguay (catalogodatos.gub.uy, CKAN).
+
+Las URLs de descarga de un dataset cambian cuando el organismo vuelve a subir un archivo. En vez
+de fijarlas, se le pregunta al catálogo con `package_show` cuáles son las vigentes.
+
+Uso:
+    python -m uydatos.catalogo inia-precipitacion-temps-extremas-sg
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Optional, Sequence
+
+API = "https://catalogodatos.gub.uy/api/3/action/package_show"
+
+
+class CatalogoInvalido(ValueError):
+    """La respuesta del catálogo no cumple el contrato de CKAN."""
+
+
+def parsear_package_show(crudo: dict) -> list[dict]:
+    """De una respuesta de `package_show`, la lista de recursos con `nombre`, `url`, `formato`
+    y `modificado`. Rechaza una respuesta con `success` falso o sin recursos."""
+    if not crudo.get("success"):
+        raise CatalogoInvalido(f"el catálogo respondió success={crudo.get('success')!r}: {crudo.get('error')}")
+    recursos = (crudo.get("result") or {}).get("resources") or []
+    if not recursos:
+        raise CatalogoInvalido("el dataset no tiene recursos")
+    return [
+        {
+            "nombre": r.get("name") or "",
+            "url": r.get("url") or "",
+            "formato": (r.get("format") or "").upper(),
+            "modificado": r.get("last_modified") or r.get("metadata_modified") or "",
+        }
+        for r in recursos
+    ]
+
+
+def recursos(dataset: str) -> list[dict]:
+    """Los recursos vigentes de un dataset. **Sale a la red.**"""
+    import urllib.parse
+    import urllib.request
+
+    from uydatos import USER_AGENT
+
+    url = f"{API}?{urllib.parse.urlencode({'id': dataset})}"
+    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+    with urllib.request.urlopen(req, timeout=60) as r:  # noqa: S310 — host fijo
+        return parsear_package_show(json.loads(r.read().decode("utf-8")))
+
+
+def bajar_recurso(url: str, destino: Path) -> Path:
+    """Baja un recurso a `destino`. **Sale a la red.**"""
+    import urllib.request
+
+    from uydatos import USER_AGENT
+
+    destino = Path(destino)
+    destino.parent.mkdir(parents=True, exist_ok=True)
+    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+    with urllib.request.urlopen(req, timeout=90) as r:  # noqa: S310 — URL del catálogo
+        destino.write_bytes(r.read())
+    return destino
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    ap = argparse.ArgumentParser(prog="python -m uydatos.catalogo", description=__doc__.splitlines()[0])
+    ap.add_argument("dataset")
+    args = ap.parse_args(argv)
+    for r in recursos(args.dataset):
+        print(f"{r['formato']:5} {r['modificado'][:10]}  {r['nombre']}\n      {r['url']}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

uydatos/ibge.py

@@ -0,0 +1,97 @@
+"""IPCA de Brasil (IBGE), número-índice, desde la API SIDRA (tabla 1737, variable 2266).
+
+Base diciembre 1993 = 100. Sin clave.
+
+Las trampas, y por qué el lector las corta
+-----------------------------------------
+1. **La tabla 1737 trae varias variables** (variación mensual 63, acumulada en 12 meses 2265,
+   número-índice 2266...). Una variación leída como índice no da error. Se exige 2266 y la
+   unidad `Número-índice`.
+2. **El dato faltante es `...` o `-`**: un nulo, no un cero.
+3. **La primera fila es el diccionario de columnas**, no un dato.
+4. Un **índice no es una inflación**: el lector devuelve el índice.
+
+Uso:
+    python -m uydatos.ibge bajar ipca.json
+    python -m uydatos.ibge leer ipca.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Optional, Sequence
+
+from uydatos import USER_AGENT
+
+URL = "https://apisidra.ibge.gov.br/values/t/1737/n1/all/v/2266/p/all"
+VARIABLE = "2266"
+UNIDAD = "Número-índice"
+SIN_DATO = ("...", "-", "..", "X", "")
+
+
+class IpcaInvalido(ValueError):
+    """La respuesta de SIDRA no cumple el contrato de la fuente."""
+
+
+def leer(ruta: Path) -> list[dict]:
+    """[{periodo: 'AAAA-MM', valor: float}] del número-índice. Rechaza en vez de arreglar."""
+    ruta = Path(ruta)
+    try:
+        filas = json.loads(ruta.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as e:
+        raise IpcaInvalido(f"{ruta}: ilegible ({e})") from None
+    if not isinstance(filas, list) or len(filas) < 2:
+        raise IpcaInvalido(f"{ruta}: sin filas de datos (la primera es el diccionario de columnas)")
+    serie = []
+    for f in filas[1:]:
+        if f.get("D2C") != VARIABLE or f.get("MN") != UNIDAD:
+            raise IpcaInvalido(
+                f"{ruta}: fila de la variable {f.get('D2C')} ({f.get('MN')}); se exige {VARIABLE} ({UNIDAD})"
+            )
+        valor = (f.get("V") or "").strip()
+        if valor in SIN_DATO:
+            continue
+        p = f["D3C"]
+        serie.append({"periodo": f"{p[:4]}-{p[4:6]}", "valor": float(valor)})
+    if not serie:
+        raise IpcaInvalido(f"{ruta}: ninguna fila con valor")
+    return serie
+
+
+def _pedido():
+    import urllib.request
+
+    return urllib.request.Request(URL, headers={"User-Agent": USER_AGENT})
+
+
+def descargar(destino: Path) -> Path:
+    """Baja la serie completa a `destino`. **Única función que sale a la red.**"""
+    import urllib.request
+
+    destino = Path(destino)
+    destino.parent.mkdir(parents=True, exist_ok=True)
+    with urllib.request.urlopen(_pedido(), timeout=90) as r:  # noqa: S310 — host fijo
+        destino.write_bytes(r.read())
+    return destino
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    ap = argparse.ArgumentParser(prog="python -m uydatos.ibge", description=__doc__.splitlines()[0])
+    ap.add_argument("orden", choices=["bajar", "leer"])
+    ap.add_argument("archivo", type=Path)
+    args = ap.parse_args(argv)
+    if args.orden == "bajar":
+        print(f"bajado {descargar(args.archivo)}")
+        return 0
+    serie = leer(args.archivo)
+    print(f"IPCA número-índice: {len(serie)} meses, {serie[0]['periodo']} a {serie[-1]['periodo']}")
+    for s in serie[-3:]:
+        print(f"  {s['periodo']}: {s['valor']}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())