morpc-census 0.1.0__tar.gz

morpc_census-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

morpc_census-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "**"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install morpc-py (private dependency)
+        run: |
+          git clone https://github.com/morpc/morpc-py.git /tmp/morpc-py
+          pip install /tmp/morpc-py/
+
+      - name: Install morpc-census
+        run: pip install -e ".[dev]"
+
+      - name: Run offline tests
+        run: pytest -m "not network" --tb=short
+
+  build:
+    name: Build check
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Install morpc-py (private dependency)
+        run: |
+          git clone https://github.com/morpc/morpc-py.git /tmp/morpc-py
+          pip install /tmp/morpc-py/
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check distribution
+        run: twine check dist/*

morpc_census-0.1.0/.github/workflows/deploy.yml

@@ -0,0 +1,49 @@
+# This file was created automatically with `myst init --gh-pages` 🪄 💚
+# Ensure your GitHub Pages settings for this repository are set to deploy with **GitHub Actions**.
+
+name: MyST GitHub Pages Deploy
+on:
+  push:
+    # Runs on pushes targeting the default branch
+    branches: [main]
+env:
+  # `BASE_URL` determines, relative to the root of the domain, the URL that your site is served from.
+  # E.g., if your site lives at `https://mydomain.org/myproject`, set `BASE_URL=/myproject`.
+  # If, instead, your site lives at the root of the domain, at `https://mydomain.org`, set `BASE_URL=''`.
+  BASE_URL: /${{ github.event.repository.name }}
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: 'pages'
+  cancel-in-progress: false
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18.x
+      - name: Install MyST Markdown
+        run: npm install -g mystmd
+      - name: Build HTML Assets
+        run: myst build --html
+        working-directory: ./doc
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './doc/_build/html'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

morpc_census-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Install morpc-py (private dependency)
+        run: |
+          git clone https://github.com/morpc/morpc-py.git /tmp/morpc-py
+          pip install /tmp/morpc-py/
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check distribution
+        run: twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

morpc_census-0.1.0/.github/workflows/python-publish.yml

@@ -0,0 +1,73 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: windows-latest
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+    - name: Install pypa/build
+      run: >-
+        python3 -m
+        pip install
+        build
+        --user
+    - name: Build a binary wheel and a source tarball
+      run: python3 -m build
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
+    environment:
+      name: pypi
+      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
+      url: https://pypi.org/p/morpc
+      #
+      # ALTERNATIVE: if your GitHub Release name is the PyPI project version string
+      # ALTERNATIVE: exactly, uncomment the following line instead:
+      # url: https://pypi.org/project/morpc/${{ github.event.release.name }}
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

morpc_census-0.1.0/.github/workflows/todo_to_issue.yml

@@ -0,0 +1,38 @@
+name: "Run TODO to Issue"
+on:
+  push:
+  workflow_dispatch:
+    inputs:
+      MANUAL_COMMIT_REF:
+        description: "The SHA of the commit to get the diff for"
+        required: true
+      MANUAL_BASE_REF:
+        description: "By default, the commit entered above is compared to the one directly before it; to go back further, enter an earlier SHA here"
+        required: false
+jobs:
+  build:
+    runs-on: "ubuntu-latest"
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: "actions/checkout@v4"
+      - name: "TODO to Issue"
+        uses: "alstr/todo-to-issue-action@v5"
+        with:
+          INSERT_ISSUE_URLS: "true"
+          CLOSE_ISSUES: "true"
+      - name: Set Git user
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+      - name: Commit and Push Changes
+        run: |
+          git add -A
+          if [[ `git status --porcelain` ]]; then
+            git commit -m "Automatically added GitHub issue links to TODOs"
+            git push origin main
+          else
+            echo "No changes to commit"
+          fi

morpc_census-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+*.pyc
+__pycache__/
+*.pkl
+dist/
+build/
+morpc.egg-info/
+demo/
+*-checkpoint.*
+
+# MyST build outputs
+#_build
+*.env

morpc_census-0.1.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+## [0.1.0] — 2026-05-16
+
+Initial beta release.
+
+### Added
+
+- **`CensusAPI`** — fetches ACS/Decennial data by group or variable list, melts wide API response to a long-format DataFrame with `estimate`/`moe` columns, `concept`, `universe`, `survey`, `reference_period`, `geoidfq`, and `name`.
+- **`DimensionTable`** — reshapes a `CensusAPI.long` DataFrame into a MultiIndex wide table (`wide()`), computes column percentages with Census Bureau derived proportion MOEs (`percent()`), remaps variable labels (`remap()`), and drops dimension levels by name, integer index, or list (`drop()`). Dimension columns are ordered categoricals preserving Census API hierarchy order.
+- **`RaceDimensionTable`** — subclass of `DimensionTable` for analysing racial-iteration groups (e.g. B17020A–I). Normalises variable codes, concept, and universe across races, adds an ordered `race` column level, and computes within-race percentages.
+- **`Endpoint` / `Group`** — lazy-cached wrappers around the Census API metadata endpoints (vintages, groups, variables).
+- **`GeoIDFQ`** — parses, inspects, and constructs Census fully-qualified geographic IDs (e.g. `1400000US39049010100`).
+- **`Scope` / `SumLevel` / `SCOPES`** — named geographic extents and summary-level utilities for building Census API `for`/`in` query parameters.
+- **`fetch_geos_from_scope_sumlevel`** — fetches TIGERweb boundary GeoDataFrames for a named scope and summary level.
+- **`get_tigerweb_layers_map`** — returns a live layer-name → MapServer-ID mapping for ACS, Decennial, or Current TIGERweb services.
+- **`morpc_census.constants`** — lookup tables for age groups, race, education, income-to-poverty, and NTD categories.
+- Frictionless schema and resource file generation via `CensusAPI.save()`.
+- `@pytest.mark.network` test suite for live API calls; full offline suite runnable without a Census API key.
+
+### Changed
+
+- `HIGHLEVEL_DESC_FROM_ID` renamed to `HIGHLEVEL_DESC_TO_ID` (the dict maps descriptions *to* IDs, not from them).
+- `DimensionTable.variable_type` renamed to `value_cols`.
+- `find_replace_variable_map` parameter `map` renamed to `label_map` (avoids shadowing the Python builtin).
+- `CensusAPI.melt()` refactored into focused private helpers (`_melt_wide_to_long`, `_attach_dataset_metadata`, `_pivot_and_coerce`).
+- `wide()` column MultiIndex now uses canonical level order (`concept > universe > survey > geoidfq > name > [race] > reference_period > value_type`) and names the value-type level `'value_type'` instead of `None`.
+- `percent()` MOE now uses the Census Bureau derived proportion formula.
+- `_get_api_key()` and `get_all_avail_endpoints()` are `@functools.cache`-decorated (no repeated filesystem/network calls).
+- `get_tigerweb_layers_map` accepts `survey='current'` (no year required).
+
+### Fixed
+
+- Python 3.10/3.11 syntax error in `geos.py` (`Scope.sql` f-string nesting).
+- `NAME` column missing from variable-batch fetch results.
+- `set_levels` race-ordering bug that swapped column labels without moving data.

morpc_census-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing to morpc-census
+
+## Setup
+
+```bash
+# 1. Install the private morpc dependency
+git clone https://github.com/morpc/morpc-py.git
+pip install /path/to/morpc-py/
+
+# 2. Clone and install morpc-census in editable mode
+git clone https://github.com/jinskeep-morpc/morpc-census.git
+pip install -e /path/to/morpc-census/[dev]
+```
+
+## Running tests
+
+```bash
+# Offline tests only (no Census API key required)
+pytest
+
+# Include live network tests (requires CENSUS_API_KEY in environment or .env)
+pytest -m network
+```
+
+Tests are split by the `network` marker. The default `pytest` run (`-m 'not network'`) is safe to run locally without credentials.
+
+## Making changes
+
+1. Create a GitHub issue describing the problem and intended solution.
+2. Create a branch (one branch per roadmap phase or per logical feature).
+3. Make changes and commit in logical chunks.
+4. Write tests for all changed behavior.
+5. Append a dated entry to `reference/dev_notes.md` summarising the change.
+6. Open a pull request and request review.
+
+## Versioning
+
+This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html): `MAJOR.MINOR.PATCH`.
+
+| Increment | When |
+|-----------|------|
+| `PATCH`   | Backwards-compatible bug fixes |
+| `MINOR`   | New backwards-compatible functionality |
+| `MAJOR`   | Breaking changes to the public API |
+
+**Breaking changes** include:
+- Removing or renaming public functions, classes, or parameters
+- Changing return types or shapes in a way callers must update for
+- Dropping support for a previously supported Python version
+
+Breaking changes must be noted in `CHANGELOG.md` under the relevant version entry before the release is tagged.
+
+## Releasing
+
+1. Update `CHANGELOG.md` — move items from `[Unreleased]` to a new `[X.Y.Z]` section.
+2. Create and push a git tag: `git tag vX.Y.Z && git push origin vX.Y.Z`.
+3. Create a GitHub release from the tag — this triggers the publish workflow.

morpc_census-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: morpc-census
+Version: 0.1.0
+Summary: Census data tools used by MORPC
+Author-email: MORPC data team <dataandmaps@morpc.org>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: morpc>=0.4.3
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: geopandas>=0.14
+Requires-Dist: frictionless>=5.0
+Requires-Dist: requests>=2.28
+Requires-Dist: shapely>=2.0
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# morpc-census
+
+## Introduction
+
+`morpc-census` is a Python package maintained by the MORPC data team for working with US Census Bureau data. It provides tools for connecting to the Census API, retrieving survey data, and structuring results as long-format tables with [frictionless](https://github.com/frictionlessdata/frictionless-py) metadata.
+
+This package depends on [morpc-py](https://github.com/morpc/morpc-py) for shared MORPC utilities.
+
+### Modules
+
+- **morpc_census.api** — Census API client (`Endpoint`, `Group`, `CensusAPI`) and data structuring classes (`DimensionTable`, `RaceDimensionTable`) for reshaping results into long- and wide-format DataFrames with frictionless metadata.
+- **morpc_census.geos** — Geography utilities: `Scope` (named query extents), `SumLevel` (summary level codes), `GeoIDFQ` (GEOID parser/builder), and functions for translating between Census GEOIDs and MORPC geography definitions.
+- **morpc_census.tigerweb** — Fetches GeoDataFrames from the Census TIGERweb REST API.
+- **morpc_census.constants** — Domain lookup tables for age groups, race, education, income-to-poverty, and NTD categories.
+
+## Installation
+
+`morpc-census` depends on [morpc-py](https://github.com/morpc/morpc-py), a private MORPC utility package that is not on PyPI. Install it manually before installing `morpc-census`:
+
+```bash
+# 1. Install the private morpc dependency first
+git clone https://github.com/morpc/morpc-py.git
+pip install /path/to/morpc-py/
+
+# 2. Install morpc-census
+pip install morpc-census
+```
+
+### Dev Install
+
+To install an editable version for development:
+
+```bash
+# 1. Install the private morpc dependency
+git clone https://github.com/morpc/morpc-py.git
+pip install /path/to/morpc-py/
+
+# 2. Clone and install morpc-census in editable mode
+git clone https://github.com/jinskeep-morpc/morpc-census.git
+pip install -e /path/to/morpc-census/
+```
+
+Then import as:
+
+```python
+import morpc_census
+```
+
+## Usage
+
+```python
+from morpc_census import Endpoint, Group, CensusAPI, DimensionTable, RaceDimensionTable, SCOPES, SumLevel
+
+ep  = Endpoint('acs/acs5', 2023)
+grp = Group(ep, 'B01001')
+
+# Fetch ACS 5-year age/sex data for counties in the 15-county region
+api = CensusAPI(ep, SCOPES['region15'], group=grp, sumlevel=SumLevel('county'))
+
+# Long-format DataFrame
+print(api.long.head())
+
+# Reshape into wide MultiIndex table and compute percentages
+table = DimensionTable(api.long)
+wide  = table.wide()
+pct   = table.percent()
+
+# Save data + frictionless schema + resource to disk
+api.save('./output')
+```
+
+## Demos and Documentation
+
+See [demos](https://jinskeep-morpc.github.io/morpc-census/) for examples and documentation.
+
+---
+
+## Roadmap — Code Improvements
+
+- [x] Fix Python 3.10/3.11 syntax bug in `geos.py`
+- [x] Cache `_get_api_key()`
+- [x] Replace global `_avail_endpoints_cache` with `@functools.cache`
+- [x] Avoid double-computing `wide()` inside `percent()`
+- [x] Rename `DimensionTable.variable_type` → `value_cols`
+- [x] Rename `map` parameter in `find_replace_variable_map` → `label_map`
+- [x] Split `CensusAPI.melt()` into focused private helpers
+- [x] Pin `numpy` as an explicit dependency
+- [x] Add minimum version pins to all dependencies
+- [x] Add module docstrings to `geos.py` and `tigerweb.py`
+- [x] Validate or auto-fetch `tigerweb.py` `current_endpoints`
+
+---
+
+## Roadmap — Production Readiness & PyPI Release
+
+### Phase 1 — Pre-release cleanup
+
+- [x] Apply all code improvement items above
+- [x] Fix the README usage example
+- [x] Expand test coverage for offline paths (`wide()`, `percent()`, `remap()`, `drop()`, `melt()`)
+- [x] Update `pyproject.toml` classifier from `Development Status :: 1 - Planning` to `4 - Beta`
+- [x] Add a `CHANGELOG.md`
+- [x] Add a `py.typed` marker file
+
+### Phase 2 — Dependency audit
+
+- [x] Assess whether `morpc` can be published to PyPI or replaced
+- [x] Document installation order if `morpc` remains a private dependency
+- [x] Pin `morpc` to a minimum version in `pyproject.toml`
+
+### Phase 3 — CI/CD
+
+- [x] Add GitHub Actions CI workflow (`pytest -m "not network"` on push/PR, Python 3.10–3.12)
+- [x] Add build verification step (`python -m build` + `twine check`)
+- [x] Add publish workflow triggered on release tags
+
+### Phase 4 — Versioning & release
+
+- [x] Switch to dynamic versioning via `setuptools-scm`
+- [x] Tag `v0.1.0` and publish first release
+- [x] Document versioning policy and breaking-change rules in `CONTRIBUTING.md`
+
+### Phase 5 — Documentation
+
+- [ ] Auto-generate API reference docs from docstrings
+- [ ] Add `CONTRIBUTING.md` with setup instructions and PR process
+- [ ] Add usage examples to docstrings for commonly called functions
+
+---
+
+This product uses the Census Bureau Data API but is not endorsed or certified by the Census Bureau.

morpc_census-0.1.0/README.md

@@ -0,0 +1,131 @@
+# morpc-census
+
+## Introduction
+
+`morpc-census` is a Python package maintained by the MORPC data team for working with US Census Bureau data. It provides tools for connecting to the Census API, retrieving survey data, and structuring results as long-format tables with [frictionless](https://github.com/frictionlessdata/frictionless-py) metadata.
+
+This package depends on [morpc-py](https://github.com/morpc/morpc-py) for shared MORPC utilities.
+
+### Modules
+
+- **morpc_census.api** — Census API client (`Endpoint`, `Group`, `CensusAPI`) and data structuring classes (`DimensionTable`, `RaceDimensionTable`) for reshaping results into long- and wide-format DataFrames with frictionless metadata.
+- **morpc_census.geos** — Geography utilities: `Scope` (named query extents), `SumLevel` (summary level codes), `GeoIDFQ` (GEOID parser/builder), and functions for translating between Census GEOIDs and MORPC geography definitions.
+- **morpc_census.tigerweb** — Fetches GeoDataFrames from the Census TIGERweb REST API.
+- **morpc_census.constants** — Domain lookup tables for age groups, race, education, income-to-poverty, and NTD categories.
+
+## Installation
+
+`morpc-census` depends on [morpc-py](https://github.com/morpc/morpc-py), a private MORPC utility package that is not on PyPI. Install it manually before installing `morpc-census`:
+
+```bash
+# 1. Install the private morpc dependency first
+git clone https://github.com/morpc/morpc-py.git
+pip install /path/to/morpc-py/
+
+# 2. Install morpc-census
+pip install morpc-census
+```
+
+### Dev Install
+
+To install an editable version for development:
+
+```bash
+# 1. Install the private morpc dependency
+git clone https://github.com/morpc/morpc-py.git
+pip install /path/to/morpc-py/
+
+# 2. Clone and install morpc-census in editable mode
+git clone https://github.com/jinskeep-morpc/morpc-census.git
+pip install -e /path/to/morpc-census/
+```
+
+Then import as:
+
+```python
+import morpc_census
+```
+
+## Usage
+
+```python
+from morpc_census import Endpoint, Group, CensusAPI, DimensionTable, RaceDimensionTable, SCOPES, SumLevel
+
+ep  = Endpoint('acs/acs5', 2023)
+grp = Group(ep, 'B01001')
+
+# Fetch ACS 5-year age/sex data for counties in the 15-county region
+api = CensusAPI(ep, SCOPES['region15'], group=grp, sumlevel=SumLevel('county'))
+
+# Long-format DataFrame
+print(api.long.head())
+
+# Reshape into wide MultiIndex table and compute percentages
+table = DimensionTable(api.long)
+wide  = table.wide()
+pct   = table.percent()
+
+# Save data + frictionless schema + resource to disk
+api.save('./output')
+```
+
+## Demos and Documentation
+
+See [demos](https://jinskeep-morpc.github.io/morpc-census/) for examples and documentation.
+
+---
+
+## Roadmap — Code Improvements
+
+- [x] Fix Python 3.10/3.11 syntax bug in `geos.py`
+- [x] Cache `_get_api_key()`
+- [x] Replace global `_avail_endpoints_cache` with `@functools.cache`
+- [x] Avoid double-computing `wide()` inside `percent()`
+- [x] Rename `DimensionTable.variable_type` → `value_cols`
+- [x] Rename `map` parameter in `find_replace_variable_map` → `label_map`
+- [x] Split `CensusAPI.melt()` into focused private helpers
+- [x] Pin `numpy` as an explicit dependency
+- [x] Add minimum version pins to all dependencies
+- [x] Add module docstrings to `geos.py` and `tigerweb.py`
+- [x] Validate or auto-fetch `tigerweb.py` `current_endpoints`
+
+---
+
+## Roadmap — Production Readiness & PyPI Release
+
+### Phase 1 — Pre-release cleanup
+
+- [x] Apply all code improvement items above
+- [x] Fix the README usage example
+- [x] Expand test coverage for offline paths (`wide()`, `percent()`, `remap()`, `drop()`, `melt()`)
+- [x] Update `pyproject.toml` classifier from `Development Status :: 1 - Planning` to `4 - Beta`
+- [x] Add a `CHANGELOG.md`
+- [x] Add a `py.typed` marker file
+
+### Phase 2 — Dependency audit
+
+- [x] Assess whether `morpc` can be published to PyPI or replaced
+- [x] Document installation order if `morpc` remains a private dependency
+- [x] Pin `morpc` to a minimum version in `pyproject.toml`
+
+### Phase 3 — CI/CD
+
+- [x] Add GitHub Actions CI workflow (`pytest -m "not network"` on push/PR, Python 3.10–3.12)
+- [x] Add build verification step (`python -m build` + `twine check`)
+- [x] Add publish workflow triggered on release tags
+
+### Phase 4 — Versioning & release
+
+- [x] Switch to dynamic versioning via `setuptools-scm`
+- [x] Tag `v0.1.0` and publish first release
+- [x] Document versioning policy and breaking-change rules in `CONTRIBUTING.md`
+
+### Phase 5 — Documentation
+
+- [ ] Auto-generate API reference docs from docstrings
+- [ ] Add `CONTRIBUTING.md` with setup instructions and PR process
+- [ ] Add usage examples to docstrings for commonly called functions
+
+---
+
+This product uses the Census Bureau Data API but is not endorsed or certified by the Census Bureau.