Internal Architecture#

FedFred is designed to be modular, extensible, and high-performance, supporting both synchronous and asynchronous interaction with the FRED® API.

This page outlines the internal class hierarchy, core mechanisms, and design principles behind FedFred.

—

Class Hierarchy Overview#

Expand Class Hierarchy

➤ Nested clients are accessible via attributes like fred.Async, fred.Maps, and fred.Async.Maps.

See FedFred API Overview for a full breakdown.

—

Key Internal Mechanisms#

Rate Limiting

Enforces the FRED 120 requests/min limit using a timestamp deque. Automatically evicts old calls and blocks excess requests.

Retry Strategy

Failed API calls (timeouts/network errors) retry using tenacity. Uses exponential backoff with jitter to avoid hammering FRED.

Local Caching

In-memory FIFO cache stores 256 entries by default. Works in sync and async clients. Toggle via cache_mode.

Asynchronous Engine

Async clients use httpx.AsyncClient and asyncio.Lock for concurrency-safe access and rate compliance. Suitable for high-throughput pipelines.

Structured Objects

API responses are parsed into Python classes like:

Enables static type checking, autocompletion, and safer usage.

DataFrame Output

Supports flexible backend switching via dataframe_method:

Ideal for data science, GIS, and big data use cases.

—

Design Philosophy#

Principles Behind the Package

  • Ease of Use: Minimal boilerplate, clear method names, simple init.

  • Performance: Async support, FIFO caching, adaptive retries.

  • Flexibility: Sync + Async, backend switching, local rate enforcement.

  • Reliability: Typed models, parameter validation, safe defaults.

—