Arquitectura y Diseño¶

Esta sección describe la organización del código, decisiones de diseño y patrones usados en la reimplementación.

Principales paquetes en src/¶

• clients/: clientes HTTP sync y async, con gestión de Timeout y RetryTransport.
• builders/: funciones puras que construyen parámetros, normalizan fechas y series.
• mappers/: transformaciones específicas de credenciales y modelos a DataFrames.
• models/: modelos Pydantic que describen respuestas y sub-objetos con nombres idiomáticos.
• sdk/: capa pública (convenience) que utiliza clientes, builders y concurrency helpers para ofrecer una API simple.

Diseño de transportabilidad¶

• Separación de responsabilidades: los clientes gestionan el transporte y validan las respuestas directamente con modelos Pydantic; los mappers y builders realizan las demás transformaciones.
• Uso de httpx para permitir sync y async con paridad de comportamientos.

Logging y Telemetría¶

• Cada módulo define logger = logging.getLogger(__name__) y emite debug/info/warning/error apropiadamente.
• No hay handlers globales en la biblioteca — el consumidor configura logging.
• El SDK nunca registra los parámetros HTTP porque contienen credenciales. La API del Banco Central exige credenciales en la query string y HTTPX registra URLs completas en nivel INFO; en producción configure el logger httpx en WARNING o superior para impedir que esos secretos lleguen a los logs.

Timeout y reintentos¶

• BCChConfig y BaseClient exponen Timeout y Retry configurables.
• Valores por defecto: timeout 10s y retry total 3 con backoff 0.5.

Concurrencia¶

• src/bcch_sdk/sdk/concurrency.py exporta run_in_threads y gather_async_tasks para evitar duplicación de patrones concurrency.

Modelos y nomenclatura¶

• Los modelos Pydantic usan snake_case y nombres explícitos: spanish_description, english_description, index_date, value.
• Los alias de validación de Pydantic convierten directamente el payload JSON original, sin una capa DTO intermedia, y facilitan el uso desde código Python.