Add Phase 0 foundation: Census API infrastructure (#293)

* Add Phase 0 foundation: Census API infrastructure

Implement the foundation layer for Census API integration (tidycensus parity):
- API key management via census_api_key() with env var support
- Geography hierarchy (21 types) with validation and query building
- File-based CensusCache with TTL support
- Bundled FIPS codes dataset (3,234 state/county entries)
- Spatial optional dependency group in pyproject.toml

All 36 phase0 TDD tests now pass. Existing tests unaffected.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Address PR review feedback

- Remove unused install/overwrite params from census_api_key() to avoid
  silently ignoring caller intent
- Hash cache keys with SHA-256 to prevent path traversal
- Scope CensusCache.clear() to only remove .pkl and .meta.json files
- Fix geography in-clause separator from "+" to space (Census API format)
- Add public exports to pypums/api/__init__.py

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: chekos

pyproject.toml

@@ -28,6 +28,7 @@ Changelog = "https://github.com/chekos/pypums/releases"
 pypums = "pypums.cli:cli"
 
 [project.optional-dependencies]
+spatial = ["geopandas>=0.12"]
 test = ["pytest"]
 docs = [
     "mkdocs",

pypums/__init__.py

@@ -1,6 +1,7 @@
 # type: ignore[attr-defined]
 """Download PUMS data files from the US Census Bureau's FTP server."""
 
+from pypums.api.key import census_api_key as census_api_key
 from pypums.surveys import ACS as ACS
 
 from .constants import __app_name__ as __app_name__

pypums/api/__init__.py

@@ -0,0 +1,5 @@
+"""Census API integration."""
+
+from pypums.api.geography import GEOGRAPHY_HIERARCHY as GEOGRAPHY_HIERARCHY
+from pypums.api.geography import build_geography_query as build_geography_query
+from pypums.api.key import census_api_key as census_api_key

pypums/api/geography.py

@@ -0,0 +1,116 @@
+"""Census geography hierarchy definitions and query building."""
+
+GEOGRAPHY_HIERARCHY: dict[str, dict] = {
+    "us": {"for": "us:1", "requires": []},
+    "region": {"for": "region:*", "requires": []},
+    "division": {"for": "division:*", "requires": []},
+    "state": {"for": "state:*", "requires": []},
+    "county": {"for": "county:*", "requires": ["state"]},
+    "county subdivision": {
+        "for": "county subdivision:*",
+        "requires": ["state", "county"],
+    },
+    "tract": {"for": "tract:*", "requires": ["state", "county"]},
+    "block group": {
+        "for": "block group:*",
+        "requires": ["state", "county"],
+    },
+    "block": {"for": "block:*", "requires": ["state", "county"]},
+    "place": {"for": "place:*", "requires": ["state"]},
+    "congressional district": {
+        "for": "congressional district:*",
+        "requires": ["state"],
+    },
+    "state legislative district (upper)": {
+        "for": "state legislative district (upper chamber):*",
+        "requires": ["state"],
+    },
+    "state legislative district (lower)": {
+        "for": "state legislative district (lower chamber):*",
+        "requires": ["state"],
+    },
+    "zcta": {"for": "zip code tabulation area:*", "requires": []},
+    "school district (unified)": {
+        "for": "school district (unified):*",
+        "requires": ["state"],
+    },
+    "school district (elementary)": {
+        "for": "school district (elementary):*",
+        "requires": ["state"],
+    },
+    "school district (secondary)": {
+        "for": "school district (secondary):*",
+        "requires": ["state"],
+    },
+    "cbsa": {
+        "for": "metropolitan statistical area/micropolitan statistical area:*",
+        "requires": [],
+    },
+    "csa": {"for": "combined statistical area:*", "requires": []},
+    "puma": {"for": "public use microdata area:*", "requires": ["state"]},
+    "american indian area/alaska native area/hawaiian home land": {
+        "for": "american indian area/alaska native area/hawaiian home land:*",
+        "requires": [],
+    },
+}
+
+
+def build_geography_query(
+    geography: str,
+    state: str | None = None,
+    county: str | None = None,
+) -> tuple[str, str | None]:
+    """Convert geography + state/county to Census API ``for`` and ``in`` params.
+
+    Parameters
+    ----------
+    geography
+        Geography level name (e.g. ``"state"``, ``"county"``, ``"tract"``).
+    state
+        State FIPS code (e.g. ``"06"`` for California).
+    county
+        County FIPS code (e.g. ``"037"`` for Los Angeles County).
+
+    Returns
+    -------
+    tuple[str, str | None]
+        A ``(for_clause, in_clause)`` pair for the Census API query.
+
+    Raises
+    ------
+    ValueError
+        If the geography is unknown or required parent geographies are missing.
+    """
+    geo = geography.lower()
+    if geo not in GEOGRAPHY_HIERARCHY:
+        raise ValueError(
+            f"Unknown geography: {geography!r}. "
+            f"Valid options: {sorted(GEOGRAPHY_HIERARCHY)}"
+        )
+
+    spec = GEOGRAPHY_HIERARCHY[geo]
+    required = spec["requires"]
+
+    if "state" in required and state is None:
+        raise ValueError(
+            f"Geography {geography!r} requires a state FIPS code. "
+            "Pass state='XX' (e.g. state='06' for California)."
+        )
+    if "county" in required and county is None:
+        raise ValueError(
+            f"Geography {geography!r} requires a county FIPS code. "
+            "Pass county='XXX' (e.g. county='037' for Los Angeles County)."
+        )
+
+    for_clause = spec["for"]
+
+    # Build the "in" clause from required parents
+    in_parts = []
+    if "state" in required and state is not None:
+        in_parts.append(f"state:{state}")
+    if "county" in required and county is not None:
+        in_parts.append(f"county:{county}")
+
+    in_clause = " ".join(in_parts) if in_parts else None
+
+    return for_clause, in_clause

pypums/api/key.py

@@ -0,0 +1,36 @@
+"""Census API key management."""
+
+import os
+
+
+def census_api_key(key: str | None = None) -> str:
+    """Get or set a Census API key for the current session.
+
+    Parameters
+    ----------
+    key
+        If provided, sets this key for the current session via env var.
+
+    Returns
+    -------
+    str
+        The active Census API key.
+
+    Raises
+    ------
+    ValueError
+        If no key is available from any source.
+    """
+    if key is not None:
+        os.environ["CENSUS_API_KEY"] = key
+        return key
+
+    env_key = os.environ.get("CENSUS_API_KEY")
+    if env_key is not None:
+        return env_key
+
+    raise ValueError(
+        "No Census API key found. Set one with census_api_key('your-key') "
+        "or set the CENSUS_API_KEY environment variable. "
+        "Request a key at https://api.census.gov/data/key_signup.html"
+    )

pypums/cache.py

@@ -0,0 +1,87 @@
+"""File-based caching for Census API responses and variable tables."""
+
+import hashlib
+import json
+import pickle
+import time
+from pathlib import Path
+
+import pandas as pd
+
+_CACHE_DATA_SUFFIX = ".pkl"
+_CACHE_META_SUFFIX = ".meta.json"
+
+
+class CensusCache:
+    """Cache Census API responses with optional TTL.
+
+    Parameters
+    ----------
+    cache_dir
+        Directory to store cached files.
+    """
+
+    def __init__(self, cache_dir: Path) -> None:
+        self._dir = Path(cache_dir)
+        self._dir.mkdir(parents=True, exist_ok=True)
+
+    @staticmethod
+    def _safe_name(key: str) -> str:
+        """Hash the key to produce a safe, fixed-length filename."""
+        return hashlib.sha256(key.encode()).hexdigest()
+
+    def _data_path(self, key: str) -> Path:
+        return self._dir / f"{self._safe_name(key)}{_CACHE_DATA_SUFFIX}"
+
+    def _meta_path(self, key: str) -> Path:
+        return self._dir / f"{self._safe_name(key)}{_CACHE_META_SUFFIX}"
+
+    def set(
+        self,
+        key: str,
+        df: pd.DataFrame,
+        ttl_seconds: int | float | None = None,
+    ) -> None:
+        """Store a DataFrame in the cache.
+
+        Parameters
+        ----------
+        key
+            Cache key identifier.
+        df
+            DataFrame to cache.
+        ttl_seconds
+            Time-to-live in seconds. ``None`` means no expiration.
+        """
+        with open(self._data_path(key), "wb") as f:
+            pickle.dump(df, f)
+        meta = {"created_at": time.time(), "ttl_seconds": ttl_seconds}
+        self._meta_path(key).write_text(json.dumps(meta))
+
+    def get(self, key: str) -> pd.DataFrame | None:
+        """Retrieve a cached DataFrame, or ``None`` if missing/expired."""
+        data_path = self._data_path(key)
+        meta_path = self._meta_path(key)
+
+        if not data_path.exists() or not meta_path.exists():
+            return None
+
+        meta = json.loads(meta_path.read_text())
+        ttl = meta.get("ttl_seconds")
+
+        if ttl is not None:
+            age = time.time() - meta["created_at"]
+            if age > ttl:
+                data_path.unlink(missing_ok=True)
+                meta_path.unlink(missing_ok=True)
+                return None
+
+        with open(data_path, "rb") as f:
+            return pickle.load(f)  # noqa: S301
+
+    def clear(self) -> None:
+        """Remove all cached entries."""
+        for path in self._dir.glob(f"*{_CACHE_DATA_SUFFIX}"):
+            path.unlink()
+        for path in self._dir.glob(f"*{_CACHE_META_SUFFIX}"):
+            path.unlink()

pypums/datasets/__init__.py

@@ -0,0 +1,3 @@
+"""Built-in reference datasets."""
+
+from pypums.datasets.fips import fips_codes as fips_codes