peruopen 0.1.0a1__tar.gz
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.
- peruopen-0.1.0a1/.claude/settings.json +6 -0
- peruopen-0.1.0a1/.github/workflows/ci.yml +24 -0
- peruopen-0.1.0a1/.github/workflows/etl.yml +53 -0
- peruopen-0.1.0a1/.github/workflows/publish.yml +53 -0
- peruopen-0.1.0a1/.github/workflows/spike_sources.yml +26 -0
- peruopen-0.1.0a1/.gitignore +24 -0
- peruopen-0.1.0a1/.python-version +1 -0
- peruopen-0.1.0a1/CLAUDE.md +78 -0
- peruopen-0.1.0a1/LICENSE +27 -0
- peruopen-0.1.0a1/PKG-INFO +126 -0
- peruopen-0.1.0a1/README.md +89 -0
- peruopen-0.1.0a1/data/registry/datasets.json +49 -0
- peruopen-0.1.0a1/docs/datasets/macro_series.md +55 -0
- peruopen-0.1.0a1/docs/datasets/macro_uit.md +41 -0
- peruopen-0.1.0a1/docs/fuentes.md +103 -0
- peruopen-0.1.0a1/docs/hosting.md +149 -0
- peruopen-0.1.0a1/docs/licencias-datos.md +22 -0
- peruopen-0.1.0a1/docs/roadmap.md +36 -0
- peruopen-0.1.0a1/pipelines/__init__.py +9 -0
- peruopen-0.1.0a1/pipelines/__main__.py +79 -0
- peruopen-0.1.0a1/pipelines/build.py +86 -0
- peruopen-0.1.0a1/pipelines/common.py +110 -0
- peruopen-0.1.0a1/pipelines/extractors/__init__.py +16 -0
- peruopen-0.1.0a1/pipelines/extractors/bcrp.py +123 -0
- peruopen-0.1.0a1/pipelines/extractors/uit.py +75 -0
- peruopen-0.1.0a1/pipelines/publish.py +227 -0
- peruopen-0.1.0a1/pipelines/registry.py +71 -0
- peruopen-0.1.0a1/pipelines/validation.py +99 -0
- peruopen-0.1.0a1/pyproject.toml +88 -0
- peruopen-0.1.0a1/spikes/probe_sources.py +238 -0
- peruopen-0.1.0a1/src/peruopen/__init__.py +109 -0
- peruopen-0.1.0a1/src/peruopen/config.py +59 -0
- peruopen-0.1.0a1/src/peruopen/data_manager.py +246 -0
- peruopen-0.1.0a1/src/peruopen/datasets/__init__.py +1 -0
- peruopen-0.1.0a1/src/peruopen/datasets/macro.py +97 -0
- peruopen-0.1.0a1/src/peruopen/engine.py +197 -0
- peruopen-0.1.0a1/src/peruopen/exceptions.py +30 -0
- peruopen-0.1.0a1/src/peruopen/mcp_server.py +72 -0
- peruopen-0.1.0a1/src/peruopen/py.typed +0 -0
- peruopen-0.1.0a1/tests/conftest.py +64 -0
- peruopen-0.1.0a1/tests/test_end_to_end.py +123 -0
- peruopen-0.1.0a1/tests/test_parsers.py +57 -0
- peruopen-0.1.0a1/tests/test_readonly.py +74 -0
- peruopen-0.1.0a1/tests/test_smoke.py +5 -0
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
pull_request:
|
|
6
|
+
|
|
7
|
+
permissions:
|
|
8
|
+
contents: read
|
|
9
|
+
|
|
10
|
+
jobs:
|
|
11
|
+
test:
|
|
12
|
+
runs-on: ubuntu-latest
|
|
13
|
+
strategy:
|
|
14
|
+
matrix:
|
|
15
|
+
python-version: ["3.11", "3.13"]
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v7
|
|
18
|
+
- uses: actions/setup-python@v7
|
|
19
|
+
with:
|
|
20
|
+
python-version: ${{ matrix.python-version }}
|
|
21
|
+
- run: pip install -e ".[pipeline,mcp]" pytest ruff
|
|
22
|
+
- run: ruff check .
|
|
23
|
+
- run: ruff format --check .
|
|
24
|
+
- run: pytest -q
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
name: Cocina — publicar datos en R2
|
|
2
|
+
|
|
3
|
+
# Extrae las fuentes oficiales, valida, construye los Parquet y los publica en
|
|
4
|
+
# Cloudflare R2. Al inicio es solo manual. Cuando esté estable, se activa el
|
|
5
|
+
# cron (descomenta `schedule`).
|
|
6
|
+
on:
|
|
7
|
+
workflow_dispatch:
|
|
8
|
+
inputs:
|
|
9
|
+
only:
|
|
10
|
+
description: "Solo estos datasets, separados por espacios (vacío = todos)"
|
|
11
|
+
required: false
|
|
12
|
+
default: ""
|
|
13
|
+
# schedule:
|
|
14
|
+
# - cron: "0 8 * * 1" # lunes 03:00 hora de Lima (08:00 UTC)
|
|
15
|
+
|
|
16
|
+
permissions:
|
|
17
|
+
contents: read
|
|
18
|
+
|
|
19
|
+
concurrency:
|
|
20
|
+
group: etl
|
|
21
|
+
cancel-in-progress: false
|
|
22
|
+
|
|
23
|
+
jobs:
|
|
24
|
+
etl:
|
|
25
|
+
runs-on: ubuntu-latest
|
|
26
|
+
timeout-minutes: 60
|
|
27
|
+
steps:
|
|
28
|
+
- uses: actions/checkout@v7
|
|
29
|
+
- uses: actions/setup-python@v7
|
|
30
|
+
with:
|
|
31
|
+
python-version: "3.11"
|
|
32
|
+
- run: pip install -e ".[pipeline]"
|
|
33
|
+
- name: Cocinar (extraer + validar + Parquet)
|
|
34
|
+
run: |
|
|
35
|
+
if [ -n "${{ inputs.only }}" ]; then
|
|
36
|
+
python -m pipelines build --only ${{ inputs.only }} || true
|
|
37
|
+
else
|
|
38
|
+
python -m pipelines build || true
|
|
39
|
+
fi
|
|
40
|
+
# Un dataset fallido no bloquea a los demás: conserva su versión anterior.
|
|
41
|
+
python -c "import json;c=json.load(open('data/normalized/catalog.json'));print('Fallidos:',c['failed'] or 'ninguno')"
|
|
42
|
+
- name: Publicar en la vitrina (R2)
|
|
43
|
+
env:
|
|
44
|
+
R2_ACCOUNT_ID: ${{ secrets.R2_ACCOUNT_ID }}
|
|
45
|
+
R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
|
|
46
|
+
R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
|
|
47
|
+
R2_BUCKET: ${{ vars.R2_BUCKET || 'peruopen-data' }}
|
|
48
|
+
run: python -m pipelines publish --target r2
|
|
49
|
+
- uses: actions/upload-artifact@v7
|
|
50
|
+
if: always()
|
|
51
|
+
with:
|
|
52
|
+
name: catalog
|
|
53
|
+
path: data/normalized/catalog.json
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
name: Publicar en PyPI
|
|
2
|
+
|
|
3
|
+
# Se dispara al subir un tag de versión (p. ej. v0.1.0a1). Usa Trusted
|
|
4
|
+
# Publishing (OIDC): no hay tokens de PyPI guardados en el repo.
|
|
5
|
+
#
|
|
6
|
+
# Configuración única en pypi.org → Account settings → Publishing → Add a new
|
|
7
|
+
# pending publisher: project "peruopen", owner "DDR2AS", repository "peruopen",
|
|
8
|
+
# workflow "publish.yml", environment "pypi".
|
|
9
|
+
on:
|
|
10
|
+
push:
|
|
11
|
+
tags: ["v*"]
|
|
12
|
+
|
|
13
|
+
permissions:
|
|
14
|
+
contents: read
|
|
15
|
+
|
|
16
|
+
jobs:
|
|
17
|
+
build:
|
|
18
|
+
runs-on: ubuntu-latest
|
|
19
|
+
steps:
|
|
20
|
+
- uses: actions/checkout@v7
|
|
21
|
+
- uses: actions/setup-python@v7
|
|
22
|
+
with:
|
|
23
|
+
python-version: "3.11"
|
|
24
|
+
- name: El tag debe coincidir con la versión de pyproject.toml
|
|
25
|
+
run: |
|
|
26
|
+
version=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
|
|
27
|
+
if [ "${GITHUB_REF_NAME}" != "v${version}" ]; then
|
|
28
|
+
echo "El tag ${GITHUB_REF_NAME} no coincide con la versión ${version} de pyproject.toml" >&2
|
|
29
|
+
exit 1
|
|
30
|
+
fi
|
|
31
|
+
- run: pip install -e ".[pipeline,mcp]" pytest build twine
|
|
32
|
+
- run: pytest -q
|
|
33
|
+
- run: python -m build
|
|
34
|
+
- run: twine check --strict dist/*
|
|
35
|
+
- uses: actions/upload-artifact@v7
|
|
36
|
+
with:
|
|
37
|
+
name: dist
|
|
38
|
+
path: dist/
|
|
39
|
+
|
|
40
|
+
pypi:
|
|
41
|
+
needs: build
|
|
42
|
+
runs-on: ubuntu-latest
|
|
43
|
+
environment:
|
|
44
|
+
name: pypi
|
|
45
|
+
url: https://pypi.org/project/peruopen/
|
|
46
|
+
permissions:
|
|
47
|
+
id-token: write # necesario para Trusted Publishing
|
|
48
|
+
steps:
|
|
49
|
+
- uses: actions/download-artifact@v8
|
|
50
|
+
with:
|
|
51
|
+
name: dist
|
|
52
|
+
path: dist/
|
|
53
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
name: Fase 0 — prueba de fuentes
|
|
2
|
+
|
|
3
|
+
# Corre spikes/probe_sources.py desde una IP de GitHub (EE.UU.) para detectar
|
|
4
|
+
# bloqueos por IP extranjera o por WAF. Solo manual.
|
|
5
|
+
on:
|
|
6
|
+
workflow_dispatch:
|
|
7
|
+
|
|
8
|
+
permissions:
|
|
9
|
+
contents: read
|
|
10
|
+
|
|
11
|
+
jobs:
|
|
12
|
+
probe:
|
|
13
|
+
runs-on: ubuntu-latest
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@v7
|
|
16
|
+
- uses: actions/setup-python@v7
|
|
17
|
+
with:
|
|
18
|
+
python-version: "3.11"
|
|
19
|
+
- run: pip install "httpx>=0.27,<1"
|
|
20
|
+
- name: Probar fuentes
|
|
21
|
+
run: python spikes/probe_sources.py --json probe_result.json | tee -a "$GITHUB_STEP_SUMMARY"
|
|
22
|
+
- uses: actions/upload-artifact@v7
|
|
23
|
+
if: always()
|
|
24
|
+
with:
|
|
25
|
+
name: probe-result
|
|
26
|
+
path: probe_result.json
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*.egg-info/
|
|
5
|
+
.venv/
|
|
6
|
+
dist/
|
|
7
|
+
build/
|
|
8
|
+
.pytest_cache/
|
|
9
|
+
.mypy_cache/
|
|
10
|
+
.ruff_cache/
|
|
11
|
+
.coverage
|
|
12
|
+
|
|
13
|
+
# Datos generados por el pipeline: se publican en R2, no se versionan en git.
|
|
14
|
+
# data/registry/ SÍ se versiona.
|
|
15
|
+
data/raw/
|
|
16
|
+
data/staging/
|
|
17
|
+
data/normalized/
|
|
18
|
+
data/vitrina/
|
|
19
|
+
spikes/out/
|
|
20
|
+
|
|
21
|
+
# Secretos y local
|
|
22
|
+
.env
|
|
23
|
+
CLAUDE.local.md
|
|
24
|
+
.claude/settings.local.json
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
3.11
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# CLAUDE.md — peruopen
|
|
2
|
+
|
|
3
|
+
> **peruopen**: librería Python que distribuye datasets públicos oficiales del
|
|
4
|
+
> Perú, curados, normalizados y validados, en Parquet. Se consultan con DuckDB
|
|
5
|
+
> y se exponen vía MCP. Pipeline: extract → build → validate → publish (R2) → catálogo.
|
|
6
|
+
|
|
7
|
+
Este archivo basta para retomar el proyecto en cualquier sesión. Empieza por
|
|
8
|
+
leer `docs/roadmap.md`, que tiene la fase actual y lo que sigue.
|
|
9
|
+
|
|
10
|
+
## La regla principal: una fuente por sesión, de punta a punta
|
|
11
|
+
|
|
12
|
+
Nunca implementes dos fuentes nuevas en la misma sesión. Nunca dejes una fuente
|
|
13
|
+
a medias: cada una se termina completa (extractor + builder + validación +
|
|
14
|
+
registro + tests + doc en `docs/datasets/`) antes de empezar la siguiente.
|
|
15
|
+
|
|
16
|
+
## Reglas duras
|
|
17
|
+
|
|
18
|
+
1. **Cero scraping al ejecutar.** La librería pública (`src/peruopen/`) nunca
|
|
19
|
+
llama a portales del Estado. Solo lee los Parquet publicados (R2) o la caché
|
|
20
|
+
local.
|
|
21
|
+
2. **Nunca fabricar datos.** Si una fuente falla, el extractor puede usar un
|
|
22
|
+
fallback mínimo para desarrollo, siempre marcado con `source_mode="fallback"`.
|
|
23
|
+
El release rechaza cualquier dataset que no esté en `source_mode="live"`.
|
|
24
|
+
3. **Los códigos son strings de ancho fijo, nunca int:** `ubigeo` (6),
|
|
25
|
+
`ruc` (11), `ciiu`. Fuerza el tipo al leer el CSV, porque Polars, DuckDB y
|
|
26
|
+
Excel pierden el cero inicial sin avisar.
|
|
27
|
+
4. **Fechas en ISO** (`date`/`YYYY-MM-DD`), y montos en `decimal` o `float64`
|
|
28
|
+
con la moneda documentada.
|
|
29
|
+
5. **Encoding:** los portales `gob.pe` suelen servir `latin-1`/`cp1252`.
|
|
30
|
+
Detéctalo y decláralo en el extractor; nunca lo supongas.
|
|
31
|
+
6. **Procedencia obligatoria.** Cada dataset lleva `source_name`, `source_url`
|
|
32
|
+
y `reuse_policy`. Nunca se quita el link a la fuente oficial.
|
|
33
|
+
7. **`data/raw/` es write-once.** Un snapshot crudo no se edita después de
|
|
34
|
+
escrito.
|
|
35
|
+
8. **La librería pública no importa del pipeline.** `src/peruopen/` nunca
|
|
36
|
+
importa de `pipelines/`, porque ahí están las dependencias pesadas detrás
|
|
37
|
+
del extra `[pipeline]`.
|
|
38
|
+
9. **Verificar el endpoint antes de implementar una fuente,** con una petición
|
|
39
|
+
real (curl o httpx), no solo con búsqueda web. Algunos portales devuelven
|
|
40
|
+
403 sin un User-Agent de navegador.
|
|
41
|
+
10. **Código propio, escrito desde cero.** No se copia código de otros
|
|
42
|
+
proyectos. Si alguna vez hiciera falta incorporar código o datos de
|
|
43
|
+
terceros, solo con licencia permisiva explícita y con su aviso de
|
|
44
|
+
copyright. Si la licencia de los datos de una fuente es ambigua, se
|
|
45
|
+
publica solo la metadata y el link.
|
|
46
|
+
11. **MCP de solo lectura.** Solo `SELECT`/`WITH`, validado con el parser de
|
|
47
|
+
DuckDB, con `enable_external_access=false` y `lock_configuration=true`
|
|
48
|
+
después de registrar las tablas, más un límite de filas y un timeout.
|
|
49
|
+
|
|
50
|
+
## Mapa (objetivo)
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
src/peruopen/ # librería pública (pip install peruopen), liviana
|
|
54
|
+
config.py # URLs de R2, caché (platformdirs), variables de entorno
|
|
55
|
+
data_manager.py # manifest + descarga por dataset, verificación SHA256
|
|
56
|
+
engine.py # DuckDB: registra vistas y ejecuta SQL seguro
|
|
57
|
+
datasets/ # helpers tipados por módulo (geo, macro, sunat, calendario)
|
|
58
|
+
mcp_server.py # FastMCP: list_datasets, describe_dataset, query
|
|
59
|
+
pipelines/ # ETL, solo en CI o local con el extra [pipeline]
|
|
60
|
+
extractors/ # uno por fuente: fetch + raw snapshot + ExtractionResult
|
|
61
|
+
builders/ # staging → Parquet final + catálogo
|
|
62
|
+
validation/ # reglas por dominio, funciones puras
|
|
63
|
+
registry/ # DatasetSpec
|
|
64
|
+
data/registry/datasets.json # fuente de verdad de los datasets, editada a mano
|
|
65
|
+
docs/ # roadmap, fuentes, hosting, licencias, datasets/{name}.md
|
|
66
|
+
spikes/ # Fase 0: scripts de prueba de fuentes (desechables)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Stack
|
|
70
|
+
|
|
71
|
+
Python ≥3.11, uv, hatchling, ruff, pytest y mypy. Base: duckdb, pyarrow,
|
|
72
|
+
httpx y platformdirs. Extras: `pipeline` (polars, tenacity…) y `mcp` (fastmcp).
|
|
73
|
+
Hosting de datos: Cloudflare R2 (ver `docs/hosting.md`).
|
|
74
|
+
|
|
75
|
+
## Referencias
|
|
76
|
+
|
|
77
|
+
Si existe `CLAUDE.local.md` (no versionado), léelo: puede apuntar a notas
|
|
78
|
+
de estudio locales. Sirven para aprender y validar, no para copiar.
|
peruopen-0.1.0a1/LICENSE
ADDED
|
@@ -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.
|
|
@@ -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,89 @@
|
|
|
1
|
+
# peruopen
|
|
2
|
+
|
|
3
|
+
**Datos públicos oficiales del Perú, curados y versionados, listos para consultar
|
|
4
|
+
con una línea de Python o SQL, y sin scraping al ejecutar.**
|
|
5
|
+
|
|
6
|
+
> 🚧 **Estado: pre-alpha.** Ya funcionan el módulo `macro` (BCRP y UIT), la
|
|
7
|
+
> librería y el servidor MCP. Todavía no hay versión en PyPI ni vitrina pública.
|
|
8
|
+
> Ver [docs/roadmap.md](https://github.com/DDR2AS/peruopen/blob/main/docs/roadmap.md).
|
|
9
|
+
|
|
10
|
+
## Qué es
|
|
11
|
+
|
|
12
|
+
peruopen reúne datasets públicos del Estado peruano (SUNAT, BCRP, INEI/RENIEC,
|
|
13
|
+
MEF, El Peruano) en archivos **Apache Parquet** normalizados y validados, con un
|
|
14
|
+
catálogo único. Se consultan con **DuckDB**, se exportan a Polars o Pandas, y se
|
|
15
|
+
exponen a agentes de IA (Claude, Cursor, etc.) mediante un servidor **MCP**.
|
|
16
|
+
|
|
17
|
+
La diferencia con un scraper: los portales del Estado cambian, se caen o bloquean
|
|
18
|
+
IPs. peruopen nunca consulta esos portales al ejecutarse. Un pipeline en CI genera
|
|
19
|
+
snapshots versionados y la librería solo lee esos snapshots, que quedan
|
|
20
|
+
cacheados en tu máquina.
|
|
21
|
+
|
|
22
|
+
## Uso
|
|
23
|
+
|
|
24
|
+
```python
|
|
25
|
+
import peruopen as po
|
|
26
|
+
|
|
27
|
+
po.list_datasets() # qué hay
|
|
28
|
+
po.macro.uit(2026) # -> 5500
|
|
29
|
+
po.macro.tipo_cambio(desde="2026-01-01").df() # pandas (o .pl() para polars)
|
|
30
|
+
|
|
31
|
+
po.query("""
|
|
32
|
+
SELECT year(fecha) AS anio, round(avg(valor), 3) AS tc_promedio
|
|
33
|
+
FROM macro_series WHERE serie = 'PD04638PD'
|
|
34
|
+
GROUP BY 1 ORDER BY 1
|
|
35
|
+
""").df()
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
La primera vez se descarga solo lo que consultas y queda en caché. Después, la
|
|
39
|
+
librería revisa como máximo una vez al día si hay datos nuevos. No hay que hacer
|
|
40
|
+
nada para actualizar.
|
|
41
|
+
|
|
42
|
+
| Necesito… | Cómo |
|
|
43
|
+
|---|---|
|
|
44
|
+
| Forzar la revisión de datos nuevos | `po.update()` |
|
|
45
|
+
| Ver qué versión tengo | `po.status()` |
|
|
46
|
+
| Trabajar sin internet | `PERUOPEN_OFFLINE=1` |
|
|
47
|
+
| Resultados reproducibles | `po.connect(snapshot="2026-11-22")` |
|
|
48
|
+
| Borrar la caché | `po.clear_cache()` |
|
|
49
|
+
|
|
50
|
+
### Para agentes de IA (MCP)
|
|
51
|
+
|
|
52
|
+
```json
|
|
53
|
+
{"mcpServers": {"peruopen": {"command": "uvx", "args": ["--from", "peruopen[mcp]", "peruopen-mcp"]}}}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Expone tres tools: `list_datasets`, `describe_dataset` y `query` (SQL de solo
|
|
57
|
+
lectura, sin acceso a otros archivos, con límite de filas y timeout).
|
|
58
|
+
|
|
59
|
+
### Desarrollo: probar en local sin la nube
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
pip install -e ".[pipeline,mcp]"
|
|
63
|
+
python -m pipelines run --target local --dir data/vitrina # cocina + vitrina local
|
|
64
|
+
PERUOPEN_BASE_URL="$PWD/data/vitrina" python -c "import peruopen as po; print(po.macro.uit())"
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Datasets planificados (v0.1)
|
|
68
|
+
|
|
69
|
+
| Módulo | Fuente | Contenido |
|
|
70
|
+
|---|---|---|
|
|
71
|
+
| `calendario` | El Peruano / gob.pe | Feriados y días no laborables, días hábiles 2020–2027 |
|
|
72
|
+
| `macro` ✅ | BCRP, SUNAT | Tipo de cambio, inflación, tasa de referencia, PBI, UIT |
|
|
73
|
+
| `geo` | INEI / RENIEC | Ubigeos con equivalencias, coordenadas y macrorregión |
|
|
74
|
+
| `sunat` | SUNAT | Padrón reducido RUC |
|
|
75
|
+
|
|
76
|
+
`estado` (MEF y SEACE/OECE) queda para v0.2.
|
|
77
|
+
|
|
78
|
+
## Proyectos relacionados
|
|
79
|
+
|
|
80
|
+
- [perudata](https://github.com/cesarchavezp29/perudata): microdatos de encuestas
|
|
81
|
+
del INEI (ENAHO, ENDES…). Complementa a peruopen.
|
|
82
|
+
- [horaciochacon/peruopen](https://github.com/horaciochacon/peruopen): paquete
|
|
83
|
+
**R** con el mismo nombre que envuelve el portal CKAN de datosabiertos.gob.pe.
|
|
84
|
+
No tiene relación con este proyecto.
|
|
85
|
+
|
|
86
|
+
## Licencia
|
|
87
|
+
|
|
88
|
+
El código es MIT (ver [LICENSE](https://github.com/DDR2AS/peruopen/blob/main/LICENSE)). Los **datos** conservan la licencia de
|
|
89
|
+
su fuente oficial.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
{
|
|
2
|
+
"macro_series": {
|
|
3
|
+
"description": "Series macroeconómicas oficiales del BCRP: tipo de cambio (interbancario y SBS), inflación (IPC Lima), tasa de referencia y PBI. Formato largo: una fila por serie y fecha.",
|
|
4
|
+
"module": "macro",
|
|
5
|
+
"extractor": "bcrp",
|
|
6
|
+
"source_name": "Banco Central de Reserva del Perú (BCRPData)",
|
|
7
|
+
"source_url": "https://estadisticas.bcrp.gob.pe/estadisticas/series/",
|
|
8
|
+
"update_frequency": "Diaria (tipo de cambio) y mensual (IPC, tasa de referencia, PBI)",
|
|
9
|
+
"primary_key": ["serie", "fecha"],
|
|
10
|
+
"min_records": 20000,
|
|
11
|
+
"columns": [
|
|
12
|
+
{"name": "serie", "type": "string", "description": "Código de la serie en BCRPData (p. ej. PD04638PD)"},
|
|
13
|
+
{"name": "nombre", "type": "string", "description": "Nombre legible de la serie"},
|
|
14
|
+
{"name": "frecuencia", "type": "string", "description": "'diaria' o 'mensual'"},
|
|
15
|
+
{"name": "unidad", "type": "string", "description": "Unidad del valor (S/ por US$, %, índice)"},
|
|
16
|
+
{"name": "fecha", "type": "date", "description": "Fecha del dato. En series mensuales es el primer día del mes"},
|
|
17
|
+
{"name": "valor", "type": "float64", "description": "Valor publicado. Los días sin dato ('n.d.') se omiten"}
|
|
18
|
+
],
|
|
19
|
+
"reuse_policy": {
|
|
20
|
+
"status": "open-attribution",
|
|
21
|
+
"license": "Condiciones de uso de BCRPData: reproducción libre citando la fuente",
|
|
22
|
+
"license_url": "https://estadisticas.bcrp.gob.pe/estadisticas/series/ayuda/condiciones-de-uso",
|
|
23
|
+
"attribution_required": true,
|
|
24
|
+
"redistribution_ok": true
|
|
25
|
+
}
|
|
26
|
+
},
|
|
27
|
+
"macro_uit": {
|
|
28
|
+
"description": "Valor histórico de la Unidad Impositiva Tributaria (UIT) por año, con el Decreto Supremo que lo fija.",
|
|
29
|
+
"module": "macro",
|
|
30
|
+
"extractor": "uit",
|
|
31
|
+
"source_name": "SUNAT (valores fijados por Decreto Supremo del MEF)",
|
|
32
|
+
"source_url": "https://www.sunat.gob.pe/indicestasas/uit.html",
|
|
33
|
+
"update_frequency": "Anual (diciembre)",
|
|
34
|
+
"primary_key": ["anio"],
|
|
35
|
+
"min_records": 25,
|
|
36
|
+
"columns": [
|
|
37
|
+
{"name": "anio", "type": "int16", "description": "Año de vigencia"},
|
|
38
|
+
{"name": "valor", "type": "int32", "description": "Valor de la UIT en soles (S/)"},
|
|
39
|
+
{"name": "base_legal", "type": "string", "description": "Decreto Supremo que fija el valor (p. ej. D.S. N° 301-2025-EF)"}
|
|
40
|
+
],
|
|
41
|
+
"reuse_policy": {
|
|
42
|
+
"status": "open-attribution",
|
|
43
|
+
"license": "Dato normativo público (Decreto Supremo)",
|
|
44
|
+
"license_url": "https://www.sunat.gob.pe/indicestasas/uit.html",
|
|
45
|
+
"attribution_required": true,
|
|
46
|
+
"redistribution_ok": true
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
}
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# `macro_series`: series macroeconómicas del BCRP
|
|
2
|
+
|
|
3
|
+
**Fuente:** Banco Central de Reserva del Perú, API pública de BCRPData
|
|
4
|
+
(`https://estadisticas.bcrp.gob.pe/estadisticas/series/api/`).
|
|
5
|
+
**Licencia:** se puede reproducir citando la fuente (condiciones de uso de BCRPData).
|
|
6
|
+
**Actualización de la fuente:** diaria (tipo de cambio) y mensual (resto).
|
|
7
|
+
**Cobertura:** desde 2000-01-01.
|
|
8
|
+
|
|
9
|
+
Formato largo: una fila por serie y fecha. Clave primaria: `(serie, fecha)`.
|
|
10
|
+
|
|
11
|
+
| Columna | Tipo | Descripción |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| `serie` | string | Código BCRPData |
|
|
14
|
+
| `nombre` | string | Nombre legible |
|
|
15
|
+
| `frecuencia` | string | `diaria` o `mensual` |
|
|
16
|
+
| `unidad` | string | `S/ por US$`, `%` o `índice` |
|
|
17
|
+
| `fecha` | date | Fecha del dato. En series mensuales, el primer día del mes |
|
|
18
|
+
| `valor` | float64 | Valor publicado. Los días sin dato (`n.d.`) se omiten |
|
|
19
|
+
|
|
20
|
+
## Series incluidas
|
|
21
|
+
|
|
22
|
+
| Código | Serie | Frecuencia |
|
|
23
|
+
|---|---|---|
|
|
24
|
+
| `PD04637PD` | Tipo de cambio interbancario, compra | diaria |
|
|
25
|
+
| `PD04638PD` | Tipo de cambio interbancario, venta | diaria |
|
|
26
|
+
| `PD04639PD` | Tipo de cambio bancario SBS, compra | diaria |
|
|
27
|
+
| `PD04640PD` | Tipo de cambio bancario SBS, venta | diaria |
|
|
28
|
+
| `PN01271PM` | IPC Lima Metropolitana, variación % mensual | mensual |
|
|
29
|
+
| `PN01273PM` | IPC Lima Metropolitana, variación % 12 meses | mensual |
|
|
30
|
+
| `PN38705PM` | IPC Lima Metropolitana, índice (dic.2021 = 100) | mensual |
|
|
31
|
+
| `PD04722MM` | Tasa de referencia de la política monetaria | mensual |
|
|
32
|
+
| `PN01770AM` | PBI, índice (2007 = 100) | mensual |
|
|
33
|
+
| `PN01728AM` | PBI, variación % interanual | mensual |
|
|
34
|
+
|
|
35
|
+
## Validaciones antes de publicar
|
|
36
|
+
|
|
37
|
+
- Están las 10 series.
|
|
38
|
+
- El último dato no tiene más de 21 días (diarias) o 200 días (mensuales).
|
|
39
|
+
- El tipo de cambio está entre 1 y 10 soles por dólar.
|
|
40
|
+
- No hay claves `(serie, fecha)` duplicadas ni vacías.
|
|
41
|
+
|
|
42
|
+
## Ejemplos
|
|
43
|
+
|
|
44
|
+
```python
|
|
45
|
+
import peruopen as po
|
|
46
|
+
|
|
47
|
+
po.macro.tipo_cambio(desde="2026-01-01").df() # interbancario venta
|
|
48
|
+
po.macro.tipo_cambio(tipo="sbs", lado="compra").pl()
|
|
49
|
+
po.macro.inflacion(periodo="12_meses", desde="2025-01-01").df()
|
|
50
|
+
po.query("""
|
|
51
|
+
SELECT year(fecha) AS anio, avg(valor) AS tc_promedio
|
|
52
|
+
FROM macro_series WHERE serie = 'PD04638PD'
|
|
53
|
+
GROUP BY 1 ORDER BY 1
|
|
54
|
+
""").df()
|
|
55
|
+
```
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# `macro_uit`: Unidad Impositiva Tributaria
|
|
2
|
+
|
|
3
|
+
**Fuente:** tabla oficial de SUNAT (`https://www.sunat.gob.pe/indicestasas/uit.html`).
|
|
4
|
+
Cada valor lo fija un Decreto Supremo del MEF.
|
|
5
|
+
**Licencia:** dato normativo público. Se cita el D.S. correspondiente.
|
|
6
|
+
**Actualización:** anual (el D.S. sale en diciembre para el año siguiente).
|
|
7
|
+
**Cobertura:** 1994 en adelante.
|
|
8
|
+
|
|
9
|
+
Clave primaria: `anio`.
|
|
10
|
+
|
|
11
|
+
| Columna | Tipo | Descripción |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| `anio` | int16 | Año de vigencia |
|
|
14
|
+
| `valor` | int32 | Valor en soles (S/) |
|
|
15
|
+
| `base_legal` | string | Decreto Supremo, p. ej. `D.S. N° 301-2025-EF` |
|
|
16
|
+
|
|
17
|
+
## Decisiones
|
|
18
|
+
|
|
19
|
+
- **Empieza en 1994.** En 1993 hubo valores por semestre fijados por R.M., y en
|
|
20
|
+
1992 regía la URT, no la UIT.
|
|
21
|
+
- **1996 tuvo dos valores** (cambió en febrero). Se usa S/ 2,200 (D.S. N°
|
|
22
|
+
012-96-EF), que estuvo vigente casi todo el año.
|
|
23
|
+
- La página de SUNAT mezcla encodings y formatos de número (`5,500` y
|
|
24
|
+
`3.100`). El extractor lee solo los dígitos.
|
|
25
|
+
|
|
26
|
+
## Validaciones antes de publicar
|
|
27
|
+
|
|
28
|
+
- Años consecutivos, sin huecos.
|
|
29
|
+
- Está el año en curso.
|
|
30
|
+
- El valor nunca baja de un año al siguiente.
|
|
31
|
+
- Valores entre S/ 1,000 y S/ 100,000.
|
|
32
|
+
|
|
33
|
+
## Ejemplos
|
|
34
|
+
|
|
35
|
+
```python
|
|
36
|
+
import peruopen as po
|
|
37
|
+
|
|
38
|
+
po.macro.uit() # año actual -> 5500
|
|
39
|
+
po.macro.uit(2020) # -> 4300
|
|
40
|
+
po.macro.uit_historica().df()
|
|
41
|
+
```
|