peruopen 0.1.0a1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of peruopen might be problematic. Click here for more details.

peruopen/__init__.py ADDED
@@ -0,0 +1,109 @@
1
+ """peruopen: datos públicos oficiales del Perú, curados en Parquet.
2
+
3
+ import peruopen as po
4
+
5
+ po.query("SELECT * FROM macro_uit ORDER BY anio DESC LIMIT 5").df()
6
+ po.macro.tipo_cambio(desde="2026-01-01").pl()
7
+ po.list_datasets()
8
+
9
+ La primera vez descarga los datos que uses y los guarda en caché. Después
10
+ revisa como máximo una vez al día si hay una versión nueva.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from importlib.metadata import PackageNotFoundError
16
+ from importlib.metadata import version as _pkg_version
17
+
18
+ try:
19
+ __version__ = _pkg_version("peruopen")
20
+ except PackageNotFoundError: # ejecutando desde el código fuente sin instalar
21
+ __version__ = "0.0.0+local"
22
+
23
+ from typing import Any
24
+
25
+ import duckdb
26
+
27
+ from .engine import PeruOpen
28
+ from .exceptions import (
29
+ ConfigError,
30
+ DatasetNotFoundError,
31
+ DataUnavailableError,
32
+ IntegrityError,
33
+ PeruOpenError,
34
+ ReadOnlyQueryError,
35
+ )
36
+
37
+ _default: PeruOpen | None = None
38
+
39
+
40
+ def _po() -> PeruOpen:
41
+ global _default
42
+ if _default is None:
43
+ _default = PeruOpen()
44
+ return _default
45
+
46
+
47
+ def connect(
48
+ *,
49
+ snapshot: str | None = None,
50
+ base_url: str | None = None,
51
+ cache_dir: str | None = None,
52
+ offline: bool | None = None,
53
+ ) -> PeruOpen:
54
+ """Crea una conexión propia. Usa `snapshot=` para fijar una versión de los datos."""
55
+ return PeruOpen(snapshot=snapshot, base_url=base_url, cache_dir=cache_dir, offline=offline)
56
+
57
+
58
+ def query(sql: str, params: list[Any] | dict[str, Any] | None = None) -> duckdb.DuckDBPyRelation:
59
+ """Ejecuta SQL sobre los datasets. Devuelve una relación: .df(), .pl(), .arrow()."""
60
+ return _po().query(sql, params)
61
+
62
+
63
+ def table(name: str) -> duckdb.DuckDBPyRelation:
64
+ return _po().table(name)
65
+
66
+
67
+ def list_datasets() -> list[dict[str, Any]]:
68
+ return _po().list_datasets()
69
+
70
+
71
+ def describe(name: str) -> dict[str, Any]:
72
+ return _po().describe(name)
73
+
74
+
75
+ def update(names: list[str] | None = None) -> dict[str, str]:
76
+ """Revisa ahora si hay datos nuevos (sin esperar las 24 h) y los descarga."""
77
+ return _po().update(names)
78
+
79
+
80
+ def status() -> dict[str, Any]:
81
+ """Qué snapshot tienes y qué datasets están en caché."""
82
+ return _po().status()
83
+
84
+
85
+ def clear_cache() -> None:
86
+ _po().clear_cache()
87
+
88
+
89
+ from .datasets import macro # noqa: E402
90
+
91
+ __all__ = [
92
+ "ConfigError",
93
+ "DataUnavailableError",
94
+ "DatasetNotFoundError",
95
+ "IntegrityError",
96
+ "PeruOpen",
97
+ "PeruOpenError",
98
+ "ReadOnlyQueryError",
99
+ "__version__",
100
+ "clear_cache",
101
+ "connect",
102
+ "describe",
103
+ "list_datasets",
104
+ "macro",
105
+ "query",
106
+ "status",
107
+ "table",
108
+ "update",
109
+ ]
peruopen/config.py ADDED
@@ -0,0 +1,59 @@
1
+ """Configuración: de dónde se leen los datos y dónde se guardan.
2
+
3
+ Variables de entorno:
4
+ - PERUOPEN_BASE_URL: URL pública de la vitrina (o una carpeta local).
5
+ - PERUOPEN_CACHE_DIR: carpeta de caché (por defecto la del sistema).
6
+ - PERUOPEN_OFFLINE=1: no usar la red, solo la caché.
7
+ - PERUOPEN_CHECK_HOURS: cada cuántas horas se revisa si hay datos nuevos (24).
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import os
13
+ from dataclasses import dataclass
14
+ from datetime import timedelta
15
+ from pathlib import Path
16
+
17
+ from platformdirs import user_cache_dir
18
+
19
+ from .exceptions import ConfigError
20
+
21
+ # URL pública del bucket `peruopen-data` en Cloudflare R2 (Public Development
22
+ # URL). Cuando haya un dominio propio, se cambia aquí. PERUOPEN_BASE_URL la
23
+ # reemplaza (mirrors, vitrina local en desarrollo).
24
+ DEFAULT_BASE_URL: str | None = "https://pub-063cb658c53b44e2be385336393ba414.r2.dev"
25
+
26
+ _TRUE = {"1", "true", "yes", "si", "sí"}
27
+
28
+
29
+ @dataclass(frozen=True)
30
+ class Settings:
31
+ base_url: str
32
+ cache_dir: Path
33
+ offline: bool
34
+ check_interval: timedelta
35
+
36
+
37
+ def load_settings(
38
+ *,
39
+ base_url: str | None = None,
40
+ cache_dir: str | Path | None = None,
41
+ offline: bool | None = None,
42
+ ) -> Settings:
43
+ url = base_url or os.environ.get("PERUOPEN_BASE_URL") or DEFAULT_BASE_URL
44
+ if not url:
45
+ raise ConfigError(
46
+ "No hay una vitrina configurada. Define la variable de entorno "
47
+ "PERUOPEN_BASE_URL (URL pública de los datos o una carpeta local), "
48
+ "o pasa base_url= a peruopen.connect()."
49
+ )
50
+ cache = Path(cache_dir or os.environ.get("PERUOPEN_CACHE_DIR") or user_cache_dir("peruopen"))
51
+ if offline is None:
52
+ offline = os.environ.get("PERUOPEN_OFFLINE", "").strip().lower() in _TRUE
53
+ hours = float(os.environ.get("PERUOPEN_CHECK_HOURS", "24"))
54
+ return Settings(
55
+ base_url=url,
56
+ cache_dir=cache,
57
+ offline=offline,
58
+ check_interval=timedelta(hours=hours),
59
+ )
@@ -0,0 +1,246 @@
1
+ """Trae los datos de la vitrina a la caché local.
2
+
3
+ 1. Lee la "etiqueta" (`v1/manifest.json`), como máximo una vez cada
4
+ `check_interval` (24 h por defecto).
5
+ 2. Descarga solo los datasets que se usan y que no están ya en caché.
6
+ 3. Verifica el sha256 de cada archivo.
7
+
8
+ Los Parquet se guardan por su sha256 (`objects/<sha>.parquet`): si un dataset
9
+ no cambia entre snapshots, no se vuelve a descargar.
10
+
11
+ Sin red: usa la caché y avisa. Solo falla si nunca se descargó nada.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import difflib
17
+ import hashlib
18
+ import json
19
+ import os
20
+ import shutil
21
+ import time
22
+ import warnings
23
+ from pathlib import Path
24
+ from typing import Any
25
+
26
+ import httpx
27
+
28
+ from . import __version__
29
+ from .config import Settings
30
+ from .exceptions import DatasetNotFoundError, DataUnavailableError, IntegrityError
31
+
32
+ FORMAT_VERSION = 1
33
+ PREFIX = f"v{FORMAT_VERSION}"
34
+ USER_AGENT = f"peruopen/{__version__} (+https://github.com/DDR2AS/peruopen)"
35
+
36
+
37
+ class DataManager:
38
+ def __init__(self, settings: Settings, snapshot: str | None = None) -> None:
39
+ self.settings = settings
40
+ self.snapshot = snapshot
41
+ self.cache_dir = settings.cache_dir
42
+ self.objects_dir = self.cache_dir / "objects"
43
+ self._manifest: dict[str, Any] | None = None
44
+
45
+ # -- acceso a la vitrina (http/https o carpeta local) -------------------
46
+
47
+ def _is_http(self) -> bool:
48
+ return self.settings.base_url.startswith(("http://", "https://"))
49
+
50
+ def _local_root(self) -> Path:
51
+ base = self.settings.base_url
52
+ return Path(base[len("file://") :] if base.startswith("file://") else base)
53
+
54
+ def _url(self, key: str) -> str:
55
+ return self.settings.base_url.rstrip("/") + "/" + key
56
+
57
+ def _read(self, key: str) -> bytes:
58
+ if self._is_http():
59
+ response = httpx.get(
60
+ self._url(key),
61
+ headers={"User-Agent": USER_AGENT},
62
+ timeout=30.0,
63
+ follow_redirects=True,
64
+ )
65
+ response.raise_for_status()
66
+ return response.content
67
+ return (self._local_root() / key).read_bytes()
68
+
69
+ def _download(self, key: str, dest: Path, expected_sha: str) -> None:
70
+ dest.parent.mkdir(parents=True, exist_ok=True)
71
+ tmp = dest.with_name(dest.name + ".partial")
72
+ digest = hashlib.sha256()
73
+ try:
74
+ with tmp.open("wb") as out:
75
+ if self._is_http():
76
+ with httpx.stream(
77
+ "GET",
78
+ self._url(key),
79
+ headers={"User-Agent": USER_AGENT},
80
+ timeout=httpx.Timeout(30.0, read=300.0),
81
+ follow_redirects=True,
82
+ ) as response:
83
+ response.raise_for_status()
84
+ for chunk in response.iter_bytes(1 << 20):
85
+ digest.update(chunk)
86
+ out.write(chunk)
87
+ else:
88
+ with (self._local_root() / key).open("rb") as src:
89
+ for chunk in iter(lambda: src.read(1 << 20), b""):
90
+ digest.update(chunk)
91
+ out.write(chunk)
92
+ if digest.hexdigest() != expected_sha:
93
+ raise IntegrityError(
94
+ f"El archivo {key} no coincide con su sha256 "
95
+ f"(esperado {expected_sha[:12]}…, obtenido {digest.hexdigest()[:12]}…)"
96
+ )
97
+ os.replace(tmp, dest)
98
+ finally:
99
+ tmp.unlink(missing_ok=True)
100
+
101
+ # -- manifest -----------------------------------------------------------
102
+
103
+ def _validate_manifest(self, manifest: dict[str, Any]) -> dict[str, Any]:
104
+ if manifest.get("format_version") != FORMAT_VERSION:
105
+ raise DataUnavailableError(
106
+ f"La vitrina usa el formato {manifest.get('format_version')} y esta versión de "
107
+ f"peruopen entiende el {FORMAT_VERSION}. Actualiza: pip install -U peruopen"
108
+ )
109
+ return manifest
110
+
111
+ def _latest_manifest(self, refresh: bool) -> dict[str, Any]:
112
+ cached = self.cache_dir / "manifest.json"
113
+ checked = self.cache_dir / "manifest.checked"
114
+ age = time.time() - float(checked.read_text()) if checked.exists() else float("inf")
115
+ fresh = age < self.settings.check_interval.total_seconds()
116
+
117
+ if cached.exists() and (self.settings.offline or (fresh and not refresh)):
118
+ return json.loads(cached.read_text(encoding="utf-8")) # type: ignore[no-any-return]
119
+ if self.settings.offline:
120
+ raise DataUnavailableError(
121
+ "Modo offline (PERUOPEN_OFFLINE) y todavía no hay datos en caché. "
122
+ "Conéctate una vez para descargarlos."
123
+ )
124
+ try:
125
+ manifest = self._validate_manifest(json.loads(self._read(f"{PREFIX}/manifest.json")))
126
+ except (httpx.HTTPError, OSError, ValueError) as exc:
127
+ if cached.exists():
128
+ warnings.warn(
129
+ f"No se pudo revisar si hay datos nuevos ({exc}). "
130
+ "Se usan los datos que ya están en caché.",
131
+ stacklevel=4,
132
+ )
133
+ return json.loads(cached.read_text(encoding="utf-8")) # type: ignore[no-any-return]
134
+ raise DataUnavailableError(
135
+ f"No se pudo leer la vitrina ({self.settings.base_url}) y no hay caché: {exc}"
136
+ ) from exc
137
+ self.cache_dir.mkdir(parents=True, exist_ok=True)
138
+ tmp = cached.with_name("manifest.json.tmp")
139
+ tmp.write_text(json.dumps(manifest, ensure_ascii=False), encoding="utf-8")
140
+ os.replace(tmp, cached)
141
+ checked.write_text(str(time.time()))
142
+ return manifest
143
+
144
+ def _snapshot_manifest(self, snapshot: str) -> dict[str, Any]:
145
+ cached = self.cache_dir / "snapshots" / snapshot / "manifest.json"
146
+ if cached.exists():
147
+ return json.loads(cached.read_text(encoding="utf-8")) # type: ignore[no-any-return]
148
+ if self.settings.offline:
149
+ raise DataUnavailableError(f"Modo offline y la snapshot {snapshot} no está en caché.")
150
+ try:
151
+ raw = self._read(f"{PREFIX}/snapshots/{snapshot}/manifest.json")
152
+ except (httpx.HTTPError, OSError) as exc:
153
+ raise DataUnavailableError(
154
+ f"No existe o no se pudo leer la snapshot {snapshot!r}: {exc}"
155
+ ) from exc
156
+ manifest = self._validate_manifest(json.loads(raw))
157
+ cached.parent.mkdir(parents=True, exist_ok=True)
158
+ cached.write_text(json.dumps(manifest, ensure_ascii=False), encoding="utf-8")
159
+ return manifest
160
+
161
+ def manifest(self, *, refresh: bool = False) -> dict[str, Any]:
162
+ if self._manifest is None or refresh:
163
+ self._manifest = (
164
+ self._snapshot_manifest(self.snapshot)
165
+ if self.snapshot
166
+ else self._latest_manifest(refresh)
167
+ )
168
+ return self._manifest
169
+
170
+ # -- datasets -----------------------------------------------------------
171
+
172
+ def names(self) -> list[str]:
173
+ return sorted(self.manifest()["datasets"])
174
+
175
+ def entry(self, name: str) -> dict[str, Any]:
176
+ datasets = self.manifest()["datasets"]
177
+ if name not in datasets:
178
+ close = difflib.get_close_matches(name, datasets, n=1)
179
+ hint = f" ¿Quisiste decir {close[0]!r}?" if close else ""
180
+ raise DatasetNotFoundError(
181
+ f"No existe el dataset {name!r}.{hint} Disponibles: {', '.join(sorted(datasets))}"
182
+ )
183
+ return datasets[name] # type: ignore[no-any-return]
184
+
185
+ def object_path(self, entry: dict[str, Any]) -> Path:
186
+ return self.objects_dir / f"{entry['sha256']}.parquet"
187
+
188
+ def is_cached(self, name: str) -> bool:
189
+ return self.object_path(self.entry(name)).exists()
190
+
191
+ def ensure(self, name: str) -> Path:
192
+ """Devuelve la ruta local del Parquet, descargándolo si hace falta."""
193
+ entry = self.entry(name)
194
+ path = self.object_path(entry)
195
+ if not path.exists():
196
+ if self.settings.offline:
197
+ raise DataUnavailableError(f"Modo offline y {name!r} no está en caché.")
198
+ try:
199
+ self._download(entry["path"], path, entry["sha256"])
200
+ except (httpx.HTTPError, OSError) as exc:
201
+ raise DataUnavailableError(f"No se pudo descargar {name!r}: {exc}") from exc
202
+ self._remember(name)
203
+ return path
204
+
205
+ def _remember(self, name: str) -> None:
206
+ used_path = self.cache_dir / "used.json"
207
+ used = set(json.loads(used_path.read_text())) if used_path.exists() else set()
208
+ if name not in used:
209
+ used.add(name)
210
+ used_path.write_text(json.dumps(sorted(used)))
211
+
212
+ def used(self) -> list[str]:
213
+ used_path = self.cache_dir / "used.json"
214
+ return sorted(json.loads(used_path.read_text())) if used_path.exists() else []
215
+
216
+ def update(self, names: list[str] | None = None) -> dict[str, str]:
217
+ """Revisa la vitrina ahora y descarga lo nuevo de los datasets indicados
218
+ (por defecto, los que ya se usaron alguna vez)."""
219
+ manifest = self.manifest(refresh=True)
220
+ targets = names or [n for n in self.used() if n in manifest["datasets"]]
221
+ return {name: (self.ensure(name), self.entry(name)["snapshot"])[1] for name in targets}
222
+
223
+ def status(self) -> dict[str, Any]:
224
+ manifest = self.manifest()
225
+ return {
226
+ "base_url": self.settings.base_url,
227
+ "cache_dir": str(self.cache_dir),
228
+ "snapshot": manifest["snapshot"],
229
+ "pinned": self.snapshot is not None,
230
+ "offline": self.settings.offline,
231
+ "datasets": [
232
+ {
233
+ "dataset": name,
234
+ "snapshot": e["snapshot"],
235
+ "record_count": e["record_count"],
236
+ "retrieved_at": e["retrieved_at"],
237
+ "cached": self.object_path(e).exists(),
238
+ }
239
+ for name, e in sorted(manifest["datasets"].items())
240
+ ],
241
+ }
242
+
243
+ def clear_cache(self) -> None:
244
+ self._manifest = None
245
+ if self.cache_dir.exists():
246
+ shutil.rmtree(self.cache_dir)
@@ -0,0 +1 @@
1
+ """Atajos tipados por módulo temático."""
@@ -0,0 +1,97 @@
1
+ """Atajos para los datos macroeconómicos (BCRP y UIT).
2
+
3
+ import peruopen as po
4
+ po.macro.tipo_cambio(desde="2026-01-01").df()
5
+ po.macro.uit(2026) # -> 5500
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from datetime import date
11
+ from typing import Literal
12
+
13
+ import duckdb
14
+
15
+ from ..engine import PeruOpen
16
+
17
+ TIPO_CAMBIO = {
18
+ ("interbancario", "compra"): "PD04637PD",
19
+ ("interbancario", "venta"): "PD04638PD",
20
+ ("sbs", "compra"): "PD04639PD",
21
+ ("sbs", "venta"): "PD04640PD",
22
+ }
23
+ INFLACION_MENSUAL = "PN01271PM"
24
+ INFLACION_12_MESES = "PN01273PM"
25
+ TASA_REFERENCIA = "PD04722MM"
26
+ PBI_VARIACION = "PN01728AM"
27
+
28
+
29
+ def _conn(po: PeruOpen | None) -> PeruOpen:
30
+ if po is not None:
31
+ return po
32
+ from .. import _po
33
+
34
+ return _po()
35
+
36
+
37
+ def serie(
38
+ codigo: str,
39
+ desde: str | date | None = None,
40
+ hasta: str | date | None = None,
41
+ *,
42
+ po: PeruOpen | None = None,
43
+ ) -> duckdb.DuckDBPyRelation:
44
+ """Una serie del BCRP por código, con columnas fecha y valor."""
45
+ sql = "SELECT fecha, valor FROM macro_series WHERE serie = ?"
46
+ params: list[object] = [codigo]
47
+ if desde is not None:
48
+ sql += " AND fecha >= CAST(? AS DATE)"
49
+ params.append(str(desde))
50
+ if hasta is not None:
51
+ sql += " AND fecha <= CAST(? AS DATE)"
52
+ params.append(str(hasta))
53
+ return _conn(po).query(sql + " ORDER BY fecha", params)
54
+
55
+
56
+ def tipo_cambio(
57
+ desde: str | date | None = None,
58
+ hasta: str | date | None = None,
59
+ *,
60
+ tipo: Literal["interbancario", "sbs"] = "interbancario",
61
+ lado: Literal["compra", "venta"] = "venta",
62
+ po: PeruOpen | None = None,
63
+ ) -> duckdb.DuckDBPyRelation:
64
+ """Tipo de cambio diario S/ por US$ (BCRP)."""
65
+ try:
66
+ codigo = TIPO_CAMBIO[(tipo, lado)]
67
+ except KeyError:
68
+ raise ValueError(
69
+ "tipo debe ser 'interbancario' o 'sbs', y lado 'compra' o 'venta'"
70
+ ) from None
71
+ return serie(codigo, desde, hasta, po=po)
72
+
73
+
74
+ def inflacion(
75
+ desde: str | date | None = None,
76
+ hasta: str | date | None = None,
77
+ *,
78
+ periodo: Literal["mensual", "12_meses"] = "12_meses",
79
+ po: PeruOpen | None = None,
80
+ ) -> duckdb.DuckDBPyRelation:
81
+ """Inflación de Lima Metropolitana en % (IPC, BCRP)."""
82
+ codigo = INFLACION_MENSUAL if periodo == "mensual" else INFLACION_12_MESES
83
+ return serie(codigo, desde, hasta, po=po)
84
+
85
+
86
+ def uit(anio: int | None = None, *, po: PeruOpen | None = None) -> int:
87
+ """Valor de la UIT en soles para un año (por defecto, el actual)."""
88
+ year = anio or date.today().year
89
+ row = _conn(po).query("SELECT valor FROM macro_uit WHERE anio = ?", [year]).fetchone()
90
+ if row is None:
91
+ raise LookupError(f"No hay valor de UIT para {year}")
92
+ return int(row[0])
93
+
94
+
95
+ def uit_historica(*, po: PeruOpen | None = None) -> duckdb.DuckDBPyRelation:
96
+ """Tabla completa de la UIT: anio, valor, base_legal."""
97
+ return _conn(po).query("SELECT * FROM macro_uit ORDER BY anio")
peruopen/engine.py ADDED
@@ -0,0 +1,197 @@
1
+ """Motor de consultas: DuckDB sobre los Parquet de la caché.
2
+
3
+ Cada dataset aparece como una tabla (vista) con su nombre. Antes de ejecutar
4
+ un SQL se detecta qué datasets menciona y solo esos se descargan.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import re
10
+ import threading
11
+ from datetime import date, datetime, time
12
+ from decimal import Decimal
13
+ from pathlib import Path
14
+ from typing import Any
15
+
16
+ import duckdb
17
+
18
+ from .config import load_settings
19
+ from .data_manager import DataManager
20
+ from .exceptions import ReadOnlyQueryError
21
+
22
+ _IDENTIFIER = re.compile(r"^[a-z][a-z0-9_]*$")
23
+ MAX_SQL_LENGTH = 10_000
24
+ DEFAULT_LIMIT = 100
25
+ MAX_LIMIT = 1_000
26
+ DEFAULT_TIMEOUT_S = 30.0
27
+
28
+
29
+ def _view_sql(name: str, path: Path) -> str:
30
+ if not _IDENTIFIER.match(name):
31
+ raise ValueError(f"Nombre de dataset inválido: {name!r}")
32
+ literal = path.as_posix().replace("'", "''")
33
+ return f"CREATE OR REPLACE VIEW {name} AS SELECT * FROM read_parquet('{literal}')"
34
+
35
+
36
+ class PeruOpen:
37
+ """Conexión a los datos de peruopen.
38
+
39
+ po = PeruOpen() # última snapshot
40
+ po = PeruOpen(snapshot="2026-11-22") # fija una versión (reproducible)
41
+ po.query("SELECT * FROM macro_uit").df()
42
+ """
43
+
44
+ def __init__(
45
+ self,
46
+ *,
47
+ snapshot: str | None = None,
48
+ base_url: str | None = None,
49
+ cache_dir: str | Path | None = None,
50
+ offline: bool | None = None,
51
+ ) -> None:
52
+ self.settings = load_settings(base_url=base_url, cache_dir=cache_dir, offline=offline)
53
+ self.data = DataManager(self.settings, snapshot=snapshot)
54
+ self.con = duckdb.connect()
55
+ self._views: dict[str, Path] = {}
56
+
57
+ # -- catálogo -----------------------------------------------------------
58
+
59
+ def list_datasets(self) -> list[dict[str, Any]]:
60
+ manifest = self.data.manifest()
61
+ return [
62
+ {
63
+ "dataset": name,
64
+ "description": e["description"],
65
+ "record_count": e["record_count"],
66
+ "source_name": e["source_name"],
67
+ "retrieved_at": e["retrieved_at"],
68
+ "license": e["reuse_policy"].get("license"),
69
+ }
70
+ for name, e in sorted(manifest["datasets"].items())
71
+ ]
72
+
73
+ def describe(self, name: str) -> dict[str, Any]:
74
+ entry = self.data.entry(name)
75
+ keep = (
76
+ "description", "module", "columns", "primary_key", "record_count", "source_name",
77
+ "source_url", "retrieved_at", "update_frequency", "reuse_policy", "snapshot",
78
+ ) # fmt: skip
79
+ return {"dataset": name, **{k: entry.get(k) for k in keep}}
80
+
81
+ def referenced(self, sql: str) -> list[str]:
82
+ """Datasets que el SQL menciona (por nombre exacto de tabla)."""
83
+ return [
84
+ name
85
+ for name in self.data.names()
86
+ if re.search(rf"(?<![\w.]){re.escape(name)}(?!\w)", sql, flags=re.IGNORECASE)
87
+ ]
88
+
89
+ # -- consultas ----------------------------------------------------------
90
+
91
+ def _register(self, names: list[str]) -> None:
92
+ for name in names:
93
+ path = self.data.ensure(name)
94
+ if self._views.get(name) != path:
95
+ self.con.execute(_view_sql(name, path))
96
+ self._views[name] = path
97
+
98
+ def query(
99
+ self, sql: str, params: list[Any] | dict[str, Any] | None = None
100
+ ) -> duckdb.DuckDBPyRelation:
101
+ """Ejecuta SQL. Devuelve una relación de DuckDB: .df(), .pl(), .arrow() o .fetchall()."""
102
+ self._register(self.referenced(sql))
103
+ return self.con.sql(sql, params=params)
104
+
105
+ def table(self, name: str) -> duckdb.DuckDBPyRelation:
106
+ self.data.entry(name) # error claro si no existe
107
+ self._register([name])
108
+ return self.con.table(name)
109
+
110
+ def query_readonly(
111
+ self,
112
+ sql: str,
113
+ *,
114
+ limit: int = DEFAULT_LIMIT,
115
+ timeout_s: float = DEFAULT_TIMEOUT_S,
116
+ ) -> dict[str, Any]:
117
+ """Consulta para agentes (MCP): solo un SELECT, sin acceso a archivos
118
+ fuera de la caché, con límite de filas y timeout."""
119
+ cleaned = sql.strip().rstrip(";").strip()
120
+ if not cleaned:
121
+ raise ReadOnlyQueryError("La consulta está vacía.")
122
+ if len(cleaned) > MAX_SQL_LENGTH:
123
+ raise ReadOnlyQueryError(f"La consulta supera {MAX_SQL_LENGTH} caracteres.")
124
+ try:
125
+ statements = duckdb.extract_statements(cleaned)
126
+ except duckdb.Error as exc:
127
+ raise ReadOnlyQueryError(f"SQL inválido: {exc}") from exc
128
+ if len(statements) != 1:
129
+ raise ReadOnlyQueryError("Solo se permite una sentencia por consulta.")
130
+ if statements[0].type != duckdb.StatementType.SELECT:
131
+ raise ReadOnlyQueryError(
132
+ f"Solo se permiten consultas SELECT (recibido: {statements[0].type.name})."
133
+ )
134
+ limit = max(1, min(int(limit), MAX_LIMIT))
135
+
136
+ names = self.referenced(cleaned)
137
+ paths = {name: self.data.ensure(name) for name in names}
138
+ con = duckdb.connect()
139
+ try:
140
+ for name, path in paths.items():
141
+ con.execute(_view_sql(name, path))
142
+ allowed = self.data.objects_dir.as_posix().rstrip("/") + "/"
143
+ con.execute(f"SET allowed_directories=['{allowed.replace(chr(39), chr(39) * 2)}']")
144
+ con.execute("SET enable_external_access=false")
145
+ con.execute("SET lock_configuration=true")
146
+ timer = threading.Timer(timeout_s, con.interrupt)
147
+ timer.start()
148
+ try:
149
+ relation = con.sql(f"SELECT * FROM ({cleaned}) AS q LIMIT {limit + 1}")
150
+ columns = list(relation.columns)
151
+ rows = relation.fetchall()
152
+ except duckdb.InterruptException as exc:
153
+ raise ReadOnlyQueryError(
154
+ f"La consulta superó el límite de {timeout_s:.0f} s."
155
+ ) from exc
156
+ except duckdb.Error as exc:
157
+ raise ReadOnlyQueryError(str(exc)) from exc
158
+ finally:
159
+ timer.cancel()
160
+ finally:
161
+ con.close()
162
+
163
+ truncated = len(rows) > limit
164
+ rows = rows[:limit]
165
+ return {
166
+ "columns": columns,
167
+ "rows": [{c: _jsonable(v) for c, v in zip(columns, row, strict=True)} for row in rows],
168
+ "row_count": len(rows),
169
+ "truncated": truncated,
170
+ "datasets": {n: self.data.entry(n)["snapshot"] for n in names},
171
+ }
172
+
173
+ # -- mantenimiento ------------------------------------------------------
174
+
175
+ def update(self, names: list[str] | None = None) -> dict[str, str]:
176
+ result = self.data.update(names)
177
+ self._views.clear()
178
+ return result
179
+
180
+ def status(self) -> dict[str, Any]:
181
+ return self.data.status()
182
+
183
+ def clear_cache(self) -> None:
184
+ self.con.close()
185
+ self.data.clear_cache()
186
+ self.con = duckdb.connect()
187
+ self._views.clear()
188
+
189
+
190
+ def _jsonable(value: Any) -> Any:
191
+ if isinstance(value, datetime | date | time):
192
+ return value.isoformat()
193
+ if isinstance(value, Decimal):
194
+ return float(value)
195
+ if isinstance(value, bytes):
196
+ return value.hex()
197
+ return value
peruopen/exceptions.py ADDED
@@ -0,0 +1,30 @@
1
+ """Errores de peruopen. Todos heredan de `PeruOpenError`."""
2
+
3
+ from __future__ import annotations
4
+
5
+
6
+ class PeruOpenError(Exception):
7
+ """Base de todos los errores de peruopen."""
8
+
9
+
10
+ class ConfigError(PeruOpenError):
11
+ """Falta configuración (p. ej. la URL de la vitrina)."""
12
+
13
+
14
+ class DataUnavailableError(PeruOpenError):
15
+ """No se pudo obtener el dato: sin red y sin caché, o la vitrina no responde."""
16
+
17
+
18
+ class DatasetNotFoundError(PeruOpenError, KeyError):
19
+ """El dataset pedido no existe en el manifest."""
20
+
21
+ def __str__(self) -> str: # KeyError pone comillas al mensaje
22
+ return str(self.args[0]) if self.args else ""
23
+
24
+
25
+ class IntegrityError(PeruOpenError):
26
+ """El archivo descargado no coincide con el sha256 del manifest."""
27
+
28
+
29
+ class ReadOnlyQueryError(PeruOpenError, ValueError):
30
+ """La consulta no está permitida en modo solo lectura (MCP)."""
peruopen/mcp_server.py ADDED
@@ -0,0 +1,72 @@
1
+ """Servidor MCP: expone los datos de peruopen a agentes de IA (Claude, Cursor…).
2
+
3
+ Tres tools, a propósito pocas, porque un agente ya sabe escribir SQL:
4
+ - list_datasets(): qué datasets hay.
5
+ - describe_dataset(dataset): columnas, fuente, licencia y fecha del dato.
6
+ - query(sql, limit): SQL de solo lectura (ver PeruOpen.query_readonly).
7
+
8
+ Configuración en Claude Desktop / Claude Code:
9
+
10
+ {"mcpServers": {"peruopen": {
11
+ "command": "uvx", "args": ["--from", "peruopen[mcp]", "peruopen-mcp"]}}}
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ from collections.abc import Callable
17
+ from typing import Any
18
+
19
+ from .engine import DEFAULT_LIMIT, MAX_LIMIT, PeruOpen
20
+ from .exceptions import PeruOpenError
21
+
22
+ INSTRUCTIONS = """\
23
+ Datos públicos oficiales del Perú (BCRP, SUNAT, INEI…), curados y versionados.
24
+ Flujo recomendado: list_datasets → describe_dataset → query.
25
+ Cada dataset es una tabla con su mismo nombre. Solo se permiten SELECT.
26
+ Cita siempre la fuente (source_name) y la fecha del dato (retrieved_at) al responder.
27
+ """
28
+
29
+
30
+ def build_server(po: PeruOpen | None = None) -> Any:
31
+ try:
32
+ from fastmcp import FastMCP
33
+ from fastmcp.exceptions import ToolError
34
+ except ImportError as exc: # pragma: no cover
35
+ raise SystemExit('El servidor MCP necesita el extra: pip install "peruopen[mcp]"') from exc
36
+
37
+ conn = po or PeruOpen()
38
+ mcp = FastMCP("peruopen", instructions=INSTRUCTIONS)
39
+
40
+ def _call(fn: Callable[[], Any]) -> Any:
41
+ # Los errores esperados (SQL rechazado, dataset inexistente…) vuelven al
42
+ # agente como un mensaje claro, sin traceback.
43
+ try:
44
+ return fn()
45
+ except PeruOpenError as exc:
46
+ raise ToolError(str(exc)) from exc
47
+
48
+ @mcp.tool
49
+ def list_datasets() -> list[dict[str, Any]]:
50
+ """Lista los datasets disponibles con su descripción, fuente y fecha."""
51
+ return _call(conn.list_datasets) # type: ignore[no-any-return]
52
+
53
+ @mcp.tool
54
+ def describe_dataset(dataset: str) -> dict[str, Any]:
55
+ """Columnas (con descripción), clave primaria, fuente oficial, licencia y fecha del dato."""
56
+ return _call(lambda: conn.describe(dataset)) # type: ignore[no-any-return]
57
+
58
+ @mcp.tool
59
+ def query(sql: str, limit: int = DEFAULT_LIMIT) -> dict[str, Any]:
60
+ """Ejecuta un SELECT (DuckDB SQL) sobre los datasets. Las tablas se llaman igual que
61
+ los datasets. Devuelve como máximo `limit` filas (tope 1000)."""
62
+ return _call(lambda: conn.query_readonly(sql, limit=min(limit, MAX_LIMIT))) # type: ignore[no-any-return]
63
+
64
+ return mcp
65
+
66
+
67
+ def main() -> None:
68
+ build_server().run()
69
+
70
+
71
+ if __name__ == "__main__":
72
+ main()
peruopen/py.typed ADDED
File without changes
@@ -0,0 +1,126 @@
1
+ Metadata-Version: 2.5
2
+ Name: peruopen
3
+ Version: 0.1.0a1
4
+ Summary: Datos públicos oficiales del Perú (SUNAT, BCRP, INEI, MEF), curados en Parquet y consultables con DuckDB y MCP.
5
+ Project-URL: Homepage, https://github.com/DDR2AS/peruopen
6
+ Project-URL: Repository, https://github.com/DDR2AS/peruopen
7
+ Project-URL: Issues, https://github.com/DDR2AS/peruopen/issues
8
+ Project-URL: Documentation, https://github.com/DDR2AS/peruopen/tree/main/docs
9
+ Author: Diego Avila
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: bcrp,datos-abiertos,duckdb,mcp,open-data,parquet,peru,sunat,ubigeo
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Intended Audience :: Science/Research
16
+ Classifier: Natural Language :: Spanish
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Topic :: Scientific/Engineering :: Information Analysis
23
+ Requires-Python: >=3.11
24
+ Requires-Dist: duckdb<2,>=1.1
25
+ Requires-Dist: httpx<1,>=0.27
26
+ Requires-Dist: platformdirs<5,>=4.3
27
+ Requires-Dist: pyarrow>=17
28
+ Provides-Extra: mcp
29
+ Requires-Dist: fastmcp<3,>=2.3; extra == 'mcp'
30
+ Provides-Extra: pandas
31
+ Requires-Dist: pandas<3,>=2.2; extra == 'pandas'
32
+ Provides-Extra: pipeline
33
+ Requires-Dist: boto3<2,>=1.34; extra == 'pipeline'
34
+ Provides-Extra: polars
35
+ Requires-Dist: polars<2,>=1.9; extra == 'polars'
36
+ Description-Content-Type: text/markdown
37
+
38
+ # peruopen
39
+
40
+ **Datos públicos oficiales del Perú, curados y versionados, listos para consultar
41
+ con una línea de Python o SQL, y sin scraping al ejecutar.**
42
+
43
+ > 🚧 **Estado: pre-alpha.** Ya funcionan el módulo `macro` (BCRP y UIT), la
44
+ > librería y el servidor MCP. Todavía no hay versión en PyPI ni vitrina pública.
45
+ > Ver [docs/roadmap.md](https://github.com/DDR2AS/peruopen/blob/main/docs/roadmap.md).
46
+
47
+ ## Qué es
48
+
49
+ peruopen reúne datasets públicos del Estado peruano (SUNAT, BCRP, INEI/RENIEC,
50
+ MEF, El Peruano) en archivos **Apache Parquet** normalizados y validados, con un
51
+ catálogo único. Se consultan con **DuckDB**, se exportan a Polars o Pandas, y se
52
+ exponen a agentes de IA (Claude, Cursor, etc.) mediante un servidor **MCP**.
53
+
54
+ La diferencia con un scraper: los portales del Estado cambian, se caen o bloquean
55
+ IPs. peruopen nunca consulta esos portales al ejecutarse. Un pipeline en CI genera
56
+ snapshots versionados y la librería solo lee esos snapshots, que quedan
57
+ cacheados en tu máquina.
58
+
59
+ ## Uso
60
+
61
+ ```python
62
+ import peruopen as po
63
+
64
+ po.list_datasets() # qué hay
65
+ po.macro.uit(2026) # -> 5500
66
+ po.macro.tipo_cambio(desde="2026-01-01").df() # pandas (o .pl() para polars)
67
+
68
+ po.query("""
69
+ SELECT year(fecha) AS anio, round(avg(valor), 3) AS tc_promedio
70
+ FROM macro_series WHERE serie = 'PD04638PD'
71
+ GROUP BY 1 ORDER BY 1
72
+ """).df()
73
+ ```
74
+
75
+ La primera vez se descarga solo lo que consultas y queda en caché. Después, la
76
+ librería revisa como máximo una vez al día si hay datos nuevos. No hay que hacer
77
+ nada para actualizar.
78
+
79
+ | Necesito… | Cómo |
80
+ |---|---|
81
+ | Forzar la revisión de datos nuevos | `po.update()` |
82
+ | Ver qué versión tengo | `po.status()` |
83
+ | Trabajar sin internet | `PERUOPEN_OFFLINE=1` |
84
+ | Resultados reproducibles | `po.connect(snapshot="2026-11-22")` |
85
+ | Borrar la caché | `po.clear_cache()` |
86
+
87
+ ### Para agentes de IA (MCP)
88
+
89
+ ```json
90
+ {"mcpServers": {"peruopen": {"command": "uvx", "args": ["--from", "peruopen[mcp]", "peruopen-mcp"]}}}
91
+ ```
92
+
93
+ Expone tres tools: `list_datasets`, `describe_dataset` y `query` (SQL de solo
94
+ lectura, sin acceso a otros archivos, con límite de filas y timeout).
95
+
96
+ ### Desarrollo: probar en local sin la nube
97
+
98
+ ```bash
99
+ pip install -e ".[pipeline,mcp]"
100
+ python -m pipelines run --target local --dir data/vitrina # cocina + vitrina local
101
+ PERUOPEN_BASE_URL="$PWD/data/vitrina" python -c "import peruopen as po; print(po.macro.uit())"
102
+ ```
103
+
104
+ ## Datasets planificados (v0.1)
105
+
106
+ | Módulo | Fuente | Contenido |
107
+ |---|---|---|
108
+ | `calendario` | El Peruano / gob.pe | Feriados y días no laborables, días hábiles 2020–2027 |
109
+ | `macro` ✅ | BCRP, SUNAT | Tipo de cambio, inflación, tasa de referencia, PBI, UIT |
110
+ | `geo` | INEI / RENIEC | Ubigeos con equivalencias, coordenadas y macrorregión |
111
+ | `sunat` | SUNAT | Padrón reducido RUC |
112
+
113
+ `estado` (MEF y SEACE/OECE) queda para v0.2.
114
+
115
+ ## Proyectos relacionados
116
+
117
+ - [perudata](https://github.com/cesarchavezp29/perudata): microdatos de encuestas
118
+ del INEI (ENAHO, ENDES…). Complementa a peruopen.
119
+ - [horaciochacon/peruopen](https://github.com/horaciochacon/peruopen): paquete
120
+ **R** con el mismo nombre que envuelve el portal CKAN de datosabiertos.gob.pe.
121
+ No tiene relación con este proyecto.
122
+
123
+ ## Licencia
124
+
125
+ El código es MIT (ver [LICENSE](https://github.com/DDR2AS/peruopen/blob/main/LICENSE)). Los **datos** conservan la licencia de
126
+ su fuente oficial.
@@ -0,0 +1,14 @@
1
+ peruopen/__init__.py,sha256=adhbt5zrYaLVTx1_W9BvZVcfgRhUeqdgTiDMx6lMYgw,2626
2
+ peruopen/config.py,sha256=-CSQe2-0PRSqbWaq-lSx468Bg5kaxOUvFcXrFM-1B5g,1957
3
+ peruopen/data_manager.py,sha256=I3dqi9iCdQ0eIcl--1T0BJC52sNUYNO09UAZcQbnrq8,10310
4
+ peruopen/engine.py,sha256=BSM2gESF3GhIk2hzsjf48o1lNe6dak5qzBE6DHilSgs,7224
5
+ peruopen/exceptions.py,sha256=cq1lYj0ONZ043IcSYFicm_qPz5y_007EV8EeXVvvl64,875
6
+ peruopen/mcp_server.py,sha256=zFuv-GL0D6sZDLTyhvwM7G3x8gnJhSi1jyjFReKTrPY,2669
7
+ peruopen/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
8
+ peruopen/datasets/__init__.py,sha256=xE_MLgNYLvl8WPBMSJ5K9PDJVNFH-xtodYcVUf6TsAQ,44
9
+ peruopen/datasets/macro.py,sha256=CHVZETEGfz_5La4QOCQ1nU-GrN0YBRfuqGqgGGTuTiQ,2915
10
+ peruopen-0.1.0a1.dist-info/METADATA,sha256=QRHeqBehYRf68K32Zc5iMZy3-aY3kBMQlXYQ1Kau14w,4923
11
+ peruopen-0.1.0a1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
12
+ peruopen-0.1.0a1.dist-info/entry_points.txt,sha256=cPGpYlOeTc0DComhjDlWhEqoo7f0c3zy5DI5h2Hcce4,58
13
+ peruopen-0.1.0a1.dist-info/licenses/LICENSE,sha256=PRwSX8x_k3cHZyx2dh6wYd1dDyfU53SN6J9e-KhYpcc,1304
14
+ peruopen-0.1.0a1.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ peruopen-mcp = peruopen.mcp_server:main
@@ -0,0 +1,27 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Diego Avila
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
23
+ ---
24
+
25
+ Los DATOS distribuidos por peruopen (archivos Parquet publicados) NO están
26
+ cubiertos por esta licencia: cada dataset conserva la licencia de su fuente
27
+ oficial. Ver docs/licencias-datos.md y el campo `reuse_policy` del catálogo.