- Changelog
- [Unreleased](#unreleased)
- [0.1.1 - 2026-10-26](#011---2026-10-26)
- [0.1.0 - 2026-10-05](#010---2026-10-05)
- Migrating from the git pre-release
- Added
- Core (team identity, colors, logos, cache, adapter contract)
- Repository standards
- Matplotlib family
- Tables, wave A (marks and team identity)
- Table themes
- Tables wave C1 (cell styling and formatting)
- Tables, wave D (image export and composition)
- Web family
- Long tail (pygal, Cartopy, gallery compatibility)
- Tables wave C2 (legends, layout and annotation)
- Parity extras (court coordinates, images by path, reference lines)
- Parity extras (title images, team tiers)
- Release hardening
- Changed
- Fixed
- Security
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_mappingspellings resolve:resolve("VA TECH", "cfb"),"NC St.","North Carolina State","UT San Antonio","Presbyterian College","St Francis (PA)".tools/export_cfbplotr.Rexports the mapping with logo_ref's type and ESPN id intodata-raw/cfbplotr_names.csv(commit indata-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 givesNonefor 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
divisioncolumn in the team index: a college team's NCAA division in its latest season in ESPN's groups ("FBS","FCS","DII","DIII"incfb;"DI","DII","DIII"elsewhere), from thesubdivision_idthattools/fetch_sources.py --groups-onlynow keeps indata-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_SOURCESintools/fetch_sources.py), and ranks after every other source. -
College football wordmarks: the index maps 360 of the 362
cfbplotr-legacymarks the 2026-11-09 sdv-assets capture archived (data-raw/manifest_marks.csv,manifest_conferences.csv; indexe04c50e5682e); 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 (andmarks()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_aliasestables in the sportsdataverse-data{league}_groupsreleases (NFL, college football, NBA, WNBA, men's and women's college basketball, MLB, NHL), snapshotted bytools/fetch_sources.py --crosswalks-onlyintodata-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, likenhl_id, they answer only an explicitid_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_aliasesmatches 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-onlysnapshots them intodata-raw/provider_ids.csv): stats.ncaa.org org (school) ids and season team ids asid_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 passid_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", andequal_area=Truefor squares of a hexagon's area),cell_pointsandbin_ids, withBinShapeinsdvplot.typing. Each bin records its centre, its points' row numbers and link ids, and its own id"x,y", thedata-sdv-idsdvplot-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 (aPolyCollection), Plotly (path shapes and a selectable trace carrying bin ids and point ids), Bokeh (apatchesglyph whose selection links both ways with the points'ColumnDataSourceand anyDataTableon it, in the browser) and Altair (anarealayer with abin_idselection param). The colors cookbook and the WNBA tutorial draw their shot charts with it (hexagons, then squares) instead ofax.hexbin. -
Bins:
origin=(x, y)onhexbin,squarebin,binnerand everyadd_binsshifts 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 eachBinaweight, the sum of its points' (the count without weights), andadd_bins(value="weight")fills by it instead of the count (BinValueinsdvplot.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) andmin_count=leaves sparse cells undrawn (min_count=2: single attempts; the binshexbin/squarebinreturn are unchanged); the WNBA tutorial's squares usemin_count=2. The same names and defaults as sdvplotR's. -
add_binsfor plotnine (ageom_polygonlayer 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 tofig.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) andmjhl(19), keyed by their HockeyTech team ids (id_system="hockeytech"); Australia'snbl(10, ESPN ids); the national teams pooled by sport,fiba(30: basketball's men's, women's and ESPN's ungendered FIBA list,programmens/womens/national) andiihf(16, ice hockey,programnational), both ESPN ids, so an abbreviation such asAUSthat names a men's and a women's team resolves to None with a warning and the ESPN id resolves; thecfl(9, ESPN ids 79-87, content.cfl.ca marks); thecebl(15, CEBL team ids), theeasl(12, DataCore team UUIDs) and Italy'slba(24, LBA club ids, marks dated by season); andf1(31 constructors, 2002-2026, by Jolpicaconstructor_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_colourfrom 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-onlyrefreshes the archive's snapshots, ESPN's teams lists and the newdata-raw/f1_teams.csv(Jolpica names, OpenF1 colors through a curated OpenF1 team name toconstructor_idmap) without the CFBD key. -
College baseball, softball and men's and women's hockey teams carry a
conferenceandconference_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'sAHA,CCHA,CHA,ECAC,Hockey East,NCHC,WCHA; women'sAHA,ECAC,Hockey East,NEWHA,WCHA), so every college hockey team with a conference joins a row.tools/fetch_sources.py --groups-onlyrefreshesdata-raw/groups_latest.csvalone. -
Soccer clubs carry their domestic league:
teams("soccer")stays one pool of ESPN club ids, and a club'sconference_id/conferenceare 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) areprogram"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, whichresolve()andsuggest()never read. The source is sdv-assets'manifest/soccer_competitions.csv(data-raw/soccer_competitions.csv). -
More conference marks draw: the NHL's
EasternandWestern(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. Thecflgains 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 HockeyTechplayer_idwithid_system="league"(assets.leaguestat.com): the PWHL, AHL, ECHL, OHL, WHL, QMJHL and USHL, and the junior and minor leaguessphl,chl,bchl,ajhl,sjhl,ojhl,cchl,gojhl,mhl,nojhl,vijhl,kijhlandmjhl(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 Jolpicadriver_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'scenter_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 raisesInputError("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, andlogo_url()/marks()reach each by its key:MLB,AL,NL(mlb);NBA,East,West(nba);WNBA,East,West(wnba);NHL, its division marksAtlantic,Metropolitan,Central,Pacificand the 2024 All-Star teamsMAT,MCD,HGS,MKN(2024 only);AAF; andNCAAin every college league (cfb,mbb,wbb,ncaa_baseball,ncaa_softball,ncaa_mhockey,ncaa_whockey). The conference and league rows now come from sdvplot's owndata-raw/curated/non_team_rows.csv, which names each row's mark by its manifest key, instead of the frozendata-raw/sdvplotr_conferences.csvexport (sdvplotR no longer has the table); the 92 existing rows, their colors and aliases are unchanged. The manifest'sdivisionlevel 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.csvnames each with its reason, andtools/fetch_sources.pydrops 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 xcenter_field_distanceacross (60 ft at 263.6 ft from home plate on an MLB field), from the league's field parameters andfield_updates, in the dark-background variant for the grass. Every surface's center logo now also followsrotation, 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'sPWHLRink: 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
altairextra needsaltair>=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'ssurfaceLayer: 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 ownModuleNotFoundErrorinstead of the surfaces-extra message.surface()andsdvplot.pydeck.surface_layer()suggestpip install -U "sportypy>=1.2"(and the GitHub install while PyPI has only sportypy 1.0), not re-installingsdvplot[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 negativefaceoff_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()andsdvplot.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, sodeck()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:
øtoo,ætoae,œtooe,đandðtod,łtol,þtothand the dotlessıtoi, in either case, soresolve("HB Koge", "soccer")finds HB Køge, as"Brondby IF","F.C. Kobenhavn"and"Sherbrooke, Phoenix"(qmjhl) find theirs (sdvplotR#70).ßalready folded toss; 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"underid_system="name"or"cfbd"is the Troy Trojans: a name thenameorcfbdsystem 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'spitch_updates = NULLdoes, instead of raisingTypeError(#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
conferencevalue 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 theirconference_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) raisedDownloadErroron a headshot the CDN answers with a 404 (an ESPN or HockeyTech id it has no photo for). They now skip that point with oneSdvplotWarning, 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 anInputError, 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./deckglbuilds (held to one shared fixture).logo_icon_layerdraws team logos at points (anIconLayerof auto-packed logo icons),pass_arc_layerdraws arcs in team colors (primary at the source, secondary at the target; withbackground, 3:1 contrast and ΔE 20 apart through sdvplot-js's team palette, ported), andsurface_layerdraws a sportypy rink, pitch, court or field as aPolygonLayerin the surface's own coordinates. The props are plain dicts (pydeck.Layer(**props));deck()builds apydeck.Deckfitted 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 JavaScriptrestore()) 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=)returnsclasses,styleand a scopedcssstring (with a Google Fonts import) that styles anitables.showtable like any of the 122 surveyed themes.sdvplot.plottable.plottable_sdv_theme(name, mode=)returns theplottable.Tablekeywords (text, dividers, stripes) for any of the 122 surveyed themes, plus afacecolorto 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()andsdv_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 bytools/gen_gt_shortcuts.py.reactable_sdv_theme(name, mode=)accepts every registry theme, and the newreactable_sdv_args(name, mode=)returns theReactablekeywords (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 (itsinclude_conferences): the 89 college conferences of cfb, mbb and wbb and the AFC, NFC and NFL, withprogram"conference"or"league", the conference's short name asteam_idandabbr, cbbplotR's colors (color_source"cbbplotR") and theconference_idthe league's teams carry. The default lists teams only, andresolve()andpalette()never answer a conference key, so no existing call changes.- Conference and league logos from the archive (sdvplotR's
logo_marksfor 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, withvariant="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'sMACis still Macalester, andresolve()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.pyconference_mark_aliases, from the newdata-raw/manifest_conferences.csvsnapshot). All 92 rows have a primary mark, as sdvplotR's 92 do. - Headshots by the league's own player id:
id_system="league"(sdvplotR'sid_type = "league") onheadshot_urland every headshot helper (add_headshotson 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 StatsPERSON_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 anInputErrornaming the ones that have them, and aDownloadErrorfrom 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_sdvandscale_fill_sdvtakealpha=, an opacity applied to the team colors (sdvplotR'salpha);na_valueis drawn as given.scale_colour_sdvis the British alias sdvplotR and plotnine both ship.gt_merge_stack_team_colortakesbackground=, 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_tierstakesalt=, a function from the image paths or URLs to their alt text. By default a logo the archive knows (anylogo_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, withflipfor teams attacking opposite ends. The port of sdvplotR'ssdv_pitch_coords(), matched to 1e-12 on every provider.court_coords(provider="euroleague")converts the Euroleague shot frame of sportsdataverse-py'seuroleague_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 courtsurface("fiba")draws, in meters, with the-1,-1free throws as null. The default"nba"is unchanged, byte for byte. Matched to sdvplotR'ssdv_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'sscale_x_sdv_headshots()/scale_y_sdv_headshots()andelement_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 raiseUnsupportedTargetErroras before.sdvplot.typing.AxisMarkTypeis theLiteralof 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/sportyand@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 framepitch_coords()returns;pitch_updatesstill overrides it key by key.gt_merge_stack_team_colorkeeps 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 (#737373on 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, orNonenot to dim.team_tiers(matplotlib and plotnine) takesvariant=, 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. Passvariant="default"for the old look (sdvplotR's), or any variantadd_logostakes.- great_tables 1.1 is supported. Its
data_colornow interpolates in CIELAB, as R gt andscales::col_numericdo, sogt_color_ranksfills match sdvplotR's exactly under it;gt_color_pills,gt_percentile_barand thegt_legend_continuoussteps now draw great_tables' own gradient, so they stay equal todata_colorcells 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_xis 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 aTypeErrorthat namedresolve()though the bad value wasx. A container sdvplot cannot read now raises aTypeErrorthat names no one function:expected a scalar, list, tuple, range, numpy array or a pandas/polars Series, got dict. - NHL
WINis 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'sresolve_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 VALLEYandRGVresolve in college football (ESPN's teams list omits UT Rio Grande Valley, 292; its per-team endpoint'sRGVis now indata-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) andUSI(Southern Indiana, 88) in mbb,MERC(Mercyhurst, 2385) andSFPAin wbb, and with them sdvplotR's keys for those teams.tools/fetch_sources.pyreads them from ESPN's Core API per season (ESPN_CORE_TEAMS) intodata-raw/espn_abbrs.csv.teams()shows that code asabbrwhere ESPN's teams lists give none, as for UTRGV (RGV) and college baseball's Loras (LOR): eight teams had a nullabbr. - sdvplotR's conference names draw the conference's logo again:
logo_url("Southeastern Conference", "cfb")islogo_url("SEC", "cfb"),logo_url("B10", "mbb")islogo_url("Big Ten", "mbb"), and so for the other keys sdvplotR'sclean_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'sMACis still Macalester;resolve("Mid-American Conference", "cfb")no longer gives Macalester (it went through sdvplotR'sMACcanon): it isNone, and its logo is the conference's. gt_tiersno longer writes twoaltattributes on an image under great_tables 1.1, whosefmt_imageadds an emptyalt="": 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")ispalette("nfl", which="secondary"):paletteispalette(league, teams=None, *, which="primary", season=None), as sdvplotR'ssdv_color_palette(sport, teams, type). The old call raisesInputError: 'secondary' is a color slot, not a team; pass it by keyword: palette(league, teams=..., which="secondary").team_colors(teams, "nfl")isteam_colors("nfl", teams): the league comes first, as in sdvplotR'ssdv_team_colors(sport, team, type). With a list or Series of teams the old order raisesInputError: 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_systemandstrictonresolve;season,variant,mark_typeandsizeonlogo_urlandlogo_image;seasononmarks;nonsuggest;id_systemonheadshot_url;xandyoncourt_coords.resolve(v, "nfl", 2020)raisesTypeError: resolve() takes 2 positional arguments but 3 were given; writeresolve(v, "nfl", season=2020). - Each public submodule exports only its
__all__, anddir()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_cellsand_rendered_html), sosdvplot.matplotlib.draw_placementsraisesAttributeError: module 'sdvplot.matplotlib' has no attribute 'draw_placements'. - A table's
heightis pixels:gt_sdv_logos(gt, "team", league="nfl", height=0.1)(and the front door on aGT) raisesInputError: 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 tablesinstead of drawing a 0.1 px image. - New errors, each still the builtin you may already catch:
SdvplotErroris the base of them all;InputError(aValueError) is raised by the shared argument checks (league,which,id_system,mark_type, height, alpha);UnsupportedTargetError(aTypeError) by an adapter given the wrong kind of object or asked for axis logos it cannot draw;UnsafeDownloadError(anOSError) andUnsafeCachePathError(aValueError) 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 stringteam_id, with a documentedPRIORITYorder andnhl_idavailable only through an explicitid_system. suggest()for near-miss candidates when a value does not resolve.palette()andteam_colors(): team colors as a{team: "#hex"}mapping or one hex per value, withcolor_source="fallback"marking placeholders.logo_url(),logo_image()andmarks(), 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) withclear_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/bytools/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.pyinto 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_headshotsandaxis_logoswork on matplotlib Axes, one-Axes Figures and seaborn grids (sdvplot.matplotlib);heightis a fraction of the Axes height at any dpi or figure size.- plotnine:
geom_sdv_logos,geom_sdv_wordmarks,geom_sdv_headshots,axis_logosand the team color scalesscale_color_sdv/scale_fill_sdv(sdvplot.plotnine). surface(): sportypy playing surfaces in team colors, the port of sdvplotR'ssdv_surface().- plottable
logo_columnandheadshot_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 withleague=forsport=:gt_sdv_logos,gt_sdv_wordmarksandgt_sdv_headshotsput marks in body, stub or row-group cells, andgt_sdv_cols_labelputs them in column labels.gt_merge_stack_team_colorstacks two columns in one cell, the bottom line in the team color.- The themes
gt_theme_sdv(light or dark, three densities) andgt_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_wordmarksandadd_headshotsroute a great_tablesGTto those functions.sdvplot.reactable(new[reactable]extra):reactable_sdv_logos,reactable_sdv_wordmarks,reactable_sdv_headshots,reactable_sdv_cols_label,reactable_sdv_team_color_barandreactable_sdv_team_color_bg. Each returnsreactable.Columnobjects.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_tierandgt_theme_tufte, each withdensity="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_naandgt_indicator_boxes. They take tables built from pandas or polars data. gt_color_pillsandgt_color_ranksrecord their color scale forgt_legend_continuous.docs/PARITY_TABLES.mdlists where they differ from R.
Tables, wave D (image export and composition)
sdvplot.great_tables:gt_save_crop,gt_social_cropandgt_save_batchsave tables as trimmed, padded images (great_tables'GT.gtsave, headless Chrome);gt_gridandgt_stack_tablescompose several tables into one HTML block or image. Ports of the sdvplotR functions of the same names; differences are indocs/PARITY_TABLES.md.[tables]nameshtmltoolsandnokap, which great_tables 1.0 already installs. Saving needs Chrome or Chromium (setCHROME_PATHfor a non-standard install); no selenium.
Web family
add_logos,add_wordmarks,add_headshotsandaxis_logoswork on Plotly figures (sdvplot.plotly; sdvplot pins the axis ranges soheightis a fraction of the plot area) and Altair charts (sdvplot.altair, plus the nativelogo_layer).add_logos,add_wordmarksandadd_headshotson Bokeh figures (sdvplot.bokeh), HoloViews elements through a Bokeh plot hook (sdvplot.holoviews) and Folium maps (sdvplot.folium,xlongitude andylatitude).embed=Trueinlines the images as data URIs, for HTML that renders offline and for static export.- The
[holoviews]extra now installs Bokeh 3 as well.
Long tail (pygal, Cartopy, gallery compatibility)
- pygal:
add_logos,add_wordmarksandadd_headshotson XY-family charts (XY,DateTimeLine,DateLine,TimeLine,TimeDeltaLine), drawn in every render;embed=Truemakes 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 withcopy.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_wordmarksandadd_headshotstaketransform=(e.g.ccrs.PlateCarree()for longitude/latitude, or any matplotlib transform); aGeoAxeswithout it raisesValueError. 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, newcompatdependency group); a watch item for Reflex XY image marks, re-checked at each release.
Tables wave C2 (legends, layout and annotation)
sdvplot.great_tablesgains 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 thatgt_percentile_bar,gt_color_ranksorgt_color_pillscolored with;gt_legend_discrete()draws the keygt_tiersused.docs/PARITY_TABLES.mdlists 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 andsurface("nba")draw, on pandas or polars, the port of sdvplotR'ssdv_court_coords(); bit-identical to it on realshotchartdetailrows.sdvplot.matplotlib.add_images()andsdvplot.plotnine.geom_from_path(): any image by local path or URL at (x, y), sized like the logo verbs, the port of ggpath'sgeom_from_path(); unreadable images are skipped with one warning.sdvplot.plotnine.geom_mean_lines()andgeom_median_lines(): per-panel reference lines, the ports of ggpath's, matching its values on real data.docs/PARITY.mdmaps the remaining sdvplotR exports to sdvplot functions or recipes;tools/export_parity_extras.Rexports the sdvplotR and ggpath oracles the parity tests read.
Parity extras (title images, team tiers)
title_image()insdvplot.matplotlib(Axes title or Figure suptitle) andsdvplot.plotnine(added with+): sdvplotR'sggtitle_image(), an image beside the title. The image is a team's logo whenleague=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);heightis in points,sideis"left"or"right", and the image and title are aligned together as the title is, through laterset_titlecalls. A second call on the same title replaces the image.team_tiers()insdvplot.matplotlib(a Figure) andsdvplot.plotnine(a ggplot): sdvplotR'ssdv_team_tiers()tier list on its dark theme, from a pandas or polars frame withtier_noandteam(optionaltier_rank), withpresort,tier_desc,no_line_below_tieranddevel=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(aFutureWarningand aSdvplotWarning), with a deprecation policy in CONTRIBUTING.md: one minor release of warnings before a removal. Nothing is deprecated yet. id_systemandstrictwherever a team is resolved, passed to the resolver asresolve()takes them:team_colors,palette,logo_url,logo_image, the great_tables helpersgt_sdv_logos,gt_sdv_wordmarks,gt_sdv_cols_labelandgt_merge_stack_team_color(gt_theme_sdv_teamtakesid_system; it is always strict), and the reactable helpersreactable_sdv_logos,reactable_sdv_wordmarks,reactable_sdv_cols_label,reactable_sdv_team_color_barandreactable_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, whileteam_colors("nhl", [1, 6, 10], id_system="nhl_id")gives the Devils, Bruins and Leafs.gt_sdv_cols_label'sid_systemnow defaults to None: "auto" for logos and wordmarks, "espn" for headshots.team_colors'swhichis typedWhich, sowhich="secondry"is a type error, as it is forpalette.sdvplot.typing: theLiteraltypes 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.leaderboardmakes a season's leaders as a great_tables table with headshots and logos;gamedaymakes 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;postpublishes it to Bluesky over plainrequests(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).
Documentation — example notebooks by section, interactive outputs and the gallery
tools/render_notebooks.pyrenders every notebook underexamples/notebooks/, its folder picking the section: the top level is "Getting started", thenleagues/(Tutorials by league),cookbooks/,recipes/andleaderboards/, each a sidebar category, beside the hand-written Automation guide. A notebook'smetadata["sdvplot"](label,position,description, optional per-celltimeout) replaces the renderer's hard-coded list, and--onlytakes a path such asleagues/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
galleryin 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-onlyrebuilds it). - The weekly
live-tests-cronrender executes every notebook and publishes every generated path.
Release hardening
-
sdvplot.plotnine.scale_color_sdv/scale_fill_sdvtakewhich,seasonandna_valueby keyword only (aspalette()andteam_colors()do), and they andsdvplot.pygal.team_styletakeid_systemandstrict: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, flaggedcolor_source="logo"because no source publishes them (teamcolorswas 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-onlyrefreshes the two new snapshots,data-raw/espn_colors.csvanddata-raw/logo_colors.csv. -
The
sdvplot.great_tableshelpers 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 passescheck_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_kenpombands 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 aftergt_theme_ncaa(gt_color_resultsfills 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_sourceespnorlogo); the WNBA tier list ranks teams within each tier, so its logos no longer overlap; the cache page listsurlimages/and the currentversions()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.testingagain: rules 0 to 8 (exactly one warning per skip reason,heightandalphachecked 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, sogt_theme_athleticor any adapter-only function was on none. -
The docstring gate (
tools/gen_docs.py --check) finds the public submodules itself, astests/test_api.pydoes, 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 holdscontents: 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-markersand--strict-config. Python 3.14 is a declared classifier. A run onmainis never cancelled by a later push (only a PR's is), and the live network tests run on manual dispatch and weekly inlive-tests-cron, not on every push. -
Repeated lookups are faster: with everything cached,
logo_urltakes about 0.1 ms per call instead of 2.5 ms, andlogo_imageabout 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 repeatedadd_logoswith 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_imagesandtitle_image, andsdvplot.plotnine.geom_from_pathandtitle_image, say an image URL must be https. They said "http or https", but an http URL is refused withUnsafeDownloadError. -
Documentation: every public function's docstring names the error classes the code can raise since the API freeze:
InputErrorfor the shared checks (heights, alpha, league, id system, season, variant; it saidValueError),UnsupportedTargetErrorfor a target an adapter cannot draw on (it saidTypeError), and each download error a function can meet (OfflineError,DownloadError,IntegrityError,UnsafeDownloadError,UnsafeCachePathError, andOptionalDependencyErrorfor an SVG mark without thesvgextra), 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 intests/test_submodule_examples.py, as the submodules' do. The concept and adapter pages say what the code does: the cache'surlimages/directory, shared downloads andUnsafeDownloadError(not anOfflineError);id_systemandstrictonpalette(),team_colors()andlogo_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'scolor_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_logoson a faceted plot likewise warns once. - plotnine:
add_logos/add_wordmarkswith 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 theseasonaesthetic. - 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 warnsskipped ... 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_contractis stricter: a call that skips nothing must not warn and each reason it skips points for gives exactly oneSdvplotWarning(rules 1, 2, 6 and 7);height(including its out-of-range values) is checked onadd_headshotsandaxis_logosas well asadd_logosandadd_wordmarks, andalphaon every verb that takes it; heights are compared within 1% of the requested value, as measured by the hooks. An out-of-rangeheightmust raise when the verb is called, not only when the marks are rendered.drawn_axis_marksnow returns(team_id, tick position, height).check_table_adapter_contractlikewise requires no warning for known values and exactly one for all-unknown input.
Tables follow-ups
- Muted text (
gt_theme_sdv_team's subtitle, thegt_legend_discretesubtitle) 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_sdvdid this before, and elsewhere the CSS (# td) reached no cell. - Every
sdvplot.great_tablesfunction 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_gtwords it; an unknowndensityand an unknown*_stylekey are worded alike across the table modules too, and the style error names the argument. gt_sdv_logos,gt_sdv_wordmarksandgt_sdv_headshotsdocument exactly whichlocationsthey take (loc.body(),loc.stub(),loc.row_groups()) and raiseValueErrorfor 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_labelputs 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 reads3139477.0) carries3139477in 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 raiseValueErrorinstead 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 withopt_table_font()stay, behind the theme's, as in sdvplotR.gt_theme_sdvandgt_theme_sdv_teamfall back to gt'sdefault_fonts(), as sdvplotR's do. - A translucent
#rgba/#rrggbbaacolor 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#rgbais 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_bgstill replacesna_color's alpha with its ownalpha, 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 whengt_legend_discreteandgt_marginaliapick 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.KCAis the Kansas City Athletics in 1955-67 and the Royals otherwise (the Royals' teamCodekcafrom 1968).WASis the Twins' Senators to 1960, the Rangers' 1961-71 and otherwise the Nationals (teamCodewasfrom 2005).PHA,BSN,BRO,NYG,SLB,WS1/WS2,MON,CAL,ANA,FLAandOAKreach 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),WSAand the rest now resolve. An ESPN abbreviation or sdvplotR key another franchise held first starts the season after it (MILfrom 1966,SEAfrom 1970,WSHfrom 1961; sdvplotR'sKCAfrom 1968), soMILin 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
NCSTand MissouriMIZZ, while its per-team endpoint, scoreboards and standings useNCSU,MIZ,UCR,KENNand 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-teamLSU), and one ESPN gives two teams (softball'sCEN) is left out. - UFL 2024-25 codes (
BIR,ARL,MEM,MIC,SA,HOUfor 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, sologo_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's24059resolves to2364, 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 areNonewith a warning and their colors are flaggedcolor_source="fallback"; none is made up. team_tiers()(matplotlib and plotnine) takestheme="dark"(the default, sdvplotR's) ortheme="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, throughfield_updates, so the numbers look the same and nothing is logged; process logging is untouched, and anumber_fontthe 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!importantbeats a plain inline style, sogt_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'sadd_patchwalked 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_kenpomno longer wipes cell fills. Its row bands were!importantcell fills, so theming a table afterdata_color,tab_style(style.fill(...))orgt_color_resultsreplaced 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.mdrecords 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 thatgt_color_results,gt_bold_rows,gt_tiers,gt_spotlight,gt_outliers,gt_highlight_cellsandgt_highlight_napair with their!importantfills: white text on a dark fill turned the stripe's dark gray. That ink is now!importanttoo.gt_color_ranksfills 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 withopt_row_striping(row_striping=False). - A failed logo download raises sdvplot's own errors, never a
requestsexception or a bareOSError: an HTTP error status (4xx or 5xx) with no cached copy is the newsdvplot.DownloadError(anOfflineErrorand anOSError), and a download whose sha256 does not match the manifest, or an archived file that is not an image, is the newsdvplot.IntegrityError(aDownloadError). A 404 used to escape asrequests.HTTPError, whichexcept sdvplot.SdvplotErrordid not catch.except OSErrorstill catches both. - Every shared input check raises
InputError, soexcept sdvplot.SdvplotErrorcatches bad input:logo_image(size=...)takes an int from 1 to 4096 (size=0was aZeroDivisionError,size=-5a PillowValueError, andsize=2.5orsize=Truedrew 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=-1was difflib'sValueErrornaming-3), a season that is not a year ("2020-21", apd.Timestamp) or a season list of the wrong length is anInputError, and so is an unknownmark_typeinreactable_sdv_cols_labelandgt_sdv_cols_label. matplotlib.title_imageandplotnine.title_imagetakeheightin points of at least 1:height=0.1(a plot fraction, asadd_logostakes) drew a 0.1 pt image without a word, and now raises anInputErrornaming points.- Importing an adapter submodule without its library (
import sdvplot.plotlywithout plotly) raisesOptionalDependencyErrornaming the extra (pip install "sdvplot[plotly]") rather than a bareModuleNotFoundError; the front door had the hint, a direct import did not.OptionalDependencyErroris now aModuleNotFoundError(and still anImportError), soexcept ModuleNotFoundErroraround 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_headshotsandaxis_logoslist theUnsupportedTargetErrorandOfflineErrorthey raise (add_imagesthe former), and plotnine'sadd_logosandadd_wordmarkssayseasontakes one season or one per point, as they always did. - A season outside the seasons sdvplot knows for the league is an
InputError(aValueError) 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)andresolve(..., 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 (apd.Timestamp) is anInputErrorthat namesseasonrather than the team values. - A
variantthat no mark in the archive has (a typo, or not a string) is anInputErrorlisting 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.pyand other sdvplot files whenever the call went through more than one function. - A misspelled column name is the same
ValueErroron pandas and polars (column(s) ['teamz'] not in the table; its columns are [...]) in every great_tables helper that takes columns: thegt_sdv_*marks (theirlocations=loc.body(...)too),gt_percentile_bar,gt_wrap_labels,gt_color_pillsand the rest, through the one column resolver they share. pandas used to match nothing silently and polars raised its ownColumnNotFoundError. - 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 raisedPermissionError: [WinError 5] Access is denied; the logo manifest's first load warnedcould 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 raiseOSErrorfromshutil.rmtreeafter deletingmanifest/, 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 oneSdvplotWarning. 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
sizexsizebox (its longest sidesizepixels, at mostsdvplot._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 asizeover 4096, is anInputErrorbefore anything is rendered. resvg used to render atwidth=sizefirst, so a tall SVG or a largesizeasked for gigabytes and could abort the Python process. urllib3>=2.6is a dependency.requests>=2.33still 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.