Merge pull request #292 from chekos/claude/tidycensus-evaluation-KVDPg

Add comprehensive implementation plan and test suite for tidycensus feature parity

Author: chekos

TIDYCENSUS_EVALUATION.md

@@ -44,6 +44,14 @@ module-root = ""
 norecursedirs = ["*.egg", ".eggs", "dist", "build", "docs", ".tox", ".git", "__pycache__"]
 doctest_optionflags = ["NUMBER", "NORMALIZE_WHITESPACE", "IGNORE_EXCEPTION_DETAIL"]
 addopts = "--strict-markers --tb=short --doctest-modules --doctest-continue-on-failure"
+markers = [
+    "phase0: Foundation (API infra, geography, FIPS, cache)",
+    "phase1: Core data functions (get_acs, get_decennial, load_variables)",
+    "phase2: MOE, spatial, enhanced PUMS",
+    "phase3: Estimates, flows, survey",
+    "integration: Requires real Census API key and network",
+    "spatial: Requires geopandas",
+]
 
 [tool.ruff]
 target-version = "py310"

pyproject.toml

@@ -0,0 +1,109 @@
+"""Shared fixtures for pypums test suite.
+
+Provides mock Census API responses, fake API keys, and temporary
+cache directories used across all test files.
+"""
+
+import pytest
+
+
+@pytest.fixture()
+def fake_api_key():
+    """A fake Census API key for testing."""
+    return "fake_test_key_0123456789abcdef"
+
+
+@pytest.fixture()
+def cache_dir(tmp_path):
+    """Temporary cache directory for testing."""
+    d = tmp_path / "cache"
+    d.mkdir()
+    return d
+
+
+# ---------------------------------------------------------------------------
+# Sample Census API JSON responses
+# These mirror the structure returned by api.census.gov so we can mock httpx
+# calls and still test DataFrame construction, column naming, etc.
+# ---------------------------------------------------------------------------
+
+@pytest.fixture()
+def acs_api_response_tidy():
+    """Sample ACS API response (JSON rows) for 2 variables, 2 counties."""
+    return [
+        ["NAME", "B01001_001E", "B01001_001M", "B02001_002E", "B02001_002M", "state", "county"],
+        ["Los Angeles County, California", "10014009", "0", "2786755", "9012", "06", "037"],
+        ["Orange County, California", "3186989", "0", "1298431", "6234", "06", "059"],
+    ]
+
+
+@pytest.fixture()
+def decennial_api_response():
+    """Sample Decennial Census API response for 2 variables, 2 states."""
+    return [
+        ["NAME", "P1_001N", "P1_002N", "state"],
+        ["California", "39538223", "39538223", "06"],
+        ["Texas", "29145505", "29145505", "48"],
+    ]
+
+
+@pytest.fixture()
+def variables_api_response():
+    """Sample variables endpoint response."""
+    return {
+        "variables": {
+            "B01001_001E": {
+                "label": "Estimate!!Total:",
+                "concept": "SEX BY AGE",
+                "predicateType": "int",
+                "group": "B01001",
+            },
+            "B01001_002E": {
+                "label": "Estimate!!Total:!!Male:",
+                "concept": "SEX BY AGE",
+                "predicateType": "int",
+                "group": "B01001",
+            },
+        }
+    }
+
+
+@pytest.fixture()
+def pums_api_response():
+    """Sample PUMS API response with person-level records."""
+    return [
+        ["SERIALNO", "SPORDER", "PWGTP", "AGEP", "SEX", "ST", "PUMA"],
+        ["2023HU0000001", "01", "50", "35", "1", "06", "03701"],
+        ["2023HU0000001", "02", "45", "33", "2", "06", "03701"],
+        ["2023HU0000002", "01", "60", "42", "1", "06", "03701"],
+    ]
+
+
+@pytest.fixture()
+def estimates_api_response():
+    """Sample Population Estimates API response."""
+    return [
+        ["NAME", "POP_2023", "DENSITY_2023", "state"],
+        ["California", "38965193", "254.3", "06"],
+        ["Texas", "30503301", "117.3", "48"],
+    ]
+
+
+@pytest.fixture()
+def flows_api_response():
+    """Sample ACS Migration Flows API response."""
+    return [
+        [
+            "FULL1_NAME", "FULL2_NAME",
+            "MOVEDIN", "MOVEDIN_M",
+            "MOVEDOUT", "MOVEDOUT_M",
+            "MOVEDNET", "MOVEDNET_M",
+            "state1", "county1", "state2", "county2",
+        ],
+        [
+            "Los Angeles County, California",
+            "Maricopa County, Arizona",
+            "15234", "1200", "22456", "1500", "-7222", "1921",
+            "06", "037", "04", "013",
+        ],
+    ]

tests/conftest.py

@@ -0,0 +1,41 @@
+"""Tests for Census API key management.
+
+Phase 0 — Foundation.
+
+These tests define the contract for ``census_api_key()``:
+* Set a key and retrieve it back within the same session.
+* Read a key from the ``CENSUS_API_KEY`` environment variable.
+* Raise a clear error when no key is configured.
+"""
+
+import os
+
+import pytest
+
+from pypums import census_api_key
+
+pytestmark = pytest.mark.phase0
+
+
+def test_census_api_key_set_and_get(monkeypatch, fake_api_key):
+    """Setting a key stores it so a subsequent call retrieves it."""
+    # Clear any pre-existing env var so we're testing in-memory storage.
+    monkeypatch.delenv("CENSUS_API_KEY", raising=False)
+
+    census_api_key(fake_api_key)
+    assert census_api_key() == fake_api_key
+
+
+def test_census_api_key_from_env(monkeypatch, fake_api_key):
+    """When no key is explicitly set, fall back to the env var."""
+    monkeypatch.setenv("CENSUS_API_KEY", fake_api_key)
+
+    assert census_api_key() == fake_api_key
+
+
+def test_census_api_key_missing_raises(monkeypatch):
+    """When no key is available anywhere, raise a helpful error."""
+    monkeypatch.delenv("CENSUS_API_KEY", raising=False)
+
+    with pytest.raises((ValueError, OSError)):
+        census_api_key()

tests/test_api_key.py

@@ -0,0 +1,56 @@
+"""Tests for the local caching layer.
+
+Phase 0 — Foundation.
+
+The cache stores API responses and variable tables locally so repeated
+queries don't hit the Census API.  Tests here verify the round-trip
+store → retrieve contract, TTL expiration, and clearing.
+"""
+
+import time
+
+import pandas as pd
+import pytest
+
+from pypums.cache import CensusCache
+
+pytestmark = pytest.mark.phase0
+
+
+@pytest.fixture()
+def cache(cache_dir):
+    """A CensusCache instance backed by a temporary directory."""
+    return CensusCache(cache_dir)
+
+
+def test_cache_stores_and_retrieves(cache):
+    """Storing a DataFrame under a key and retrieving it returns equal data."""
+    df = pd.DataFrame({"a": [1, 2, 3], "b": ["x", "y", "z"]})
+    cache.set("test_key", df)
+    result = cache.get("test_key")
+    assert result is not None
+    pd.testing.assert_frame_equal(result, df)
+
+
+def test_cache_miss_returns_none(cache):
+    """Getting a key that was never stored returns None."""
+    assert cache.get("nonexistent_key") is None
+
+
+def test_cache_respects_ttl(cache):
+    """An entry older than its TTL should not be returned."""
+    df = pd.DataFrame({"a": [1]})
+    cache.set("short_lived", df, ttl_seconds=0)
+    # Even a TTL of 0 means "already expired"
+    time.sleep(0.05)
+    assert cache.get("short_lived") is None
+
+
+def test_cache_clear(cache):
+    """Clearing the cache removes all stored entries."""
+    df = pd.DataFrame({"a": [1]})
+    cache.set("key1", df)
+    cache.set("key2", df)
+    cache.clear()
+    assert cache.get("key1") is None
+    assert cache.get("key2") is None

tests/test_cache.py

@@ -0,0 +1,39 @@
+"""Tests for the built-in FIPS codes dataset.
+
+Phase 0 — Foundation.
+
+The ``fips_codes`` dataset should be a pandas DataFrame bundling every
+US state and county FIPS code, mirroring the ``fips_codes`` tibble shipped
+with tidycensus.
+"""
+
+import pandas as pd
+import pytest
+
+from pypums.datasets import fips_codes
+
+pytestmark = pytest.mark.phase0
+
+
+def test_fips_codes_is_dataframe():
+    """``fips_codes`` is a pandas DataFrame."""
+    assert isinstance(fips_codes, pd.DataFrame)
+
+
+def test_fips_codes_has_expected_columns():
+    """Must include at minimum these identifier columns."""
+    for col in ("state", "state_code", "county", "county_code"):
+        assert col in fips_codes.columns, f"Missing column: {col}"
+
+
+def test_fips_codes_has_all_states():
+    """All 50 states + DC should be present."""
+    states = fips_codes["state"].unique()
+    assert len(states) >= 51  # 50 states + DC at minimum
+
+
+def test_fips_lookup_california():
+    """Can look up California by name and get FIPS code '06'."""
+    ca = fips_codes[fips_codes["state"] == "California"]
+    assert not ca.empty
+    assert ca["state_code"].iloc[0] == "06"

tests/test_fips.py

@@ -0,0 +1,78 @@
+"""Tests for geography hierarchy definitions and validation.
+
+Phase 0 — Foundation.
+
+These tests define the contract for the geography module:
+* All 25+ Census geography names are accepted.
+* Geographies that require parent geographies (e.g. county → state) raise
+  when those parents are not supplied.
+* ``build_geography_query`` returns the correct Census API ``for`` / ``in``
+  parameter strings.
+"""
+
+import pytest
+
+from pypums.api.geography import GEOGRAPHY_HIERARCHY, build_geography_query
+
+pytestmark = pytest.mark.phase0
+
+
+# The minimum set of geographies tidycensus supports — pypums must too.
+EXPECTED_GEOGRAPHIES = [
+    "us",
+    "region",
+    "division",
+    "state",
+    "county",
+    "county subdivision",
+    "tract",
+    "block group",
+    "block",
+    "place",
+    "congressional district",
+    "state legislative district (upper)",
+    "state legislative district (lower)",
+    "zcta",
+    "school district (unified)",
+    "school district (elementary)",
+    "school district (secondary)",
+    "cbsa",
+    "csa",
+    "puma",
+    "american indian area/alaska native area/hawaiian home land",
+]
+
+
+@pytest.mark.parametrize("geo", EXPECTED_GEOGRAPHIES)
+def test_valid_geography_names(geo):
+    """Every expected geography string is present in the hierarchy mapping."""
+    assert geo in GEOGRAPHY_HIERARCHY
+
+
+def test_county_requires_state():
+    """Requesting county-level data without a state should raise."""
+    with pytest.raises(ValueError, match="(?i)state"):
+        build_geography_query("county")
+
+
+def test_tract_requires_state_and_county():
+    """Requesting tract-level data without state+county should raise."""
+    with pytest.raises(ValueError):
+        build_geography_query("tract", state="06")  # missing county
+
+
+def test_build_geography_query_state():
+    """State-level query needs no 'in' clause."""
+    for_clause, in_clause = build_geography_query("state")
+    assert "state" in for_clause
+    assert in_clause is None
+
+
+def test_build_geography_query_county_in_state():
+    """County-level query returns a 'for' and an 'in' clause."""
+    for_clause, in_clause = build_geography_query(
+        "county", state="06"
+    )
+    assert "county" in for_clause
+    assert in_clause is not None
+    assert "state:06" in in_clause