sdvplot 0.1.0__py3-none-any.whl

sdvplot/_dispatch.py

@@ -0,0 +1,342 @@
+"""One front door for every library: sdvplot.add_logos(target, ...) routes to the adapter for target's library.
+
+Each adapter registers at the end of this module (registering imports nothing; the adapter module loads on first
+use). The full adapter contract, its rules and its test hooks are documented in sdvplot.testing; in short, an adapter
+module exposes add_logos, add_wordmarks, add_headshots and axis_logos, plus the test hook
+
+    _drawn_marks(target) -> list[tuple]
+
+which returns one (team_id, x, y, height) or (team_id, x, y, height, url) tuple per image the adapter drew, in draw
+order. team_id is the canonical string id, x/y are the position values passed in (positional, never index labels),
+height is the fraction of the plot height the image was drawn at (measured, not the value asked for), and url the
+image source it drew.
+
+add_logos must return the object that was drawn on: the target itself when the library mutates in place
+(matplotlib), or the new object when it builds one (plotnine, altair, tables). The harness reads _drawn_marks from
+the returned object when it is not None, and from the target otherwise.
+"""
+
+from __future__ import annotations
+
+import importlib
+from dataclasses import dataclass
+from types import ModuleType
+from typing import TYPE_CHECKING, Any, TypeVar, overload
+
+from sdvplot._errors import OptionalDependencyError, UnsupportedTargetError
+
+if TYPE_CHECKING:
+    from bokeh.models import Plot
+    from folium import Map
+    from great_tables import GT
+    from matplotlib.axes import Axes
+    from matplotlib.figure import Figure
+    from plotly.basedatatypes import BaseFigure
+    from plotnine import ggplot
+
+# The targets whose verbs return the target itself, or a new object of its type (plotnine, great_tables), so the
+# result has the type the target had. Altair is not one: a Chart comes back as a LayerChart.
+_Target = TypeVar("_Target", bound="Axes | Figure | BaseFigure | ggplot | GT | Plot | Map")
+# The same, for the libraries that draw axis logos
+_AxisTarget = TypeVar("_AxisTarget", bound="Axes | Figure | BaseFigure | ggplot")
+
+
+@dataclass(frozen=True)
+class Adapter:
+    name: str  # display name, e.g. "Plotly"
+    package: str  # top-level package of the target object's type, e.g. "plotly"
+    module: str  # adapter module, e.g. "sdvplot.plotly"
+    extra: str  # pip extra, e.g. "plotly"
+
+
+ADAPTERS: dict[str, Adapter] = {}
+
+
+def register_adapter(adapter: Adapter) -> None:
+    ADAPTERS[adapter.package] = adapter
+
+
+def adapter_for(target: Any) -> ModuleType:
+    """The adapter module for target's library.
+
+    Walks type(target).__mro__ and uses the first class whose top-level package is registered, so a user's
+    subclass of a library class (even one defined in __main__) still reaches that library's adapter.
+    """
+    cls = type(target)
+    adapter = None
+    for klass in cls.__mro__:
+        adapter = ADAPTERS.get((klass.__module__ or "").split(".")[0])
+        if adapter is not None:
+            break
+    if adapter is None:
+        supported = ", ".join(sorted(a.name for a in ADAPTERS.values())) or "none yet"
+        raise UnsupportedTargetError(
+            f"sdvplot has no adapter for {cls.__module__}.{cls.__name__} objects; supported: {supported}"
+        )
+    try:
+        return importlib.import_module(adapter.module)
+    except OptionalDependencyError:
+        raise  # the adapter module's requires_extra already named the extra
+    except ModuleNotFoundError as e:
+        # Only a missing adapter module or target library (ModuleNotFoundError) means "extra not installed";
+        # any other ImportError (a broken transitive import inside the adapter) is a real bug: surface it unchanged.
+        name = e.name or ""
+        if name == adapter.module or name == adapter.package or name.startswith(adapter.package + "."):
+            raise OptionalDependencyError(
+                f"{adapter.name} support needs the {adapter.extra} extra: pip install sdvplot[{adapter.extra}]"
+            ) from e
+        raise
+
+
+@overload
+def add_logos(target: _Target, *args: Any, **kwargs: Any) -> _Target: ...
+@overload
+def add_logos(target: Any, *args: Any, **kwargs: Any) -> Any: ...
+def add_logos(target: Any, *args: Any, **kwargs: Any) -> Any:
+    """Add team logos to a plot or table of any supported library.
+
+    Routes to the adapter for ``target``'s library (matplotlib, plotnine, Plotly, Altair, great_tables, ...) and returns
+    the object that was drawn on: ``target`` itself when the library mutates in place, a new object otherwise. Plots and
+    tables take different arguments. A plot (matplotlib, plotnine, Plotly, Altair, Bokeh, HoloViews, folium and pygal)
+    takes ``x``, ``y`` and ``teams``, and a ``height`` that is a fraction of the plot height. A great_tables ``GT``
+    takes ``columns`` and a ``height`` in pixels, with no ``alpha`` or ``variant`` (see
+    ``sdvplot.great_tables.gt_sdv_logos``).
+
+    Args:
+        target: The plot or table object. Its type picks the adapter.
+        *args: Passed to the adapter. For a plot: ``x``, ``y`` (positions in the target's own coordinates) and
+            ``teams`` (the team values to draw), in that order. For a table: ``columns`` (the columns whose cells
+            become marks).
+        **kwargs: Passed to the adapter: ``league`` (the SDV league key) and ``season`` (for a plot one season or one
+            per team, for a table one season).
+            For a plot, also ``height`` (a fraction of the plot height, in (0, 1]), ``alpha`` (opacity, 0 to 1) and
+            ``variant`` (a mark variant, as in ``logo_url``); for a table, ``height`` is in pixels (default 30).
+
+    Returns:
+        object: The drawn-on plot or table: ``target`` itself, or the new object the adapter built.
+
+    Raises:
+        UnsupportedTargetError: (a TypeError) If no adapter is registered for ``target``'s library, or the adapter
+            cannot draw on this kind of ``target`` (a pygal Bar chart, a folium FeatureGroup).
+        OptionalDependencyError: (a ModuleNotFoundError) If the adapter's optional extra is not installed, or a mark a
+            raster adapter draws is an SVG and the ``svg`` extra is not installed.
+        TypeError: If the adapter does not take an argument given (a table takes no ``x``, ``y``, ``alpha``).
+        InputError: (a ValueError) If a value is out of range: a plot ``height`` outside (0, 1] or ``alpha`` outside [0,
+            1], or a table ``height`` below 1 pixel (a fraction such as 0.1 is a plot's unit, not a table's); or
+            ``league``, ``id_system``, ``variant`` or ``season`` is not one sdvplot knows.
+        ValueError: If the adapter's own checks fail (inputs of different lengths, an axis it cannot place on); its page
+            lists them.
+        UnresolvedTeamError: (a ValueError) If a table adapter is given ``strict=True`` and a value does not resolve.
+        OfflineError: If a download the adapter needs (the logo manifest, a mark's image, a headshot) fails and no
+            cached copy exists: a DownloadError (also an OSError) for an HTTP error status, an IntegrityError for a file
+            that does not match the manifest's sha256. Which downloads an adapter makes is on its page.
+        UnsafeDownloadError: (an OSError) If a download is refused: larger than the byte cap, past the deadline, or
+            redirected away from https.
+
+    Example:
+        ::
+
+            import matplotlib.pyplot as plt
+            import sdvplot
+
+            fig, ax = plt.subplots()
+            ax.set_xlim(0, 30)
+            ax.set_ylim(-10, 0)
+            sdvplot.add_logos(ax, [10, 20], [-3, -7], ["KC", "BUF"], league="nfl", height=0.15)
+
+    See Also:
+        sdvplotR: https://sdvplotR.sportsdataverse.org/ ;
+        sdv-py: https://py.sportsdataverse.org/
+    """
+    return adapter_for(target).add_logos(target, *args, **kwargs)
+
+
+@overload
+def add_wordmarks(target: _Target, *args: Any, **kwargs: Any) -> _Target: ...
+@overload
+def add_wordmarks(target: Any, *args: Any, **kwargs: Any) -> Any: ...
+def add_wordmarks(target: Any, *args: Any, **kwargs: Any) -> Any:
+    """Add team wordmarks to a plot or table of any supported library.
+
+    Routes to the adapter for ``target``'s library (matplotlib, plotnine, Plotly, Altair, great_tables, ...) and returns
+    the object that was drawn on: ``target`` itself when the library mutates in place, a new object otherwise. Plots and
+    tables take different arguments. A plot (matplotlib, plotnine, Plotly, Altair, Bokeh, HoloViews, folium and pygal)
+    takes ``x``, ``y`` and ``teams``, and a ``height`` that is a fraction of the plot height. A great_tables ``GT``
+    takes ``columns`` and a ``height`` in pixels, with no ``alpha`` or ``variant`` (see
+    ``sdvplot.great_tables.gt_sdv_wordmarks``).
+
+    Args:
+        target: The plot or table object. Its type picks the adapter.
+        *args: Passed to the adapter. For a plot: ``x``, ``y`` (positions in the target's own coordinates) and
+            ``teams`` (the team values to draw), in that order. For a table: ``columns`` (the columns whose cells
+            become marks).
+        **kwargs: Passed to the adapter: ``league`` (the SDV league key) and ``season`` (for a plot one season or one
+            per team, for a table one season).
+            For a plot, also ``height`` (a fraction of the plot height, in (0, 1]), ``alpha`` (opacity, 0 to 1) and
+            ``variant`` (a mark variant, as in ``logo_url``); for a table, ``height`` is in pixels (default 30).
+
+    Returns:
+        object: The drawn-on plot or table: ``target`` itself, or the new object the adapter built.
+
+    Raises:
+        UnsupportedTargetError: (a TypeError) If no adapter is registered for ``target``'s library, or the adapter
+            cannot draw on this kind of ``target`` (a pygal Bar chart, a folium FeatureGroup).
+        OptionalDependencyError: (a ModuleNotFoundError) If the adapter's optional extra is not installed, or a mark a
+            raster adapter draws is an SVG and the ``svg`` extra is not installed.
+        TypeError: If the adapter does not take an argument given (a table takes no ``x``, ``y``, ``alpha``).
+        InputError: (a ValueError) If a value is out of range: a plot ``height`` outside (0, 1] or ``alpha`` outside [0,
+            1], or a table ``height`` below 1 pixel (a fraction such as 0.1 is a plot's unit, not a table's); or
+            ``league``, ``id_system``, ``variant`` or ``season`` is not one sdvplot knows.
+        ValueError: If the adapter's own checks fail (inputs of different lengths, an axis it cannot place on); its page
+            lists them.
+        UnresolvedTeamError: (a ValueError) If a table adapter is given ``strict=True`` and a value does not resolve.
+        OfflineError: If a download the adapter needs (the logo manifest, a mark's image, a headshot) fails and no
+            cached copy exists: a DownloadError (also an OSError) for an HTTP error status, an IntegrityError for a file
+            that does not match the manifest's sha256. Which downloads an adapter makes is on its page.
+        UnsafeDownloadError: (an OSError) If a download is refused: larger than the byte cap, past the deadline, or
+            redirected away from https.
+
+    Example:
+        ::
+
+            import matplotlib.pyplot as plt
+            import sdvplot
+
+            fig, ax = plt.subplots()
+            sdvplot.add_wordmarks(ax, [0.5], [0.5], ["KC"], league="nfl", height=0.1)
+
+    See Also:
+        sdvplotR: https://sdvplotR.sportsdataverse.org/ ;
+        sdv-py: https://py.sportsdataverse.org/
+    """
+    return adapter_for(target).add_wordmarks(target, *args, **kwargs)
+
+
+@overload
+def add_headshots(target: _Target, *args: Any, **kwargs: Any) -> _Target: ...
+@overload
+def add_headshots(target: Any, *args: Any, **kwargs: Any) -> Any: ...
+def add_headshots(target: Any, *args: Any, **kwargs: Any) -> Any:
+    """Add player headshots to a plot or table of any supported library.
+
+    Routes to the adapter for ``target``'s library (matplotlib, plotnine, Plotly, Altair, great_tables, ...) and returns
+    the object that was drawn on: ``target`` itself when the library mutates in place, a new object otherwise. For
+    headshots, ``teams`` holds player ids and ``league`` picks the ESPN league. Plots and tables take different
+    arguments. A plot (matplotlib, plotnine, Plotly, Altair, Bokeh, HoloViews, folium and pygal) takes ``x``, ``y`` and
+    ``teams``, and a ``height`` that is a fraction of the plot height. A great_tables ``GT`` takes ``columns`` and a
+    ``height`` in pixels, with no ``alpha`` (see ``sdvplot.great_tables.gt_sdv_headshots``).
+
+    Args:
+        target: The plot or table object. Its type picks the adapter.
+        *args: Passed to the adapter. For a plot: ``x``, ``y`` (positions in the target's own coordinates) and
+            ``teams`` (the player ids to draw), in that order. For a table: ``columns`` (the columns whose cells
+            become headshots).
+        **kwargs: Passed to the adapter: ``league`` (the SDV league key) and ``id_system`` (``"espn"`` or
+            ``"gsis"``, as in ``headshot_url``). For a plot, also ``height`` (a fraction of the plot height, in
+            (0, 1]) and ``alpha`` (opacity, 0 to 1); for a table, ``height`` is in pixels (default 30). Headshots take
+            no ``season`` or ``variant``.
+
+    Returns:
+        object: The drawn-on plot or table: ``target`` itself, or the new object the adapter built.
+
+    Raises:
+        UnsupportedTargetError: (a TypeError) If no adapter is registered for ``target``'s library, or the adapter
+            cannot draw on this kind of ``target`` (a pygal Bar chart, a folium FeatureGroup).
+        OptionalDependencyError: (a ModuleNotFoundError) If the adapter's optional extra is not installed, or a mark a
+            raster adapter draws is an SVG and the ``svg`` extra is not installed.
+        TypeError: If the adapter does not take an argument given (a table takes no ``x``, ``y``, ``alpha``).
+        InputError: (a ValueError) If a value is out of range: a plot ``height`` outside (0, 1] or ``alpha`` outside [0,
+            1], or a table ``height`` below 1 pixel (a fraction such as 0.1 is a plot's unit, not a table's); or
+            ``league`` has no ESPN headshots or ``id_system`` is not valid for it.
+        ValueError: If the adapter's own checks fail (inputs of different lengths, an axis it cannot place on); its page
+            lists them.
+        OfflineError: If a download the adapter needs (the logo manifest, a mark's image, a headshot) fails and no
+            cached copy exists: a DownloadError (also an OSError) for an HTTP error status, an IntegrityError for a file
+            that does not match the manifest's sha256. Which downloads an adapter makes is on its page.
+        UnsafeDownloadError: (an OSError) If a download is refused: larger than the byte cap, past the deadline, or
+            redirected away from https.
+
+    Example:
+        ::
+
+            import matplotlib.pyplot as plt
+            import sdvplot
+
+            fig, ax = plt.subplots()
+            sdvplot.add_headshots(ax, [0.5], [0.5], ["3139477"], league="nfl", height=0.2)
+
+    See Also:
+        sdvplotR: https://sdvplotR.sportsdataverse.org/ ;
+        sdv-py: https://py.sportsdataverse.org/
+    """
+    return adapter_for(target).add_headshots(target, *args, **kwargs)
+
+
+@overload
+def axis_logos(target: _AxisTarget, *args: Any, **kwargs: Any) -> _AxisTarget: ...
+@overload
+def axis_logos(target: Any, *args: Any, **kwargs: Any) -> Any: ...
+def axis_logos(target: Any, *args: Any, **kwargs: Any) -> Any:
+    """Replace an axis' team labels with team logos on a plot of any supported library.
+
+    Routes to the adapter for ``target``'s library (matplotlib, plotnine, Plotly, Altair, great_tables, ...) and returns
+    the object that was drawn on: ``target`` itself when the library mutates in place, a new object otherwise. The
+    adapters that draw axis logos (matplotlib, plotnine, Plotly and Altair) all take ``axis_logos(target, axis, *,
+    league, season=None, height=0.1, variant="default", mark_type="logo", id_system="auto")``, and Plotly and Altair
+    also take ``embed``. Bokeh, HoloViews, folium, pygal and great_tables have no axis logos: there it raises
+    UnsupportedTargetError (a TypeError).
+
+    Args:
+        target: The plot object. Its type picks the adapter.
+        *args: Passed to the adapter: ``axis`` (which axis' tick labels to replace, ``"x"`` or ``"y"``).
+        **kwargs: Passed to the adapter: ``league`` (the SDV league key, required), ``season`` (one season for every
+            label, default ``None``), ``height`` (the mark's height as a fraction of the plot height, default 0.1),
+            and ``variant``, ``mark_type`` and ``id_system`` as in ``logo_url`` and ``resolve``.
+
+    Returns:
+        object: The drawn-on plot: ``target`` itself, or the new object the adapter built.
+
+    Raises:
+        UnsupportedTargetError: (a TypeError) If no adapter is registered for ``target``'s library, its library has no
+            axis logos (Bokeh, HoloViews, folium, pygal, great_tables), or the adapter cannot draw on this kind of
+            ``target``.
+        OptionalDependencyError: (a ModuleNotFoundError) If the adapter's optional extra is not installed, or a mark a
+            raster adapter draws is an SVG and the ``svg`` extra is not installed.
+        InputError: (a ValueError) If ``height`` is outside (0, 1], or ``league``, ``id_system``, ``mark_type``,
+            ``variant`` or ``season`` is not one sdvplot knows.
+        ValueError: If ``axis`` is not "x"/"y", or the axis is not one the adapter can read team labels from (its page
+            lists the cases).
+        OfflineError: If a download the adapter needs (the logo manifest, a mark's image) fails and no cached copy
+            exists: a DownloadError (also an OSError) for an HTTP error status, an IntegrityError for a file that does
+            not match the manifest's sha256. Which downloads an adapter makes is on its page.
+        UnsafeDownloadError: (an OSError) If a download is refused: larger than the byte cap, past the deadline, or
+            redirected away from https.
+
+    Example:
+        ::
+
+            import matplotlib.pyplot as plt
+            import sdvplot
+
+            fig, ax = plt.subplots()
+            ax.bar(["KC", "BUF", "BAL"], [12, 10, 9])
+            sdvplot.axis_logos(ax, "x", league="nfl", height=0.08)
+
+    See Also:
+        sdvplotR: https://sdvplotR.sportsdataverse.org/ ;
+        sdv-py: https://py.sportsdataverse.org/
+    """
+    return adapter_for(target).axis_logos(target, *args, **kwargs)
+
+
+# The adapters sdvplot ships. Registering imports nothing: the adapter module loads on first use.
+register_adapter(Adapter("matplotlib", "matplotlib", "sdvplot.matplotlib", "mpl"))
+register_adapter(Adapter("seaborn", "seaborn", "sdvplot.matplotlib", "mpl"))
+register_adapter(Adapter("plotnine", "plotnine", "sdvplot.plotnine", "plotnine"))
+register_adapter(Adapter("great_tables", "great_tables", "sdvplot.great_tables", "tables"))
+register_adapter(Adapter("plotly", "plotly", "sdvplot.plotly", "plotly"))
+register_adapter(Adapter("altair", "altair", "sdvplot.altair", "altair"))
+register_adapter(Adapter("bokeh", "bokeh", "sdvplot.bokeh", "bokeh"))
+register_adapter(Adapter("holoviews", "holoviews", "sdvplot.holoviews", "holoviews"))
+register_adapter(Adapter("folium", "folium", "sdvplot.folium", "folium"))
+register_adapter(Adapter("pygal", "pygal", "sdvplot.pygal", "pygal"))

sdvplot/_errors.py

@@ -0,0 +1,93 @@
+"""Warning and exception types. Every error subclasses SdvplotError and the builtin a caller would already catch."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import sys
+import warnings
+from collections.abc import Iterator
+from types import FrameType
+
+_PACKAGE = os.path.dirname(os.path.abspath(__file__)) + os.sep
+
+
+class SdvplotWarning(UserWarning):
+    """Something was skipped or degraded (an unresolved team, a stale cache), but the call still returned."""
+
+
+class SdvplotDeprecationWarning(SdvplotWarning, FutureWarning):
+    """A deprecated sdvplot name or argument: it still works, and the message names its replacement and the release
+    that removes it. A FutureWarning, so it shows by default."""
+
+
+def warn(message: str, category: type[Warning] = SdvplotWarning) -> None:
+    """``warnings.warn`` at the first frame outside the sdvplot package: the caller's own line, however deep inside
+    sdvplot the warning is raised (a fixed ``stacklevel`` named sdvplot's files whenever the call chain changed)."""
+    frame: FrameType | None = sys._getframe(1)
+    level = 2
+    while frame is not None and frame.f_code.co_filename.startswith(_PACKAGE):
+        frame, level = frame.f_back, level + 1
+    warnings.warn(message, category, stacklevel=level)
+
+
+class SdvplotError(Exception):
+    """The base of sdvplot's errors: an unresolved team, a failed or refused download, a missing extra, an unsupported
+    target, and the shared argument checks (``InputError``). A check specific to one helper (an axis name, a column,
+    a chart setting) raises a plain ValueError or TypeError."""
+
+
+class InputError(SdvplotError, ValueError):
+    """An argument sdvplot cannot use: an unknown league, id system, color slot, mark type or variant, a color slot
+    such as ``"secondary"`` passed as a team, a season that is not a year or is outside the ones sdvplot knows, or a
+    height, alpha, image size or candidate count out of range."""
+
+
+class UnresolvedTeamError(SdvplotError, ValueError):
+    """A team value did not resolve and strict=True was set."""
+
+
+class OfflineError(SdvplotError, RuntimeError):
+    """A download failed and no cached copy exists."""
+
+
+class DownloadError(OfflineError, OSError):
+    """A download got an HTTP error status (a 4xx or 5xx response) and no cached copy exists. Also an OSError, so
+    ``except OSError`` catches it."""
+
+
+class IntegrityError(DownloadError):
+    """A download is not the file the manifest promises: its sha256 differs (it is not cached), or the archived file is
+    not an image PIL can decode."""
+
+
+class OptionalDependencyError(SdvplotError, ModuleNotFoundError):
+    """A feature needs an optional extra that is not installed: an adapter submodule imported without its library
+    (``import sdvplot.plotly`` without plotly), an SVG mark without the svg extra. The message names the extra to
+    install."""
+
+
+@contextlib.contextmanager
+def requires_extra(extra: str) -> Iterator[None]:
+    """Around an adapter module's library imports: a missing library is an OptionalDependencyError naming the extra
+    (still a ModuleNotFoundError, with the missing module's ``name``) instead of a bare ModuleNotFoundError."""
+    try:
+        yield
+    except ModuleNotFoundError as e:
+        raise OptionalDependencyError(
+            f'{e.name or "a library"} is not installed: this needs the {extra} extra, pip install "sdvplot[{extra}]"',
+            name=e.name,
+        ) from e
+
+
+class UnsupportedTargetError(SdvplotError, TypeError):
+    """sdvplot cannot draw on this object: no adapter takes its kind of plot or table, or the adapter does not support
+    the verb (axis logos on a map, a table, Bokeh, HoloViews or pygal)."""
+
+
+class UnsafeCachePathError(SdvplotError, ValueError):
+    """A manifest value (sha256, ext) or cache path would reach outside the sdvplot cache directory."""
+
+
+class UnsafeDownloadError(SdvplotError, OSError):
+    """A download was refused: too large, too slow, or redirected away from https."""

sdvplot/_headshots.py

@@ -0,0 +1,131 @@
+"""Player headshot URLs: ESPN athlete ids directly, nflverse gsis ids through nflverse's player table."""
+
+from __future__ import annotations
+
+import functools
+import io
+from typing import TYPE_CHECKING, Any
+
+from sdvplot._cache import MEMORY_CACHES, fetch_cached, safe_url
+from sdvplot._errors import InputError, warn
+from sdvplot._normalize import norm_value
+from sdvplot._types import HeadshotIdSystem
+
+if TYPE_CHECKING:
+    import polars as pl
+else:
+    from sdvplot._lazy import pl
+
+ESPN_HEADSHOT_LEAGUES = {
+    "nfl": "nfl",
+    "nba": "nba",
+    "wnba": "wnba",
+    "mlb": "mlb",
+    "nhl": "nhl",
+    "cfb": "college-football",
+    "mbb": "mens-college-basketball",
+    "wbb": "womens-college-basketball",
+}
+NFLVERSE_PLAYERS_URL = "https://github.com/nflverse/nflverse-data/releases/download/players/players.parquet"
+PLAYER_COLUMNS = ["gsis_id", "espn_id", "headshot"]
+
+
+@functools.lru_cache(maxsize=1)  # keyed by mtime so a refreshed table is read again; only the current file matters
+def _players(path: str, mtime: float) -> dict[str, tuple[str | None, str | None]]:
+    p = pl.read_parquet(path, columns=PLAYER_COLUMNS).drop_nulls("gsis_id")
+    players, bad = {}, []
+    for g, e, h in p.iter_rows():
+        if h and not safe_url(h):  # it would reach the web adapters' HTML: treat it as missing instead
+            bad.append(h)
+            h = None
+        players[g] = (e, h)
+    if bad:
+        warn(
+            f"ignored {len(bad)} nflverse headshot URL(s) that are not plain https URLs, e.g. {bad[0]!r:.100}; "
+            "those players get their ESPN headshot when nflverse has their ESPN id"
+        )
+    return players
+
+
+MEMORY_CACHES.append(_players.cache_clear)  # clear_cache() also frees the player table
+
+
+def _is_valid_espn_id(normalized_id: str) -> bool:
+    """Check if a normalized id is all ASCII digits, matching sdvplotR's shape validation."""
+    return normalized_id.isascii() and normalized_id.isdigit()
+
+
+def _espn(player_id: str, league: str) -> str | None:
+    if not _is_valid_espn_id(player_id):
+        return None
+    slug = ESPN_HEADSHOT_LEAGUES[league]
+    return f"https://a.espncdn.com/combiner/i?img=/i/headshots/{slug}/players/full/{player_id}.png"
+
+
+def _transform_nfl_headshot(url: str) -> str:
+    """Transform an NFL.com headshot URL.
+
+    Replace /f_auto,q_auto/ with /t_headshot_desktop/f_auto/, then append .png if needed.
+    """
+    transformed = url.replace("/f_auto,q_auto/", "/t_headshot_desktop/f_auto/")
+    if not transformed.endswith(".png"):
+        transformed += ".png"
+    return transformed
+
+
+def headshot_url(player_id: Any, league: str, *, id_system: HeadshotIdSystem = "espn") -> str | None:
+    """A headshot URL for one player.
+
+    Args:
+        player_id: One player id: an ESPN athlete id, or an nflverse gsis id.
+        league: The SDV league key. "espn" ids work for nfl, nba, wnba, mlb, nhl, cfb, mbb and wbb; "gsis" is NFL only.
+        id_system: "espn" (ESPN athlete id, any ESPN league) or "gsis" (mapped to ESPN through nflverse's player table,
+            preferring nflverse's own headshot).
+
+    Returns:
+        str | None: The image URL, or None when the id is missing, malformed, or not in the player table.
+
+    Raises:
+        InputError: (a ValueError) If ``league`` has no ESPN headshots or ``id_system`` is not valid for ``league``.
+        OfflineError: If ``id_system`` is "gsis" and the nflverse player table cannot be downloaded and no
+            cached copy exists (a DownloadError, also an OSError, when GitHub answers with an error status).
+        UnsafeDownloadError: (an OSError) If ``id_system`` is "gsis" and the player table download is refused: larger
+            than the byte cap, past the deadline, or redirected away from https.
+
+    Example:
+        ::
+
+            import sdvplot
+
+            sdvplot.headshot_url("3139477", "nfl")
+            # 'https://a.espncdn.com/combiner/i?img=/i/headshots/nfl/players/full/3139477.png'
+            sdvplot.headshot_url("00-0033873", "nfl", id_system="gsis")   # Patrick Mahomes, an nfl.com URL ending .png
+
+    See Also:
+        sdvplotR: https://sdvplotR.sportsdataverse.org/ ;
+        sdv-py: https://py.sportsdataverse.org/
+    """
+    # check the arguments first, so a null id never hides a bad league or id_system
+    if id_system == "espn" and league not in ESPN_HEADSHOT_LEAGUES:
+        raise InputError(f"no ESPN headshots for league {league!r}; supported: {sorted(ESPN_HEADSHOT_LEAGUES)}")
+    if id_system != "espn" and (id_system, league) != ("gsis", "nfl"):
+        raise InputError(f"id_system must be 'espn' (any league) or 'gsis' (nfl), got {id_system!r} for {league!r}")
+    pid = norm_value(player_id)
+    if pid is None:
+        return None
+    if id_system == "espn":
+        return _espn(pid, league)
+    path = fetch_cached(
+        NFLVERSE_PLAYERS_URL,
+        "nflverse/players.parquet",
+        validate=lambda body: pl.read_parquet(io.BytesIO(body), columns=PLAYER_COLUMNS),
+    )
+    row = _players(str(path), path.stat().st_mtime).get(str(player_id).strip())
+    if row is None:
+        return None
+    espn_id, headshot = row
+    if headshot:
+        return _transform_nfl_headshot(headshot)
+    if espn_id:
+        return _espn(espn_id, "nfl")
+    return None