Skip to main content

Changelog

All notable changes to sdvplot are documented here. The format follows Keep a Changelog, and the project adheres to Semantic Versioning.

Unreleased​

Added​

  • cfbplotR's team_name_mapping spellings resolve: resolve("VA TECH", "cfb"), "NC St.", "North Carolina State", "UT San Antonio", "Presbyterian College", "St Francis (PA)". tools/export_cfbplotr.R exports the mapping with logo_ref's type and ESPN id into data-raw/cfbplotr_names.csv (commit in data-raw/cfbplotr_commit.txt), and the build adds each spelling the index lacks as a "name" alias of the team cfbplotR meant, when that is one team (80 spellings). One the index already has, for any team, adds nothing, and so does one whose cfbplotR rows name two teams or no team the index has: resolve() still gives None for it. The logo functions take cfbplotR's "Big South" for cfb's OVC row, the Big South-OVC Football Association (data-raw/curated/conference_aliases.csv, hand-kept conference keys).

  • A division column in the team index: a college team's NCAA division in its latest season in ESPN's groups ("FBS", "FCS", "DII", "DIII" in cfb; "DI", "DII", "DIII" elsewhere), from the subdivision_id that tools/fetch_sources.py --groups-only now keeps in data-raw/groups_latest.csv. It is the last column, so readers that select the columns they know are unaffected.

  • The build keys manifest marks of cfbplotr-legacy (sdv-assets' archive of cfbplotR's college wordmarks) to teams by their ESPN ids, and its conference and league marks, filed under ESPN's keys, to the rows the curated ESPN lines name; the source names no team and adds none (MARKS_ONLY_SOURCES in tools/fetch_sources.py), and ranks after every other source.

  • College football wordmarks: the index maps 360 of the 362 cfbplotr-legacy marks the 2026-11-09 sdv-assets capture archived (data-raw/manifest_marks.csv, manifest_conferences.csv; index e04c50e5682e); the 2 mbb marks for ESPN ids 2597 and 42 map to no index team. logo_url(team, "cfb", mark_type="wordmark") now finds a wordmark for most FBS and FCS teams (and marks() lists them, mark_type == "wordmark"), and the conferences cfbplotR drew get its marks after ESPN's.

  • Fox, Yahoo, CBS, 247Sports, On3, KenPom and Torvik team ids in the index, from sdv-reference-data's {league}_team_aliases tables in the sportsdataverse-data {league}_groups releases (NFL, college football, NBA, WNBA, men's and women's college basketball, MLB, NHL), snapshotted by tools/fetch_sources.py --crosswalks-only into data-raw/provider_ids.csv. Yahoo's dotted ids resolve under "auto" (resolve("ncaaf.t.1", "cfb")). Fox, CBS, 247Sports (team and institution ids) and On3 (org ids) numbers are other teams' ESPN ids, so, like nhl_id, they answer only an explicit id_system: resolve("25", "cfb") is ESPN's California, resolve("25", "cfb", id_system="fox") is Ohio State. KenPom and Torvik team names ("kenpom", "torvik") come before "name" under "auto". Each id keeps the seasons the source gives it, and one two teams held in overlapping seasons is left out.

  • headshot_url() (and every headshot adapter) takes other providers' player ids: id_system="fox", "yahoo", "cbs", "kenpom", "ncaa", "nba_stats" or "wnba_stats" (by league: NFL, college football, NBA, WNBA, men's and women's college basketball) draw the ESPN headshot of the athlete sdv-reference-data's {league}_player_aliases matches the id to (headshot_url("nba.p.3704", "nba", id_system="yahoo") is LeBron James). The league's table is downloaded and cached when first needed.

  • More provider team ids in the index, from the sportsdataverse-data crosswalk releases (tools/fetch_sources.py --crosswalks-only snapshots them into data-raw/provider_ids.csv): stats.ncaa.org org (school) ids and season team ids as id_system="ncaa" for men's and women's college basketball and college baseball, and org ids for college softball (resolve(193, "mbb", id_system="ncaa") is Duke), and WNBA Stats team ids and tricodes as "nba_api" (resolve(1611661319, "wnba", id_system="nba_api") is the Aces). An id two teams held in overlapping seasons is left out; one a relocated franchise kept under a new ESPN id carries each team's seasons. Under "auto" an ESPN id wins over an equal NCAA id, so pass id_system="ncaa" for NCAA ids. College hockey and the G League get none: no release maps their stats.ncaa.org or G League Stats ids to ESPN's.

  • Hexagonal and square bins, ported from sdvplot-js @sportsdataverse/sdvplot/bins: hexbin, squarebin, binner (shape="hex" or "square", and equal_area=True for squares of a hexagon's area), cell_points and bin_ids, with BinShape in sdvplot.typing. Each bin records its centre, its points' row numbers and link ids, and its own id "x,y", the data-sdv-id sdvplot-js stamps on a cell; on 2000 real 2025-26 Brooklyn shots the bins, their order, centres and ids equal sdvplot-js's own output bit for bit (tests/test_bins.py). add_bins(target, x, y, shape=...) draws them in matplotlib (a PolyCollection), Plotly (path shapes and a selectable trace carrying bin ids and point ids), Bokeh (a patches glyph whose selection links both ways with the points' ColumnDataSource and any DataTable on it, in the browser) and Altair (an area layer with a bin_id selection param). The colors cookbook and the WNBA tutorial draw their shot charts with it (hexagons, then squares) instead of ax.hexbin.

  • Bins: origin=(x, y) on hexbin, squarebin, binner and every add_bins shifts the lattice so a cell centre falls on it (a hoop-centred lattice: origin = the basket's coordinates); ids stay the absolute centre "x,y", and the default (0, 0) bins exactly as before. weights= (one non-negative weight per point, by position; a missing or non-finite one counts 0 and the point stays in its bin) gives each Bin a weight, the sum of its points' (the count without weights), and add_bins(value="weight") fills by it instead of the count (BinValue in sdvplot.typing). add_bins(fill=...) draws each cell at a fraction of the lattice cell (default 0.88 for squares, so they no longer touch edge to edge, and 1.0 for hexagons) and min_count= leaves sparse cells undrawn (min_count=2: single attempts; the bins hexbin/squarebin return are unchanged); the WNBA tutorial's squares use min_count=2. The same names and defaults as sdvplotR's.

  • add_bins for plotnine (a geom_polygon layer filled by count or weight), HoloViews (the Bokeh glyph through a plot hook, with Bokeh's linked selection: link= the points element), folium (one GeoJSON layer of polygons; on a map the lattice is in degrees of longitude and latitude) and pygal (SVG polygons under the series, drawn by an xml filter at each render), so every plotting adapter has it.

  • sdvplot.plotly.link_script(fig) links Plotly's bins to the points trace in a static HTML file, with no Python running: pass it to fig.write_html(post_script=...) and selecting cells selects their points, selecting points selects their cells, and hovering a cell highlights its points.

  • 21 new leagues in the index (49 in all), from the archive's 2026-11-03 capture: the junior and minor HockeyTech leagues sphl (16 teams), chl (41), bchl (23), ajhl (17), sjhl (13), ojhl (28), cchl (13), gojhl (45), mhl (13), nojhl (27), vijhl (12), kijhl (23) and mjhl (19), keyed by their HockeyTech team ids (id_system="hockeytech"); Australia's nbl (10, ESPN ids); the national teams pooled by sport, fiba (30: basketball's men's, women's and ESPN's ungendered FIBA list, program mens / womens / national) and iihf (16, ice hockey, program national), both ESPN ids, so an abbreviation such as AUS that names a men's and a women's team resolves to None with a warning and the ESPN id resolves; the cfl (9, ESPN ids 79-87, content.cfl.ca marks); the cebl (15, CEBL team ids), the easl (12, DataCore team UUIDs) and Italy's lba (24, LBA club ids, marks dated by season); and f1 (31 constructors, 2002-2026, by Jolpica constructor_id, the key sdv-py's F1 family uses, named as Jolpica's latest season with each, with formula1.com marks by season and Wikimedia Commons' for the 2002-2015 constructors formula1.com never archived: Toyota, Honda, Super Aguri, BMW Sauber, Brawn, HRT, Caterham, ...). surface("cfl" | "fiba" | "iihf", team) now paints the team. The three college hockey teams that had no logo (Delaware women's, SUNY Morrisville, Maryville (Mo)) now draw, and take their logos' colors instead of the placeholder.

  • A new color_source, openf1: the F1 constructors' team_colour from OpenF1's latest session (one color, so no secondary); the 2002-2022 constructors OpenF1 predates (Racing Point, Renault, Toyota, ...) take their logo's. tools/fetch_sources.py --teams-only refreshes the archive's snapshots, ESPN's teams lists and the new data-raw/f1_teams.csv (Jolpica names, OpenF1 colors through a curated OpenF1 team name to constructor_id map) without the CFBD key.

  • College baseball, softball and men's and women's hockey teams carry a conference and conference_id (ncaa_baseball, ncaa_softball, ncaa_mhockey, ncaa_whockey), from sdv-reference-data's ESPN-keyed groups: 78%, 77%, 58% and 98% of each league's teams (most non-Division I programs and the defunct ones stay null). Each team carries its latest released season's conference: 2026 for baseball and softball (so softball's July 2025 realignment shows), 2026-27 for hockey. teams(league, include_conferences=True) adds their conference rows where the archive has the conference's logo: the basketball conference logos ESPN shares across sports (30 baseball, 31 softball and the men's hockey Big Ten) and the hockey-only conferences' own sites' logos, Wayback-pinned (men's AHA, CCHA, CHA, ECAC, Hockey East, NCHC, WCHA; women's AHA, ECAC, Hockey East, NEWHA, WCHA), so every college hockey team with a conference joins a row. tools/fetch_sources.py --groups-only refreshes data-raw/groups_latest.csv alone.

  • Soccer clubs carry their domestic league: teams("soccer") stays one pool of ESPN club ids, and a club's conference_id / conference are the league competition it was seen in in its latest season (ESPN's slug and name, "eng.1" / "English Premier League"): 1,675 of 2,631 clubs. Cups, super cups, playoffs and the confederations' and FIFA's competitions are told apart by slug and never count; a club in two leagues that season gets none. The 384 teams of a World Cup or its qualifying (men's, women's, youth) are program "national". Every competition a club was seen in (214 slugs: the UCL, cups, fifa.world) is an alias of id system "competition", dated by that competition's season, which resolve() and suggest() never read. The source is sdv-assets' manifest/soccer_competitions.csv (data-raw/soccer_competitions.csv).

  • More conference marks draw: the NHL's Eastern and Western (its Conference Final wordmarks, 2024 on, the only official conference marks the NHL publishes), and 44 Division II / III football conferences from their own sites' logos, Wayback-pinned (CIAA, GLIAC, NESCAC, PSAC, Carolinas, Landmark, NACC, Centennial, American Rivers, SAA, SCAC, G-MAC, ...), each joined to its teams' conference_id (the Conference of New England has no football team). College baseball (CNE, SIAC, SCAC) and softball (CIAA, CNE, SIAC, SAA, SCAC) reuse five of them. The cfl gains its league row, CFL (content.cfl.ca's mark). A conference or league row whose only mark is a wordmark draws it for a logo request; a conference whose only logo is an on-dark one draws it on any background.

  • headshot_url() (and every headshot adapter) covers more leagues, as sdvplotR does: G League ("nbagl"; ESPN files its photos with the NBA's) and soccer by ESPN athlete id, and the 20 HockeyTech leagues by their HockeyTech player_id with id_system="league" (assets.leaguestat.com): the PWHL, AHL, ECHL, OHL, WHL, QMJHL and USHL, and the junior and minor leagues sphl, chl, bchl, ajhl, sjhl, ojhl, cchl, gojhl, mhl, nojhl, vijhl, kijhl and mjhl (each league's key is its leaguestat client code; the web adapters draw them square, as the others). F1 driver headshots are not covered: formula1.com keys them by its own driver reference (MAXVER01), not a driver number or Jolpica driver_id. ESPN and leaguestat answer an unknown id with a 404, which draws nothing, as any missing image.

  • surface() draws every sportyR 2.3.0 surface (sportypy 1.2.0): softball (ncaa_softball, a team league, so the field takes the team's center_logo), lacrosse (nll, pll, world_lacrosse, ncaa_mlacrosse, ncaa_wlacrosse, usa_mlacrosse, usa_wlacrosse), tennis (atp, wta, itf, ita, usta, ncaa_tennis), volleyball (fivb, usa_volleyball, ncaa_volleyball), curling (wcf, curling_canada) and more leagues of the other sports (cfl, nfhs_football, nfhs_basketball, little_league, pony, nfhs_baseball, iihf, nwhl, fifa, epl, mls, nwsl, ncaa_soccer): 59 keys, the same table as sdvplotR and sdvplot-js. A team on a key that is not an SDV team league raises InputError ("no team identities for ..."), as in sdvplotR and sdvplot-js.

  • Docs: a lacrosse, tennis, volleyball and curling tutorial (every lacrosse field and box, the men's and women's goal areas, a tennis court on three surfaces, the volleyball free zones, a curling sheet and house); the surfaces cookbook's first recipe draws all ten sports; the college baseball and softball tutorial puts the Women's College World Series champion on a softball field; the PWHL tutorial's shot map is on the PWHL's own rink.

  • League, pro-conference and division marks draw: teams(include_conferences=True) gains 26 rows, and logo_url() / marks() reach each by its key: MLB, AL, NL (mlb); NBA, East, West (nba); WNBA, East, West (wnba); NHL, its division marks Atlantic, Metropolitan, Central, Pacific and the 2024 All-Star teams MAT, MCD, HGS, MKN (2024 only); AAF; and NCAA in every college league (cfb, mbb, wbb, ncaa_baseball, ncaa_softball, ncaa_mhockey, ncaa_whockey). The conference and league rows now come from sdvplot's own data-raw/curated/non_team_rows.csv, which names each row's mark by its manifest key, instead of the frozen data-raw/sdvplotr_conferences.csv export (sdvplotR no longer has the table); the 92 existing rows, their colors and aliases are unchanged. The manifest's division level counts as a non-team mark level.

Changed​

  • The team index takes the rest of the archive's 2026-11-03 capture: 50 more soccer clubs (Liga MX Femenil and Women's FA Cup sides, Copa del Rey, India's I-League 2 and friendlies; 16 renamed to ESPN's current names), ESPN's current names for three women's basketball teams (Central Arkansas Sugar Bears, East Tennessee State Buccaneers, Hawai'i Rainbow Wahine), and ESPN's current college baseball and softball abbreviations. A women's club that shares a name with the men's club (Cruz Azul, Leeds United) makes that name match both; the team id picks one.
  • Nine HockeyTech interleague and exhibition opponents are no longer teams of the league whose season lists them: six OHL teams in the QMJHL and three NAHL, SJHL and SIJHL teams in the MJHL. data-raw/curated/excluded_marks.csv names each with its reason, and tools/fetch_sources.py drops them before any snapshot is written.
  • surface(..., center_logo=True) on a baseball or softball field (mlb, milb, ncaa_baseball, ncaa_softball) draws the logo in shallow center field instead of on home plate, the field's origin, exactly as sdvplotR: at x = 0, midway between second base (baseline_distance * sqrt(2)) and the center-field fence, 0.15 x center_field_distance across (60 ft at 263.6 ft from home plate on an MLB field), from the league's field parameters and field_updates, in the dark-background variant for the grass. Every surface's center logo now also follows rotation, as the surface does (it stayed at the origin).
  • surface(..., center_logo=True) draws the team's dark-background logo variant on grass, football fields and soccer pitches as well as diamonds, as sdvplotR does: the variant is "dark" wherever white reads better than black on the sport's regulation surface color (basketball's wood and hockey's ice keep the default). A team without a dark variant falls back to its default logo.
  • surface("pwhl") draws the PWHL's own rink (sportypy's PWHLRink: no goalie trapezoid) instead of the NHL rink. The surfaces extra now needs sportypy 1.2.0.
  • The surfaces cookbook imports EuroLeague from sportsdataverse.basketball.euroleague, its home since sportsdataverse-py 0.2.0b1; the cookbook says that cell needs 0.2.0b1 or newer (pip install -U --pre), and with an older release (the examples still pin 0.1.4) the cell prints that note and draws nothing instead of failing the page.
  • The altair extra needs altair>=5.5. Altair 5.1-5.4 fail on polars 2 frames (Data has no parameter 'x').
  • sdvplot.pydeck.surface_layer() draws all ten sportypy sports, as sdvplot-js's surfaceLayer: lacrosse, softball and volleyball join the seven it drew.
  • surface() names the fix when the installed sportypy is older than 1.2 (a key it has no module or class for), and a library sportypy itself imports raises its own ModuleNotFoundError instead of the surfaces-extra message. surface() and sdvplot.pydeck.surface_layer() suggest pip install -U "sportypy>=1.2" (and the GitHub install while PyPI has only sportypy 1.0), not re-installing sdvplot[surfaces], which let pip backtrack to an older sdvplot.
  • Docs: the surface() reference lists all 59 surface keys (sport, sportypy class, team league or not), generated from the code; the README and the getting-started page list the [itables] extra, and the README links every league tutorial and cookbook; the root docs (main) carry an "unreleased" banner while their version is not yet released, and the newest release's snapshot no longer says it is unmaintained.
  • Surfaces follow sportypy 1.2.4 / sportyR 2.4.5: the surfaces extra needs sportypy 1.2.4 (from GitHub while PyPI has only 1.0.0). surface() draws what sportypy 1.2.4 draws: a feature with no area and no visible outline is left out, a hockey goaltender trapezoid is two strips and the nhl92 (OHL) crease its arc band and two L marks (each one patch with a sub-path per ring), and the lacrosse goal frame, net and bench outlines close on their first point. sdvplot.pydeck.surface_layer() draws each trapezoid's strips as two rows (an NHL rink has 4, was 6: each trapezoid crossed itself at a corner and was split) and the faceoff hash marks as 16 simple loops; the self-crossing split now only catches odd updates (a negative faceoff_line_width). The deck.gl fixture shared with sdvplot-js (tests/fixtures/deckgl_shared.json) is sdvplot-js's for sporty's sportyR 2.4.5 geometry (4 trapezoid rows).
  • Hockey surfaces follow sportypy 1.2.5 / sportyR 2.4.5: the surfaces extra needs sportypy 1.2.5 (from GitHub while PyPI has only 1.0.0). surface() and sdvplot.pydeck.surface_layer() draw sportyR 2.4.5's goal frames, goal crease fills and outlines, a single referee's crease, and penalty boxes anchored at -rink_width / 2 (an NHL rink's penalty box outline now reaches y = -48.33 ft, so deck() centres it at y = 0.25). The shared deck.gl fixture is sdvplot-js's with the faceoff hash marks counted (odzone_faceoff_lines: 16 loops).

Fixed​

  • Team values fold eight Latin letters that have no accent to drop: ø to o, æ to ae, œ to oe, đ and ð to d, ł to l, þ to th and the dotless ı to i, in either case, so resolve("HB Koge", "soccer") finds HB Køge, as "Brondby IF", "F.C. Kobenhavn" and "Sherbrooke, Phoenix" (qmjhl) find theirs (sdvplotR#70). ß already folded to ss; other such letters (ħ, ŧ, ŀ) do not fold. On the shipped index no value that resolved before resolves differently.
  • resolve("Charlotte", "cfb") is the Charlotte 49ers (2429) instead of ambiguous with the Charlotte Saints (3253, Faith NC, located in Charlotte), and "Troy" under id_system="name" or "cfbd" is the Troy Trojans: a name the name or cfbd system gives several teams without a season range goes to the one team whose own name it is. A season-dated alias keeps its range, so in a season it covers that also has another team's own-name alias the value stays ambiguous. No value that resolved before changes its answer.
  • surface("soccer", pitch_updates=None) draws the 105 x 68 m defaults, as sdvplotR's pitch_updates = NULL does, instead of raising TypeError (#100).
  • The ESPN soccer shot map recipe keeps penalties (Penalty - Scored / Penalty - Missed), and the StatsBomb recipe says why it marks five goals for a 4-2 final: the own goal is its own event type (#101). The HockeyTech tutorial drops the out-of-league exhibition opponent the QMJHL's 2025-26 table carries, so every team resolves (#118).
  • A team's conference value now draws its conference's logo: conference and league rows with a mark get "conference" aliases for their full name and for every conference name their league's teams carry under their conference_id (logo_url("Hockey East Association", "ncaa_mhockey"), "Big Ten Conference" in college baseball). The college baseball, softball and hockey rows had drawn only by their short keys.
  • Five college hockey teams (men's Augsburg, Concordia (MN), Stonehill; women's LIU, Union) take their school's ESPN colors instead of their logo's. Which ESPN name an id with no color kept depended on how the build happened to order its rows, so the exact-name match to the school's basketball entry could miss; the teams list's name now always wins, so adding rows elsewhere no longer moves a team's colors.
  • With embed=True, the web adapters (Plotly, Altair, Bokeh, HoloViews, Folium, pygal) raised DownloadError on a headshot the CDN answers with a 404 (an ESPN or HockeyTech id it has no photo for). They now skip that point with one SdvplotWarning, as matplotlib and plotnine do; any other download error still raises.
  • surface() drew no line thinner than a pixel: matplotlib snapped each straight-edged line to the pixel grid, so at screen size a volleyball court lost its attack and end lines, a tennis court its baselines and alleys, a lacrosse field its sidelines, and an NBA half court its free-throw lane end and hash marks. sportypy 1.2.0 draws the surface's shapes unsnapped, so every line shows (antialiased); the NBA half-court image baseline is regenerated with them.
  • surface(..., team, center_logo=0) drew no logo and raised nothing; a zero height is now an InputError, as any height outside (0, 1] is.

0.1.1 - 2026-10-26​

Added​

  • sdvplot.pydeck (new [pydeck] extra): deck.gl layer props for pydeck, the same as sdvplot-js's ./deckgl builds (held to one shared fixture). logo_icon_layer draws team logos at points (an IconLayer of auto-packed logo icons), pass_arc_layer draws arcs in team colors (primary at the source, secondary at the target; with background, 3:1 contrast and ΔE 20 apart through sdvplot-js's team palette, ported), and surface_layer draws a sportypy rink, pitch, court or field as a PolygonLayer in the surface's own coordinates. The props are plain dicts (pydeck.Layer(**props)); deck() builds a pydeck.Deck fitted to a surface or a map.
  • sdvplot.perspective (new [perspective] extra, Python 3.11+): perspective_sdv_config(frame, team_col=, league=, plugin=, theme=, mode=) returns a Perspective viewer config (PerspectiveWidget(data, **config) or the JavaScript restore()) that colors each team with the shared team palette: the Datagrid fills the team column's cells, and a chart splits by team and colors each team's series. A registry table theme sets the grid's fonts and sign colors. Number columns get formats (3 decimals, 1 for a percentage, integers plain; formats= overrides). perspective_logo_column(frame, team_col, league=) adds each team's logo URL, shown as a link.
  • sdvplot.itables.itables_sdv_theme(name, mode=, table_id=) returns classes, style and a scoped css string (with a Google Fonts import) that styles an itables.show table like any of the 122 surveyed themes.
  • sdvplot.plottable.plottable_sdv_theme(name, mode=) returns the plottable.Table keywords (text, dividers, stripes) for any of the 122 surveyed themes, plus a facecolor to pop and apply to the figure; a font matplotlib cannot find falls back to its generic family with one warning per family.
  • table_theme_spec() and sdv_table_themes(): resolve and list the 122 surveyed table themes (light and dark).
  • sdvplot.great_tables.gt_theme_source(gt, name, mode=, density=) styles a table like any of the 122 surveyed themes, plus 20 named shortcuts (gt_theme_datagolf, gt_theme_economist, gt_theme_basketball_reference, ...) generated by tools/gen_gt_shortcuts.py.
  • reactable_sdv_theme(name, mode=) accepts every registry theme, and the new reactable_sdv_args(name, mode=) returns the Reactable keywords (theme, striped, highlight, bordered, compact) that match it. reactablefmtr names are unchanged; mode="dark" on a reactablefmtr theme raises unless the theme is dark already.
  • teams(league, include_conferences=True) lists sdvplotR's conference and league rows (its include_conferences): the 89 college conferences of cfb, mbb and wbb and the AFC, NFC and NFL, with program "conference" or "league", the conference's short name as team_id and abbr, cbbplotR's colors (color_source "cbbplotR") and the conference_id the league's teams carry. The default lists teams only, and resolve() and palette() never answer a conference key, so no existing call changes.
  • Conference and league logos from the archive (sdvplotR's logo_marks for those rows): logo_url("SEC", "cfb"), logo_url("AFC", "nfl"), logo_url("NFL", "nfl") and every mark helper (marks, logo_image, add_logos, axis_logos, geom_sdv_logos, the table marks, the web adapters) take a conference or league row's key, with variant="dark" where the archive has one (16 CFB conferences, the AFC, NFC and NFL) and the usual fallbacks. The key is read after every team alias, so CFB's MAC is still Macalester, and resolve() still answers no conference: the rows' only aliases are "mark" aliases, which name the manifest's own conference rows (level:league:source:entity_id; tools/build_index.py conference_mark_aliases, from the new data-raw/manifest_conferences.csv snapshot). All 92 rows have a primary mark, as sdvplotR's 92 do.
  • Headshots by the league's own player id: id_system="league" (sdvplotR's id_type = "league") on headshot_url and every headshot helper (add_headshots on every adapter, geom_sdv_headshots, gt_sdv_headshots, gt_sdv_cols_label(mark_type="headshot"), reactable_sdv_headshots, plottable.headshot_column) draws an NBA or WNBA Stats PERSON_ID (what nba_api, hoopR and wehoop return), an MLBAM id or an NHL API id from the league's CDN, with sdvplotR's URL templates; for the NFL it is the gsis id. "espn" stays the default. A league without them is an InputError naming the ones that have them, and a DownloadError from cdn.nba.com or cdn.wnba.com with a 403 says that those CDNs block datacenter and cloud IPs.
  • surface("fiba") draws a FIBA court (no team yet).
  • sdvplot.plotnine.scale_color_sdv and scale_fill_sdv take alpha=, an opacity applied to the team colors (sdvplotR's alpha); na_value is drawn as given. scale_colour_sdv is the British alias sdvplotR and plotnine both ship.
  • gt_merge_stack_team_color takes background=, the cell background the bottom line's color is checked against; the default reads the table's background, so a theme applied first is taken into account.
  • gt_tiers takes alt=, a function from the image paths or URLs to their alt text. By default a logo the archive knows (any logo_url) is named by its team and any other image by its file name; the images had no alt text at all. The alt comes from the cell's value, so a local file (embedded as a data URI) gets a real name.
  • pitch_coords() converts soccer event coordinates from Opta / Stats Perform, Wyscout, StatsBomb, UEFA, Impect, ESPN and the tracking providers (Tracab, SkillCorner, Second Spectrum, Metrica) to one regulation 105 x 68 m frame, piecewise-linearly between pitch landmarks, with flip for teams attacking opposite ends. The port of sdvplotR's sdv_pitch_coords(), matched to 1e-12 on every provider.
  • court_coords(provider="euroleague") converts the Euroleague shot frame of sportsdataverse-py's euroleague_game_points() (coord_x/coord_y: integer centimeters, hoop at the origin, both teams on one basket, free throws as -1,-1) onto the FIBA court surface("fiba") draws, in meters, with the -1,-1 free throws as null. The default "nba" is unchanged, byte for byte. Matched to sdvplotR's sdv_court_coords(provider = "euroleague") bit for bit on a real Euroleague game (tests/fixtures/euroleague_points_E2025_1.csv).
  • tools/espn_soccer_y_gate.py, the measurement behind the ESPN frame's y direction.
  • axis_logos(..., mark_type="headshot") draws player headshots as axis labels on matplotlib, plotnine, Plotly and Altair (the port of sdvplotR's scale_x_sdv_headshots() / scale_y_sdv_headshots() and element_sdv_headshot()): the tick labels are read as player ids (id_system "espn", which "auto" means, "gsis" or "league"), each headshot keeps its own aspect, an unknown id stays as text with one warning, and the adapters without axis logos raise UnsupportedTargetError as before. sdvplot.typing.AxisMarkType is the Literal of the three mark types. The matplotlib y-axis label pad now grows by the widest image's width, so wordmarks and headshots no longer overlap their tick labels' room. The adapter contract (check_adapter_contract, rule 7) checks the headshot axis too.

Changed​

  • The README links the JavaScript / TypeScript port, sdvplot-js, now on npm: an npm badge and an Installation note for @sportsdataverse/sdvplot, @sportsdataverse/sporty and @sportsdataverse/sdvtables, with their docs at plot.sportsdataverse.org.
  • The docs site's SDV menu adds cfbseedR and sdvplot-js, and the README's SportsDataverse table adds sdvplot-js, so the package lists match the other SportsDataverse sites.
  • polars 2.x is supported: the dependency is polars>=1.24 (was <2). With every optional extra installed, the full suite (2,343 tests) passes on polars 2.0.0, the same as on 1.44.
  • numpy is now a core dependency (it was optional, needed only by pitch_coords()).
  • surface("soccer") draws a regulation 105 x 68 m pitch by default (it drew sportypy's 120 x 90 m maximum), the frame pitch_coords() returns; pitch_updates still overrides it key by key.
  • gt_merge_stack_team_color keeps the bottom line readable (sdvplotR #55): the team's primary color when it clears 4.5:1 contrast (WCAG AA) on the cell background, else the secondary, else the primary darkened (or lightened, on a dark table) until it does, so Missouri's gold (1.8:1 on white) reads on a white table and stays gold on a dark one. An unknown team's grey goes through the same rule.
  • gt_spotlight(dim_color=) defaults to "auto" (sdvplotR #61): the other rows are dimmed to the table's text blended toward its background until it clears 4.5:1 (#737373 on white), instead of the fixed #BBBBBB, which is 1.9:1 on white and barely dimmer than the text on a dark theme. Pass a color to choose it, or None not to dim.
  • team_tiers (matplotlib and plotnine) takes variant=, default "auto": the dark theme now draws the archive's dark-background logos (the "dark" variant), so dark marks such as the Capitals', the Giants', Penn State's or Iowa's no longer fade into the near-black background. A team with no dark mark draws its default one, with no warning; the light theme still draws the default logos. Pass variant="default" for the old look (sdvplotR's), or any variant add_logos takes.
  • great_tables 1.1 is supported. Its data_color now interpolates in CIELAB, as R gt and scales::col_numeric do, so gt_color_ranks fills match sdvplotR's exactly under it; gt_color_pills, gt_percentile_bar and the gt_legend_continuous steps now draw great_tables' own gradient, so they stay equal to data_color cells on every version (CIELAB from 1.1, sRGB before) and match sdvplotR's colors from 1.1 (they were sRGB approximations).

Fixed​

  • The surfaces cookbook's soccer shot map (§9) placed ESPN shots at twice their distance from goal (ESPN's field_position_x is a fraction of half the pitch, not of the whole), mirrored the home team's wings, and kept ESPN's (0, 0) "no location" events. It now scales by 52.5 m, turns the away team half a turn, and drops them.
  • Coordinates, teams and seasons accept a range: add_logos(ax, range(1, 8), ...) raised a TypeError that named resolve() though the bad value was x. A container sdvplot cannot read now raises a TypeError that names no one function: expected a scalar, list, tuple, range, numpy array or a pandas/polars Series, got dict.
  • NHL WIN is season-aware: resolve("WIN", "nhl", season=1990) (and NHL team id 33, and the archive's logos of those seasons) gives the original Jets' line, today's Utah Mammoth, for the seasons ending 1980-1996, as sdvplotR's resolve_historical_abbr() does; any other season, or none, gives today's Winnipeg Jets, the relocated Thrashers. Every season used to give today's Jets, because the NHL stats API files the 1979-96 team under their franchise.
  • UTRGV, TEXAS-RIO GRANDE VALLEY and RGV resolve in college football (ESPN's teams list omits UT Rio Grande Valley, 292; its per-team endpoint's RGV is now in data-raw/espn_abbrs.csv).
  • Six college basketball teams ESPN's teams lists omit resolve by their ESPN abbreviation: LIN (Lindenwood, 2815), QUC (Queens, 2511), SFPA (Saint Francis, 2598) and USI (Southern Indiana, 88) in mbb, MERC (Mercyhurst, 2385) and SFPA in wbb, and with them sdvplotR's keys for those teams. tools/fetch_sources.py reads them from ESPN's Core API per season (ESPN_CORE_TEAMS) into data-raw/espn_abbrs.csv. teams() shows that code as abbr where ESPN's teams lists give none, as for UTRGV (RGV) and college baseball's Loras (LOR): eight teams had a null abbr.
  • sdvplotR's conference names draw the conference's logo again: logo_url("Southeastern Conference", "cfb") is logo_url("SEC", "cfb"), logo_url("B10", "mbb") is logo_url("Big Ten", "mbb"), and so for the other keys sdvplotR's clean_team_abbrs() maps to a conference or league row ("B1G", "Pac-10", "American Football Conference"): 275 keys in cfb, mbb, wbb and the NFL, a new internal id system "conference" that only the mark functions read, after every team alias. resolve() still answers no conference, and CFB's MAC is still Macalester; resolve("Mid-American Conference", "cfb") no longer gives Macalester (it went through sdvplotR's MAC canon): it is None, and its logo is the conference's.
  • gt_tiers no longer writes two alt attributes on an image under great_tables 1.1, whose fmt_image adds an empty alt="": the image's alt text replaces it.

0.1.0 - 2026-10-05​

First release.

Migrating from the git pre-release​

0.1.0 freezes the public API. Code written against a git install from before it needs these changes; each old call now fails loudly, with the message shown:

  • palette("nfl", "secondary") is palette("nfl", which="secondary"): palette is palette(league, teams=None, *, which="primary", season=None), as sdvplotR's sdv_color_palette(sport, teams, type). The old call raises InputError: 'secondary' is a color slot, not a team; pass it by keyword: palette(league, teams=..., which="secondary").
  • team_colors(teams, "nfl") is team_colors("nfl", teams): the league comes first, as in sdvplotR's sdv_team_colors(sport, team, type). With a list or Series of teams the old order raises InputError: league must be a league key such as 'nfl', got list; team_colors and palette take the league first: team_colors(league, teams); with one team, InputError: unknown league 'KC'; known leagues: [...].
  • Secondary arguments are keyword-only: season, id_system and strict on resolve; season, variant, mark_type and size on logo_url and logo_image; season on marks; n on suggest; id_system on headshot_url; x and y on court_coords. resolve(v, "nfl", 2020) raises TypeError: resolve() takes 2 positional arguments but 3 were given; write resolve(v, "nfl", season=2020).
  • Each public submodule exports only its __all__, and dir() shows only that. Helpers and the adapter test hooks are underscored (_drawn_marks, _drawn_axis_marks, _visible_axis_labels, _SUPPORTS_AXIS_LOGOS, _drawn_title_images, great_tables' _drawn_cells and _rendered_html), so sdvplot.matplotlib.draw_placements raises AttributeError: module 'sdvplot.matplotlib' has no attribute 'draw_placements'.
  • A table's height is pixels: gt_sdv_logos(gt, "team", league="nfl", height=0.1) (and the front door on a GT) raises InputError: height is the image height in pixels for a table (such as 30), got 0.1; a fraction of the plot height is the unit for plots, not tables instead of drawing a 0.1 px image.
  • New errors, each still the builtin you may already catch: SdvplotError is the base of them all; InputError (a ValueError) is raised by the shared argument checks (league, which, id_system, mark_type, height, alpha); UnsupportedTargetError (a TypeError) by an adapter given the wrong kind of object or asked for axis logos it cannot draw; UnsafeDownloadError (an OSError) and UnsafeCachePathError (a ValueError) are exported.

Added​

Core (team identity, colors, logos, cache, adapter contract)​

  • Team resolver and id systems: resolve() maps abbreviations, names and provider ids (ESPN, NHL, nflverse, MLB, NBA, HockeyTech, NCAA, PFF, Cricinfo, CFBD, Baseball-Reference, FanGraphs, sdvplotR) to a stable string team_id, with a documented PRIORITY order and nhl_id available only through an explicit id_system.
  • suggest() for near-miss candidates when a value does not resolve.
  • palette() and team_colors(): team colors as a {team: "#hex"} mapping or one hex per value, with color_source="fallback" marking placeholders.
  • logo_url(), logo_image() and marks(), with era selection by season (relocated franchises get their era's mark), variant and source preference.
  • headshot_url(): ESPN athlete ids for NFL, NBA, WNBA, MLB, NHL and college football and basketball, plus NFL gsis ids through the nflverse player table.
  • A download cache (SDVPLOT_CACHE_DIR, SDVPLOT_CACHE_TTL) with clear_cache().
  • The adapter registry and contract harness (add_logos, add_wordmarks, add_headshots, axis_logos, sdvplot.testing).
  • A bundled index of 5,879 teams across 28 leagues, rebuilt reproducibly from data-raw/ by tools/build_index.py.
  • sdvplotR parity: 99.8% of sdvplotR's clean_team_abbrs() keys resolve to the same team (4,232 of 4,241 checked).

Repository standards​

  • A Docusaurus docs site at https://sdvplot.sportsdataverse.org with a generated API reference and rendered tutorials.
  • Example notebooks, executed by tools/render_notebooks.py into the tutorials.
  • CI, a release workflow, and pre-commit hooks, in sdv-py's layout.
  • CONTRIBUTING.md, CLAUDE.md, .github/copilot-instructions.md, issue and pull-request templates, and sdv-py's dotfiles.

Matplotlib family​

  • add_logos, add_wordmarks, add_headshots and axis_logos work on matplotlib Axes, one-Axes Figures and seaborn grids (sdvplot.matplotlib); height is a fraction of the Axes height at any dpi or figure size.
  • plotnine: geom_sdv_logos, geom_sdv_wordmarks, geom_sdv_headshots, axis_logos and the team color scales scale_color_sdv / scale_fill_sdv (sdvplot.plotnine).
  • surface(): sportypy playing surfaces in team colors, the port of sdvplotR's sdv_surface().
  • plottable logo_column and headshot_column (sdvplot.plottable, new [plottable] extra).
  • The adapter contract (sdvplot.testing) now covers wordmarks, headshots, axis logos and alpha (rules 0-8).

Tables, wave A (marks and team identity)​

  • sdvplot.great_tables, ported from sdvplotR with league= for sport=:
    • gt_sdv_logos, gt_sdv_wordmarks and gt_sdv_headshots put marks in body, stub or row-group cells, and gt_sdv_cols_label puts them in column labels.
    • gt_merge_stack_team_color stacks two columns in one cell, the bottom line in the team color.
    • The themes gt_theme_sdv (light or dark, three densities) and gt_theme_sdv_team.
    • Heights are pixels. Unknown values keep their text and warn once, when the function is called.
  • sdvplot.add_logos(gt, "team", league="nfl"), add_wordmarks and add_headshots route a great_tables GT to those functions.
  • sdvplot.reactable (new [reactable] extra): reactable_sdv_logos, reactable_sdv_wordmarks, reactable_sdv_headshots, reactable_sdv_cols_label, reactable_sdv_team_color_bar and reactable_sdv_team_color_bg. Each returns reactable.Column objects.
  • sdvplot.testing.check_table_adapter_contract (rules T0-T6) for table adapters.
  • docs/PARITY_TABLES.md: how each sdvplotR table function maps to sdvplot.
  • The [tables] extra now needs great_tables 1.0 or later.

Table themes​

  • The 18 sdvplotR table themes for great_tables, with sdvplotR's names, arguments and defaults (sdvplot.great_tables): gt_theme_almanac, gt_theme_athletic, gt_theme_booktabs, gt_theme_broadsheet, gt_theme_brutalist, gt_theme_drench, gt_theme_gtutils, gt_theme_kenpom, gt_theme_midnight, gt_theme_ncaa, gt_theme_pl, gt_theme_savant, gt_theme_scoreboard, gt_theme_sofa, gt_theme_swiss, gt_theme_terminal, gt_theme_tier and gt_theme_tufte, each with density="comfortable" | "compact" | "social".
  • pal_midnight: sdvplotR's five-color rank palette for dark grounds (every step clears 4.5:1 on midnight and terminal).
  • gt_theme_preview(): the same rows in every theme, as {theme name: GT}.
  • Theme fonts load every weight from Google Fonts, over gt's fallback stack.

Tables wave C1 (cell styling and formatting)​

  • 17 sdvplotR cell helpers in sdvplot.great_tables, with R's names and arguments: gt_538_caption, gt_bold_rows, gt_border_bars_bottom, gt_border_bars_top, gt_border_grid, gt_color_pills, gt_color_ranks, gt_color_results, gt_column_subheaders, gt_cutline, gt_delta, gt_fmt_rank, gt_fmt_tally, gt_group_stripes, gt_highlight_cells, gt_highlight_na and gt_indicator_boxes. They take tables built from pandas or polars data.
  • gt_color_pills and gt_color_ranks record their color scale for gt_legend_continuous.
  • docs/PARITY_TABLES.md lists where they differ from R.

Tables, wave D (image export and composition)​

  • sdvplot.great_tables: gt_save_crop, gt_social_crop and gt_save_batch save tables as trimmed, padded images (great_tables' GT.gtsave, headless Chrome); gt_grid and gt_stack_tables compose several tables into one HTML block or image. Ports of the sdvplotR functions of the same names; differences are in docs/PARITY_TABLES.md.
  • [tables] names htmltools and nokap, which great_tables 1.0 already installs. Saving needs Chrome or Chromium (set CHROME_PATH for a non-standard install); no selenium.

Web family​

  • add_logos, add_wordmarks, add_headshots and axis_logos work on Plotly figures (sdvplot.plotly; sdvplot pins the axis ranges so height is a fraction of the plot area) and Altair charts (sdvplot.altair, plus the native logo_layer).
  • add_logos, add_wordmarks and add_headshots on Bokeh figures (sdvplot.bokeh), HoloViews elements through a Bokeh plot hook (sdvplot.holoviews) and Folium maps (sdvplot.folium, x longitude and y latitude).
  • embed=True inlines the images as data URIs, for HTML that renders offline and for static export.
  • The [holoviews] extra now installs Bokeh 3 as well.
  • pygal: add_logos, add_wordmarks and add_headshots on XY-family charts (XY, DateTimeLine, DateLine, TimeLine, TimeDeltaLine), drawn in every render; embed=True makes SVG and PNG exports work offline; team_style() colors series by team (sdvplot.pygal, new [pygal] extra).
  • pygal: a deep copy of a chart (copy.deepcopy) renders the marks it was copied with, marks added to the copy or to the original afterwards stay on that chart, and a chart with marks pickles. Copy with copy.deepcopy; a shallow copy (copy.copy) shares pygal's own series and filters and is not supported.
  • Cartopy: the matplotlib adapter's add_logos, add_wordmarks and add_headshots take transform= (e.g. ccrs.PlateCarree() for longitude/latitude, or any matplotlib transform); a GeoAxes without it raises ValueError. A mark whose point falls outside the Axes is not drawn, in any coordinate system.
  • docs/COMPATIBILITY.md: every package on python-graph-gallery's best dataviz packages list, how it gets marks or colors, and the test that proves it (tests/test_compat_*.py, new compat dependency group); a watch item for Reflex XY image marks, re-checked at each release.

Tables wave C2 (legends, layout and annotation)​

  • sdvplot.great_tables gains sdvplotR's legend, layout and annotation helpers, with sdvplotR's names and arguments on pandas or polars data: gt_legend_continuous, gt_legend_discrete, gt_marginalia, gt_outliers, gt_percentile_bar, gt_row_accent, gt_scale_note, gt_set_font, gt_significance, gt_snake, gt_snake_align, gt_social_tag, gt_spotlight, gt_tiers, gt_title_header, gt_watermark, gt_wrap_labels.
  • gt_legend_continuous() with no arguments draws the scale that gt_percentile_bar, gt_color_ranks or gt_color_pills colored with; gt_legend_discrete() draws the key gt_tiers used.
  • docs/PARITY_TABLES.md lists every difference from sdvplotR for these functions.

Parity extras (court coordinates, images by path, reference lines)​

  • sdvplot.court_coords(): stats.nba.com / stats.wnba.com legacy shot locations (LOC_X/LOC_Y, x_legacy/y_legacy) to the court frame sportypy and surface("nba") draw, on pandas or polars, the port of sdvplotR's sdv_court_coords(); bit-identical to it on real shotchartdetail rows.
  • sdvplot.matplotlib.add_images() and sdvplot.plotnine.geom_from_path(): any image by local path or URL at (x, y), sized like the logo verbs, the port of ggpath's geom_from_path(); unreadable images are skipped with one warning.
  • sdvplot.plotnine.geom_mean_lines() and geom_median_lines(): per-panel reference lines, the ports of ggpath's, matching its values on real data.
  • docs/PARITY.md maps the remaining sdvplotR exports to sdvplot functions or recipes; tools/export_parity_extras.R exports the sdvplotR and ggpath oracles the parity tests read.

Parity extras (title images, team tiers)​

  • title_image() in sdvplot.matplotlib (Axes title or Figure suptitle) and sdvplot.plotnine (added with +): sdvplotR's ggtitle_image(), an image beside the title. The image is a team's logo when league= is given (an unknown team warns once and keeps the title) or any image by URL or local path (one that cannot be read warns once and keeps the title); height is in points, side is "left" or "right", and the image and title are aligned together as the title is, through later set_title calls. A second call on the same title replaces the image.
  • team_tiers() in sdvplot.matplotlib (a Figure) and sdvplot.plotnine (a ggplot): sdvplotR's sdv_team_tiers() tier list on its dark theme, from a pandas or polars frame with tier_no and team (optional tier_rank), with presort, tier_desc, no_line_below_tier and devel=True (team text, no downloads). One shared preparation (sdvplot._tiers) ranks, wraps the tier labels and sets the limits for both. The default logo height, 0.1 of the panel, is about the largest at which 32 logos in 5 tiers neither overlap nor leave the panel at the default figure size.

Release hardening​

  • A deprecation helper, sdvplot._deprecate (deprecate() and @deprecated_alias), and its warning, sdvplot.SdvplotDeprecationWarning (a FutureWarning and a SdvplotWarning), with a deprecation policy in CONTRIBUTING.md: one minor release of warnings before a removal. Nothing is deprecated yet.
  • id_system and strict wherever a team is resolved, passed to the resolver as resolve() takes them: team_colors, palette, logo_url, logo_image, the great_tables helpers gt_sdv_logos, gt_sdv_wordmarks, gt_sdv_cols_label and gt_merge_stack_team_color (gt_theme_sdv_team takes id_system; it is always strict), and the reactable helpers reactable_sdv_logos, reactable_sdv_wordmarks, reactable_sdv_cols_label, reactable_sdv_team_color_bar and reactable_sdv_team_color_bg. NHL stats ids need it: team_colors("nhl", [1, 6, 10]) reads them as ESPN ids and returns the Bruins, Oilers and Canadiens without a warning, while team_colors("nhl", [1, 6, 10], id_system="nhl_id") gives the Devils, Bruins and Leafs. gt_sdv_cols_label's id_system now defaults to None: "auto" for logos and wordmarks, "espn" for headshots. team_colors's which is typed Which, so which="secondry" is a type error, as it is for palette.
  • sdvplot.typing: the Literal types of the closed argument vocabularies (IdSystem, HeadshotIdSystem, Which, MarkType), for annotating code that keeps an argument in a variable (which: Which = "primary").

Changed​

Documentation​

  • An automation example, examples/automation/sdvplot_social.py: social game-day graphics from live ESPN data through sportsdataverse-py, for the NFL, college football, NBA, WNBA, MLB and NHL. leaderboard makes a season's leaders as a great_tables table with headshots and logos; gameday makes final-score cards and a player-of-the-game card in matplotlib. Images are 1080 x 1080 or 1200 x 675, in team colors with readable ink. With no games or leaders yet it falls back to the most recent date or season and says so in the caption. Each run writes a manifest of images, alt text, captions and hashtags; post publishes it to Bluesky over plain requests (a dry-run unless --post), posting only fresh posts and each one once (a posted-ledger), retrying what is safe to retry. With it: a GitHub Actions template to copy (examples/automation/workflows/sdvplot-social.yml), a weekly dry-run in sdvplot's CI (.github/workflows/automation-example.yml, which never posts), offline tests (tests/test_automation_example.py) and the docs page Social graphics (docs/docs/automation/index.md).
  • tools/render_notebooks.py renders every notebook under examples/notebooks/, its folder picking the section: the top level is "Getting started", then leagues/ (Tutorials by league), cookbooks/, recipes/ and leaderboards/, each a sidebar category, beside the hand-written Automation guide. A notebook's metadata["sdvplot"] (label, position, description, optional per-cell timeout) replaces the renderer's hard-coded list, and --only takes a path such as leagues/nfl. A deleted notebook's page and outputs go with it.
  • Interactive outputs (Plotly, Vega-Lite, Altair, great_tables, folium, Bokeh, HoloViews, reactable widgets) render as standalone pages under docs/static/outputs/, shown in iframes that a site client module sizes to their content.
  • A gallery page shows every figure tagged gallery in a notebook as a thumbnail linked to its example; each render writes a per-notebook sidecar, so a partial render keeps the gallery whole (--gallery-only rebuilds it).
  • The weekly live-tests-cron render executes every notebook and publishes every generated path.

Release hardening​

  • sdvplot.plotnine.scale_color_sdv / scale_fill_sdv take which, season and na_value by keyword only (as palette() and team_colors() do), and they and sdvplot.pygal.team_style take id_system and strict: scale_color_sdv("nhl", id_system="nhl_id") reads NHL stats ids, which "auto" reads as ESPN ids and colored as other teams without a word. A season before the league's first is reported with the league's own range in the first error (season 1850 ... for nfl (1920 to ...)), not the index's and then the league's on a retry.

  • Team colors for the 3,636 teams that had only placeholder colors: all of soccer, MiLB, cricket, the HockeyTech leagues, college hockey, the PHF, AAF, USFL and XFL, and the college teams ESPN's lists give none. 2,270 now carry ESPN's colors (color_source="espn"): its per-team endpoint by ESPN id, and for a college team its school's colors in another ESPN sport, through the same school id at the same location or, for college baseball and softball (which number their teams apart from the school), a unique exact name and location. The other 1,364 carry the two dominant colors of their archived logo, flagged color_source="logo" because no source publishes them (teamcolors was surveyed and not used: GPL data from 2020 that adds 5 teams). Two scoreboard-only men's college hockey teams, with no logo and no ESPN color, keep a fallback. ESPN's stand-in colors (black alone, or black with its stock red) no longer count as a team's: 417 college teams that showed them now show their school's ESPN colors (119) or their logo's (298). A secondary equal to its primary is dropped (5 teams). tools/fetch_sources.py --colors-only refreshes the two new snapshots, data-raw/espn_colors.csv and data-raw/logo_colors.csv.

  • The sdvplot.great_tables helpers take their options by keyword only: past the table and the columns (or the other leading "what" arguments: gt_delta(gt, from_, to), gt_highlight_cells(gt, columns, condition), gt_significance(gt, columns, p_columns), gt_tiers(gt, levels, colors), gt_save_batch(data, group, fn, file), gt_save_crop(data, file), gt_title_header(gt, title) and so on) every argument is keyword-only, so a later release can add an option without rebinding a positional value. No public function of sdvplot or its submodules takes more than four arguments by position (a test keeps it so). Migrate by naming the option: gt_color_pills(gt, "pts", palette=...), gt_save_batch(df, "conf", build, "{group}.png", dir="out").

  • Documentation: an "Add an adapter" guide for contributors (docs/docs/adapters/add-an-adapter.md), a checklist from the adapter module to the changelog entry, with a worked example that passes check_adapter_contract.

  • Documentation: the MBB, WBB and college-hockey tutorials draw their tier lists on team_tiers(theme="light"), where dark logos (Iowa, West Virginia, Penn State) no longer vanish into the dark background.

  • Documentation: the tables cookbook's stripes gotcha says theme order no longer matters (gt_theme_kenpom bands with a CSS rule) and that stripes cover plain fills only in VS Code and Positron notebooks, and the college softball World Series table turns row striping off after gt_theme_ncaa (gt_color_results fills every row).

  • Documentation: every example notebook is re-rendered against the 0.1.0 API. The pages that called a league's colors fallbacks (the colors tutorial and cookbook; cricket, MLB, NBA, PWHL, soccer, spring football, college hockey; the rank bump chart) now say where the index's colors come from (color_source espn or logo); the WNBA tier list ranks teams within each tier, so its logos no longer overlap; the cache page lists urlimages/ and the current versions() output. The docs pages' Python examples run offline in the test suite, which checks every output their comments show. The social-graphics workflow template pins a current sdvplot commit.

  • The social-graphics example (examples/automation/sdvplot_social.py) covers men's and women's college basketball (--league mbb / wbb, hashtags CBB and WCBB). Both keep NCAA Division I only, as ESPN's group 50 (checked by name): leaderboards read that group's own leaders, since ESPN's league-wide college leaders are mostly Division II, III and NAIA players on teams the index does not hold, and score cards keep games between two of its teams.

  • Documentation: "The adapter contract" page follows sdvplot.testing again: rules 0 to 8 (exactly one warning per skip reason, height and alpha checked on every verb when called, drawn heights measured within 1%), the axis hooks _drawn_axis_marks ((team_id, tick, height)) and _visible_axis_labels, the table harness's rules T0 to T6, and a minimal adapter that passes the current harness.

  • API reference: one page per public submodule (sdvplot.matplotlib, sdvplot.plotnine, sdvplot.plotly, sdvplot.altair, sdvplot.bokeh, sdvplot.holoviews, sdvplot.folium, sdvplot.pygal, sdvplot.great_tables, sdvplot.reactable, sdvplot.plottable, sdvplot.testing, sdvplot.typing), with a section per public name in the top-level pages' format (signature, arguments, returns, raises, example, see also). Only the 17 top-level functions had pages, so gt_theme_athletic or any adapter-only function was on none.

  • The docstring gate (tools/gen_docs.py --check) finds the public submodules itself, as tests/test_api.py does, instead of reading a list a new submodule could be left off; a new one also fails until it has a reference page.

  • The submodule examples run on a seeded cache (a logo and wordmark for every NFL team, the examples' headshots and images) instead of an empty one, so the 32 that stopped at their first download now run to the end: an error after the first mark lookup no longer passes. Only the four that render through a headless browser stay tolerated.

  • Release: a release run refuses a README without a PyPI install line (it becomes the version's PyPI page), a CHANGELOG without a dated heading for the tag, or entries left under [Unreleased] (tests/test_repo_files.py::test_the_tagged_release_is_ready). The dist is built in its own job from a fresh checkout after the tests pass, with no uv cache from other workflows, a pinned uv and no persisted credentials; the docs deploy (which holds contents: write) pins its actions by commit SHA.

  • CI: the built wheel is installed with no extras and its core is exercised (3.10 and 3.14), then every public submodule is imported with [all]; the offline suite runs on 3.10 through 3.13; pytest runs with --strict-markers and --strict-config. Python 3.14 is a declared classifier. A run on main is never cancelled by a later push (only a PR's is), and the live network tests run on manual dispatch and weekly in live-tests-cron, not on every push.

  • Repeated lookups are faster: with everything cached, logo_url takes about 0.1 ms per call instead of 2.5 ms, and logo_image about 1 ms instead of 4 ms (most of it the copy of the image the caller gets). A cached file within its TTL is remembered for the session instead of having its metadata re-read on every call, the bundled index's directory is looked up once, and each team's marks are taken from the manifest once per manifest load.

  • The matplotlib-family adapters (matplotlib, seaborn, plotnine, plottable, title_image) keep a mark in memory no bigger than they draw it, 512 px tall. Half of the logo archive is 4096 px: each such mark held 64 MiB, a quarter of the decoded-image cache, so a few of them pushed out everything else and every plot decoded them again (about 0.5 s each). Now a repeated add_logos with a 4096 px mark takes about 0.02 s instead of 0.5 s; the first one still pays the decode.

  • Documentation: sdvplot.matplotlib.add_images and title_image, and sdvplot.plotnine.geom_from_path and title_image, say an image URL must be https. They said "http or https", but an http URL is refused with UnsafeDownloadError.

  • Documentation: every public function's docstring names the error classes the code can raise since the API freeze: InputError for the shared checks (heights, alpha, league, id system, season, variant; it said ValueError), UnsupportedTargetError for a target an adapter cannot draw on (it said TypeError), and each download error a function can meet (OfflineError, DownloadError, IntegrityError, UnsafeDownloadError, UnsafeCachePathError, and OptionalDependencyError for an SVG mark without the svg extra), with the ones a plotnine layer, a reactable column or a plottable column raises when it is drawn marked as such. The 17 top-level functions' examples now run offline in tests/test_submodule_examples.py, as the submodules' do. The concept and adapter pages say what the code does: the cache's urlimages/ directory, shared downloads and UnsafeDownloadError (not an OfflineError); id_system and strict on palette(), team_colors() and logo_url(); the MLB Stats API codes whose team a season does change (KCA, WAS, SEA, MIL), where the page said no code's did; the libraries each extra installs.

  • Issue templates: the bug report asks for the plotting or table library and the league, and takes the whole sdvplot.versions() output; the feature request lists every top-level function, the submodule helpers, new adapters and new leagues; the wrong-team template, now also for wrong colors, picks the league from a list and asks for the team id returned and expected, the season and the team's color_source. A test keeps those lists equal to the leagues, adapters, functions and color sources sdvplot has. The issue chooser links the docs and private security reporting.

Fixed​

Adapter contract follow-ups​

  • plotnine: a faceted plot warns once per render for each reason points are skipped (an unknown team, a missing mark), naming the values of every panel, instead of once per panel; axis_logos on a faceted plot likewise warns once.
  • plotnine: add_logos/add_wordmarks with one season per team draw on a faceted plot (each panel's copy of a point keeps its season); the mark geoms take a per-row season as the season aesthetic.
  • plotnine: the mark geoms leave missing and out-of-limits x/y to plotnine (na_rm, scale limits), so a row plotnine drops itself no longer also warns skipped ... missing x or y.
  • plotnine: a point that plotnine copies into every panel (a layer without the facet column) counts once in the warning, not once per panel.
  • plotnine: drawing no longer swaps the interpreter's warning filters (warnings.catch_warnings, not thread-safe) to keep the per-panel placement quiet; it uses a private quiet path instead.
  • The adapters' test hooks report the height an image was drawn at, not the height they were asked for: matplotlib and plotnine measure each image's extent after a draw, pygal renders the chart and reads the SVG, and the axis-logo hooks of matplotlib, plotnine, Plotly and Altair report each image's height too.
  • sdvplot.testing.check_adapter_contract is stricter: a call that skips nothing must not warn and each reason it skips points for gives exactly one SdvplotWarning (rules 1, 2, 6 and 7); height (including its out-of-range values) is checked on add_headshots and axis_logos as well as add_logos and add_wordmarks, and alpha on every verb that takes it; heights are compared within 1% of the requested value, as measured by the hooks. An out-of-range height must raise when the verb is called, not only when the marks are rendered. drawn_axis_marks now returns (team_id, tick position, height). check_table_adapter_contract likewise requires no warning for known values and exactly one for all-unknown input.

Tables follow-ups​

  • Muted text (gt_theme_sdv_team's subtitle, the gt_legend_discrete subtitle) blends at sdvplotR's exact weights, as the table themes already did; a few colors were one step off in a channel.
  • A table whose id is the empty string gets a random id before a theme or cell, border or watermark helper scopes CSS to it; only gt_theme_sdv did this before, and elsewhere the CSS (# td) reached no cell.
  • Every sdvplot.great_tables function refuses raw data with one message ("gt must be a great_tables GT, not DataFrame. It looks like raw data: wrap it in great_tables.GT() first."), as sdvplotR's .check_gt words it; an unknown density and an unknown *_style key are worded alike across the table modules too, and the style error names the argument.
  • gt_sdv_logos, gt_sdv_wordmarks and gt_sdv_headshots document exactly which locations they take (loc.body(), loc.stub(), loc.row_groups()) and raise ValueError for any other: column labels used to come out as escaped <img> text, and a title or source note was silently left alone. gt_sdv_cols_label puts marks in the column labels.
  • A headshot whose ESPN player id was read through a float (pandas stores [3139477, None] as floats, so the cell reads 3139477.0) carries 3139477 in its alt text and team attribute, in every adapter; the URL was already right.
  • gt_theme_preview(n=...) takes only a positive whole number of rows (numpy integers included); 0, negative numbers, booleans, floats and strings raise ValueError instead of showing no rows, all but the last, one row or a polars error.
  • A table theme swaps out the fonts an earlier sdvplot theme put in front of the table's fonts instead of stacking on them: a table themed twice no longer lists every font twice, and a second theme no longer keeps the first one's font as its fallback (with gt_theme_sdv, directly behind Lato). Fonts you set with opt_table_font() stay, behind the theme's, as in sdvplotR. gt_theme_sdv and gt_theme_sdv_team fall back to gt's default_fonts(), as sdvplotR's do.
  • A translucent #rgba/#rrggbbaa color is refused (ValueError) where sdvplot draws the color it computes (palette stops and ramps, legend and tier swatches, theme accents), instead of being drawn solid with its alpha silently dropped; an opaque alpha (f/ff) is accepted and #rgba is now read. A color sdvplot passes to CSS as given and only measures for its ink (gt_color_pills(na_color=), gt_indicator_boxes(color_yes=, color_no=, color_na=), gt_outliers(fill=)) is still drawn translucent, and its ink is now read on the color it shows over the table background rather than on the color with its alpha dropped. reactable_sdv_team_color_bg still replaces na_color's alpha with its own alpha, as sdvplotR does; CSS-only color arguments take any CSS color.
  • A translucent table background (tab_options(table_background_color="#111111CC")) is read as the color it shows over the page when gt_legend_discrete and gt_marginalia pick their ink, so a near-black one gets light text.

Content findings (team index, team tiers, surface)​

  • MLB historical codes are season-dated and reach their franchise. A new snapshot, data-raw/mlbstats_history.csv (the MLB Stats API's teams for every season since 1901; its team ids are franchise ids), dates each abbreviation and teamCode by the seasons the API used it. KCA is the Kansas City Athletics in 1955-67 and the Royals otherwise (the Royals' teamCode kca from 1968). WAS is the Twins' Senators to 1960, the Rangers' 1961-71 and otherwise the Nationals (teamCode was from 2005). PHA, BSN, BRO, NYG, SLB, WS1/WS2, MON, CAL, ANA, FLA and OAK reach today's team. A teamCode or fileCode is dropped only over seasons that overlap another franchise's run of the same abbreviation. Baseball-Reference/sportsipy MLB codes now go through that history instead of today's team names, which sent the 1901 Milwaukee Brewers (MLA) to today's Brewers and the 1872 Washington Nationals to today's Nationals; PHA, KCA, MLN, SEP, WSH (1901-60), WSA and the rest now resolve. An ESPN abbreviation or sdvplotR key another franchise held first starts the season after it (MIL from 1966, SEA from 1970, WSH from 1961; sdvplotR's KCA from 1968), so MIL in 1960 is the Milwaukee Braves.
  • resolve() without a season reads a reused code as its current holder: the team whose range covers the latest season in the index, then any. A season no alias covers falls back the same way before ranges are ignored. Measured over every alias of every league, undated and in each season 1870-2026, the only answers that change are the MLB eras above; a code only one team ever held, and every other league, answer as before.
  • ESPN's college baseball and softball abbreviations resolve. ESPN's teams list gives NC State NCST and Missouri MIZZ, while its per-team endpoint, scoreboards and standings use NCSU, MIZ, UCR, KENN and about 120 others; a new snapshot, data-raw/espn_abbrs.csv, keeps the per-team abbreviations. One the list gives another team stays with that team (LSU Alexandria's per-team LSU), and one ESPN gives two teams (softball's CEN) is left out.
  • UFL 2024-25 codes (BIR, ARL, MEM, MIC, SA, HOU for the Roughnecks) and every XFL code (2020, 2023) resolve, dated by the seasons ESPN's scoreboards show them (data-raw/espn_abbrs.csv), with the names of those seasons ("Houston Roughnecks", "Arlington Renegades"). Known gap: ESPN id 126075 was the Houston Roughnecks in 2024-25, but the archive has only the 2026 Houston Gamblers marks for it, so logo_url("HOU", "ufl", season=2024) is the Gamblers logo. The archive's Roughnecks mark is the XFL team's (xfl 112648, 2020-23), another league's entity, and nothing establishes that the UFL team used it, so it is not wired (docs/PARITY.md).
  • NHL Utah: logo_url("UTA", "nhl", season=2025) (2024-25; NHL seasons are end years) is the Utah Hockey Club's mark again, and 2026 on the Utah Mammoth's. The NHL's logo API dates the Mammoth's (team 68) logos from 2024-25, so they outranked the Hockey Club's (team 59) one-season marks. A curated range (data-raw/curated/mark_ranges.csv, each row with its reason) now starts team 68's marks in 2026, and a mark alias's range narrows a manifest row's own range instead of only filling an open one (no other archived mark changes).
  • Women's college hockey: ESPN's scoreboards use team ids its teams list lacks. A new snapshot, data-raw/espn_unlisted_teams.csv, keeps them: one whose name and abbreviation are a listed team's is that team's second ESPN id (Minnesota State's 24059 resolves to 2364, not only by name), and any other is a team of its own (Delaware, 48, DEL). Men's college hockey adds the teams its scoreboards use that the archive lacks, listed by ESPN or not (SUNY Morrisville, 126813; Maryville, 132633); the scan reads one month at a time, since a year of men's games passes the scoreboard's 1,000-event cap. The archive has no mark for these teams, so their logos are None with a warning and their colors are flagged color_source="fallback"; none is made up.
  • team_tiers() (matplotlib and plotnine) takes theme="dark" (the default, sdvplotR's) or theme="light": dark logos such as Ohio State's, Texas A&M's and Penn State's vanished on the fixed dark background. The light theme's labels, lines, subtitle and caption meet WCAG contrast on white; sdvplotR has only the dark theme (docs/PARITY.md).
  • surface() no longer floods stderr with "findfont: Font family 'Clarendon-Regular' not found". sportypy numbers football fields in Clarendon-Regular, a font it does not ship, so matplotlib logged a warning for every number it measured and drew its default font anyway. When Clarendon is not installed, surface() asks sportypy for that default (DejaVu Sans) by name, through field_updates, so the numbers look the same and nothing is logged; process logging is untouched, and a number_font the caller passes still wins.
  • Borders and fills that sdvplot's great_tables helpers draw now show in a notebook too. great_tables' notebook repr marks its own cell rules !important (td, th {border-style: none}, the stub's and row groups' backgrounds), and a stylesheet !important beats a plain inline style, so gt_row_accent's bars, for one, showed in saved images and vanished in Jupyter. Every border and fill the helpers set (gt_row_accent, gt_spotlight, gt_border_grid, gt_cutline, gt_group_stripes, gt_marginalia, gt_snake, gt_tiers, gt_outliers, gt_bold_rows, gt_color_results, gt_highlight_cells, the team-mark row groups and the themes) is now inline !important, through one helper.

Release hardening​

  • surface() draws a rink or court in well under a second instead of 16-19 s: matplotlib's add_patch walked every segment of sportypy's 10,000-point circle polygons as a Bezier curve to find the data limits (~1.3 M segments per rink); for a polygon those limits are its vertices, so they now come from the vertices in one call. The drawn PNG and the Axes' data limits are byte-for-byte the same.
  • gt_theme_kenpom no longer wipes cell fills. Its row bands were !important cell fills, so theming a table after data_color, tab_style(style.fill(...)) or gt_color_results replaced their fills, and a plain fill applied after the theme lost to them. The bands are now a table-scoped stylesheet rule on the data rows as drawn (row group headings and summary rows are neither counted nor painted), which every cell fill shows over, in either order and in the notebook repr (docs/PARITY_TABLES.md records the divergence).
  • Row striping no longer covers the text color sdvplot's fill helpers draw in VS Code and Positron notebooks. There, great_tables' repr marks its whole stylesheet !important (Jupyter, Quarto, Databricks and saved files do not), and on every other row the stripe's text color beat the plain inline ink that gt_color_results, gt_bold_rows, gt_tiers, gt_spotlight, gt_outliers, gt_highlight_cells and gt_highlight_na pair with their !important fills: white text on a dark fill turned the stripe's dark gray. That ink is now !important too. gt_color_ranks fills through great_tables' data_color, whose plain fills sdvplot cannot mark, so on a striped table in VS Code or Positron it warns once (SdvplotWarning) and says to turn striping off with opt_row_striping(row_striping=False).
  • A failed logo download raises sdvplot's own errors, never a requests exception or a bare OSError: an HTTP error status (4xx or 5xx) with no cached copy is the new sdvplot.DownloadError (an OfflineError and an OSError), and a download whose sha256 does not match the manifest, or an archived file that is not an image, is the new sdvplot.IntegrityError (a DownloadError). A 404 used to escape as requests.HTTPError, which except sdvplot.SdvplotError did not catch. except OSError still catches both.
  • Every shared input check raises InputError, so except sdvplot.SdvplotError catches bad input: logo_image(size=...) takes an int from 1 to 4096 (size=0 was a ZeroDivisionError, size=-5 a Pillow ValueError, and size=2.5 or size=True drew a 2x2 or 1x1 image; a size far past 4096 could abort the process in the SVG renderer), suggest(n=...) an int of at least 1 (n=-1 was difflib's ValueError naming -3), a season that is not a year ("2020-21", a pd.Timestamp) or a season list of the wrong length is an InputError, and so is an unknown mark_type in reactable_sdv_cols_label and gt_sdv_cols_label.
  • matplotlib.title_image and plotnine.title_image take height in points of at least 1: height=0.1 (a plot fraction, as add_logos takes) drew a 0.1 pt image without a word, and now raises an InputError naming points.
  • Importing an adapter submodule without its library (import sdvplot.plotly without plotly) raises OptionalDependencyError naming the extra (pip install "sdvplot[plotly]") rather than a bare ModuleNotFoundError; the front door had the hint, a direct import did not. OptionalDependencyError is now a ModuleNotFoundError (and still an ImportError), so except ModuleNotFoundError around the import keeps working.
  • The warning (or, with strict=True, the error) for an ambiguous team value lists the teams it could mean and what picks one: 'Charlotte' (ambiguous: 2429 Charlotte 49ers or 3253 Charlotte Saints); pass season= for a code reused across eras, or id_system= for the id system of the values. It used to say only "ambiguous".
  • Docstrings: matplotlib.add_logos, add_wordmarks, add_headshots and axis_logos list the UnsupportedTargetError and OfflineError they raise (add_images the former), and plotnine's add_logos and add_wordmarks say season takes one season or one per point, as they always did.
  • A season outside the seasons sdvplot knows for the league is an InputError (a ValueError) naming the bounds, wherever a season is taken. The first season is the league's earliest dated alias in the bundled index (1920 for the NFL, 1947 for the NBA, 1997 for the WNBA, 2020 for the XFL; 1871, MLB's, for a league whose history is not dated), the last is next year. logo_url("OAK", "nfl", season=1900) and resolve(..., season=20) used to resolve silently. A split season such as "2020-21" gets a hint (pass the ending year), and a season of the wrong type (a pd.Timestamp) is an InputError that names season rather than the team values.
  • A variant that no mark in the archive has (a typo, or not a string) is an InputError listing the league's variants; it used to fall back to the default mark without a word. A variant the team lacks still falls back, as before.
  • Warnings point at the caller's line: they walk out of sdvplot's frames instead of using fixed stacklevels, which named _colors.py, _placement.py and other sdvplot files whenever the call went through more than one function.
  • A misspelled column name is the same ValueError on pandas and polars (column(s) ['teamz'] not in the table; its columns are [...]) in every great_tables helper that takes columns: the gt_sdv_* marks (their locations=loc.body(...) too), gt_percentile_bar, gt_wrap_labels, gt_color_pills and the rest, through the one column resolver they share. pandas used to match nothing silently and polars raised its own ColumnNotFoundError.
  • Threads that ask for the same uncached mark at once (logo_image() from a thread pool) download and decode it once: the cache runs one fetch per file and the others wait for it, and the decoded-image cache decodes each key once. On Windows every thread used to download its own copy, and replacing the file while another thread had it open raised PermissionError: [WinError 5] Access is denied; the logo manifest's first load warned could not refresh ... the same way. A replace that another process refuses, over the same content-addressed file it already wrote, is no longer an error.
  • A long-running session no longer keeps every logo manifest (about 17 MiB parsed) or nflverse player table it has read: when the cached file is refreshed, the previous one is freed. clear_cache() now also frees the parsed manifest, the player table and the per-league tables built from the manifest, as it already freed the decoded images.
  • clear_cache() unlinks a cache subdirectory that is a symlink in the default cache directory (what it points to is untouched) and leaves one alone with a warning in a directory you chose. It used to raise OSError from shutil.rmtree after deleting manifest/, leaving the later subdirectories and the in-memory caches as they were; the in-memory caches are now emptied even when a removal fails.
  • The in-memory cache of decoded images counts bytes per sample: a 16-bit image (mode I;16) is two bytes a pixel and a 32-bit one (I, F) four. They were counted at one byte a sample, so they could hold two to four times the 256 MB budget.

Security​

  • Image URLs from the logo manifest (archive_url) and from nflverse's player table (headshot) must be plain https URLs: a host, then only RFC 3986 characters, with no quote, <, >, whitespace, backslash or control character. A manifest row that fails is dropped and a headshot that fails is treated as missing (the player gets their ESPN headshot when nflverse has their ESPN id), each with one SdvplotWarning. Such a URL used to reach the web adapters unchanged, and Altair's HTML export wrote it into a <script> block unescaped, so a poisoned manifest or player table could run script in an exported page. The web adapters also percent-encode any such character left in an image URL.
  • SVG rendering is bounded. An SVG mark is rendered inside a size x size box (its longest side size pixels, at most sdvplot._images.MAX_SIZE, 4096) after a small probe render measures its aspect ratio. An SVG more than 64 times longer than it is wide, or a size over 4096, is an InputError before anything is rendered. resvg used to render at width=size first, so a tall SVG or a large size asked for gigabytes and could abort the Python process.
  • urllib3>=2.6 is a dependency. requests>=2.33 still allowed urllib3 1.26 and 2.0 to 2.5, which decompress a whole received chunk at once: a 275-byte gzip body cost 4 GB of memory before the download byte cap saw it (CVE-2025-66471). The download loop's fallback for urllib3 below 2 is removed.
  • A download's 120 s deadline covers the TLS handshake and the response headers, not only the body: a watchdog shuts the connection's socket down at the deadline, across every redirect hop, and no single read waits past it. Each read had a 60 s timeout of its own, so a server sending a header byte every 59 s held the call open almost indefinitely. Through a proxy, the watchdog covers the body only.