bcchapi — Guía de desarrollo y pruebas

Librería Python para consumir la API REST del Banco Central de Chile (BDE).
Soporta autenticación por token (nuevo método) y por usuario/contraseña (método anterior).

---

Estructura del proyecto

bcchapi_pkg/
├── bcchapi/               # Código fuente de la librería
│   ├── __init__.py
│   ├── credentials.py
│   ├── exception.py
│   ├── siete.py
│   ├── webservice.py
│   └── wsresponse.py
├── tests/                 # Pruebas unitarias
│   ├── conftest.py
│   ├── test_credentials.py
│   ├── test_exceptions.py
│   ├── test_wsresponse.py
│   ├── test_webservice.py
│   └── test_siete.py
└── pyproject.toml

---

1. Cómo probar la librería localmente antes de publicarla

Paso 1 — Instalar en modo editable

Desde la carpeta bcchapi_pkg/, ejecuta:

pip install -e .

El flag -e (editable) hace que Python apunte directamente a tu código fuente.
Cualquier cambio que hagas en los archivos .py se refleja de inmediato sin reinstalar.

Paso 2 — Verificar la instalación

python -c "import bcchapi; print(bcchapi.__file__)"
# Debe mostrar la ruta local de tu proyecto, no una ruta de site-packages

Paso 3 — Instalar dependencias de prueba

pip install pytest

Paso 4 — Ejecutar las pruebas

# Todas las pruebas
python -m pytest tests/ -v

# Un módulo específico
python -m pytest tests/test_webservice.py -v

# Una prueba específica
python -m pytest tests/test_webservice.py::TestSessionGet::test_get_returns_gsresponse -v

Paso 5 — Probar con la API real (integración manual)

Crea un archivo credenciales.txt con tu token en la primera línea:

$2a$10$mgQJ9T0FJoOzzT.6fkB3Texr2E5TBRA...

Luego en Python:

import bcchapi

# Con token (método actual)
siete = bcchapi.Siete(token="$2a$10$mgQJ9T0FJoOzzT.6fkB...")

# Con usuario y contraseña (método anterior, también funciona)
siete = bcchapi.Siete("usuario@ejemplo.com", "contraseña")

# Desde archivo de credenciales
siete = bcchapi.Siete(file="credenciales.txt")

# Buscar series
siete.buscar("imacec")

# Obtener datos
import numpy as np
df = siete.cuadro(
    series=["F032.IMC.IND.Z.Z.EP18.Z.Z.0.M", "G073.IPC.IND.2018.M"],
    nombres=["imacec", "ipc"],
    desde="2018-01-01",
    hasta="2023-12-01",
)
print(df.tail())

---

2. Si ya tienes la librería instalada desde PyPI, ¿deja de funcionar?

No, no deja de funcionar.
Al ejecutar pip install -e . dentro de tu carpeta de desarrollo, Python reemplaza el apuntador de la librería instalada por el de tu versión local.

Para volver a la versión de PyPI en cualquier momento:

pip install bcchapi --force-reinstall

Para confirmar qué versión está activa y desde dónde se carga:

pip show bcchapi

---

3. Cómo publicar en PyPI para que otros puedan instalarla con pip install bcchapi

Registrar el paquete (solo la primera vez)

1. Crea una cuenta en https://pypi.org
2. Activa la autenticación de dos factores (obligatorio para publicar)

Generar el paquete

pip install build twine
python -m build
# Genera dist/bcchapi-1.2.0.tar.gz y dist/bcchapi-1.2.0-py3-none-any.whl

Publicar

python -m twine upload dist/*

PyPI te pedirá usuario y un API Token (no tu contraseña directamente).
Puedes guardar el token en ~/.pypirc para no tenerlo que ingresar cada vez:

[pypi]
username = __token__
password = pypi-AgEIcHlwaS5vcm...

---

4. Cómo restringir quién puede publicar la librería

PyPI usa un sistema de propietarios y mantenedores por proyecto:

• Solo la cuenta que registró el proyecto puede publicar nuevas versiones por defecto.
• Puedes agregar colaboradores de confianza desde la configuración del proyecto en PyPI → Manage → Collaborators.
• Nadie más puede subir archivos con el mismo nombre de paquete.

Para mayor seguridad:

• Usa API Tokens con alcance limitado al proyecto (no el token global de la cuenta).
• Activa Trusted Publishers (GitHub Actions) para que solo tu repositorio pueda publicar automáticamente, sin exponer tokens: https://docs.pypi.org/trusted-publishers/

---

5. Resumen del flujo de trabajo recomendado

Modificar código  →  pip install -e .  →  pytest tests/  →  bump versión  →  python -m build  →  twine upload

Paso	Comando
Instalar localmente	pip install -e .
Correr pruebas	python -m pytest tests/ -v
Empaquetar	python -m build
Publicar	python -m twine upload dist/*

---

6. Descripción de los tests

Archivo	Qué prueba
test_exceptions.py	Jerarquía de excepciones y que se lanzan correctamente
test_wsresponse.py	Conversión de respuestas JSON a pd.Series / pd.DataFrame
test_credentials.py	Lectura de credenciales desde archivo de texto
test_webservice.py	Session: inicialización, autenticación, get(), search() — con HTTP mockeado
test_siete.py	Stat.table(), Stat.browse(), Siete.cuadro(), Siete.buscar() — sin llamadas reales a la API

Las pruebas usan unittest.mock.patch para simular las llamadas HTTP, por lo que no requieren credenciales ni conexión a internet.