sdvplot 0.1.0__py3-none-any.whl

sdvplot/_resolve.py

@@ -0,0 +1,363 @@
+"""Turn whatever team identifiers a user has into canonical (league, team_id) keys, never guessing."""
+
+from __future__ import annotations
+
+import functools
+import numbers
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any, overload
+
+from sdvplot import _index
+from sdvplot._errors import InputError, UnresolvedTeamError, warn
+from sdvplot._normalize import _is_na, check_season, norm_season, norm_value
+from sdvplot._types import IdSystem
+
+if TYPE_CHECKING:
+    import numpy as np
+    import pandas as pd
+    import polars as pl
+else:
+    from sdvplot._lazy import pl
+
+# The order "auto" tries id systems in; the first system with a candidate decides
+PRIORITY: tuple[str, ...] = (
+    "team_id",
+    "espn",
+    "espn_abbr",
+    "nhl",
+    "nflverse",
+    "mlbstats",
+    "nba_api",
+    "hockeytech",
+    "ncaa",
+    "pff",
+    "cricinfo",
+    "cfbd",
+    "bref",
+    "sportsipy",
+    "fangraphs",
+    "sdvplotr",  # sdvplotR's clean_team_abbrs keys: after every id system, so it only fills gaps (R43)
+    "name",
+)
+# Systems "auto" never tries, only an explicit id_system: NHL stats API ids 1-28 are other teams' ESPN ids (R49)
+EXPLICIT_ONLY: tuple[str, ...] = ("nhl_id",)
+Candidates = list[tuple[str, int | None, int | None]]
+
+
+@functools.cache
+def _lookup(league: str) -> dict[str, dict[str, Candidates]]:
+    """id_system -> normalized value -> [(team_id, valid_from, valid_to)] for one league."""
+    out: dict[str, dict[str, Candidates]] = {}
+    for r in _index.alias_table().filter(pl.col("league") == league).iter_rows(named=True):
+        key = norm_value(r["value"])
+        if key is not None:
+            out.setdefault(r["id_system"], {}).setdefault(key, []).append(
+                (r["team_id"], r["valid_from"], r["valid_to"])
+            )
+    return out
+
+
+_index.on_reload(_lookup.cache_clear)
+
+
+@functools.cache
+def _latest(league: str) -> int | None:
+    """The latest season any of the league's id-system aliases names (a range's end, else its start); None if none
+    is dated. A value given without a season is read in this season first: the code's current holder."""
+    a = _index.alias_table().filter((pl.col("league") == league) & (pl.col("id_system") != "mark"))
+    latest = a.select(pl.max_horizontal(pl.col("valid_from").max(), pl.col("valid_to").max())).item()
+    return None if latest is None else int(latest)
+
+
+_index.on_reload(_latest.cache_clear)
+
+
+def _covers(lo: int | None, hi: int | None, season: int) -> bool:
+    return (lo is None or season >= lo) and (hi is None or season <= hi)
+
+
+def _match(
+    key: str,
+    season: int | None,
+    systems: Sequence[str],
+    table: dict[str, dict[str, Candidates]],
+    latest: int | None = None,
+) -> Any:
+    """The team_id for one key, None if unknown, or a sorted tuple of the team_ids when the deciding system names
+    several teams (ambiguous).
+
+    With a season, a first pass only considers aliases whose range covers it, so a reused code such as "LA" goes
+    to the team that used it that season. Then, or first without a season, a pass reads the ``latest`` season, so a
+    code two franchises used (KCA: the 1955-67 Kansas City Athletics, the Royals since) means its current holder.
+    A last pass ignores ranges, so a unique code still resolves when no range covers the season (a modern
+    abbreviation used on old data)."""
+    for when in [*(s for s in dict.fromkeys((season, latest)) if s is not None), None]:
+        for system in systems:
+            cands = table.get(system, {}).get(key)
+            if not cands:
+                continue
+            if when is not None:
+                cands = [c for c in cands if _covers(c[1], c[2], when)]
+                if not cands:
+                    continue
+            ids = {c[0] for c in cands}
+            return next(iter(ids)) if len(ids) == 1 else tuple(sorted(ids))
+    return None
+
+
+def _scalar(values: Any) -> tuple[bool, Any]:
+    """(True, the value) for one value, 0-d numpy arrays included (np.array("KC") is "KC"); else (False, values)."""
+    if getattr(values, "ndim", None) == 0 and hasattr(values, "item"):
+        values = values.item()
+    # numbers.Number covers numpy scalars such as np.int64
+    one = values is None or isinstance(values, (str, bytes, numbers.Number)) or type(values).__name__ == "NAType"
+    return one, values
+
+
+def one_team(team: Any, fn: str) -> Any:
+    """team as a scalar, or a TypeError naming fn: the mark functions answer for one team at a time."""
+    one, value = _scalar(team)
+    if not one:
+        raise TypeError(f"{fn}() takes one team, got {type(team).__name__}; use resolve() for several")
+    return value
+
+
+def _unpack(values: Any) -> tuple[list[Any], Callable[[list[Any]], Any]]:
+    """values as a list, plus a function that wraps a same-length result back into the caller's container."""
+    one, values = _scalar(values)
+    if one:
+        return [values], lambda out: out[0]
+    if isinstance(values, (list, tuple)):
+        return list(values), list
+    if hasattr(values, "tolist") and not hasattr(values, "to_list"):  # numpy arrays
+        kind = getattr(values.dtype, "kind", "")
+        if kind in ("m", "M"):
+            import numpy as np  # importable: values is a numpy array
+
+            if np.datetime_data(values.dtype)[0] in ("ns", "ps", "fs", "as"):
+                # tolist() turns sub-microsecond datetime64/timedelta64 (pandas' default) into integers
+                values = values.astype(f"{kind}8[us]")
+        return list(values.tolist()), list
+    return _unpack_series(values)
+
+
+def _unpack_series(values: Any) -> tuple[list[Any], Callable[[list[Any]], Any]]:
+    """A pandas/polars (or any narwhals-supported) Series in; a same-library String Series of results out."""
+    import narwhals as nw
+
+    try:
+        s = nw.from_native(values, series_only=True)
+    except TypeError as e:
+        raise TypeError(
+            f"resolve() takes a scalar, list, tuple, numpy array or a pandas/polars Series, got {type(values).__name__}"
+        ) from e
+    backend = nw.get_native_namespace(s)
+    # Capture the original index for pandas-like Series
+    original_input = values
+    idx = nw.maybe_get_index(s)
+
+    def wrap_result(out: list[Any]) -> Any:
+        result = nw.new_series(s.name, out, nw.String(), backend=backend).to_native()
+        # Restore the index for pandas-like objects
+        if idx is not None and hasattr(result, "index"):
+            result.index = original_input.index
+        return result
+
+    return s.to_list(), wrap_result
+
+
+def _seasons(season: Any, n: int, league: str | None = None) -> list[int | None]:
+    one, season = _scalar(season)
+    if one or _is_na(season):
+        return [norm_season(season, league)] * n  # the league's own bounds: one error naming them
+    try:
+        items, _ = _unpack(season)
+    except TypeError:  # _unpack's message names values; this is the season argument
+        raise InputError(f"season must be a year, or one per team, got {type(season).__name__}") from None
+    if len(items) != n:
+        raise InputError(f"season has {len(items)} values but there are {n} teams")
+    return [norm_season(s, league) for s in items]
+
+
+def _report(unresolved: dict[str, str], league: str, strict: bool) -> None:
+    shown = ", ".join(f"{v!r} ({why})" for v, why in unresolved.items())
+    msg = f"{len(unresolved)} value(s) did not resolve to a {league} team: {shown}"
+    if any(why.startswith("ambiguous") for why in unresolved.values()):
+        # the candidates are listed: what picks one is a season (a reused code) or the id system the values come from
+        msg += "; pass season= for a code reused across eras, or id_system= for the id system of the values"
+    if strict:
+        raise UnresolvedTeamError(msg)
+    warn(msg + ". Use sdvplot.suggest() for candidates, or strict=True to raise.")
+
+
+def _ambiguous(team_ids: tuple[str, ...], league: str) -> str:
+    """'ambiguous: 2390 Miami Hurricanes or 193 Miami (OH) RedHawks': the teams one value could mean."""
+    names = dict(_index.teams(league).select("team_id", "name").iter_rows())
+    return "ambiguous: " + " or ".join(f"{tid} {names.get(tid, '')}".strip() for tid in team_ids)
+
+
+# The result comes back in the container the values came in (_unpack). The last overload takes what the others do not
+# name: numpy scalars, pandas NA, other narwhals backends. pandas ships no types, so without pandas-stubs (as here)
+# pd.Series is Any and the last overload is never reached: hence its ignore.
+@overload
+def resolve(
+    values: str | bytes | int | float | None,
+    league: str,
+    *,
+    season: Any = None,
+    id_system: IdSystem = "auto",
+    strict: bool = False,
+) -> str | None: ...
+@overload
+def resolve(
+    values: pl.Series, league: str, *, season: Any = None, id_system: IdSystem = "auto", strict: bool = False
+) -> pl.Series: ...
+@overload
+def resolve(
+    values: list[Any] | tuple[Any, ...] | np.ndarray[Any, Any],
+    league: str,
+    *,
+    season: Any = None,
+    id_system: IdSystem = "auto",
+    strict: bool = False,
+) -> list[str | None]: ...
+@overload
+def resolve(
+    values: pd.Series, league: str, *, season: Any = None, id_system: IdSystem = "auto", strict: bool = False
+) -> pd.Series: ...
+@overload
+def resolve(  # type: ignore[overload-cannot-match]
+    values: Any, league: str, *, season: Any = None, id_system: IdSystem = "auto", strict: bool = False
+) -> Any: ...
+def resolve(values: Any, league: str, *, season: Any = None, id_system: IdSystem = "auto", strict: bool = False) -> Any:
+    """Canonical team_id(s) for team values in one league.
+
+    Accepts ids and names from any supported source (ESPN, nflverse, MLB Stats, nba_api, HockeyTech, CFBD, sdvplotR) and
+    returns the bundled index's canonical team_id, in the same container the values came in. Values that do not resolve
+    come back as None with one SdvplotWarning, or raise with ``strict=True``.
+
+    Args:
+        values: A scalar, list/tuple, numpy array, or pandas/polars Series of team identifiers in any supported id
+            system. NHL stats API ids overlap ESPN's, so "auto" never reads a number as one: pass
+            ``id_system="nhl_id"`` for them (NHL tri-codes such as "NJD" resolve under "auto").
+        league: The SDV league key, e.g. "nfl", "cfb", "ohl". Required: the same abbreviation means different teams in
+            different leagues.
+        season: One season for all values, or one per value. Picks the right team for a reused code; without one,
+            a reused code means its current holder (KCA: the Royals, not the 1955-67 Kansas City Athletics).
+        id_system: "auto" (try the priority order) or one system name.
+        strict: Raise UnresolvedTeamError instead of warning when a value does not resolve.
+
+    Returns:
+        str | list | Series | None: The same shape as ``values``: a team_id string (or None), a list, or a Series of the
+        caller's library.
+
+    Raises:
+        TypeError: If ``values`` is not a scalar, list, tuple, numpy array, or pandas/polars Series.
+        InputError: (a ValueError) If ``league`` or ``id_system`` is unknown, or ``season`` is neither a year nor a
+            list of them (a ``pd.Timestamp``, ``"2020-21"``), is outside the seasons sdvplot knows for the league
+            (from its first dated season in the bundled index, 1920 for the NFL, to next year), or is a list whose
+            length does not match the teams.
+        UnresolvedTeamError: If ``strict=True`` and a value does not resolve.
+
+    Example:
+        ::
+
+            import sdvplot
+
+            sdvplot.resolve("LV", "nfl")                  # '13'
+            sdvplot.resolve(["KC", "SF"], "nfl")          # ['12', '25']
+
+    See Also:
+        sdvplotR: https://sdvplotR.sportsdataverse.org/ ;
+        sdv-py: https://py.sportsdataverse.org/
+    """
+    _index.check_league(league)
+    _systems(id_system)
+    items, wrap = _unpack(values)
+    out, unresolved = _resolve_ids(items, league, _seasons(season, len(items), league), id_system)
+    if unresolved:
+        _report(unresolved, league, strict)
+    return wrap(out)
+
+
+def _systems(id_system: str) -> tuple[str, ...]:
+    if id_system != "auto" and id_system not in PRIORITY + EXPLICIT_ONLY:
+        raise InputError(f"unknown id_system {id_system!r}; use 'auto' or one of {list(PRIORITY + EXPLICIT_ONLY)}")
+    return PRIORITY if id_system == "auto" else (id_system,)
+
+
+def _resolve_ids(
+    items: list[Any], league: str, seasons: list[int | None], id_system: str
+) -> tuple[list[str | None], dict[str, str]]:
+    """resolve() without the report: the ids (None where a value does not resolve), and each unresolved value with
+    why ("unknown", or "ambiguous: " and the teams it could mean). The caller decides whether to warn."""
+    _index.check_league(league)
+    systems = _systems(id_system)
+    for year in {s for s in seasons if s is not None}:  # every season path resolves here: the league's own range
+        check_season(year, league)
+    table, latest = _lookup(league), _latest(league)
+    out: list[str | None] = []
+    unresolved: dict[str, str] = {}
+    memo: dict[tuple[str, int | None], Any] = {}
+    for value, s in zip(items, seasons, strict=True):
+        key = norm_value(value)
+        if key is None:
+            out.append(None)
+            continue
+        if (key, s) not in memo:
+            memo[(key, s)] = _match(key, s, systems, table, latest)
+        hit = memo[(key, s)]
+        if hit is None or isinstance(hit, tuple):
+            unresolved[str(value)] = "unknown" if hit is None else _ambiguous(hit, league)
+            out.append(None)
+        else:
+            out.append(hit)
+    return out, unresolved
+
+
+def suggest(value: Any, league: str, *, n: int = 5) -> list[tuple[str, str]]:
+    """Up to n (team_id, name) candidates for a value that did not resolve, best first.
+
+    It never picks one for you: similar names can be different teams ("Bethany (KS)" and "Bethany (WV)").
+
+    Args:
+        value: The team value that failed to resolve.
+        league: The SDV league key, e.g. "nfl".
+        n: The most candidates to return.
+
+    Returns:
+        list[tuple[str, str]]: ``(team_id, name)`` pairs, best match first; empty when nothing is close.
+
+    Raises:
+        InputError: (a ValueError) If ``league`` is unknown, or ``n`` is not an int of at least 1.
+
+    Example:
+        ::
+
+            import sdvplot
+
+            sdvplot.suggest("Kansas Cty Chiefs", "nfl", n=2)   # [('12', 'Kansas City Chiefs')]
+
+    See Also:
+        sdvplotR: https://sdvplotR.sportsdataverse.org/ ;
+        sdv-py: https://py.sportsdataverse.org/
+    """
+    import difflib
+
+    _index.check_league(league)
+    if isinstance(n, bool) or not isinstance(n, numbers.Integral) or n < 1:
+        raise InputError(f"n is the most candidates to return, an int of at least 1, got {n!r}")
+    key = norm_value(value)
+    if key is None:
+        return []
+    merged: dict[str, list[str]] = {}
+    for system in _lookup(league).values():
+        for k, cands in system.items():
+            merged.setdefault(k, []).extend(c[0] for c in cands)
+    names = dict(_index.teams(league).select("team_id", "name").iter_rows())
+    out: list[tuple[str, str]] = []
+    for k in difflib.get_close_matches(key, list(merged), n=n * 3, cutoff=0.6):
+        for tid in merged[k]:
+            if tid not in {t for t, _ in out}:
+                out.append((tid, names.get(tid, tid)))
+    return out[:n]

sdvplot/_surface.py

@@ -0,0 +1,220 @@
+"""sportypy playing surfaces in team colors: the port of sdvplotR's sdv_surface()."""
+
+from __future__ import annotations
+
+import contextlib
+import importlib
+from collections.abc import Iterator
+from typing import Any
+
+from sdvplot._colors import team_colors
+from sdvplot._contrast import contrast, on_color
+from sdvplot._errors import InputError, OptionalDependencyError
+
+# SDV league -> (sportypy.surfaces module, class). Always the sport module: the top-level sportypy.surfaces.NCAACourt
+# is the tennis court and NCAAField the football field, shadowing the basketball court and the baseball field.
+SURFACES: dict[str, tuple[str, str]] = {
+    "nfl": ("football", "NFLField"),
+    "aaf": ("football", "NFLField"),
+    "ufl": ("football", "NFLField"),
+    "usfl": ("football", "NFLField"),
+    "xfl": ("football", "NFLField"),
+    "cfb": ("football", "NCAAField"),
+    "nba": ("basketball", "NBACourt"),
+    "nbagl": ("basketball", "NBAGLeagueCourt"),
+    "wnba": ("basketball", "WNBACourt"),
+    "mbb": ("basketball", "NCAACourt"),
+    "wbb": ("basketball", "NCAACourt"),
+    "mlb": ("baseball", "MLBField"),
+    "milb": ("baseball", "MiLBField"),
+    "ncaa_baseball": ("baseball", "NCAAField"),
+    "nhl": ("hockey", "NHLRink"),
+    "whl": ("hockey", "NHLRink"),
+    "pwhl": ("hockey", "NHLRink"),
+    "ahl": ("hockey", "AHLRink"),
+    "echl": ("hockey", "ECHLRink"),
+    "ohl": ("hockey", "OHLRink"),
+    "qmjhl": ("hockey", "QMJHLRink"),
+    "ushl": ("hockey", "USHLRink"),
+    "phf": ("hockey", "PHFRink"),
+    "ncaa_mhockey": ("hockey", "NCAARink"),
+    "ncaa_whockey": ("hockey", "NCAARink"),
+    "soccer": ("soccer", "FIFAPitch"),
+}
+SURFACE_BASE = {"basketball": "#d2ab6f", "football": "#196f0c", "hockey": "#ffffff"}  # sportyR's default colors
+_DRAW_KWARGS = ("display_range", "xlim", "ylim", "rotation")
+_NUMBER_FONT = "Clarendon-Regular"  # sportypy's football yard-line number font (data/surface_dimensions.json)
+
+
+def _has_font(family: str) -> bool:
+    """Whether matplotlib can find ``family`` itself; asking with no fallback logs nothing."""
+    from matplotlib import font_manager
+
+    try:
+        font_manager.findfont(font_manager.FontProperties(family=family), fallback_to_default=False)
+    except ValueError:
+        return False
+    return True
+
+
+@contextlib.contextmanager
+def _polygon_limits(ax: Any) -> Iterator[None]:
+    """Within the block, ``ax.add_patch`` takes a polygon's data limits from its vertices in one call.
+
+    matplotlib walks every segment of an added patch as a Bezier curve to find its extrema, and sportypy draws its
+    circles and arcs as 10,000-point polygons: a rink or court walked ~1.3 M segments, 16-19 s. A straight segment's
+    extrema are its two ends, so a polygon's vertices are exactly the points matplotlib's walk measures (the CLOSEPOLY
+    slot is not a point; one vertex alone is no segment). Anything else (a curve, a NaN, a transform not in data on
+    both axes, a non-rectilinear Axes) goes through matplotlib's own walk.
+    """
+    import numpy as np
+    from matplotlib.patches import Polygon
+    from matplotlib.path import Path
+
+    straight = (Path.LINETO, Path.CLOSEPOLY)
+
+    walk = ax._update_patch_limits  # the Axes' own updater, or one set on it before this block
+    own = vars(ax).get("_update_patch_limits")
+
+    def update(patch: Any) -> None:
+        path, transform = patch.get_path(), patch.get_transform()
+        codes, vertices = path.codes, path.vertices
+        if not (
+            isinstance(patch, Polygon)
+            and len(vertices) > 1
+            and (codes is None or (codes[0] == Path.MOVETO and np.isin(codes[1:], straight).all()))
+            and np.isfinite(vertices).all()
+            and ax.name == "rectilinear"
+            and transform.contains_branch(ax.transData)
+        ):
+            walk(patch)
+            return
+        points = vertices if codes is None else vertices[codes != Path.CLOSEPOLY]
+        ax.update_datalim((transform - ax.transData).transform(points))
+
+    ax._update_patch_limits = update
+    try:
+        yield
+    finally:
+        if own is None:
+            del ax._update_patch_limits
+        else:
+            ax._update_patch_limits = own
+
+
+def color_updates(sport: str, primary: str, secondary: str | None) -> dict[str, str]:
+    """sportypy ``color_updates`` for a team (sdvplotR's ``surface_color_updates()``): basketball paints the lane and
+    apron with a readable ink on top, football the end zones, hockey the center line, faceoff circle and spot and the
+    boards (the secondary color when the primary does not read on ice); baseball and soccer nothing."""
+    if sport == "basketball":
+        ink = on_color(primary)
+        return {
+            "painted_area": primary,
+            "court_apron": primary,
+            "restricted_arc": ink,
+            "free_throw_circle_dash": ink,
+            "lane_lower_defensive_box": ink,
+            "baseline_lower_defensive_box": ink,
+        }
+    if sport == "football":
+        return {"offensive_endzone": primary, "defensive_endzone": primary}
+    if sport == "hockey":
+        ice = SURFACE_BASE["hockey"]
+        readable = secondary is not None and contrast(primary, ice) < 3 and contrast(secondary, ice) >= 3
+        accent = secondary if readable and secondary is not None else primary
+        return {
+            "center_line": accent,
+            "center_faceoff_circle": accent,
+            "center_faceoff_spot": accent,
+            "boards": primary,
+        }
+    return {}
+
+
+def surface(
+    league: str,
+    team: Any = None,
+    *,
+    season: Any = None,
+    ax: Any = None,
+    center_logo: bool | float = False,
+    **sportypy_kwargs: Any,
+) -> Any:
+    """Draw the league's playing surface with sportypy, in a team's colors.
+
+    Args:
+        league: The SDV league key, e.g. "nfl", "nba", "nhl", "cfb", "soccer".
+        team: A team to color the surface by (end zones, lane and apron, center line and boards); None for the plain
+            surface.
+        season: The season, for teams whose colors changed.
+        ax: The matplotlib Axes to draw on; None makes a new figure.
+        center_logo: True to draw the team's logo at center ice / court / field (0.25 of the Axes height), or a
+            height fraction.
+        **sportypy_kwargs: Passed to sportypy: ``display_range``, ``xlim``, ``ylim`` and ``rotation`` go to
+            ``draw()``; the rest (``field_updates``, ``color_updates``, ``units``, ...) to the surface class.
+
+    Returns:
+        matplotlib.axes.Axes: The Axes sportypy drew on.
+
+    Raises:
+        InputError: (a ValueError) If sportypy has no surface for ``league``; and, when ``team`` is given, if
+            ``season`` is not a year or is outside the seasons sdvplot knows for the league, or ``center_logo`` is a
+            height outside (0, 1]. Without ``team``, ``season`` and ``center_logo`` are not used.
+        OptionalDependencyError: If the surfaces extra (sportypy) is not installed, or ``team`` and ``center_logo`` are
+            set and the team's logo is an SVG without the ``svg`` extra.
+        OfflineError: If ``team`` and ``center_logo`` are set and the logo manifest or the team's logo is neither
+            cached nor downloadable (a DownloadError, also an OSError, when the CDN answers with an error status; an
+            IntegrityError when it sends a file that does not match the manifest's sha256, or one PIL cannot decode).
+        UnsafeDownloadError: (an OSError) If ``team`` and ``center_logo`` are set and a download is refused: larger
+            than the byte cap, past the deadline, or redirected away from https.
+        UnsafeCachePathError: (a ValueError) If ``team`` and ``center_logo`` are set and the manifest's sha256 or
+            extension for the logo would put the file outside the cache directory.
+
+    Example:
+        ::
+
+            import sdvplot
+
+            ax = sdvplot.surface("nfl", "KC", center_logo=True)
+
+    See Also:
+        sdvplotR sdv_surface(): https://sdvplotR.sportsdataverse.org/ ;
+        sportypy: https://sportypy.sportsdataverse.org/
+    """
+    if league not in SURFACES:
+        raise InputError(f"no sportypy surface for league {league!r}; supported: {sorted(SURFACES)}")
+    sport, cls_name = SURFACES[league]
+    try:
+        module = importlib.import_module(f"sportypy.surfaces.{sport}")
+    except ModuleNotFoundError as e:
+        raise OptionalDependencyError(
+            "sdvplot.surface() needs the surfaces extra: pip install sdvplot[surfaces]"
+        ) from e
+    draw_kwargs = {k: sportypy_kwargs.pop(k) for k in _DRAW_KWARGS if k in sportypy_kwargs}
+    if sport == "football" and not _has_font(_NUMBER_FONT):
+        # sportypy numbers football fields in Clarendon-Regular, which it does not ship: matplotlib then logs "findfont:
+        # Font family 'Clarendon-Regular' not found" for every number it measures and draws its default font anyway.
+        # Naming that default draws the same numbers (bar sportypy's Clarendon-only nudge of one "1") and logs nothing.
+        sportypy_kwargs["field_updates"] = {"number_font": "DejaVu Sans", **sportypy_kwargs.get("field_updates", {})}
+    if team is not None:
+        primary, secondary = (team_colors(league, [team], which=w, season=season)[0] for w in ("primary", "secondary"))
+        if primary is not None:
+            sportypy_kwargs["color_updates"] = {
+                **color_updates(sport, primary, secondary),
+                **sportypy_kwargs.get("color_updates", {}),
+            }
+    drawing = getattr(module, cls_name)(**sportypy_kwargs)
+    if ax is None:  # as sportypy's draw() does, so the limits shortcut has an Axes to go on
+        import matplotlib.pyplot as plt
+
+        fig, ax = plt.subplots()
+        fig.patch.set_facecolor(drawing.feature_colors["plot_background"])
+    with _polygon_limits(ax):
+        drawn = drawing.draw(ax=ax, **draw_kwargs)
+    if center_logo and team is not None:
+        from sdvplot.matplotlib import add_logos
+
+        top = max((a.get_zorder() for a in drawn.get_children()), default=0)
+        add_logos(drawn, [0.0], [0.0], [team], league=league, season=season, zorder=top + 1,
+                  height=0.25 if center_logo is True else float(center_logo))  # fmt: skip
+    return drawn

sdvplot/_tables.py

@@ -0,0 +1,87 @@
+"""What the table adapters share (sdvplot.great_tables, sdvplot.reactable): pixel heights and a mark's ``<img>`` markup.
+
+No table library is imported here, so either adapter works without the other installed.
+"""
+
+from __future__ import annotations
+
+import html
+import math
+import numbers
+from typing import Any
+
+import polars as pl
+
+from sdvplot import _index
+from sdvplot._errors import InputError
+from sdvplot._normalize import norm_season
+from sdvplot._placement import place
+
+
+def _position(row: Any) -> Any:
+    return int(row) if isinstance(row, numbers.Integral) and not isinstance(row, bool) else row
+
+
+def row_positions(rows: Any) -> Any:
+    """A great_tables row selection with numpy integers made plain ``int``s.
+
+    great_tables' row resolver silently skips any position that is not an ``int``, so ``rows=[np.int64(1)]`` (or a
+    numpy array of positions) would select nothing. Expressions, callables and ``None`` pass through unchanged.
+    """
+    if isinstance(rows, numbers.Integral) and not isinstance(rows, bool):
+        return [int(rows)]
+    if getattr(rows, "ndim", None) == 1 and hasattr(rows, "tolist"):  # a numpy array of positions
+        rows = rows.tolist()
+    if isinstance(rows, (list, tuple)):
+        return [_position(r) for r in rows]
+    return rows
+
+
+def check_px(height: Any) -> float:
+    """``height`` as a float, or ValueError unless it is a finite number of pixels, at least 1."""
+    if isinstance(height, bool) or not isinstance(height, numbers.Real) or not math.isfinite(height) or height <= 0:
+        raise InputError(f"height is the image height in pixels, a number > 0, got {height!r}")
+    if height < 1:  # a plot's height is a fraction of the plot; a table's is pixels, so 0.1 would draw a 0.1 px image
+        raise InputError(
+            f"height is the image height in pixels for a table (such as 30), got {height!r}; a fraction of the plot "
+            "height is the unit for plots, not tables"
+        )
+    return float(height)
+
+
+def img_tag(src: str, height: float, alt: str, *, team: str | None = None, margin: bool = False) -> str:
+    """An ``<img>`` ``height`` pixels tall; ``team`` adds the ``data-sdvplot-team`` attribute the test hooks read."""
+    style = f"height:{height:g}px;vertical-align:middle" + (";margin-right:0.35em" if margin else "")
+    data = f' data-sdvplot-team="{html.escape(team)}"' if team is not None else ""
+    return f'<img src="{html.escape(src)}" style="{style}" alt="{html.escape(alt)}"{data}>'
+
+
+def mark_html(
+    values: list[Any],
+    *,
+    league: str,
+    kind: str,
+    height: float,
+    season: Any = None,
+    variant: str = "default",
+    id_system: str = "auto",
+    strict: bool = False,
+    include_name: bool = False,
+) -> list[str | None]:
+    """The ``<img>`` of each value's mark, or None where there is none (one SdvplotWarning for those, from place()).
+
+    ``season`` is one season for every value (sdvplotR's rule for tables); a list of seasons is a ValueError. The alt
+    text is the team's name from the bundled index (the player id for headshots).
+    """
+    s = norm_season(season)
+    n = len(values)
+    placed = place(list(range(n)), [0] * n, values, league=league, season=s, kind=kind, variant=variant,
+                   id_system=id_system, strict=strict)  # fmt: skip
+    names: dict[str, str] = {}
+    if kind != "headshot":
+        rows = _index.team_table().filter(pl.col("league") == league).select("team_id", "name").iter_rows()
+        names = {tid: name for tid, name in rows if name}
+    out: list[str | None] = [None] * n
+    for p in placed:
+        out[p.x] = img_tag(p.url, height, names.get(p.team_id, p.team_id), team=p.team_id, margin=include_name)
+    return out