uydatos 0.2.1__tar.gz

uydatos-0.2.1/.gitattributes

@@ -0,0 +1,2 @@
+* text=auto eol=lf
+tests/fixtures/** -text

uydatos-0.2.1/.github/workflows/publicar.yml

@@ -0,0 +1,27 @@
+name: publicar
+
+# Se dispara al publicar una Release en GitHub. PyPI confía en este workflow
+# (trusted publishing): no hay tokens ni contraseñas guardadas en el repo.
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - name: La etiqueta coincide con la versión del paquete
+        run: |
+          version=$(grep -m1 '^version = ' pyproject.toml | cut -d'"' -f2)
+          test "v$version" = "${GITHUB_REF_NAME}" || { echo "etiqueta ${GITHUB_REF_NAME} != versión $version"; exit 1; }
+      - name: Tests
+        run: uv run --python 3.13 --with pytest --with-editable . pytest -q
+      - name: Construir
+        run: uv build && uvx twine check dist/*
+      - name: Publicar en PyPI
+        run: uv publish --trusted-publishing always

uydatos-0.2.1/.github/workflows/tests.yml

@@ -0,0 +1,42 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    # Una vez por semana contra las fuentes reales: avisa si alguna cambió de forma.
+    - cron: "0 9 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    if: github.event_name != 'schedule'
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.10", "3.11", "3.12", "3.13"]
+        include:
+          - os: windows-latest
+            python: "3.13"
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - name: Lint
+        run: uvx ruff check src tests && uvx ruff format --check src tests
+      - name: Tests sin red
+        run: uv run --python ${{ matrix.python }} --with pytest --with-editable . pytest -q
+
+  fuentes-reales:
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - name: Tests contra las fuentes reales
+        run: uv run --python 3.13 --with pytest --with-editable . pytest -q -m red

uydatos-0.2.1/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+# datos bajados: este repo publica código, no datos
+datos/
+.ruff_cache/

uydatos-0.2.1/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Cambios
+
+## 0.2.1 — 2026-10-09
+
+- Publicado en PyPI: `pip install uydatos`. Se publica solo al crear una Release en GitHub, con
+  trusted publishing (sin tokens).
+- Marcado como paquete tipado (`py.typed`), con clasificadores y palabras clave.
+- Insignias y un resumen en inglés en el README.
+
+## 0.2.0 — 2026-10-09
+
+- **Nuevo: `uydatos.ideuy`**, geocodificación de direcciones uruguayas con la API pública de IDE.uy.
+  Cada resultado lleva su calidad (`puerta_exacta`, `puerta_aproximada`, `esquina`,
+  `calle_sin_numero`) y descarta lo que la API devuelve sin haberlo encontrado:
+  - el centro de la localidad;
+  - **otra calle**: una calle inexistente devolvió "CALLE N 2570" con el mismo aviso que una
+    puerta ajustada;
+  - las respuestas de texto libre que no son una esquina.
+- Las esquinas se piden a v1 como `ESQ` (con `Y` no las reconoce) y en los dos órdenes de
+  calles, porque v1 depende del orden. Si v1 no responde, se conserva el resultado de v0.
+- CI: tests en Python 3.10 a 3.13 y Windows, y una corrida semanal contra las fuentes reales.
+
+## 0.1.0 — 2026-10-09
+
+Primera versión: BCU, ANCAP, INIA, Salto Grande, INDEC, IBGE, RUT y cédula, semanas ISO y el
+catálogo de datos abiertos de Uruguay.

uydatos-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manu Martinez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

uydatos-0.2.1/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.5
+Name: uydatos
+Version: 0.2.1
+Summary: Lectores estrictos de datos públicos de Uruguay y la región: BCU, ANCAP, INIA, Salto Grande, INDEC, IBGE, IDE.uy, RUT y cédula.
+Project-URL: Repository, https://github.com/manusabbath-arch/uy-datos-abiertos
+Project-URL: Changelog, https://github.com/manusabbath-arch/uy-datos-abiertos/blob/main/CHANGELOG.md
+Author: Manu Martinez
+License: MIT License
+        
+        Copyright (c) 2026 Manu Martinez
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: bcu,datos-abiertos,ide-uy,open-data,rut,uruguay
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: Spanish
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# uydatos
+
+[![tests](https://github.com/manusabbath-arch/uy-datos-abiertos/actions/workflows/tests.yml/badge.svg)](https://github.com/manusabbath-arch/uy-datos-abiertos/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/uydatos)](https://pypi.org/project/uydatos/)
+[![Python](https://img.shields.io/pypi/pyversions/uydatos)](https://pypi.org/project/uydatos/)
+[![Licencia: MIT](https://img.shields.io/badge/licencia-MIT-blue)](LICENSE)
+
+> **In English:** strict, dependency-free Python readers for Uruguayan and regional public data
+> (Central Bank of Uruguay exchange rates, ANCAP fuel prices, INIA weather, Salto Grande river
+> stations, Argentina's CPI, Brazil's IPCA, IDE.uy geocoding, RUT/ID check digits). Each reader
+> documents its source's traps and **raises instead of silently fixing** bad data.
+
+Lectores **estrictos** de datos públicos de Uruguay y la región, en Python puro (sin
+dependencias).
+
+La idea es una sola: **rechazar en vez de arreglar**. Cada fuente de acá tiene al menos una
+trampa que no da error y produce una serie creíble pero falsa: una respuesta de error guardada
+como si fuera un mes sin datos, columnas con los nombres invertidos, un archivo que apila
+publicaciones en vez de ser una serie, una API que sigue sirviendo índices discontinuados. Cada
+lector conoce las trampas de su fuente, las documenta y levanta una excepción con el motivo.
+
+| Módulo | Fuente | Qué trae | La trampa principal |
+|---|---|---|---|
+| `uydatos.bcu` | Banco Central del Uruguay (web service SOAP) | Dólar, Unidad Indexada, peso argentino, real | Una respuesta de error se guarda igual y parece un mes sin cotización. |
+| `uydatos.ancap` | ANCAP, catálogo de datos abiertos | Precio máximo al público de combustibles | Las columnas `Unidad` y `Valor` vienen invertidas, y el archivo apila publicaciones. |
+| `uydatos.inia` | INIA, estación Salto Grande | Lluvia y temperaturas diarias desde 1970, normales y anomalías | El día va de 9:00 a 9:00; un vacío es nulo, no cero. |
+| `uydatos.salto_grande` | Comisión Técnica Mixta de Salto Grande (SOAP) | Estaciones hidrometeorológicas de la cuenca del río Uruguay | El arreglo SOAP encoded se llama `item`: buscar `Estacion` da lista vacía sin error. |
+| `uydatos.indec` | API de series de datos.gob.ar | IPC nacional de Argentina, base dic-2016 | La API sigue sirviendo las bases 2003 y 2008, discontinuadas. |
+| `uydatos.ibge` | API SIDRA del IBGE | IPCA de Brasil, número-índice | La tabla trae varias variables; una variación leída como índice no da error. |
+| `uydatos.ideuy` | IDE.uy (direcciones.ide.uy) | Coordenadas de una dirección o esquina, con su calidad | Ante lo que no encuentra devuelve el centro de la localidad, una puerta vecina u otra calle, sin error. |
+| `uydatos.rut` | Offline | Dígito verificador de RUT y cédula | Excel convierte el RUT en float y se come el cero inicial. |
+| `uydatos.semanas` | Offline | Semanas ISO 8601 (`W41`) | El 01/01/2027 es la `2026-W53`. |
+| `uydatos.catalogo` | catalogodatos.gub.uy (CKAN) | URLs vigentes de los recursos de un dataset | Las URLs de descarga cambian cuando el organismo resube un archivo. |
+
+## Instalación
+
+```sh
+pip install uydatos
+```
+
+Requiere Python 3.10 o posterior.
+
+## Uso
+
+Cada módulo separa **bajar** (la única función que sale a internet) de **leer** (que trabaja
+sobre el archivo en disco). Así lo bajado queda guardado tal cual vino, y lo que se lee se puede
+volver a verificar.
+
+```python
+from pathlib import Path
+from uydatos import bcu
+
+bcu.descargar(9800, "2025-01", "2026-09", Path("datos/bcu"))   # un XML por mes
+ui = bcu.leer_serie(Path("datos/bcu"), 9800)                    # {date: valor}
+
+ui_mensual = {f["mes"]: f["promedio"] for f in bcu.promedio_mensual(ui)}
+bcu.a_pesos_de({"2025-01": 1000.0}, base="2026-09", ui=ui_mensual)  # pesos constantes
+```
+
+```python
+from uydatos.rut import validar_rut, validar_ci
+
+validar_rut(12345678919.0)  # ('dv_ok_estructura_rara', '012345678919'): Excel se había comido el 0
+validar_ci("1.234.567-2")    # ('valido', '12345672')
+validar_ci("1.234.567-3")    # ('dv_no_valida', '12345673')
+```
+
+Desde la línea de comandos:
+
+```sh
+python -m uydatos.bcu bajar datos/bcu 2225 2026-01 2026-09
+python -m uydatos.bcu serie datos/bcu 2225
+python -m uydatos.ancap bajar datos/ancap.csv
+python -m uydatos.ancap serie datos/ancap.csv "GASOIL 50-S *"
+python -m uydatos.inia bajar datos/inia && python -m uydatos.inia resumen datos/inia
+python -m uydatos.salto_grande bajar datos/estaciones.xml
+python -m uydatos.salto_grande cerca datos/estaciones.xml -31.383 -57.960
+python -m uydatos.indec bajar datos/ipc_ar.json
+python -m uydatos.ibge bajar datos/ipca.json
+python -m uydatos.catalogo inia-precipitacion-temps-extremas-sg
+python -m uydatos.ideuy "Avenida 18 de Julio 1360" --localidad Montevideo --departamento Montevideo
+```
+
+## Lo que estos lectores se niegan a hacer
+
+- **Rellenar huecos.** Un fin de semana sin cotización devuelve `None`, salvo que se pida
+  explícitamente el último día hábil (`hacia_atras=True`), y aun así no salta más de una semana.
+- **Convertir un índice en inflación.** Eso es una decisión de análisis, no una lectura.
+- **Inventar unidades** que la fuente no declara.
+- **Elegir por vos** qué cotización corresponde a un fin fiscal.
+
+## Tests
+
+```sh
+pip install -e ".[test]"
+pytest              # sin red: todo con archivos de prueba
+pytest -m red       # contra las fuentes reales
+```
+
+## Datos
+
+Este repositorio publica **código**, no datos. Cada fuente tiene sus propias condiciones de uso;
+los datos de los catálogos de Uruguay se publican bajo la Licencia de Datos Abiertos de Uruguay.
+
+## Licencia
+
+MIT. Usalo, adaptalo y compartilo; solo mantené el aviso de autoría.

uydatos-0.2.1/README.md

@@ -0,0 +1,107 @@
+# uydatos
+
+[![tests](https://github.com/manusabbath-arch/uy-datos-abiertos/actions/workflows/tests.yml/badge.svg)](https://github.com/manusabbath-arch/uy-datos-abiertos/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/uydatos)](https://pypi.org/project/uydatos/)
+[![Python](https://img.shields.io/pypi/pyversions/uydatos)](https://pypi.org/project/uydatos/)
+[![Licencia: MIT](https://img.shields.io/badge/licencia-MIT-blue)](LICENSE)
+
+> **In English:** strict, dependency-free Python readers for Uruguayan and regional public data
+> (Central Bank of Uruguay exchange rates, ANCAP fuel prices, INIA weather, Salto Grande river
+> stations, Argentina's CPI, Brazil's IPCA, IDE.uy geocoding, RUT/ID check digits). Each reader
+> documents its source's traps and **raises instead of silently fixing** bad data.
+
+Lectores **estrictos** de datos públicos de Uruguay y la región, en Python puro (sin
+dependencias).
+
+La idea es una sola: **rechazar en vez de arreglar**. Cada fuente de acá tiene al menos una
+trampa que no da error y produce una serie creíble pero falsa: una respuesta de error guardada
+como si fuera un mes sin datos, columnas con los nombres invertidos, un archivo que apila
+publicaciones en vez de ser una serie, una API que sigue sirviendo índices discontinuados. Cada
+lector conoce las trampas de su fuente, las documenta y levanta una excepción con el motivo.
+
+| Módulo | Fuente | Qué trae | La trampa principal |
+|---|---|---|---|
+| `uydatos.bcu` | Banco Central del Uruguay (web service SOAP) | Dólar, Unidad Indexada, peso argentino, real | Una respuesta de error se guarda igual y parece un mes sin cotización. |
+| `uydatos.ancap` | ANCAP, catálogo de datos abiertos | Precio máximo al público de combustibles | Las columnas `Unidad` y `Valor` vienen invertidas, y el archivo apila publicaciones. |
+| `uydatos.inia` | INIA, estación Salto Grande | Lluvia y temperaturas diarias desde 1970, normales y anomalías | El día va de 9:00 a 9:00; un vacío es nulo, no cero. |
+| `uydatos.salto_grande` | Comisión Técnica Mixta de Salto Grande (SOAP) | Estaciones hidrometeorológicas de la cuenca del río Uruguay | El arreglo SOAP encoded se llama `item`: buscar `Estacion` da lista vacía sin error. |
+| `uydatos.indec` | API de series de datos.gob.ar | IPC nacional de Argentina, base dic-2016 | La API sigue sirviendo las bases 2003 y 2008, discontinuadas. |
+| `uydatos.ibge` | API SIDRA del IBGE | IPCA de Brasil, número-índice | La tabla trae varias variables; una variación leída como índice no da error. |
+| `uydatos.ideuy` | IDE.uy (direcciones.ide.uy) | Coordenadas de una dirección o esquina, con su calidad | Ante lo que no encuentra devuelve el centro de la localidad, una puerta vecina u otra calle, sin error. |
+| `uydatos.rut` | Offline | Dígito verificador de RUT y cédula | Excel convierte el RUT en float y se come el cero inicial. |
+| `uydatos.semanas` | Offline | Semanas ISO 8601 (`W41`) | El 01/01/2027 es la `2026-W53`. |
+| `uydatos.catalogo` | catalogodatos.gub.uy (CKAN) | URLs vigentes de los recursos de un dataset | Las URLs de descarga cambian cuando el organismo resube un archivo. |
+
+## Instalación
+
+```sh
+pip install uydatos
+```
+
+Requiere Python 3.10 o posterior.
+
+## Uso
+
+Cada módulo separa **bajar** (la única función que sale a internet) de **leer** (que trabaja
+sobre el archivo en disco). Así lo bajado queda guardado tal cual vino, y lo que se lee se puede
+volver a verificar.
+
+```python
+from pathlib import Path
+from uydatos import bcu
+
+bcu.descargar(9800, "2025-01", "2026-09", Path("datos/bcu"))   # un XML por mes
+ui = bcu.leer_serie(Path("datos/bcu"), 9800)                    # {date: valor}
+
+ui_mensual = {f["mes"]: f["promedio"] for f in bcu.promedio_mensual(ui)}
+bcu.a_pesos_de({"2025-01": 1000.0}, base="2026-09", ui=ui_mensual)  # pesos constantes
+```
+
+```python
+from uydatos.rut import validar_rut, validar_ci
+
+validar_rut(12345678919.0)  # ('dv_ok_estructura_rara', '012345678919'): Excel se había comido el 0
+validar_ci("1.234.567-2")    # ('valido', '12345672')
+validar_ci("1.234.567-3")    # ('dv_no_valida', '12345673')
+```
+
+Desde la línea de comandos:
+
+```sh
+python -m uydatos.bcu bajar datos/bcu 2225 2026-01 2026-09
+python -m uydatos.bcu serie datos/bcu 2225
+python -m uydatos.ancap bajar datos/ancap.csv
+python -m uydatos.ancap serie datos/ancap.csv "GASOIL 50-S *"
+python -m uydatos.inia bajar datos/inia && python -m uydatos.inia resumen datos/inia
+python -m uydatos.salto_grande bajar datos/estaciones.xml
+python -m uydatos.salto_grande cerca datos/estaciones.xml -31.383 -57.960
+python -m uydatos.indec bajar datos/ipc_ar.json
+python -m uydatos.ibge bajar datos/ipca.json
+python -m uydatos.catalogo inia-precipitacion-temps-extremas-sg
+python -m uydatos.ideuy "Avenida 18 de Julio 1360" --localidad Montevideo --departamento Montevideo
+```
+
+## Lo que estos lectores se niegan a hacer
+
+- **Rellenar huecos.** Un fin de semana sin cotización devuelve `None`, salvo que se pida
+  explícitamente el último día hábil (`hacia_atras=True`), y aun así no salta más de una semana.
+- **Convertir un índice en inflación.** Eso es una decisión de análisis, no una lectura.
+- **Inventar unidades** que la fuente no declara.
+- **Elegir por vos** qué cotización corresponde a un fin fiscal.
+
+## Tests
+
+```sh
+pip install -e ".[test]"
+pytest              # sin red: todo con archivos de prueba
+pytest -m red       # contra las fuentes reales
+```
+
+## Datos
+
+Este repositorio publica **código**, no datos. Cada fuente tiene sus propias condiciones de uso;
+los datos de los catálogos de Uruguay se publican bajo la Licencia de Datos Abiertos de Uruguay.
+
+## Licencia
+
+MIT. Usalo, adaptalo y compartilo; solo mantené el aviso de autoría.

uydatos-0.2.1/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "uydatos"
+version = "0.2.1"
+description = "Lectores estrictos de datos públicos de Uruguay y la región: BCU, ANCAP, INIA, Salto Grande, INDEC, IBGE, IDE.uy, RUT y cédula."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Manu Martinez" }]
+keywords = ["uruguay", "datos-abiertos", "open-data", "bcu", "ide-uy", "rut"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: Spanish",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Typing :: Typed",
+]
+requires-python = ">=3.10"
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/uydatos"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-m 'not red'"
+markers = [
+    "red: sale a internet contra la fuente real; se corre a mano con `pytest -m red`",
+]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[project.urls]
+Repository = "https://github.com/manusabbath-arch/uy-datos-abiertos"
+Changelog = "https://github.com/manusabbath-arch/uy-datos-abiertos/blob/main/CHANGELOG.md"

uydatos-0.2.1/src/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-0.2.1/src/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())