sdvplot 0.1.0__py3-none-any.whl

sdvplot/bokeh.py

@@ -0,0 +1,323 @@
+"""The Bokeh adapter: logos, wordmarks and headshots as one ``image_url`` glyph per call on a Bokeh figure.
+
+Images are sized in screen pixels, so they keep their size when the user zooms: ``height`` times the reference height,
+which is the figure's ``frame_height`` (the plot area) when set, else its ``height`` (the whole canvas: set
+``frame_height`` for exact sizing). Factor (categorical) and datetime axes work natively, because ``x``/``y`` hold the
+caller's own values. HoloViews draws through ``_draw`` too.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sdvplot._errors import UnsupportedTargetError, requires_extra
+
+with requires_extra("bokeh"):
+    from bokeh.models import ColumnDataSource
+
+from sdvplot._placement import Placement, check_alpha, check_height, place
+from sdvplot._web import aspect, image_sources
+
+_SUPPORTS_AXIS_LOGOS = False
+
+__all__ = ["add_headshots", "add_logos", "add_wordmarks", "axis_logos"]
+
+
+def __dir__() -> list[str]:  # dir() and tab completion show the public API only
+    return list(__all__)
+
+
+def _figure(target: Any) -> Any:
+    if not hasattr(target, "image_url") or not hasattr(target, "frame_height"):
+        raise UnsupportedTargetError(f"sdvplot.bokeh draws on a bokeh.plotting figure, got {type(target).__name__}")
+    return target
+
+
+def _reference_height(fig: Any) -> float:
+    """The pixel height ``height`` is a fraction of: ``frame_height`` when set, else the figure's ``height``."""
+    h = fig.frame_height or fig.height
+    if not h:  # a responsive figure (e.g. a HoloViews plot with responsive=True) has neither
+        raise ValueError(
+            "sdvplot sizes images from the figure's pixel height, but it has none; set frame_height (or height), "
+            "e.g. figure(frame_height=400) or .opts(frame_height=400) in HoloViews"
+        )
+    return float(h)
+
+
+def _draw(fig: Any, placements: list[Placement], sources: list[str], *, kind: str, height: float, alpha: float) -> Any:
+    """One ``image_url`` renderer named ``sdvplot_<kind>`` with every placement, centred on its (x, y)."""
+    if not placements:
+        return None
+    h = height * _reference_height(fig)
+    data = {
+        "url": sources,
+        "x": [p.x for p in placements],
+        "y": [p.y for p in placements],
+        "w": [h * aspect(p) for p in placements],
+        "h": [h] * len(placements),
+        "team_id": [p.team_id for p in placements],
+    }
+    return fig.image_url(
+        url="url", x="x", y="y", w="w", h="h", w_units="screen", h_units="screen", anchor="center",
+        global_alpha=alpha, source=ColumnDataSource(data), name=f"sdvplot_{kind}",
+    )  # fmt: skip
+
+
+def _add(
+    target: Any,
+    x: Any,
+    y: Any,
+    teams: Any,
+    *,
+    kind: str,
+    league: str,
+    season: Any,
+    height: float,
+    alpha: float,
+    variant: str,
+    embed: bool,
+    id_system: str,
+) -> Any:
+    h, a = check_height(height), check_alpha(alpha)
+    fig = _figure(target)
+    placements = place(x, y, teams, league=league, season=season, kind=kind, variant=variant, id_system=id_system)
+    _draw(fig, placements, image_sources(placements, embed=embed), kind=kind, height=h, alpha=a)
+    return fig
+
+
+def add_logos(
+    target: Any,
+    x: Any,
+    y: Any,
+    teams: Any,
+    *,
+    league: str,
+    season: Any = None,
+    height: float = 0.1,
+    alpha: float = 1,
+    variant: str = "default",
+    embed: bool = False,
+    id_system: str = "auto",
+) -> Any:
+    """Draw each team's logo centred on its (x, y) point of a Bokeh figure.
+
+    The logos are sized in screen pixels, so they keep their size when the user zooms. ``height`` is a fraction of
+    the figure's ``frame_height`` (the plot area) when it is set, else of its ``height`` (the whole canvas, a little
+    taller than the plot area): set ``frame_height`` for the same sizing as the other libraries.
+
+    Args:
+        target: A ``bokeh.plotting.figure``.
+        x: The points' x positions, in the figure's x values (numbers, factors or datetimes).
+        y: The points' y positions, the same length as ``x``.
+        teams: The team for each point, in any id system ``resolve()`` understands.
+        league: The SDV league key, e.g. "nfl".
+        season: One season, or one per point, to pick each team's mark for that era.
+        height: The logo height as a fraction of the reference height, in (0, 1].
+        alpha: Opacity, 0 to 1.
+        variant: "default", "dark", or a named variant from ``marks()``.
+        embed: Inline each image as a data URI (HTML that renders offline) instead of linking its URL.
+        id_system: The id system of ``teams``; "auto" tries each in order.
+
+    Returns:
+        object: ``target`` itself, with one ``image_url`` renderer named ``sdvplot_logo`` added.
+
+    Raises:
+        InputError: (a ValueError) If ``height`` or ``alpha`` is out of range, ``league``, ``id_system`` or ``variant``
+            is unknown, or ``season`` is not a year or is outside the seasons sdvplot knows for the league.
+        ValueError: If the inputs differ in length, or the figure has no pixel height (neither ``frame_height`` nor
+            ``height`` is set).
+        UnsupportedTargetError: (a TypeError) If ``target`` is not a Bokeh figure.
+        OfflineError: If the logo manifest, or with ``embed=True`` a mark's image, 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).
+        UnsafeDownloadError: (an OSError) If a download is refused: larger than the byte cap, past the deadline, or
+            redirected away from https.
+        UnsafeCachePathError: (a ValueError) If ``embed=True`` and the manifest's sha256 or extension for a mark would
+            put the file outside the cache directory.
+
+    Example:
+        ::
+
+            from bokeh.plotting import figure
+            import sdvplot
+
+            p = figure(frame_width=400, frame_height=300)
+            p.scatter([10, 20], [-3, -7])
+            sdvplot.add_logos(p, [10, 20], [-3, -7], ["KC", "BUF"], league="nfl", height=0.15)
+
+    See Also:
+        sdvplotR geom_nfl_logos(): https://sdvplotR.sportsdataverse.org/ ;
+        Bokeh ImageURL: https://docs.bokeh.org/en/latest/docs/reference/models/glyphs/image_url.html
+    """
+    return _add(
+        target, x, y, teams, kind="logo", league=league, season=season, height=height, alpha=alpha,
+        variant=variant, embed=embed, id_system=id_system,
+    )  # fmt: skip
+
+
+def add_wordmarks(
+    target: Any,
+    x: Any,
+    y: Any,
+    teams: Any,
+    *,
+    league: str,
+    season: Any = None,
+    height: float = 0.1,
+    alpha: float = 1,
+    variant: str = "default",
+    embed: bool = False,
+    id_system: str = "auto",
+) -> Any:
+    """Draw each team's wordmark centred on its (x, y) point of a Bokeh figure.
+
+    Args:
+        target: A ``bokeh.plotting.figure``.
+        x: The points' x positions, in the figure's x values.
+        y: The points' y positions, the same length as ``x``.
+        teams: The team for each point, in any id system ``resolve()`` understands.
+        league: The SDV league key, e.g. "nfl".
+        season: One season, or one per point.
+        height: The wordmark height as a fraction of the reference height (see ``add_logos``), in (0, 1].
+        alpha: Opacity, 0 to 1.
+        variant: "default", "dark", or a named variant from ``marks()``.
+        embed: Inline each image as a data URI instead of linking its URL.
+        id_system: The id system of ``teams``; "auto" tries each in order.
+
+    Returns:
+        object: ``target`` itself, with one renderer named ``sdvplot_wordmark`` added.
+
+    Raises:
+        InputError: (a ValueError) If ``height`` or ``alpha`` is out of range, ``league``, ``id_system`` or ``variant``
+            is unknown, or ``season`` is not a year or is outside the seasons sdvplot knows for the league.
+        ValueError: If the inputs differ in length, or the figure has no pixel height (neither ``frame_height`` nor
+            ``height`` is set).
+        UnsupportedTargetError: (a TypeError) If ``target`` is not a Bokeh figure.
+        OfflineError: If the logo manifest, or with ``embed=True`` a mark's image, 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).
+        UnsafeDownloadError: (an OSError) If a download is refused: larger than the byte cap, past the deadline, or
+            redirected away from https.
+        UnsafeCachePathError: (a ValueError) If ``embed=True`` and the manifest's sha256 or extension for a mark would
+            put the file outside the cache directory.
+
+    Example:
+        ::
+
+            from bokeh.plotting import figure
+            import sdvplot
+
+            p = figure(x_range=["KC", "BUF"], frame_height=300)
+            p.vbar(x=["KC", "BUF"], top=[12, 10], width=0.8)
+            sdvplot.add_wordmarks(p, ["KC", "BUF"], [12, 10], ["KC", "BUF"], league="nfl", height=0.06)
+
+    See Also:
+        sdvplotR geom_nfl_wordmarks(): https://sdvplotR.sportsdataverse.org/
+    """
+    return _add(
+        target, x, y, teams, kind="wordmark", league=league, season=season, height=height, alpha=alpha,
+        variant=variant, embed=embed, id_system=id_system,
+    )  # fmt: skip
+
+
+def add_headshots(
+    target: Any,
+    x: Any,
+    y: Any,
+    players: Any,
+    *,
+    league: str,
+    height: float = 0.1,
+    alpha: float = 1,
+    embed: bool = False,
+    id_system: str = "espn",
+) -> Any:
+    """Draw each player's headshot centred on its (x, y) point of a Bokeh figure.
+
+    Args:
+        target: A ``bokeh.plotting.figure``.
+        x: The points' x positions, in the figure's x values.
+        y: The points' y positions, the same length as ``x``.
+        players: The player id for each point.
+        league: The SDV league key, e.g. "nfl".
+        height: The headshot height as a fraction of the reference height (see ``add_logos``), in (0, 1].
+        alpha: Opacity, 0 to 1.
+        embed: Inline each image as a data URI instead of linking its URL.
+        id_system: "espn" (ESPN athlete ids) or "gsis" (NFL), as in ``headshot_url``.
+
+    Returns:
+        object: ``target`` itself, with one renderer named ``sdvplot_headshot`` added.
+
+    Raises:
+        InputError: (a ValueError) If ``height`` or ``alpha`` is out of range, ``league`` has no ESPN headshots, or
+            ``id_system`` is not valid for ``league``.
+        ValueError: If the inputs differ in length, or the figure has no pixel height (neither ``frame_height`` nor
+            ``height`` is set).
+        UnsupportedTargetError: (a TypeError) If ``target`` is not a Bokeh figure.
+        OfflineError: If the nflverse player table (``id_system="gsis"``), or with ``embed=True`` a headshot, is neither
+            cached nor downloadable (a DownloadError, also an OSError, for an HTTP error status).
+        UnsafeDownloadError: (an OSError) If a download is refused: larger than the byte cap, past the deadline, or
+            redirected away from https.
+
+    Example:
+        ::
+
+            from bokeh.plotting import figure
+            import sdvplot
+
+            p = figure(frame_height=300)
+            sdvplot.add_headshots(p, [0.5], [0.5], ["3139477"], league="nfl", height=0.2)
+
+    See Also:
+        sdvplotR geom_nfl_headshots(): https://sdvplotR.sportsdataverse.org/
+    """
+    return _add(
+        target, x, y, players, kind="headshot", league=league, season=None, height=height, alpha=alpha,
+        variant="default", embed=embed, id_system=id_system,
+    )  # fmt: skip
+
+
+def axis_logos(target: Any, axis: str, **kwargs: Any) -> Any:
+    """Not supported on Bokeh: Bokeh glyphs cannot sit outside the plot frame at a fixed pixel offset.
+
+    Args:
+        target: A Bokeh figure.
+        axis: "x" or "y".
+        **kwargs: Ignored.
+
+    Returns:
+        object: Never returns.
+
+    Raises:
+        UnsupportedTargetError: (a TypeError) Always. Draw the logos inside the plot with ``add_logos`` at a y below the
+            bars, or use the matplotlib, Plotly or Altair adapter for axis logos.
+
+    Example:
+        ::
+
+            from bokeh.plotting import figure
+            import sdvplot
+
+            try:
+                sdvplot.axis_logos(figure(), "x", league="nfl")
+            except TypeError:
+                pass   # raised: Bokeh has no axis logos yet
+
+    See Also:
+        sdvplotR element_sdv_logo(): https://sdvplotR.sportsdataverse.org/
+    """
+    raise UnsupportedTargetError(
+        "Bokeh has no axis logos yet: draw them inside the plot with add_logos (e.g. at a y just below the bars), "
+        "or use matplotlib, Plotly or Altair for axis logos"
+    )
+
+
+def _drawn_marks(target: Any) -> list[tuple[Any, ...]]:
+    """Test hook: (team_id, x, y, height, url) for each image of the sdvplot renderers, height = h / reference."""
+    ref = _reference_height(target)
+    out = []
+    for r in target.renderers:
+        if (r.name or "").startswith("sdvplot_"):
+            d = r.data_source.data
+            out += list(zip(d["team_id"], d["x"], d["y"], [h / ref for h in d["h"]], d["url"], strict=True))
+    return out

sdvplot/data/INDEX_VERSION

@@ -0,0 +1 @@
+88b114b58b3d

sdvplot/folium.py

@@ -0,0 +1,316 @@
+"""The Folium adapter: logos, wordmarks and headshots as map markers with image icons.
+
+On a map, ``x`` is longitude and ``y`` latitude. A map has no plot height, so ``height`` is a fraction of the map's
+pixel height when it is given in pixels, else of _FOLIUM_REFERENCE_HEIGHT (a notebook map's usual height). The markers
+go into one ``FeatureGroup`` named "sdvplot logos", so a ``LayerControl`` can toggle them.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sdvplot._errors import UnsupportedTargetError, requires_extra
+
+with requires_extra("folium"):
+    import folium
+
+from sdvplot._index import teams as team_index
+from sdvplot._placement import check_alpha, check_height, place
+from sdvplot._web import aspect, image_sources
+
+_SUPPORTS_AXIS_LOGOS = False
+_FOLIUM_REFERENCE_HEIGHT = 500  # px: the reference for a map whose height is not in pixels (the default "100%")
+_GROUP_NAME = "sdvplot logos"
+
+__all__ = ["add_headshots", "add_logos", "add_wordmarks", "axis_logos"]
+
+
+def __dir__() -> list[str]:  # dir() and tab completion show the public API only
+    return list(__all__)
+
+
+def _map(target: Any) -> folium.Map:
+    if not isinstance(target, folium.Map):
+        raise UnsupportedTargetError(f"sdvplot.folium draws on a folium.Map, got {type(target).__name__}")
+    return target
+
+
+def _reference_height(m: folium.Map) -> float:
+    """The pixel height ``height`` is a fraction of: the map's own when in pixels, else _FOLIUM_REFERENCE_HEIGHT."""
+    value, unit = m.height
+    return float(value) if unit == "px" else float(_FOLIUM_REFERENCE_HEIGHT)
+
+
+def _group(m: folium.Map) -> folium.FeatureGroup:
+    for child in m._children.values():
+        if isinstance(child, folium.FeatureGroup) and child.layer_name == _GROUP_NAME:
+            return child
+    group = folium.FeatureGroup(name=_GROUP_NAME)
+    group.add_to(m)
+    return group
+
+
+def _add(
+    target: Any,
+    x: Any,
+    y: Any,
+    teams: Any,
+    *,
+    kind: str,
+    league: str,
+    season: Any,
+    height: float,
+    alpha: float,
+    variant: str,
+    embed: bool,
+    id_system: str,
+) -> Any:
+    h, a = check_height(height), check_alpha(alpha)
+    m = _map(target)
+    placements = place(x, y, teams, league=league, season=season, kind=kind, variant=variant, id_system=id_system)
+    if not placements:
+        return m
+    names = {} if kind == "headshot" else dict(team_index(league).select("team_id", "name").iter_rows())
+    px = max(1, round(h * _reference_height(m)))  # Leaflet icon sizes are whole pixels
+    group = _group(m)
+    for p, src in zip(placements, image_sources(placements, embed=embed), strict=True):
+        w = max(1, round(px * aspect(p)))
+        marker: Any = folium.Marker(  # Any: it carries the test hook below (a type: ignore is unused without folium)
+            location=[p.y, p.x],
+            icon=folium.CustomIcon(src, icon_size=(w, px), icon_anchor=(w // 2, px // 2)),
+            tooltip=names.get(p.team_id, p.team_id),
+            opacity=a,
+        )
+        marker._sdvplot_mark = (p.team_id, p.x, p.y, src)
+        marker.add_to(group)
+    return m
+
+
+def add_logos(
+    target: Any,
+    x: Any,
+    y: Any,
+    teams: Any,
+    *,
+    league: str,
+    season: Any = None,
+    height: float = 0.1,
+    alpha: float = 1,
+    variant: str = "default",
+    embed: bool = False,
+    id_system: str = "auto",
+) -> Any:
+    """Put each team's logo on a Folium map at its (longitude, latitude), with the team name as a tooltip.
+
+    Args:
+        target: A ``folium.Map``.
+        x: The longitudes.
+        y: The latitudes, the same length as ``x``.
+        teams: The team for each point, in any id system ``resolve()`` understands.
+        league: The SDV league key, e.g. "nfl".
+        season: One season, or one per point, to pick each team's mark for that era.
+        height: The logo height as a fraction of the map's pixel height (or of _FOLIUM_REFERENCE_HEIGHT, 500 px, when
+            the map height is not in pixels), in (0, 1].
+        alpha: Opacity, 0 to 1.
+        variant: "default", "dark", or a named variant from ``marks()``.
+        embed: Inline each image as a data URI (a map that renders offline) instead of linking its URL.
+        id_system: The id system of ``teams``; "auto" tries each in order.
+
+    Returns:
+        object: ``target`` itself, with the markers in the "sdvplot logos" feature group.
+
+    Raises:
+        InputError: (a ValueError) If ``height`` or ``alpha`` is out of range, ``league``, ``id_system`` or ``variant``
+            is unknown, or ``season`` is not a year or is outside the seasons sdvplot knows for the league.
+        ValueError: If the inputs differ in length, or a location is not a number.
+        UnsupportedTargetError: (a TypeError) If ``target`` is not a ``folium.Map``.
+        OfflineError: If the logo manifest, or with ``embed=True`` a mark's image, 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).
+        UnsafeDownloadError: (an OSError) If a download is refused: larger than the byte cap, past the deadline, or
+            redirected away from https.
+        UnsafeCachePathError: (a ValueError) If ``embed=True`` and the manifest's sha256 or extension for a mark would
+            put the file outside the cache directory.
+
+    Example:
+        ::
+
+            import folium
+            import sdvplot
+
+            m = folium.Map(location=[39, -95], zoom_start=4, height=600)
+            sdvplot.add_logos(m, [-94.48, -78.79], [39.05, 42.77], ["KC", "BUF"], league="nfl", height=0.06)
+
+    See Also:
+        sdvplotR: https://sdvplotR.sportsdataverse.org/ ;
+        Folium CustomIcon: https://python-visualization.github.io/folium/latest/user_guide/ui_elements/icons.html
+    """
+    return _add(
+        target, x, y, teams, kind="logo", league=league, season=season, height=height, alpha=alpha,
+        variant=variant, embed=embed, id_system=id_system,
+    )  # fmt: skip
+
+
+def add_wordmarks(
+    target: Any,
+    x: Any,
+    y: Any,
+    teams: Any,
+    *,
+    league: str,
+    season: Any = None,
+    height: float = 0.1,
+    alpha: float = 1,
+    variant: str = "default",
+    embed: bool = False,
+    id_system: str = "auto",
+) -> Any:
+    """Put each team's wordmark on a Folium map at its (longitude, latitude).
+
+    Args:
+        target: A ``folium.Map``.
+        x: The longitudes.
+        y: The latitudes, the same length as ``x``.
+        teams: The team for each point, in any id system ``resolve()`` understands.
+        league: The SDV league key, e.g. "nfl".
+        season: One season, or one per point.
+        height: The wordmark height as a fraction of the map's reference height (see ``add_logos``), in (0, 1].
+        alpha: Opacity, 0 to 1.
+        variant: "default", "dark", or a named variant from ``marks()``.
+        embed: Inline each image as a data URI instead of linking its URL.
+        id_system: The id system of ``teams``; "auto" tries each in order.
+
+    Returns:
+        object: ``target`` itself, with the markers added.
+
+    Raises:
+        InputError: (a ValueError) If ``height`` or ``alpha`` is out of range, ``league``, ``id_system`` or ``variant``
+            is unknown, or ``season`` is not a year or is outside the seasons sdvplot knows for the league.
+        ValueError: If the inputs differ in length, or a location is not a number.
+        UnsupportedTargetError: (a TypeError) If ``target`` is not a ``folium.Map``.
+        OfflineError: If the logo manifest, or with ``embed=True`` a mark's image, 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).
+        UnsafeDownloadError: (an OSError) If a download is refused: larger than the byte cap, past the deadline, or
+            redirected away from https.
+        UnsafeCachePathError: (a ValueError) If ``embed=True`` and the manifest's sha256 or extension for a mark would
+            put the file outside the cache directory.
+
+    Example:
+        ::
+
+            import folium
+            import sdvplot
+
+            m = folium.Map(location=[39, -95], zoom_start=4)
+            sdvplot.add_wordmarks(m, [-94.48], [39.05], ["KC"], league="nfl", height=0.04)
+
+    See Also:
+        sdvplotR: https://sdvplotR.sportsdataverse.org/
+    """
+    return _add(
+        target, x, y, teams, kind="wordmark", league=league, season=season, height=height, alpha=alpha,
+        variant=variant, embed=embed, id_system=id_system,
+    )  # fmt: skip
+
+
+def add_headshots(
+    target: Any,
+    x: Any,
+    y: Any,
+    players: Any,
+    *,
+    league: str,
+    height: float = 0.1,
+    alpha: float = 1,
+    embed: bool = False,
+    id_system: str = "espn",
+) -> Any:
+    """Put each player's headshot on a Folium map at its (longitude, latitude).
+
+    Args:
+        target: A ``folium.Map``.
+        x: The longitudes.
+        y: The latitudes, the same length as ``x``.
+        players: The player id for each point (shown as the tooltip).
+        league: The SDV league key, e.g. "nfl".
+        height: The headshot height as a fraction of the map's reference height (see ``add_logos``), in (0, 1].
+        alpha: Opacity, 0 to 1.
+        embed: Inline each image as a data URI instead of linking its URL.
+        id_system: "espn" (ESPN athlete ids) or "gsis" (NFL), as in ``headshot_url``.
+
+    Returns:
+        object: ``target`` itself, with the markers added.
+
+    Raises:
+        InputError: (a ValueError) If ``height`` or ``alpha`` is out of range, ``league`` has no ESPN headshots, or
+            ``id_system`` is not valid for ``league``.
+        ValueError: If the inputs differ in length, or a location is not a number.
+        UnsupportedTargetError: (a TypeError) If ``target`` is not a ``folium.Map``.
+        OfflineError: If the nflverse player table (``id_system="gsis"``), or with ``embed=True`` a headshot, is neither
+            cached nor downloadable (a DownloadError, also an OSError, for an HTTP error status).
+        UnsafeDownloadError: (an OSError) If a download is refused: larger than the byte cap, past the deadline, or
+            redirected away from https.
+
+    Example:
+        ::
+
+            import folium
+            import sdvplot
+
+            m = folium.Map(location=[39, -95], zoom_start=4)
+            sdvplot.add_headshots(m, [-94.48], [39.05], ["3139477"], league="nfl", height=0.08)
+
+    See Also:
+        sdvplotR: https://sdvplotR.sportsdataverse.org/
+    """
+    return _add(
+        target, x, y, players, kind="headshot", league=league, season=None, height=height, alpha=alpha,
+        variant="default", embed=embed, id_system=id_system,
+    )  # fmt: skip
+
+
+def axis_logos(target: Any, axis: str, **kwargs: Any) -> Any:
+    """Not supported: a map has no category axes.
+
+    Args:
+        target: A ``folium.Map``.
+        axis: "x" or "y".
+        **kwargs: Ignored.
+
+    Returns:
+        object: Never returns.
+
+    Raises:
+        UnsupportedTargetError: (a TypeError) Always. Put the logos on the map with ``add_logos`` instead.
+
+    Example:
+        ::
+
+            import folium
+            import sdvplot
+
+            try:
+                sdvplot.axis_logos(folium.Map(), "x", league="nfl")
+            except TypeError:
+                pass   # raised: maps have no axis logos
+
+    See Also:
+        sdvplotR: https://sdvplotR.sportsdataverse.org/
+    """
+    raise UnsupportedTargetError("a folium map has no category axes; put the logos on the map with add_logos instead")
+
+
+def _drawn_marks(target: Any) -> list[tuple[Any, ...]]:
+    """Test hook: (team_id, x, y, height, url) for each marker sdvplot added; height = icon px / reference px."""
+    m = _map(target)
+    ref = _reference_height(m)
+    out = []
+    for group in m._children.values():
+        if isinstance(group, folium.FeatureGroup) and group.layer_name == _GROUP_NAME:
+            markers: list[Any] = list(group._children.values())
+            for marker in markers:
+                if hasattr(marker, "_sdvplot_mark"):
+                    team_id, x, y, src = marker._sdvplot_mark
+                    out.append((team_id, x, y, marker.icon.options["icon_size"][1] / ref, src))
+    return out