Overview¶

echo-connhandler provides a unified interface for connecting to servers — SQL databases, HTTP APIs, and FTP servers — with built-in retry logic, thread safety, and async support.

Architecture¶

All handlers follow the same two-class pattern:

A ConnProperties dataclass holds the connection parameters (host, credentials, timeouts, etc.).
A ConnHandler subclass uses those properties to connect, execute requests, and reconnect automatically on failure.

Both base classes live in core.py and should not be imported directly. Use the concrete subclasses described below.

Available handlers¶

SQL¶

Handler	Properties class	Database
`PgSqlHandler`	`SqlConnProperties`	PostgreSQL
`MsSqlHandler`	`SqlConnProperties`	Microsoft SQL Server
`MySqlHandler`	`SqlConnProperties`	MySQL
`SqlLiteHandler`	`SqlLiteConnProperties`	SQLite

HTTP¶

Handler	Properties class	Target
`HttpHandler`	`HttpConnProperties`	Any HTTP/REST API (no auth)
`BazeHttpHandler`	`HttpConnProperties`	Bazefield API
`CceeHttpHandler`	`HttpConnProperties`	CCEE Dados Abertos
`OnsHttpHandler`	`OnsHttpConnProperties`	ONS SAGER / SINAPSE

All HTTP handlers support both synchronous (get, post, …) and asynchronous (async_get, async_post, …) requests. See the HTTP guide for details.

FTP¶

Handler	Properties class	Target
`FtpHandler`	`FtpConnProperties`	Any FTP server

Retry strategy¶

All handlers implement exponential backoff with jitter using tenacity. The default sequence for 8 retries is approximately:

Text Only

0.1s → 0.2s → 0.4s → 0.8s → 1.6s → 3.2s → 6.4s → 12.8s (capped at 30s)

The retry counts and timing are configurable per-handler via constructor arguments (max_retries, max_conn_retries, retry_wait_time, exponential_min_retry_wait_time, exponential_multiplier).

Thread safety¶

All handlers are thread-safe. Each thread gets its own independent connection via threading.local(), so a single handler instance can be safely shared across threads without external locking.

Context managers¶

All handlers support the with statement (and async with for HTTP handlers), which automatically closes the connection on exit:

Python

with PgSqlHandler(conn_properties) as handler:
    df = handler.read_to_pandas("SELECT * FROM my_table")

async with BazeHttpHandler(props, skip_connect=True) as handler:
    data = (await handler.async_get("api/endpoint")).json()

Importing¶

Import directly from the package — no need to dig into submodules:

Python

from echo_connhandler import (
    SqlConnProperties, PgSqlHandler,
    HttpConnProperties, BazeHttpHandler,
    OnsHttpConnProperties, OnsHttpHandler,
)