fred-client 0.1.0__py3-none-any.whl

fred_client/__init__.py

@@ -0,0 +1,89 @@
+"""fred-client -- read economic data from the FRED / ALFRED / GeoFRED API.
+
+    from fred_client import FRED
+
+    fred = FRED()                                 # or set FRED_API_KEY
+    rows = fred.series.observations("GNPCA")       # a series' observations
+    hit = fred.series.search("unemployment rate")  # series matching text
+
+Single lookups return one raw dictionary; collections return ``list[dict]`` with the
+vendor's own field names. The offline :mod:`fred_client.catalog` describes every service
+without a call.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from . import catalog
+from .client import FRED
+from .errors import (
+    FREDAuthError,
+    FREDConfigError,
+    FREDError,
+    FREDNetworkError,
+    FREDProtocolError,
+    FREDRateLimitError,
+    FREDResponseError,
+)
+from .types import (
+    AggregationMethod,
+    Frequency,
+    OutputType,
+    RegionType,
+    ReleaseDateOrder,
+    ReleaseOrder,
+    Row,
+    SearchOrder,
+    SearchType,
+    Season,
+    SeriesFilter,
+    SeriesOrder,
+    Shape,
+    SortOrder,
+    SourceOrder,
+    TagGroup,
+    TagOrder,
+    Transformation,
+    Units,
+    UpdateFilter,
+    VintageDates,
+)
+
+try:
+    __version__ = version("fred-client")  # single source of truth: pyproject.toml
+except PackageNotFoundError:  # running from source without an install
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "FRED",
+    "AggregationMethod",
+    "FREDAuthError",
+    "FREDConfigError",
+    "FREDError",
+    "FREDNetworkError",
+    "FREDProtocolError",
+    "FREDRateLimitError",
+    "FREDResponseError",
+    "Frequency",
+    "OutputType",
+    "RegionType",
+    "ReleaseDateOrder",
+    "ReleaseOrder",
+    "Row",
+    "SearchOrder",
+    "Season",
+    "SearchType",
+    "SeriesFilter",
+    "SeriesOrder",
+    "Shape",
+    "SourceOrder",
+    "SortOrder",
+    "TagGroup",
+    "TagOrder",
+    "Transformation",
+    "Units",
+    "UpdateFilter",
+    "VintageDates",
+    "catalog",
+]

fred_client/_config.py

@@ -0,0 +1,92 @@
+"""Resolve the FRED API key from the caller, the environment, or the config file.
+
+The key is looked up in a fixed order, so an explicit value always wins and a set
+environment variable beats a file on disk:
+
+1. the ``api_key`` passed to ``FRED(...)``
+2. the ``FRED_API_KEY`` environment variable
+3. ``"FRED_API_KEY"`` in ``$XDG_CONFIG_HOME/fred-client/credentials.json``
+   (``$XDG_CONFIG_HOME`` defaults to ``~/.config``)
+
+The file is optional -- its absence just means "no key here." But a file that is present
+and unreadable, not JSON, or not a JSON object is an error, because a caller who wrote one
+meant it to be used and a silent skip would hide the mistake.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+
+from .errors import FREDConfigError
+
+_ENV_VAR = "FRED_API_KEY"
+_CONFIG_DIR = "fred-client"
+_CONFIG_FILE = "credentials.json"
+_API_KEY_PATTERN = re.compile(r"[a-z0-9]{32}")
+
+
+def resolve_api_key(explicit: str | None) -> str:
+    """Return the first key found across the three sources, or raise if none exists."""
+    # Surrounding whitespace is harmless copy/paste residue and is normalized. Control
+    # characters that remain inside the key are rejected below.
+    key = (explicit or "").strip() or os.environ.get(_ENV_VAR, "").strip() or _key_from_file()
+    if not key:
+        raise FREDConfigError(
+            f"no FRED API key: pass api_key=, set the {_ENV_VAR} environment "
+            f"variable, or put it in {credentials_path()}"
+        )
+    if _API_KEY_PATTERN.fullmatch(key) is None:
+        # FRED keys use only lowercase ASCII letters and digits. Enforcing that wire
+        # contract also means query encoding has exactly one representation.
+        raise FREDConfigError("the FRED API key must be 32 lowercase letters or digits")
+    return key
+
+
+def credentials_path() -> Path:
+    """The path fred-client reads a stored key from (honoring ``$XDG_CONFIG_HOME``)."""
+    configured_home = os.environ.get("XDG_CONFIG_HOME")
+    if configured_home:
+        config_home = Path(configured_home)
+        if not config_home.is_absolute():
+            raise FREDConfigError("XDG_CONFIG_HOME must be an absolute path")
+    else:
+        config_home = Path.home() / ".config"
+    return config_home / _CONFIG_DIR / _CONFIG_FILE
+
+
+def _key_from_file() -> str:
+    path = credentials_path()
+    failure: FREDConfigError | None = None
+    try:
+        text = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return ""
+    except UnicodeDecodeError:
+        failure = FREDConfigError(f"{path} is not valid UTF-8")
+    except OSError as err:
+        raise FREDConfigError(f"could not read {path}: {err}") from err
+    if failure is not None:
+        # A UnicodeDecodeError carries the offending bytes, and this file can hold the API
+        # key -- from None keeps those bytes out of any traceback.
+        raise failure from None
+
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        failure = FREDConfigError(f"{path} is not valid JSON")
+    if failure is not None:
+        # A JSONDecodeError retains the parsed text in .doc, and this file can hold the API
+        # key -- from None keeps the key out of any traceback.
+        raise failure from None
+    if not isinstance(data, dict):
+        raise FREDConfigError(f"{path} must contain a JSON object")
+
+    key = data.get(_ENV_VAR)
+    if key is None:
+        return ""
+    if not isinstance(key, str):
+        raise FREDConfigError(f"{path} property {_ENV_VAR} must be a string")
+    return key.strip()

fred_client/_endpoint.py

@@ -0,0 +1,105 @@
+"""The :class:`_FREDEndpoint` value object and the registry of every FRED service.
+
+Each endpoint is data: which API namespace it lives in, its path, the *shape* of the
+response, and -- for the array-shaped responses -- the JSON key that holds the array.
+``url`` resolves from namespace + path, so the wire location lives in exactly one place.
+
+The FRED API answers most requests as a top-level object with one named array whose key
+differs per endpoint (``seriess`` with two s's, ``observations``, ``categories``, ...),
+but two core endpoints and the whole GeoFRED maps surface break that mould: a vintage-date
+list is an array of bare strings, a release table is a nested tree, and the maps responses
+are GeoJSON or doubly-nested objects. ``shape`` records which, so the session extracts each
+correctly instead of assuming one form.
+
+``_ENDPOINTS`` is kept read-only (a ``MappingProxyType``): it is package dispatch state
+that every accessor reads, so a caller must not be able to mutate it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Literal
+
+# How the session turns a parsed body into the caller's return value.
+#   objects -> body[key] is a list[dict]      (the common case)
+#   strings -> body[key] is a list[str]       (series/vintagedates)
+#   tree    -> the whole body dict            (release/tables, a nested element tree)
+#   geojson -> the whole body dict            (maps shapes, a GeoJSON FeatureCollection)
+#   single  -> the whole body dict            (maps series/group, one meta object)
+#   nested  -> the whole body dict            (maps series/data & regional/data)
+#   bulk    -> cursor-paged v2 release histories, merged into one whole object
+_ResponseShape = Literal["objects", "strings", "tree", "geojson", "single", "nested", "bulk"]
+_APINamespace = Literal["fred", "geofred"]
+
+_HOST = "https://api.stlouisfed.org"
+_BASE_URL_BY_API_NAMESPACE: Mapping[_APINamespace, str] = MappingProxyType(
+    {"fred": f"{_HOST}/fred", "geofred": f"{_HOST}/geofred"}
+)
+
+
+@dataclass(frozen=True, slots=True)
+class _FREDEndpoint:
+    """One FRED service: where its data lives and how its response is shaped."""
+
+    path: str  # e.g. "series/observations"
+    shape: _ResponseShape  # how to extract the return value
+    response_array_key: str = ""  # "" for whole-dict response shapes
+    api_namespace: _APINamespace = "fred"
+
+    @property
+    def url(self) -> str:
+        return f"{_BASE_URL_BY_API_NAMESPACE[self.api_namespace]}/{self.path}"
+
+
+def _registry(*endpoints: _FREDEndpoint) -> Mapping[str, _FREDEndpoint]:
+    return MappingProxyType({endpoint.path: endpoint for endpoint in endpoints})
+
+
+# Every service, path -> _FREDEndpoint. Read-only. Grouped by the FRED doc's own sections,
+# mirroring the vendor's taxonomy (the module lays out the same way).
+_ENDPOINTS: Mapping[str, _FREDEndpoint] = _registry(
+    # -- Categories --------------------------------------------------------
+    _FREDEndpoint("category", "objects", "categories"),
+    _FREDEndpoint("category/children", "objects", "categories"),
+    _FREDEndpoint("category/related", "objects", "categories"),
+    _FREDEndpoint("category/series", "objects", "seriess"),
+    _FREDEndpoint("category/tags", "objects", "tags"),
+    _FREDEndpoint("category/related_tags", "objects", "tags"),
+    # -- Releases ----------------------------------------------------------
+    _FREDEndpoint("releases", "objects", "releases"),
+    _FREDEndpoint("releases/dates", "objects", "release_dates"),
+    _FREDEndpoint("release", "objects", "releases"),
+    _FREDEndpoint("release/dates", "objects", "release_dates"),
+    _FREDEndpoint("release/series", "objects", "seriess"),
+    _FREDEndpoint("release/sources", "objects", "sources"),
+    _FREDEndpoint("release/tags", "objects", "tags"),
+    _FREDEndpoint("release/related_tags", "objects", "tags"),
+    _FREDEndpoint("release/tables", "tree"),
+    _FREDEndpoint("v2/release/observations", "bulk"),
+    # -- Series ------------------------------------------------------------
+    _FREDEndpoint("series", "objects", "seriess"),
+    _FREDEndpoint("series/categories", "objects", "categories"),
+    _FREDEndpoint("series/observations", "objects", "observations"),
+    _FREDEndpoint("series/release", "objects", "releases"),
+    _FREDEndpoint("series/search", "objects", "seriess"),
+    _FREDEndpoint("series/search/tags", "objects", "tags"),
+    _FREDEndpoint("series/search/related_tags", "objects", "tags"),
+    _FREDEndpoint("series/tags", "objects", "tags"),
+    _FREDEndpoint("series/updates", "objects", "seriess"),
+    _FREDEndpoint("series/vintagedates", "strings", "vintage_dates"),
+    # -- Sources -----------------------------------------------------------
+    _FREDEndpoint("sources", "objects", "sources"),
+    _FREDEndpoint("source", "objects", "sources"),
+    _FREDEndpoint("source/releases", "objects", "releases"),
+    # -- Tags --------------------------------------------------------------
+    _FREDEndpoint("tags", "objects", "tags"),
+    _FREDEndpoint("related_tags", "objects", "tags"),
+    _FREDEndpoint("tags/series", "objects", "seriess"),
+    # -- Maps (GeoFRED) ----------------------------------------------------
+    _FREDEndpoint("shapes/file", "geojson", api_namespace="geofred"),
+    _FREDEndpoint("series/group", "single", api_namespace="geofred"),
+    _FREDEndpoint("series/data", "nested", api_namespace="geofred"),
+    _FREDEndpoint("regional/data", "nested", api_namespace="geofred"),
+)

fred_client/catalog.py

@@ -0,0 +1,34 @@
+"""Offline catalog of the FRED services -- browse the surface without an API key.
+
+Every service is data already in the internal endpoint registry. This module presents it
+in a read-friendly form so a caller (or the CLI) can answer "what endpoints exist, in which
+API namespace, returning what shape?" with no network call and no key.
+"""
+
+from __future__ import annotations
+
+from ._endpoint import _ENDPOINTS
+
+
+def endpoints() -> list[dict[str, str]]:
+    """Every service as a plain dict: path, API namespace, response shape, and array key."""
+    return [
+        {
+            "path": endpoint.path,
+            "api_namespace": endpoint.api_namespace,
+            "shape": endpoint.shape,
+            "response_array_key": endpoint.response_array_key,
+        }
+        for endpoint in _ENDPOINTS.values()
+    ]
+
+
+def paths() -> list[str]:
+    """The sorted list of every service path."""
+    return sorted(_ENDPOINTS)
+
+
+def find(text: str) -> list[dict[str, str]]:
+    """The services whose path contains ``text`` (case-insensitive)."""
+    needle = text.lower()
+    return [entry for entry in endpoints() if needle in entry["path"].lower()]

fred_client/cli.py

@@ -0,0 +1,221 @@
+"""Command-line access to curated indicators and arbitrary FRED series.
+
+``list`` browses the curated accessor groups offline. ``fetch`` mirrors either a
+curated accessor (``fred fetch growth gdp``) or a raw series ID (``fred fetch GDP``).
+``metadata`` describes one series, and ``search`` finds series IDs by text. Data
+commands print aligned output by default and the raw response as JSON under ``--json``;
+all data-shape knowledge stays in the library -- this only formats what it returns.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Callable, Sequence
+from typing import get_args
+
+from . import __version__
+from .client import FRED, _list_indicator_groups, _list_indicators
+from .errors import FREDError
+from .types import AggregationMethod, Frequency, OutputType, Row, SortOrder, Units
+
+__all__ = ["main"]
+
+_PROG = "fred"
+_ERROR_PREFIX = f"{_PROG}: "
+# How many rows the table view prints; the full result is always available with --json.
+_MAX_SHOWN_ROWS = 20
+
+
+def _cell(value: object) -> str:
+    """A value as a single-line table cell (FRED metadata ``notes`` can hold newlines)."""
+    return str(value).replace("\n", " ")
+
+
+def _render(headers: Sequence[str], rows: Sequence[Sequence[object]]) -> str:
+    """Rows as an aligned table over ``headers``, one row per line.
+
+    Widths are code-point counts, which assume the effectively-ASCII FRED payloads; a
+    wide or combining character would misalign a column.
+    """
+    cells = [[_cell(value) for value in row] for row in rows]
+    if cells:
+        columns = list(zip(headers, *cells, strict=True))
+    else:
+        columns = [(header,) for header in headers]
+    widths = [max(len(cell) for cell in column) for column in columns]
+    header_line = "  ".join(
+        header.ljust(width) for header, width in zip(headers, widths, strict=True)
+    )
+    body = "\n".join(
+        "  ".join(cell.ljust(width) for cell, width in zip(row, widths, strict=True))
+        for row in cells
+    )
+    return f"{header_line}\n{body}" if body else header_line
+
+
+def _table(rows: Sequence[Row]) -> tuple[list[str], list[list[object]]]:
+    """A row list as ``(headers, cell-rows)``, unioning keys across the rows.
+
+    The key union (not just the first row's keys) keeps an ALFRED vintage view
+    (output_type 2/3), whose rows are keyed by different vintage dates, from silently
+    dropping columns the table should show.
+    """
+    headers = list(dict.fromkeys(key for row in rows for key in row))
+    body: list[list[object]] = [[row.get(key, "") for key in headers] for row in rows]
+    return headers, body
+
+
+def _render_rows(rows: Sequence[Row]) -> str:
+    """Rows as an aligned table then a total count. Over ``_MAX_SHOWN_ROWS`` rows, show
+    the first and last halves split by a gap marker so both ends of the series stay
+    visible (use ``--json`` for everything). Empty -> ``(no rows)``."""
+    if not rows:
+        return "(no rows)"
+    noun = "row" if len(rows) == 1 else "rows"
+    if len(rows) <= _MAX_SHOWN_ROWS:
+        headers, body = _table(rows)
+        return f"{_render(headers, body)}\n({len(rows)} {noun})"
+    head = _MAX_SHOWN_ROWS // 2
+    tail = _MAX_SHOWN_ROWS - head
+    headers, body = _table([*rows[:head], *rows[-tail:]])
+    lines = _render(headers, body).splitlines()  # header line + head rows + tail rows
+    # A bare "..." marks the omitted middle; the footer already gives the omitted count.
+    table = "\n".join([*lines[: head + 1], "...", *lines[head + 1 :]])
+    return f"{table}\n({len(rows)} {noun} total, first {head} and last {tail} shown)"
+
+
+def _render_mapping(mapping: Row) -> str:
+    """One object as aligned ``key   value`` lines. Empty -> ``(no fields)``."""
+    if not mapping:
+        return "(no fields)"
+    width = max(len(key) for key in mapping)
+    return "\n".join(f"{key.ljust(width)}  {_cell(value)}" for key, value in mapping.items())
+
+
+def _emit_rows(rows: Sequence[Row], as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(list(rows), ensure_ascii=False, indent=2))
+    else:
+        print(_render_rows(rows))
+
+
+def _emit_mapping(mapping: Row, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(mapping, ensure_ascii=False, indent=2))
+    else:
+        print(_render_mapping(mapping))
+
+
+def _add_observation_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--realtime-start")
+    parser.add_argument("--realtime-end")
+    parser.add_argument("--observation-start")
+    parser.add_argument("--observation-end")
+    parser.add_argument("--units", choices=get_args(Units))
+    parser.add_argument("--frequency", choices=get_args(Frequency))
+    parser.add_argument("--aggregation-method", choices=get_args(AggregationMethod))
+    parser.add_argument("--output-type", type=int, choices=get_args(OutputType))
+    parser.add_argument("--vintage-dates")
+    parser.add_argument("--limit", type=int)
+    parser.add_argument("--offset", type=int)
+    parser.add_argument("--sort-order", choices=get_args(SortOrder))
+
+
+def _make_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog=_PROG, description="Read FRED economic data.")
+    parser.add_argument("--version", action="version", version=f"fred-client {__version__}")
+    commands = parser.add_subparsers(required=True)
+
+    list_command = commands.add_parser("list", help="list curated indicator accessors (offline)")
+    list_command.add_argument("group", nargs="?", choices=_list_indicator_groups())
+    list_command.set_defaults(run=_run_list)
+
+    fetch = commands.add_parser("fetch", help="fetch observations by accessor or series ID")
+    fetch.add_argument("group_or_series", help="an accessor group or a FRED series ID")
+    fetch.add_argument("indicator", nargs="?", help="an indicator in the accessor group")
+    _add_observation_options(fetch)
+    fetch.add_argument("--json", action="store_true", help="emit JSON rows instead of a table")
+    fetch.set_defaults(run=_run_fetch)
+
+    metadata = commands.add_parser("metadata", help="show one series' metadata")
+    metadata.add_argument("series_id")
+    metadata.add_argument("--json", action="store_true", help="emit JSON instead of a table")
+    metadata.set_defaults(run=_run_metadata)
+
+    search = commands.add_parser("search", help="find series matching search text")
+    search.add_argument("text")
+    search.add_argument("--limit", type=int)
+    search.add_argument("--json", action="store_true", help="emit JSON rows instead of a table")
+    search.set_defaults(run=_run_search)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _make_parser().parse_args(argv)
+    run: Callable[[argparse.Namespace], int] = args.run
+    try:
+        return run(args)
+    except FREDError as err:
+        print(f"{_ERROR_PREFIX}{err}", file=sys.stderr)
+        return 1
+    except ValueError as err:
+        print(f"{_ERROR_PREFIX}{err}", file=sys.stderr)
+        return 2
+
+
+def _run_list(args: argparse.Namespace) -> int:
+    groups = (args.group,) if args.group else _list_indicator_groups()
+    lines: list[str] = []
+    for group in groups:
+        lines.append(group)
+        lines.extend(f"  {group} {indicator}" for indicator in _list_indicators(group))
+    print("\n".join(lines))
+    return 0
+
+
+def _run_fetch(args: argparse.Namespace) -> int:
+    params = {
+        "realtime_start": args.realtime_start,
+        "realtime_end": args.realtime_end,
+        "observation_start": args.observation_start,
+        "observation_end": args.observation_end,
+        "units": args.units,
+        "frequency": args.frequency,
+        "aggregation_method": args.aggregation_method,
+        "output_type": args.output_type,
+        "vintage_dates": args.vintage_dates,
+        "limit": args.limit,
+        "offset": args.offset,
+        "sort_order": args.sort_order,
+    }
+    if args.indicator is None:
+        fred = FRED()
+        payload = fred.series.observations(args.group_or_series, **params)
+    else:
+        group = args.group_or_series.lower()
+        indicator = args.indicator.lower()
+        if group not in _list_indicator_groups():
+            raise ValueError(f"unknown indicator group {group!r} (try `{_PROG} list`)")
+        if indicator not in _list_indicators(group):
+            raise ValueError(f"unknown indicator {group}.{indicator} (try `{_PROG} list {group}`)")
+        fred = FRED()
+        payload = getattr(getattr(fred, group), indicator)(**params)
+    _emit_rows(payload, args.json)
+    return 0
+
+
+def _run_metadata(args: argparse.Namespace) -> int:
+    _emit_mapping(FRED().series.get(args.series_id), args.json)
+    return 0
+
+
+def _run_search(args: argparse.Namespace) -> int:
+    _emit_rows(FRED().series.search(args.text, limit=args.limit), args.json)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())