Add Phase 3: estimates, flows, FIPS lookups, and caching integration (#297)

* Add Phase 3: estimates, flows, variable caching, FIPS lookups, and API caching

- Create pypums/estimates.py with get_estimates() for Population Estimates Program data
- Create pypums/flows.py with get_flows() for ACS Migration Flows data
- Enhance load_variables() with persistent disk caching via CensusCache
- Add lookup_fips() and lookup_name() to pypums/datasets/fips.py
- Wire cache_table=True option into get_acs(), get_decennial(), get_pums()
- Export get_estimates, get_flows, lookup_fips, lookup_name from package

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

* Fix review issues: cache key collisions, pickle→parquet, input validation

- Fix cache key collisions: include output, moe_level, summary_var,
  pop_group, rep_weights, recode, variables_filter, puma in cache keys
- Switch cache.py from pickle to parquet to eliminate arbitrary code
  execution risk from tampered cache files
- Add pyarrow dependency (required for parquet serialization)
- Validate product parameter in get_estimates() — raise ValueError for
  unknown products instead of silent fallback
- Validate geography parameter in get_flows() against allowed values
- Add cache_table parameter to get_estimates() and get_flows() for
  consistent API surface
- Document unimplemented parameters (time_series, breakdown_labels,
  output, moe_level) in docstrings
- Fix double _get_persistent_cache() instantiation in variables.py

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

* Fix cache_table to read from cache before API call in estimates/flows

The cache_table parameter was write-only — it stored results but never
checked for cached data before making API calls. Also adds variables,
breakdown, and year to cache keys to prevent collisions.

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

* Add pre-commit hooks with Ruff linting and formatting

Set up .pre-commit-config.yaml with ruff-check, ruff-format, and
standard pre-commit hooks (trailing whitespace, end-of-file, yaml/toml
checks). Fix all lint errors across the codebase: line length, import
ordering, formatting, zip() strict parameter, and trailing whitespace.

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

* Reuse single CensusCache instance per cached call

Instantiate CensusCache once before the cache read check and reuse the
same instance for the write, instead of creating two separate instances.

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

---------

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

Author: chekos

.github/PULL_REQUEST_TEMPLATE.md

@@ -24,4 +24,3 @@
 - [ ] I've read the [`CODE_OF_CONDUCT.md`](https://github.com/chekos/pypums/blob/master/CODE_OF_CONDUCT.md) document.
 - [ ] I've read the [`CONTRIBUTING.md`](https://github.com/chekos/pypums/blob/master/CONTRIBUTING.md) guide.
 - [ ] I've written tests for all new methods and classes that I created.
-

.github/workflows/claude.yml

@@ -47,4 +47,3 @@ jobs:
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://code.claude.com/docs/en/cli-reference for available options
           # claude_args: '--allowed-tools Bash(gh pr:*)'
-

.pre-commit-config.yaml

@@ -5,6 +5,7 @@ repos:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-yaml
+        args: [--unsafe]
       - id: check-toml
       - id: check-added-large-files
   - repo: https://github.com/astral-sh/ruff-pre-commit

docs/about/contributing.md

@@ -73,7 +73,7 @@ local development.
     Or if you are using `pipenv`:
 
         pipenv shell
-    
+
     Now install the dependencies and test dependencies:
 
         pip install -e '.[test]'
@@ -82,7 +82,7 @@ local development.
 
         git checkout -b name-of-your-bugfix-or-feature
 
-    Now you can make your changes locally.  
+    Now you can make your changes locally.
     <br>
 
 5.  When you're done making changes, check that your changes pass
@@ -111,4 +111,3 @@ Before you submit a pull request, check that it meets these guidelines:
 3.  The pull request should work for Python 3.6 - 3.9.
     Check <https://travis-ci.org/chekos/pypums/pull_requests>
     and make sure that the tests pass for all supported Python versions.
-

docs/about/history.md

@@ -10,10 +10,10 @@
 - Bug fixes (some url's at the census website didn't have `content-size`, switched to default dict to move past that case)
 
 ## 0.0.5 (2019-05-11)
-- Add `.as_dataframe()` to ACS class. 
+- Add `.as_dataframe()` to ACS class.
 
 ## 0.0.4 (2019-05-10)
-- Add `.download_data()` to ACS class. 
+- Add `.download_data()` to ACS class.
 
 ## 0.0.3 (2019-05-09)
 - Accidentally released lol

docs/css/custom.css

@@ -3,8 +3,8 @@ div.autodoc-docstring {
     margin-bottom: 30px;
     border-left: 5px solid rgba(230, 230, 230);
   }
-  
+
   div.autodoc-members {
     padding-left: 20px;
     margin-bottom: 15px;
-  }
+  }

docs/reference/surveys.md

@@ -5,4 +5,3 @@
         members:
             - download
             - as_dataframe
-

docs/user-guide/usage.md

@@ -4,7 +4,7 @@ You can use `pypums` as a CLI on your terminal or in your scripts or notebooks.
 
 ## As a CLI
 
-On your terminal `pypums --help` or `pypums --version` to make sure it's installed 
+On your terminal `pypums --help` or `pypums --version` to make sure it's installed
 
 ```shell
 pypums --version
@@ -40,7 +40,7 @@ Options:
 ```
 
 ### `pypums download-acs`
-You can use the `download-acs` command to download the zip file containing the data for the specified ACS. It will extract it by default. 
+You can use the `download-acs` command to download the zip file containing the data for the specified ACS. It will extract it by default.
 
 This command requires at least the `year` and `state` of the survey to download.
 
@@ -98,4 +98,4 @@ ca_2023.download(data_directory="./data/")
 
 # to use it as a dataframe
 ca_2023_df = ca_2023.as_dataframe()
-```
+```

mkdocs.yml

@@ -6,7 +6,7 @@ nav:
   - User guide:
     - Installation: user-guide/installation.md
     - Usage: user-guide/usage.md
-  - API reference: 
+  - API reference:
     - Surveys (ACS): reference/surveys.md
     - CLI: reference/cli.md
   - About:
@@ -24,7 +24,7 @@ plugins:
           options:
             show_source: false
             show_root_heading: true
-  
+
 markdown_extensions:
     - smarty
     - toc:

pyproject.toml

@@ -14,6 +14,7 @@ dependencies = [
     "us>=2.0.2",
     "httpx>=0.22.0",
     "pandas>=1.1.0",
+    "pyarrow>=10.0.0",
     "rich>=11.0.0",
     "typer>=0.4.0",
 ]