FRED and ALFRED¶
Construct FredClient directly or with from_env, then use its discovery and series
namespaces. The adapter keeps provider discovery metadata separate from source-level observations.
Client¶
persistra.data.fred.client.FredClient
¶
A synchronous client for source-level FRED discovery and ALFRED series data.
_transport = transport
instance-attribute
¶
discovery = DiscoveryNamespace(context)
instance-attribute
¶
series = SeriesNamespace(context)
instance-attribute
¶
__init__(api_key: str, *, base_url: str = 'https://api.stlouisfed.org/fred', cache_directory: str | Path | None = None, timeout: float = 30, strict_schema: bool = False, cache_ages: Mapping[str, timedelta | None] | None = None, session: SessionLike | None = None) -> None
¶
close() -> None
¶
Close the client and its Persistra-owned HTTP session.
__enter__() -> Self
¶
__exit__(*_args: object) -> None
¶
from_env(*, base_url: str = 'https://api.stlouisfed.org/fred', cache_directory: str | Path | None = None, timeout: float = 30, strict_schema: bool = False, cache_ages: Mapping[str, timedelta | None] | None = None, session: SessionLike | None = None) -> Self
classmethod
¶
Create a client from PERSISTRA_FRED_API_KEY.
Series¶
persistra.data.fred.series.SeriesNamespace
¶
Source-level FRED series and ALFRED revision operations.
_context = context
instance-attribute
¶
__init__(context: AdapterContext) -> None
¶
definition(series_id: str, *, realtime_start: date | str | None = None, realtime_end: date | str | None = None, refresh: bool = False, offline: bool = False) -> SeriesDefinition
¶
Retrieve the definition used to interpret one provider series.
latest(series_id: str, *, observation_start: date | str | None = None, observation_end: date | str | None = None, refresh: bool = False, offline: bool = False) -> SeriesSet
¶
Retrieve current source-level observations at the native frequency.
vintages(series_id: str, *, realtime_start: date | str | None = None, realtime_end: date | str | None = None, vintage_dates: Sequence[date | str] | None = None, observation_start: date | str | None = None, observation_end: date | str | None = None, refresh: bool = False, offline: bool = False) -> VintageSeriesSet
¶
Retrieve explicit vintages or one bounded ALFRED revision history.
vintage_dates(series_id: str, *, realtime_start: date | str | None = None, realtime_end: date | str | None = None, refresh: bool = False, offline: bool = False) -> VintageDatesResult
¶
List every change date for one series inside inclusive real-time bounds.
_definition(parameters: dict[str, Any], *, refresh: bool, offline: bool) -> tuple[SeriesDefinition, datetime | None, tuple[SchemaDiagnostic, ...], RawResponse]
¶
Discovery¶
persistra.data.fred.discovery
¶
FRED series discovery and release-context metadata.
_PAGE_LIMIT = 1000
module-attribute
¶
_SERIES_SEARCH_MAXIMUM = 5000
module-attribute
¶
_SERIES_FIELDS = {'id', 'realtime_start', 'realtime_end', 'title', 'observation_start', 'observation_end', 'frequency', 'frequency_short', 'units', 'units_short', 'seasonal_adjustment', 'seasonal_adjustment_short', 'last_updated', 'popularity', 'group_popularity', 'notes'}
module-attribute
¶
_CATEGORY_FIELDS = {'id', 'name', 'parent_id', 'notes'}
module-attribute
¶
_RELEASE_FIELDS = {'id', 'realtime_start', 'realtime_end', 'name', 'press_release', 'link', 'notes'}
module-attribute
¶
_TAG_FIELDS = {'name', 'group_id', 'notes', 'created', 'popularity', 'series_count'}
module-attribute
¶
AdapterContext
dataclass
¶
Configuration shared by the focused FRED namespaces.
json(operation: str, parameters: dict[str, Any], *, refresh: bool = False, offline: bool = False) -> tuple[dict[str, Any], RawResponse]
¶
Request and decode one JSON object.
pages(operation: str, parameters: dict[str, Any], *, item_key: str, limit: int, maximum_items: int | None = None, refresh: bool = False, offline: bool = False) -> tuple[list[Any], tuple[RawResponse, ...], tuple[SchemaDiagnostic, ...]]
¶
Read every offset page and validate the pagination envelope.
metadata(operation: str, parameters: dict[str, Any], responses: Sequence[RawResponse], *, diagnostics: Sequence[SchemaDiagnostic] = (), provider_as_of: datetime | None = None) -> ResultMetadata
¶
Create one result provenance record from one or more response pages.
NoDataError
¶
Bases: ProviderError
Raised for an unambiguous provider no-data response.
ResponseError
¶
Bases: ProviderError
Raised when a provider response is invalid.
ResultMetadata
dataclass
¶
Required provenance with deeply immutable portable request parameters.
Request parameters may contain strings, integers, finite floats, booleans, None,
string-keyed mappings, lists, and tuples. Persistra copies the complete structure,
removes api_key and apikey fields recursively, freezes mappings, and converts
sequences to tuples.
FredSeriesSummary
dataclass
¶
One source-level series match without canonical identity inference.
FredSeriesSearchResult
dataclass
¶
Ordered series matches and their acquisition provenance.
FredCategory
dataclass
¶
One FRED category assigned to a series.
FredSeriesCategoriesResult
dataclass
¶
Categories assigned to one provider series.
FredRelease
dataclass
¶
The FRED release that owns one series.
FredSeriesReleaseResult
dataclass
¶
Release context for one provider series.
FredTag
dataclass
¶
One source-level tag assigned to a FRED series.
FredSeriesTagsResult
dataclass
¶
Tags assigned to one provider series.
DiscoveryNamespace
¶
Focused FRED series search and release-context operations.
search(query: str, *, search_type: Literal['full_text', 'series_id'] = 'full_text', tag_names: tuple[str, ...] = (), exclude_tag_names: tuple[str, ...] = (), realtime_start: date | str | None = None, realtime_end: date | str | None = None, refresh: bool = False, offline: bool = False) -> FredSeriesSearchResult
¶
Find source-level series by text or provider identifier.
categories(series_id: str, *, realtime_start: date | str | None = None, realtime_end: date | str | None = None, refresh: bool = False, offline: bool = False) -> FredSeriesCategoriesResult
¶
Return categories assigned to one provider series.
release(series_id: str, *, realtime_start: date | str | None = None, realtime_end: date | str | None = None, refresh: bool = False, offline: bool = False) -> FredSeriesReleaseResult
¶
Return the release that owns one provider series.
tags(series_id: str, *, realtime_start: date | str | None = None, realtime_end: date | str | None = None, refresh: bool = False, offline: bool = False) -> FredSeriesTagsResult
¶
Return tags assigned to one provider series in stable name order.
unknown_fields(payload: Mapping[str, Any], known: set[str], *, context: str) -> tuple[SchemaDiagnostic, ...]
¶
Describe provider fields outside one known FRED schema.
_series_summary(item: dict[str, Any]) -> FredSeriesSummary
¶
_add_bounds(parameters: dict[str, Any], start: date | str | None, end: date | str | None) -> None
¶
_date_argument(value: date | str, field: str) -> str
¶
_tag_arguments(values: tuple[str, ...], field: str) -> tuple[str, ...]
¶
_text_argument(value: str, field: str) -> str
¶
_rows(payload: dict[str, Any], field: str, operation: str) -> list[Any]
¶
_row(value: Any, operation: str, label: str) -> dict[str, Any]
¶
_required_text(payload: dict[str, Any], field: str, context: str) -> str
¶
_optional_text(payload: dict[str, Any], field: str, context: str) -> str | None
¶
_nonnegative_integer(payload: dict[str, Any], field: str, context: str) -> int
¶
_provider_date(value: str, field: str) -> date
¶
_provider_datetime(value: str, field: str) -> datetime
¶
_optional_datetime(payload: dict[str, Any], field: str, context: str) -> datetime | None
¶
Transport¶
Most applications should use the configured client. FredTransport is public for controlled
tests, custom session setup, and integration diagnostics.
persistra.data.fred.transport.FredTransport
¶
FRED transport with raw caching, retries, and redacted failures.
api_key = api_key
instance-attribute
¶
base_url = base_url.rstrip('/')
instance-attribute
¶
session = session if session is not None else cast('SessionLike', owned_session)
instance-attribute
¶
_owned_session = owned_session
instance-attribute
¶
_closed = False
instance-attribute
¶
cache = cache
instance-attribute
¶
timeout = timeout
instance-attribute
¶
clock = clock or (lambda: datetime.now(UTC))
instance-attribute
¶
delay = delay
instance-attribute
¶
random_source = random_source
instance-attribute
¶
retries = retries
instance-attribute
¶
__init__(api_key: str, *, base_url: str = 'https://api.stlouisfed.org/fred', session: SessionLike | None = None, cache: RawResponseCache | None = None, timeout: float = 30, clock: Callable[[], datetime] | None = None, delay: Callable[[float], None] = time.sleep, random_source: Callable[[], float] = random.random, retries: int = 3) -> None
¶
close() -> None
¶
Close the transport and its Persistra-owned HTTP session.
request(operation: str, parameters: dict[str, Any], *, cache_age: timedelta | None = timedelta(hours=24), refresh: bool = False, offline: bool = False) -> RawResponse
¶
Return classified bytes for one supported FRED operation.