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 +109 -0
- peruopen/config.py +59 -0
- peruopen/data_manager.py +246 -0
- peruopen/datasets/__init__.py +1 -0
- peruopen/datasets/macro.py +97 -0
- peruopen/engine.py +197 -0
- peruopen/exceptions.py +30 -0
- peruopen/mcp_server.py +72 -0
- peruopen/py.typed +0 -0
- peruopen-0.1.0a1.dist-info/METADATA +126 -0
- peruopen-0.1.0a1.dist-info/RECORD +14 -0
- peruopen-0.1.0a1.dist-info/WHEEL +4 -0
- peruopen-0.1.0a1.dist-info/entry_points.txt +2 -0
- peruopen-0.1.0a1.dist-info/licenses/LICENSE +27 -0
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
|
+
)
|
peruopen/data_manager.py
ADDED
|
@@ -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,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.
|