Internal Architecture#

Edgar-SEC is built to be modular, typed, and asynchronous-ready, designed for scalable, secure interaction with the SEC EDGAR® API.

This page outlines the internal client structure, core mechanisms, and the design philosophy guiding Edgar-SEC.

—

Class Hierarchy Overview#

Expand Class Hierarchy

➤ Call EdgarAPI().Async to access async methods for each endpoint.➤ Use edgar_sec.EdgarHelpers for static utility helpers like CIK resolution.

See Edgar-SEC API Overview for endpoint-specific breakdowns.

—

Key Internal Mechanisms#

Rate Limiting

Enforces EDGAR’s safe usage limits using a timestamp-based limiter. Prevents accidental denial-of-service and burst requests.

Retry Strategy

Automatic retry on network failures via tenacity with exponential backoff. Applies to all sync and async endpoints.

Local File Caching

File-based FIFO cache system stores successful responses. Enabled via cache_mode=True and configurable with cache_size.

Asynchronous Engine

Fully async using httpx.AsyncClient + asyncio.Lock. Supports concurrent SEC submission fetches with minimal blocking.

Structured Dataclasses

All endpoints return structured, type-safe objects like:

Enforces safe unpacking, IDE integration, and schema reliability.

Helper Utilities

Parameter conversion, type coercion, and validation handled through shared static methods. Ensures consistent behavior between sync and async clients.

—

Design Philosophy#

Principles Behind the Package

  • Type-Safe: Uses Python dataclasses.dataclass models for every response.

  • Async-Ready: Fully asynchronous client with sync fallback.

  • Performant: Built-in caching, retry logic, and minimal overhead.

  • Robust: Validates inputs and ensures graceful failure modes.

  • Developer-Oriented: Concise naming, inline docs, static typing, and modern architecture.

—