Metadata-Version: 2.4
Name: bcchapi
Version: 1.3.0
Summary: Python web service API for the Central Bank of Chile Statistical Database (adds token authentication, in addition to username/password).
Author-email: Banco Central de Chile <stat@bcentral.cl>
License: MIT
Project-URL: Homepage, https://si3.bcentral.cl/estadisticas/Principal1/Web_Services/index.htm
Project-URL: Bug Tracker, https://contactocentral.bcentral.cl/
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.3.0
Requires-Dist: requests>=2.25.0
Dynamic: license-file

# 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:

```bash
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

```bash
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

```bash
pip install pytest
```

### Paso 4 — Ejecutar las pruebas

```bash
# 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:

```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:

```bash
pip install bcchapi --force-reinstall
```

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

```bash
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](https://pypi.org)
2. Activa la autenticación de dos factores (obligatorio para publicar)

### Generar el paquete

```bash
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

```bash
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:

```ini
[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/](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**.
