fredq 0.1.0__py3-none-any.whl

fredq/__init__.py

@@ -0,0 +1,7 @@
+"""Expose FRED (Federal Reserve Economic Data) endpoints as a raw JSON CLI."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

fredq/__main__.py

@@ -0,0 +1,8 @@
+"""Run fredq as a module."""
+
+from __future__ import annotations
+
+from fredq.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fredq/auth.py

@@ -0,0 +1,114 @@
+"""FRED API key resolution."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Final, TextIO
+
+from fredq.exceptions import FredApiKeyMissingError
+
+_ENV_VAR: Final[str] = "FRED_API_KEY"
+# On POSIX, warn when the key file is readable by group or world.
+_WIDE_MODE_MASK: Final[int] = 0o077
+
+
+def default_key_path() -> Path:
+    """Return fredq's default API key file path.
+
+    Returns:
+        Path: Default location for the FRED API key file.
+    """
+
+    return Path.home() / ".fredq" / "api_key"
+
+
+def _check_key_file_permissions(path: Path, stderr: TextIO) -> None:
+    """Emit a one-line warning to ``stderr`` when ``path`` is world- or group-readable.
+
+    Only runs on POSIX (``os.name != 'nt'``).  Windows ACL checks are
+    too platform-specific and are skipped.
+
+    Args:
+        path: Path to the API key file.
+        stderr: Stream for the permission warning.
+    """
+
+    if os.name == "nt":
+        return
+    try:
+        mode = path.stat().st_mode
+    except OSError:
+        return
+    if mode & _WIDE_MODE_MASK:
+        stderr.write(
+            f"warning: {path} is readable by group or world; "
+            "run `chmod 600` to restrict access.\n"
+        )
+
+
+def _read_key_file(path: Path, stderr: TextIO) -> str | None:
+    if not path.exists():
+        return None
+    _check_key_file_permissions(path, stderr)
+    try:
+        contents = path.read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+    if not contents:
+        return None
+    # Take only the first non-empty line so trailing whitespace or a
+    # comment-style second line cannot leak into the request.
+    return contents.splitlines()[0].strip() or None
+
+
+def resolve_api_key(
+    *,
+    explicit: str | None = None,
+    key_path: Path | None = None,
+    use_key_file: bool = True,
+    stderr: TextIO | None = None,
+) -> str:
+    """Resolve the FRED API key.
+
+    Lookup order:
+        1. ``explicit`` argument (e.g. from a CLI override).
+        2. ``FRED_API_KEY`` environment variable.
+        3. Single-line file at ``key_path`` (defaults to ``~/.fredq/api_key``),
+           unless ``use_key_file=False``.
+
+    Args:
+        explicit: Explicit API key from a CLI override; ignored when ``None``.
+        key_path: Override the fallback file path. Defaults to
+            :func:`default_key_path`.
+        use_key_file: When ``False``, skip the file fallback entirely.  Set
+            by ``--no-key-file`` or ``FREDQ_DISABLE_KEY_FILE=1``.
+        stderr: Stream for the permission warning.  Defaults to
+            ``sys.stderr`` when ``None``.
+
+    Returns:
+        str: A non-empty FRED API key.
+
+    Raises:
+        FredApiKeyMissingError: If no key can be located by any mechanism.
+    """
+
+    err = stderr if stderr is not None else sys.stderr
+
+    if explicit:
+        stripped = explicit.strip()
+        if stripped:
+            return stripped
+
+    env_value = os.environ.get(_ENV_VAR, "").strip()
+    if env_value:
+        return env_value
+
+    if use_key_file:
+        path = key_path or default_key_path()
+        from_file = _read_key_file(path, err)
+        if from_file:
+            return from_file
+
+    raise FredApiKeyMissingError