[dcstats]

Release branch for 2.2.0. Full detail is in CHANGELOG.md; this is the summary.

Highlights

ESPN's JSON API as a second transport. Game data can now be fetched from ESPN's JSON API (source="api", the new default) or the HTML pages (source="html"). Both emit an identical output schema. The API path makes one summary?event={id} request that carries header, boxscore, and plays, instead of three page fetches.

WAF workaround. HTTP now goes through curl_cffi with browser TLS impersonation. ESPN's AWS WAF fingerprints TLS clients and serves flagged ones an empty challenge response — requests no longer gets through at all.

New columns. game_datetime (ISO-8601 UTC tipoff), period/secs_left_period (format-agnostic, replacing the half/quarter pairs), home_win_prob, point spread / over-under / moneylines, play_type_id, and per-play player names and ids.

cbbpy CLI. A console script over the same scraper functions, writing csv/parquet.

Two-layer test suite. Offline tests replay recorded ESPN pages and API responses through the full scraper and compare against parquet snapshots for both transports, plus a parity test asserting the two sources agree; live tests hit real ESPN but assert only drift-stable invariants. This separates "my code broke" from "ESPN changed." CI runs the offline suite on 3.9–3.13, again on 3.9 at dependency floors, and the live suite on 3.12.

Behavior changes worth knowing

• play_type now carries ESPN's structured JSON value verbatim (JumpShot, MadeFreeThrow) instead of the lossy text-parsed one (jumper, free throw). Filters written against the old strings need updating.
• Bulk scraping defaults changed to n_jobs=8, throttle=1.0 (~8 req/s) from CPU-count-minus-1 at throttle=0.5. The work is I/O-bound, so the old default scaled request rate with core count for no throughput gain and more WAF challenges. Many-core machines will see longer wall-clock times; pass n_jobs/throttle to tune.
• Retries back off exponentially (~2s → 20s cap, ±50% jitter) over 10 attempts, instead of a flat 1–3s over 15.
• User-facing notices are warnings (CBBpyWarning) rather than prints, and the library no longer suppresses warnings globally.
• Shot coordinates come from the play-by-play feed alone; the HTML shot chart carried identical coordinates for every shared play.

Deprecated (removal in 3.0)

game_day/game_time → game_datetime · half/secs_left_half and quarter/secs_left_qt → period/secs_left_period · shooter → player_name

Fixes

Truncated team/conference schedules — ESPN began serving only one season type per schedule page, so a team viewed in a season it reached the postseason in returned its tournament games and nothing else (UNC 2017: 6 games instead of 42), silently affecting get_team_schedule, get_conference_schedule and get_games_conference · get_conference_schedule() now warns instead of quietly returning an incomplete conference when a team's schedule fetch fails · boxscore string columns no longer widen to object under pandas 3 · wrong-basket shot coordinates (#54) · is_three from ESPN's stated shot value rather than description text · fabricated shot coordinates for games ESPN never located (#93) · empty boxscore stat lines from cached summaries (#92) · conference-game labelling (#64) · team maps through 2026 with a season fallback (#66, #86, #90, #91) · home team detection · duplicate intra-conference games (#84) · pbp clock parsing (#82) · failure-path return types (#83) · retry-block NameErrors (#69) · status-code-based error classification (#74) · overtime count read from data (#71) · CLI season TypeError (#87) · empty-DataFrame sorting (#89) · request throttling and timeout (#70, #79)

Verification

• 87 offline tests pass; flake8 clean.
• Live suite passes on both transports.
• Public API compatible with master modulo the documented behavior changes above.

Before tagging

Stamp the release date on ## [2.2.0] - Unreleased in CHANGELOG.md.