ocpf 0.1.0__py3-none-any.whl

ocpf-0.1.0.dist-info/METADATA

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: ocpf
+Version: 0.1.0
+Summary: An opinionated command-line interface to the OCPF (Massachusetts campaign finance) API
+Project-URL: Homepage, https://github.com/bwbensonjr/ocpf-cli
+Project-URL: Repository, https://github.com/bwbensonjr/ocpf-cli
+Project-URL: Issues, https://github.com/bwbensonjr/ocpf-cli/issues
+Author-email: Brent Benson <bwbensonjr@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: campaign-finance,cli,elections,massachusetts,ocpf,politics
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# OCPF Command Line Interface
+
+`ocpf` is an opinionated command-line interface to the Massachusetts
+[Office of Campaign and Political Finance](https://www.ocpf.us/) (OCPF) API
+(`https://api.ocpf.us/`). It turns a recurring, multi-step lookup — "who is
+running in this district and how much have they raised and spent?" — into a
+single command.
+
+## Install
+
+Run it with no install at all using [`uvx`](https://docs.astral.sh/uv/):
+
+```bash
+uvx ocpf race 37th
+```
+
+Or install the `ocpf` command onto your PATH:
+
+```bash
+pipx install ocpf     # isolated, recommended
+pip install ocpf      # into the current environment
+```
+
+Then:
+
+```bash
+ocpf --help
+```
+
+## Usage
+
+```bash
+ocpf race <district> [--year <year>] [--json]
+```
+
+`ocpf race` produces a year-to-date (YTD) financial summary of the legislative
+(House or Senate) candidates in a district.
+
+- `<district>` may be a **name** matched case-insensitively against OCPF's
+  district descriptions (`&` and `and` are treated alike) or a **raw numeric
+  district code**. Ambiguous names are never guessed — the tool prints the
+  matching districts with their codes and exits so you can pick one.
+- `--year` defaults to the current calendar year.
+- `--json` emits the merged, filtered candidate records (including the
+  underlying `*Numeric` values) as JSON to stdout. Human status/progress goes
+  to stderr, so JSON output stays pipeable.
+
+### Example
+
+```bash
+$ ocpf race "Suffolk and Middlesex" --year 2026
+District:  Senate, Suffolk and Middlesex (code 166)
+Election:  primary 9/1/2026, general 11/3/2026
+As of:     6/30/2026 (year-to-date, cumulative)
+
+Candidate                 Party  Inc   Raised YTD    Spent YTD  Cash on Hand
+------------------------  -----  ---  -----------  -----------  ------------
+Brownsberger, William N.  -      *    $265,435.76  $135,490.74   $326,673.49
+Lander, Daniel            -           $117,740.53   $32,674.59   $136,386.28
+Wood, Brandon             -                $80.00        $3.00        $77.00
+
+* incumbent (holds this seat)
+```
+
+Election dates and the as-of date are **timeline context**. The money is the
+single cumulative YTD figure the API provides for each candidate; it is never
+split into per-primary and per-general amounts.
+
+### `ocpf filer` — one candidate's filing summary
+
+```bash
+ocpf filer <filer> [--year <year>] [--json]
+```
+
+`ocpf filer` drills into a single filer: their committee profile, cumulative
+YTD finances, and most recent reports.
+
+- `<filer>` may be a **raw numeric cpfId** (works for any filer type) or a
+  **candidate name** matched case-insensitively against the legislative field
+  for the year. cpfIds are shown by `ocpf race`. As with district names,
+  ambiguous names are never guessed — the tool prints the matching filers with
+  their cpfIds and exits. Name lookup covers legislative filers; for other
+  filer types, pass a cpfId directly.
+- `--year` defaults to the current calendar year (used for name resolution and
+  YTD context).
+- `--json` emits the `filer`, `ytdReport`, and `logReports` records (including
+  numeric values) to stdout.
+
+```bash
+$ ocpf filer "Brownsberger" --year 2026
+Filer:      Brownsberger, William N.  (cpfId 14454)
+Committee:  Brownsberger Committee
+Party:      Democratic    Type: Legislative Candidates
+Office:     Senate, Suffolk and Middlesex
+Status:     active
+Organized:  12/13/2005
+Treasurer:  David Merfeld
+
+Year-to-date (as of 6/30/2026):
+  Raised YTD:    $265,435.76
+  Spent YTD:     $135,490.74
+  Cash on Hand:  $326,673.49
+
+Recent reports:
+Type            Period   Filed            Receipts  Expenditures
+--------------  -------  --------------  ---------  ------------
+Deposit Report  7/20/26  Mon, 7/20/2026    $500.00         $0.00
+...
+```
+
+## Scope
+
+v1 covers **legislative** races (House and Senate). Other office types
+(statewide, county, mayoral, ballot question), drill-down into individual
+reports/donors/expenditures, and free-text candidate-name search are out of
+scope. See `openspec/` for the design and specifications.
+
+## Development
+
+The project is managed with [`uv`](https://docs.astral.sh/uv/). From a clone of
+this repository:
+
+```bash
+uv sync --extra dev     # runtime deps + pytest/respx
+uv run pytest           # run the test suite
+uv run ocpf race 37th   # run the CLI from source
+```
+
+## Releasing
+
+Releases are published to PyPI automatically by GitHub Actions when a version tag
+is pushed. Versioning is tag-driven (via `hatch-vcs`), so the tag is the single
+source of truth for the package version:
+
+```bash
+git tag v0.1.0
+git push --tags
+```
+
+The release workflow runs the test suite, builds the sdist and wheel, and
+publishes to PyPI using [Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
+(OIDC) — no API token is stored in the repository.
+
+**First release only:** before pushing the first tag, register a *pending*
+Trusted Publisher on PyPI (Your projects → Publishing) so the initial upload can
+create the project:
+
+- PyPI project name: `ocpf`
+- Owner: `bwbensonjr`  ·  Repository: `ocpf-cli`
+- Workflow: `release.yml`  ·  Environment: `pypi`
+
+## Design Guidelines
+
+- Use OpenSpec to draft designs and create change proposals.
+- Use [clig.dev](https://clig.dev/) for command line interface guidelines.
+- Use the `github.com/bwbensonjr/ocpf-analysis` repository (available
+  locally) for information about the OCPF APIs, especially the `/api`
+  directory which contains `ENDPOINT-STATUS.md` and other script and
+  OCPF API test code.
+- Use the `github.com/bwbensonjr/ma-election-db` repository (available
+  locally) for information on candidates and districts we might want
+  to look up.

ocpf-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+ocpf_cli/__init__.py,sha256=v9NPEHoM3NguJ5wWtiw60cF0ZL6Iar0q5gz5EKHipl8,94
+ocpf_cli/api.py,sha256=4m8koY0hM3bpdH5KMQxKexPYXMWjhLVWXyecw8QNlYc,2298
+ocpf_cli/cli.py,sha256=Llw7bzbl7dXh3Urqe0y6gMHcru_TV_azX2nUEnwORw0,911
+ocpf_cli/districts.py,sha256=BBdvCECvdmBd6V0FaARZJdVcnVU6i-EEDuyzjHENomY,3738
+ocpf_cli/legislative.py,sha256=vazG2OTHoqlanG_hIx4MS509adJGbQH1l9emmdtaWwU,4111
+ocpf_cli/render.py,sha256=J_kvGf6Zqoyn7X3vRYvx2Baon_3W61-4uLRLCLIFzFE,2727
+ocpf_cli/commands/__init__.py,sha256=_AADeyIQCA5GT0tAHVldze53scgIXA-EvUxISO5bxEA,36
+ocpf_cli/commands/filer.py,sha256=_wmU8YopX1UI2a9DR7AMYGzHzlOsjaak4taRrC0J3K0,7300
+ocpf_cli/commands/race.py,sha256=nKGqd4K9cE009HeAD8zo8VVb0XNrknvVf4sWRTr6ZhU,8207
+ocpf-0.1.0.dist-info/METADATA,sha256=tfKWbo8KL24vWvDlX9dFzL53-HrADX59kzpZgchjDFU,6755
+ocpf-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+ocpf-0.1.0.dist-info/entry_points.txt,sha256=WYlJK_0txq2VvbmbkLXuE3ZlonlGy9pyuJjHalcxZTE,42
+ocpf-0.1.0.dist-info/licenses/LICENSE,sha256=ebfY9LaFkb36Mhe17raVRibZx12WMYkVk3EhohZ0iP0,1069
+ocpf-0.1.0.dist-info/RECORD,,

ocpf-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ocpf-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ocpf = ocpf_cli.cli:app

ocpf-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brent Benson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ocpf_cli/__init__.py

@@ -0,0 +1,3 @@
+"""ocpf-cli: an opinionated command-line interface to the OCPF API."""
+
+__version__ = "0.1.0"

ocpf_cli/api.py

@@ -0,0 +1,80 @@
+"""Shared HTTP client for the OCPF REST API.
+
+All network access to `https://api.ocpf.us/` funnels through `get_json`, so
+commands stay testable (mock one function) and error handling lives in one
+place. Failures surface as `OcpfApiError` rather than raw library exceptions.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+BASE_URL = "https://api.ocpf.us/"
+
+# Default per-request timeout in seconds. The OCPF API is generally fast, but
+# some report-page endpoints return hundreds of rows.
+DEFAULT_TIMEOUT = 30.0
+
+
+class OcpfApiError(Exception):
+    """A failure talking to the OCPF API.
+
+    Carries the requested `path` and, for HTTP errors, the `status_code`.
+    Network and timeout failures leave `status_code` as None.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        path: str,
+        status_code: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.path = path
+        self.status_code = status_code
+
+
+def get_json(
+    path: str,
+    params: dict[str, Any] | None = None,
+    *,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> Any:
+    """GET `path` from the OCPF API and return the parsed JSON body.
+
+    `path` is joined onto `BASE_URL`; a leading slash is tolerated. Raises
+    `OcpfApiError` on any HTTP 4xx/5xx status, network failure, timeout, or
+    unparseable body.
+    """
+    url = BASE_URL + path.lstrip("/")
+    try:
+        response = httpx.get(url, params=params, timeout=timeout)
+    except httpx.TimeoutException as exc:
+        raise OcpfApiError(
+            f"Request to {path} timed out after {timeout:g}s",
+            path=path,
+        ) from exc
+    except httpx.HTTPError as exc:
+        raise OcpfApiError(
+            f"Network error requesting {path}: {exc}",
+            path=path,
+        ) from exc
+
+    if response.status_code >= 400:
+        raise OcpfApiError(
+            f"OCPF API returned HTTP {response.status_code} for {path}",
+            path=path,
+            status_code=response.status_code,
+        )
+
+    try:
+        return response.json()
+    except ValueError as exc:
+        raise OcpfApiError(
+            f"OCPF API returned a non-JSON response for {path}",
+            path=path,
+            status_code=response.status_code,
+        ) from exc

ocpf_cli/cli.py

@@ -0,0 +1,35 @@
+"""Typer application: the `ocpf` command and its subcommands."""
+
+from __future__ import annotations
+
+import typer
+
+from .commands.filer import filer
+from .commands.race import race
+
+app = typer.Typer(
+    name="ocpf",
+    help="Query the Massachusetts OCPF campaign-finance API from the command line.",
+    add_completion=False,
+)
+
+
+@app.callback(invoke_without_command=True)
+def main(ctx: typer.Context) -> None:
+    """Query the OCPF campaign-finance API from the command line.
+
+    With no subcommand, print top-level help and exit successfully. The
+    callback also keeps the app in multi-command (group) mode so that `race`
+    stays a named subcommand rather than collapsing into the root command.
+    """
+    if ctx.invoked_subcommand is None:
+        print(ctx.get_help())
+        raise typer.Exit(code=0)
+
+
+app.command("race")(race)
+app.command("filer")(filer)
+
+
+if __name__ == "__main__":
+    app()

ocpf_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Subcommands for the ocpf CLI."""

ocpf_cli/commands/filer.py

@@ -0,0 +1,217 @@
+"""`ocpf filer` — profile, YTD finances, and recent reports for one filer.
+
+Pipeline: resolve the argument to a `cpfId` (a bare integer is used directly; a
+name is matched against the legislative field for the year) -> fetch
+`filer/payload/{cpfId}` in one call -> render the profile, YTD line, and recent
+filing log (or JSON).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from typing import Any
+
+import typer
+
+from .. import api, render
+from ..legislative import fetch_merged_field
+
+FILER_PAYLOAD_PATH = "filer/payload/{cpf_id}"
+
+
+@dataclass(frozen=True)
+class FilerMatch:
+    """A candidate name match from the legislative field."""
+
+    cpf_id: int
+    name: str
+    office: str
+
+
+class FilerResolutionError(Exception):
+    """Name resolution failed. `matches` is populated for the ambiguous case."""
+
+    def __init__(self, message: str, *, matches: list[FilerMatch] | None = None) -> None:
+        super().__init__(message)
+        self.matches = matches or []
+
+
+def _normalize(text: str) -> str:
+    """Lowercase and collapse whitespace for forgiving name matching."""
+    return " ".join(text.lower().split())
+
+
+def resolve_filer(query: str, year: int) -> int:
+    """Resolve `query` to a single `cpfId`.
+
+    A bare integer is used directly (works for any filer type). Otherwise the
+    value is matched case-insensitively against `filerName` in the legislative
+    field for `year`; ambiguity is never guessed away.
+    """
+    stripped = query.strip()
+    if stripped.lstrip("-").isdigit():
+        return int(stripped)
+
+    target = _normalize(query)
+    field = fetch_merged_field(year)
+    matches = [
+        FilerMatch(
+            cpf_id=row.get("cpfId"),
+            name=row.get("filerName", ""),
+            office=row.get("officeSought", ""),
+        )
+        for row in field
+        if target in _normalize(row.get("filerName", ""))
+    ]
+
+    if len(matches) == 1:
+        return matches[0].cpf_id
+    if len(matches) == 0:
+        raise FilerResolutionError(
+            f'"{query}" matches no legislative filer for {year}; '
+            f"pass a numeric cpfId directly to look up any filer"
+        )
+    raise FilerResolutionError(
+        f'"{query}" matches more than one legislative filer',
+        matches=matches,
+    )
+
+
+def fetch_filer_payload(cpf_id: int) -> dict:
+    """Fetch `filer/payload/{cpfId}`; raise on an unknown/invalid cpfId.
+
+    OCPF returns HTTP 400 for an out-of-range cpfId; we translate that into a
+    clear "no filer found" error rather than a bare HTTP message.
+    """
+    try:
+        payload = api.get_json(FILER_PAYLOAD_PATH.format(cpf_id=cpf_id))
+    except api.OcpfApiError as exc:
+        if exc.status_code == 400:
+            raise FilerResolutionError(f"No filer found for cpfId {cpf_id}") from exc
+        raise
+
+    if not isinstance(payload, dict) or not payload.get("filer"):
+        raise FilerResolutionError(f"No filer found for cpfId {cpf_id}")
+    return payload
+
+
+def _office_str(value: Any) -> str:
+    """Render an office field that may be a string or a nested object."""
+    if isinstance(value, dict):
+        return value.get("officeDistrict") or value.get("display") or ""
+    return value or ""
+
+
+def _render_summary(payload: dict) -> None:
+    """Print the human-readable profile, YTD line, and recent-reports table."""
+    filer = payload.get("filer", {})
+
+    name = filer.get("fullNameReverse") or filer.get("fullName") or ""
+    print(f"Filer:      {name}  (cpfId {filer.get('cpfId')})")
+    if filer.get("committeeName"):
+        print(f"Committee:  {filer.get('committeeName')}")
+    party = filer.get("partyAffiliation") or "-"
+    acct = filer.get("accountType", {}).get("description", "")
+    print(f"Party:      {party}" + (f"    Type: {acct}" if acct else ""))
+
+    office = _office_str(filer.get("officeSoughtDescription") or filer.get("officeSought"))
+    if office:
+        print(f"Office:     {office}")
+    held = _office_str(filer.get("officeHeld"))
+    if held and held != office:
+        print(f"Holds:      {held}")
+
+    if filer.get("isActive") and not filer.get("closedDate"):
+        status = "active"
+    else:
+        status = "closed"
+        if filer.get("closedDate"):
+            status += f" ({filer.get('closedDate')})"
+    print(f"Status:     {status}")
+    if filer.get("organizationDate"):
+        print(f"Organized:  {filer.get('organizationDate')}")
+
+    treasurer = filer.get("treasurer") or {}
+    if isinstance(treasurer, dict) and treasurer.get("fullName"):
+        print(f"Treasurer:  {treasurer.get('fullName')}")
+
+    # Year-to-date finances (single cumulative figure, never split by election).
+    ytd = payload.get("ytdReport") or {}
+    print()
+    if ytd:
+        as_of = ytd.get("bankReportEndDate")
+        suffix = f" (as of {as_of})" if as_of else ""
+        print(f"Year-to-date{suffix}:")
+        print(f"  Raised YTD:    {render.format_currency(ytd.get('receiptsYtdNumeric'))}")
+        print(f"  Spent YTD:     {render.format_currency(ytd.get('expendituresYtdNumeric'))}")
+        print(f"  Cash on Hand:  {render.format_currency(ytd.get('currentCashOnHandNumeric'))}")
+    else:
+        print("Year-to-date: no current summary on file")
+
+    # Recent filing log.
+    logs = payload.get("logReports") or []
+    print()
+    if not logs:
+        print("Recent reports: none found")
+        return
+    print("Recent reports:")
+    rows = [
+        [
+            log.get("reportTypeDescription", ""),
+            log.get("reportingPeriod", ""),
+            log.get("dateFiledHeader", "") or log.get("dateFiled", ""),
+            log.get("receiptTotal", ""),
+            log.get("expenditureTotal", ""),
+        ]
+        for log in logs
+    ]
+    headers = ["Type", "Period", "Filed", "Receipts", "Expenditures"]
+    print(render.render_table(rows, headers, right_align=[3, 4]))
+
+
+def filer(
+    filer: str = typer.Argument(
+        ..., help="Numeric cpfId, or a candidate name (legislative filers)"
+    ),
+    year: int = typer.Option(
+        None, "--year", help="Year for name resolution / YTD context (default: current)"
+    ),
+    json_output: bool = typer.Option(
+        False, "--json", help="Emit the filer profile, YTD, and reports as JSON"
+    ),
+) -> None:
+    """Profile, year-to-date finances, and recent reports for a single filer."""
+    if year is None:
+        year = date.today().year
+
+    try:
+        cpf_id = resolve_filer(filer, year)
+    except FilerResolutionError as exc:
+        render.error(str(exc))
+        for m in exc.matches:
+            render.status(f"  {m.cpf_id}  {m.name}  ({m.office})")
+        raise typer.Exit(code=1)
+    except api.OcpfApiError as exc:
+        render.error(str(exc))
+        raise typer.Exit(code=1)
+
+    try:
+        payload = fetch_filer_payload(cpf_id)
+    except FilerResolutionError as exc:
+        render.error(str(exc))
+        raise typer.Exit(code=1)
+    except api.OcpfApiError as exc:
+        render.error(str(exc))
+        raise typer.Exit(code=1)
+
+    if json_output:
+        render.emit_json(
+            {
+                "filer": payload.get("filer"),
+                "ytdReport": payload.get("ytdReport"),
+                "logReports": payload.get("logReports"),
+            }
+        )
+    else:
+        _render_summary(payload)

ocpf_cli/commands/race.py

@@ -0,0 +1,244 @@
+"""`ocpf race` — YTD financial summary for a legislative district's candidates.
+
+Pipeline: resolve the district -> fetch and merge the depository + non-depository
+legislative feeds -> filter to the district -> add timeline context (election
+dates, as-of date) -> render a table (or JSON).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import typer
+
+from .. import api, render
+from ..districts import DistrictResolutionError, District, resolve_district
+from ..legislative import (
+    DEPOSITORY_PATH,
+    NON_DEPOSITORY_PATH,
+    fetch_finsummaries,
+    fetch_merged_field,
+    has_money,
+    normalize_finsummaries,
+    reports_of,
+)
+
+# Backwards-compatible alias: the merge helpers now live in `legislative`.
+_reports_of = reports_of
+
+
+def filter_by_district(rows: list[dict], code: int) -> list[dict]:
+    """Keep rows sought-for or held-in the given district code."""
+    return [
+        row
+        for row in rows
+        if row.get("districtCodeSought") == code
+        or row.get("districtCodeHeld") == code
+    ]
+
+
+def _parse_report_date(value: str | None) -> tuple[int, int, int] | None:
+    """Parse an `M/D/YYYY` OCPF date into a sortable `(y, m, d)` tuple."""
+    if not value:
+        return None
+    parts = value.split("/")
+    if len(parts) != 3:
+        return None
+    try:
+        month, day, year = (int(p) for p in parts)
+    except ValueError:
+        return None
+    return (year, month, day)
+
+
+@dataclass
+class Timeline:
+    """Timeline context for the summary header."""
+
+    primary_election_date: str | None
+    general_election_date: str | None
+    as_of_date: str | None
+    lagging_filers: list[str]
+
+
+def build_timeline(year: int, rows: list[dict]) -> Timeline:
+    """Fetch election dates and derive the as-of date from the matched rows.
+
+    The as-of date is the latest `bankReportEndDate` present; any row whose
+    date lags behind that is flagged so comparisons aren't silently uneven.
+    """
+    schedule = api.get_json(f"filingSchedules/{year}")
+    primary = schedule.get("primaryElectionDate") if isinstance(schedule, dict) else None
+    general = schedule.get("generalElectionDate") if isinstance(schedule, dict) else None
+
+    dated = [
+        (row, _parse_report_date(row.get("bankReportEndDate")))
+        for row in rows
+    ]
+    present = [(row, d) for row, d in dated if d is not None]
+
+    as_of_date: str | None = None
+    lagging: list[str] = []
+    if present:
+        latest = max(d for _, d in present)
+        as_of_row = next(row for row, d in present if d == latest)
+        as_of_date = as_of_row.get("bankReportEndDate")
+        lagging = [
+            row.get("filerName", "")
+            for row, d in present
+            if d != latest
+        ]
+
+    return Timeline(
+        primary_election_date=primary,
+        general_election_date=general,
+        as_of_date=as_of_date,
+        lagging_filers=lagging,
+    )
+
+
+def _is_incumbent(row: dict, code: int) -> bool:
+    # Historical (finsummaries) rows carry an explicit flag and a districtCode of
+    # 0, so they can't be matched on districtCodeHeld; current-cycle rows use the
+    # held-code comparison.
+    if "isIncumbent" in row:
+        return bool(row["isIncumbent"])
+    return row.get("districtCodeHeld") == code
+
+
+def _sort_key(row: dict) -> Any:
+    # Order by receipts descending (biggest fundraiser first), then name.
+    return (-(row.get("receiptsYtdNumeric") or 0), row.get("filerName", ""))
+
+
+def _render_table(
+    district: District,
+    rows: list[dict],
+    timeline: Timeline,
+    historical: bool = False,
+) -> None:
+    """Print the human-readable summary header and table to stdout.
+
+    Current-cycle data renders as a YTD snapshot with an as-of date. Historical
+    (finsummaries) data renders as final full-cycle totals: no as-of line,
+    final-total column labels, and a winner marker.
+    """
+    print(f"District:  {district.label} (code {district.code})")
+    dates = []
+    if timeline.primary_election_date:
+        dates.append(f"primary {timeline.primary_election_date}")
+    if timeline.general_election_date:
+        dates.append(f"general {timeline.general_election_date}")
+    if dates:
+        print(f"Election:  {', '.join(dates)}")
+    if timeline.as_of_date:
+        print(f"As of:     {timeline.as_of_date} (year-to-date, cumulative)")
+    print()
+
+    ordered = sorted(rows, key=_sort_key)
+    table_rows = []
+    for row in ordered:
+        incumbent = "*" if _is_incumbent(row, district.code) else ""
+        money = [
+            render.format_currency(row.get("receiptsYtdNumeric")),
+            render.format_currency(row.get("expendituresYtdNumeric")),
+            render.format_currency(row.get("currentCashOnHandNumeric")),
+        ]
+        base = [
+            row.get("filerName", ""),
+            row.get("partyAffiliation", "") or "-",
+            incumbent,
+        ]
+        if historical:
+            won = "W" if row.get("isWinner") else ""
+            table_rows.append(base + [won] + money)
+        else:
+            table_rows.append(base + money)
+
+    if historical:
+        headers = ["Candidate", "Party", "Inc", "Won", "Raised", "Spent", "End Bal"]
+        right_align = [4, 5, 6]
+    else:
+        headers = [
+            "Candidate",
+            "Party",
+            "Inc",
+            "Raised YTD",
+            "Spent YTD",
+            "Cash on Hand",
+        ]
+        right_align = [3, 4, 5]
+    print(render.render_table(table_rows, headers, right_align=right_align))
+    print()
+    print("* incumbent (holds this seat)")
+    # Only explain the winner marker when at least one candidate carries it;
+    # OCPF's isWinner is unset for some historical races (e.g. unopposed).
+    if historical and any(row.get("isWinner") for row in rows):
+        print("W won the general election")
+    if timeline.lagging_filers:
+        names = ", ".join(timeline.lagging_filers)
+        render.status(
+            f"note: figures for {names} are as of an earlier report than "
+            f"{timeline.as_of_date}"
+        )
+
+
+def race(
+    district: str = typer.Argument(
+        ..., help="District name (e.g. 'Suffolk and Middlesex') or numeric code"
+    ),
+    year: int = typer.Option(
+        None, "--year", help="Election/filing year (defaults to the current year)"
+    ),
+    json_output: bool = typer.Option(
+        False, "--json", help="Emit merged candidate records as JSON"
+    ),
+) -> None:
+    """Year-to-date financial summary of the candidates in a legislative district."""
+    if year is None:
+        # Avoid importing datetime at module load; current year is a runtime fact.
+        from datetime import date
+
+        year = date.today().year
+
+    try:
+        resolved = resolve_district(district)
+    except DistrictResolutionError as exc:
+        render.error(str(exc))
+        for cand in exc.candidates:
+            render.status(f"  {cand.code}  {cand.label}")
+        raise typer.Exit(code=1)
+    except api.OcpfApiError as exc:
+        render.error(str(exc))
+        raise typer.Exit(code=1)
+
+    try:
+        merged = fetch_merged_field(year)
+        matched = filter_by_district(merged, resolved.code)
+        historical = False
+        # The current-cycle feeds only carry money from ~2020 on. For earlier
+        # cycles they resolve names but leave the money blank, so fall back to
+        # the district-scoped historical summaries (final full-cycle totals).
+        if not has_money(matched):
+            hist_rows = normalize_finsummaries(
+                fetch_finsummaries(year, resolved.code)
+            )
+            if hist_rows:
+                matched = hist_rows
+                historical = True
+        if not matched:
+            render.error(
+                f"No candidates found for {resolved.label} (code "
+                f"{resolved.code}) in {year}"
+            )
+            raise typer.Exit(code=1)
+        timeline = build_timeline(year, matched)
+    except api.OcpfApiError as exc:
+        render.error(str(exc))
+        raise typer.Exit(code=1)
+
+    if json_output:
+        render.emit_json(sorted(matched, key=_sort_key))
+    else:
+        _render_table(resolved, matched, timeline, historical=historical)

ocpf_cli/districts.py

@@ -0,0 +1,116 @@
+"""District resolution: turn a `<district>` argument into one OCPF code.
+
+Resolution is district-first (the API's free-text filer search is dead). A raw
+numeric code is validated against the legislative set; otherwise the name is
+matched case-insensitively against district descriptions, restricted to
+legislative offices (House and Senate). Ambiguity is never guessed away.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from . import api
+
+# Office values in the `districts` reference that count as legislative.
+LEGISLATIVE_OFFICES = ("House", "Senate")
+
+
+@dataclass(frozen=True)
+class District:
+    """A single legislative district from the OCPF `districts` reference."""
+
+    code: int
+    office: str
+    description: str
+
+    @property
+    def label(self) -> str:
+        """Human label, e.g. `Senate, Suffolk and Middlesex`."""
+        return f"{self.office}, {self.description}"
+
+
+class DistrictResolutionError(Exception):
+    """Resolution failed. `candidates` is populated for the ambiguous case."""
+
+    def __init__(
+        self, message: str, *, candidates: list[District] | None = None
+    ) -> None:
+        super().__init__(message)
+        self.candidates = candidates or []
+
+
+def _normalize(text: str) -> str:
+    """Lowercase, collapse whitespace, and treat `&` and `and` alike.
+
+    So `"Suffolk and Middlesex"` and `"Suffolk & Middlesex"` normalize to the
+    same string, while `"Middlesex & Suffolk"` stays distinct (order matters).
+    """
+    lowered = text.lower().replace("&", " and ")
+    return " ".join(lowered.split())
+
+
+def fetch_legislative_districts() -> list[District]:
+    """Fetch the `districts` reference and keep only House/Senate offices."""
+    raw: Any = api.get_json("districts")
+    districts = []
+    for row in raw:
+        office = row.get("office", "")
+        if office in LEGISLATIVE_OFFICES:
+            districts.append(
+                District(
+                    code=int(row["code"]),
+                    office=office,
+                    description=row.get("description", ""),
+                )
+            )
+    return districts
+
+
+def resolve_district(
+    query: str, districts: list[District] | None = None
+) -> District:
+    """Resolve `query` to exactly one legislative `District`.
+
+    Raises `DistrictResolutionError` on no match or ambiguous match (with the
+    candidate list attached), so the caller can print options without guessing.
+    """
+    if districts is None:
+        districts = fetch_legislative_districts()
+
+    by_code = {d.code: d for d in districts}
+
+    # A bare integer is treated as a raw district code.
+    stripped = query.strip()
+    if stripped.lstrip("-").isdigit():
+        code = int(stripped)
+        if code in by_code:
+            return by_code[code]
+        raise DistrictResolutionError(
+            f"{code} is not a legislative (House/Senate) district code"
+        )
+
+    target = _normalize(query)
+
+    # Prefer an exact normalized-name match; fall back to substring matches.
+    exact = [d for d in districts if _normalize(d.description) == target]
+    if len(exact) == 1:
+        return exact[0]
+    if len(exact) > 1:
+        raise DistrictResolutionError(
+            f'"{query}" matches more than one legislative district',
+            candidates=exact,
+        )
+
+    matches = [d for d in districts if target in _normalize(d.description)]
+    if len(matches) == 1:
+        return matches[0]
+    if len(matches) == 0:
+        raise DistrictResolutionError(
+            f'"{query}" matches no legislative (House/Senate) district'
+        )
+    raise DistrictResolutionError(
+        f'"{query}" matches more than one legislative district',
+        candidates=matches,
+    )

ocpf_cli/legislative.py

@@ -0,0 +1,104 @@
+"""Shared access to the legislative YTD field.
+
+Both `ocpf race` and `ocpf filer` need the merged legislative field: `race`
+filters it by district, `filer` matches names against it. The fetch/merge logic
+lives here so there is one source of truth for the two feeds.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from . import api, render
+
+# The two legislative feeds. The depository feed is the fuller record (bank
+# reports) and wins on conflict; the non-depository feed catches smaller filers.
+DEPOSITORY_PATH = "reports/legislative/depository/ytd/{year}"
+NON_DEPOSITORY_PATH = "reports/legislative/race/nd/{year}"
+
+# Historical fallback. The current-cycle feeds above are only populated from
+# ~2020 on; earlier cycles live in this district-scoped endpoint, which returns
+# a bare list of final full-cycle totals (not a YTD snapshot).
+FINSUMMARIES_PATH = "onballot/finsummaries/{year}/{code}"
+
+
+def reports_of(payload: Any) -> list[dict]:
+    """Normalize a feed payload to a list of report rows.
+
+    The depository feed returns `{reports: [...], summary: {...}}`; the
+    non-depository feed returns a bare list. Either way we want the rows.
+    """
+    if isinstance(payload, dict):
+        return list(payload.get("reports", []))
+    if isinstance(payload, list):
+        return list(payload)
+    return []
+
+
+def fetch_merged_field(year: int) -> list[dict]:
+    """Fetch both legislative feeds and merge by `cpfId` (depository wins)."""
+    depository = reports_of(api.get_json(DEPOSITORY_PATH.format(year=year)))
+    non_depository = reports_of(api.get_json(NON_DEPOSITORY_PATH.format(year=year)))
+
+    merged: dict[Any, dict] = {}
+    # Seed with non-depository first so depository rows overwrite on conflict.
+    for row in non_depository:
+        merged[row.get("cpfId")] = row
+    for row in depository:
+        merged[row.get("cpfId")] = row
+    return list(merged.values())
+
+
+# The numeric money fields shared by the current-cycle feed rows and the
+# normalized historical rows. Used to decide whether a field actually has money.
+MONEY_FIELDS = (
+    "receiptsYtdNumeric",
+    "expendituresYtdNumeric",
+    "currentCashOnHandNumeric",
+)
+
+
+def has_money(rows: list[dict]) -> bool:
+    """True if any row carries a nonzero value in any money field.
+
+    Drives the historical fallback: the current-cycle feeds resolve names for
+    older cycles but leave the money blank, so "did we actually get money?" is
+    the signal to fall back to `finsummaries`.
+    """
+    return any(row.get(field) for row in rows for field in MONEY_FIELDS)
+
+
+def fetch_finsummaries(year: int, code: int) -> list[dict]:
+    """Fetch the district-scoped historical financial summaries (a bare list)."""
+    payload = api.get_json(FINSUMMARIES_PATH.format(year=year, code=code))
+    return list(payload) if isinstance(payload, list) else []
+
+
+def normalize_finsummaries(rows: list[dict]) -> list[dict]:
+    """Map `finsummaries` rows into the shared candidate-row shape.
+
+    The historical feed reports money as currency strings (`receipts`,
+    `expenditures`, `endBalance`) and carries `isIncumbent`/`isWinner` flags.
+    We parse the strings into the same numeric fields the current-cycle path
+    uses so rendering, sorting, and `--json` work unchanged. `districtCode` is
+    `0` on every row, so incumbency comes from the flag, not the code.
+    """
+    normalized = []
+    for row in rows:
+        normalized.append(
+            {
+                "cpfId": row.get("cpfId"),
+                "filerName": row.get("filerName", ""),
+                "partyAffiliation": row.get("partyAffiliation", ""),
+                "receiptsYtdNumeric": render.parse_currency(row.get("receipts")),
+                "expendituresYtdNumeric": render.parse_currency(
+                    row.get("expenditures")
+                ),
+                "currentCashOnHandNumeric": render.parse_currency(
+                    row.get("endBalance")
+                ),
+                "isIncumbent": bool(row.get("isIncumbent")),
+                "isWinner": bool(row.get("isWinner")),
+            }
+        )
+    return normalized

ocpf_cli/render.py

@@ -0,0 +1,89 @@
+"""Output rendering helpers: aligned human tables and JSON emission.
+
+Conventions (per clig.dev):
+- Data goes to stdout. Human status/progress and errors go to stderr, so a
+  `--json` stdout stays a clean, pipeable document.
+- `emit_json` prints only JSON to stdout.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Sequence
+
+
+def status(message: str) -> None:
+    """Print a human status/progress line to stderr (never stdout)."""
+    print(message, file=sys.stderr)
+
+
+def error(message: str) -> None:
+    """Print an error line to stderr."""
+    print(f"error: {message}", file=sys.stderr)
+
+
+def emit_json(value: Any) -> None:
+    """Print `value` as a JSON document to stdout and nothing else."""
+    json.dump(value, sys.stdout, indent=2, default=str)
+    sys.stdout.write("\n")
+
+
+def format_currency(amount: float | int | None) -> str:
+    """Format a numeric dollar amount as `$1,234.56`. None -> empty string."""
+    if amount is None:
+        return ""
+    return f"${amount:,.2f}"
+
+
+def parse_currency(value: str | float | int | None) -> float:
+    """Parse a currency string like `$63,727.50` into a float.
+
+    Inverse of `format_currency` for the currency-string fields the historical
+    `finsummaries` feed returns. Blank or unparseable input yields `0.0`.
+    """
+    if value is None:
+        return 0.0
+    if isinstance(value, (int, float)):
+        return float(value)
+    cleaned = value.strip().lstrip("$").replace(",", "")
+    if not cleaned:
+        return 0.0
+    try:
+        return float(cleaned)
+    except ValueError:
+        return 0.0
+
+
+def render_table(
+    rows: Sequence[Sequence[Any]],
+    headers: Sequence[str],
+    *,
+    right_align: Sequence[int] | None = None,
+) -> str:
+    """Render `rows` as an aligned, labeled table.
+
+    `right_align` is a set of column indexes to right-justify (e.g. currency).
+    Returns the table as a string; the caller prints it to stdout.
+    """
+    right = set(right_align or ())
+    str_rows = [["" if cell is None else str(cell) for cell in row] for row in rows]
+    widths = [len(h) for h in headers]
+    for row in str_rows:
+        for i, cell in enumerate(row):
+            widths[i] = max(widths[i], len(cell))
+
+    def fmt_row(cells: Sequence[str]) -> str:
+        out = []
+        for i, cell in enumerate(cells):
+            if i in right:
+                out.append(cell.rjust(widths[i]))
+            else:
+                out.append(cell.ljust(widths[i]))
+        return "  ".join(out).rstrip()
+
+    lines = [fmt_row(list(headers))]
+    lines.append("  ".join("-" * widths[i] for i in range(len(headers))).rstrip())
+    for row in str_rows:
+        lines.append(fmt_row(row))
+    return "\n".join(lines)