sdvplot 0.1.0__py3-none-any.whl

sdvplot/_images.py

@@ -0,0 +1,292 @@
+"""Decoded logo images for matplotlib-style libraries (web libraries use logo_url() instead)."""
+
+from __future__ import annotations
+
+import collections
+import contextlib
+import hashlib
+import io
+import numbers
+import re
+import threading
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlsplit
+from urllib.request import url2pathname
+
+from sdvplot._cache import MEMORY_CACHES, atomic_write, cache_path, fetch_cached, fetch_immutable, key_lock
+from sdvplot._errors import InputError, IntegrityError, OptionalDependencyError, UnsafeCachePathError, warn
+from sdvplot._marks import _check_mark_type, _check_variant, select_mark
+from sdvplot._resolve import one_team, resolve
+from sdvplot._types import IdSystem, MarkType
+
+if TYPE_CHECKING:
+    from PIL import Image
+
+DEFAULT_SVG_SIZE = 512
+# The largest longest side an image is rendered at: 4096 x 4096 RGBA is 64 MiB, DECODED_BUDGET // 4, the largest image
+# the decoded cache keeps. resvg allocates the whole canvas before Pillow's bomb guard sees it (a far larger one aborted
+# the process), so an SVG's size and aspect ratio are checked before rendering.
+MAX_SIZE = 4096
+MAX_ASPECT = 64  # an SVG more than 64 times longer than it is wide is refused
+_PROBE = 1024  # the box of the probe render that measures an SVG's aspect ratio
+_SHA256 = re.compile(r"[0-9a-f]{64}")
+URL_IMAGE_MAX_BYTES = 10 * 1024 * 1024
+IMAGE_EXTS = frozenset({"png", "jpg", "jpeg", "svg", "webp", "gif", "bmp"})
+
+
+def _rasterize(path: Path, sha: str, size: int, ext: str) -> Image.Image:
+    from PIL import Image
+
+    if not 1 <= size <= MAX_SIZE:
+        raise InputError(f"an SVG mark is rasterized at 1 to {MAX_SIZE} pixels, got size={size!r}")
+    try:
+        import importlib.metadata
+
+        import resvg_py
+    except ImportError as e:
+        raise OptionalDependencyError("SVG logos need the svg extra: pip install sdvplot[svg]") from e
+
+    try:
+        version = importlib.metadata.version("resvg-py")
+    except importlib.metadata.PackageNotFoundError as e:
+        raise OptionalDependencyError("SVG logos need the svg extra: pip install sdvplot[svg]") from e
+    out = cache_path(f"rasters/{sha}_{size}_v{version}.png")
+
+    # Try to open cached raster; if corrupt, treat as cache miss
+    if out.exists():
+        try:
+            img = Image.open(out)
+            img.load()
+            return img
+        except (OSError, Image.UnidentifiedImageError):
+            # Cache miss due to corruption; delete (best effort: the cache may be read-only) and re-render
+            with contextlib.suppress(OSError):
+                out.unlink()
+
+    # Render SVG
+    try:
+        svg = path.read_text(encoding="utf-8-sig")
+    except UnicodeDecodeError as e:
+        raise ValueError(f"SVG {sha}.{ext}: {e}") from e
+
+    def render(box: int) -> bytes:
+        # given a width and a height, resvg fits the SVG inside that box keeping its aspect ratio: the longest side is
+        # box pixels and nothing larger is allocated, however tall, wide or large the SVG says it is
+        try:
+            return bytes(resvg_py.svg_to_bytes(svg_string=svg, width=box, height=box))
+        except ValueError as e:
+            raise ValueError(f"SVG {sha}.{ext}: {e}") from e
+
+    w, h = Image.open(io.BytesIO(render(_PROBE))).size
+    if max(w, h) > MAX_ASPECT * min(w, h):
+        raise InputError(f"SVG {sha}.{ext} renders {w} x {h}: an aspect ratio beyond 1:{MAX_ASPECT}, not drawn")
+    png = render(size)
+
+    with contextlib.suppress(OSError):  # a read-only cache still gets the image, just not cached
+        atomic_write(out, png)
+    img = Image.open(io.BytesIO(png))
+    img.load()
+    return img
+
+
+def logo_image(
+    team: Any,
+    league: str,
+    *,
+    season: Any = None,
+    variant: str = "default",
+    mark_type: MarkType = "logo",
+    size: int | None = None,
+    id_system: IdSystem = "auto",
+    strict: bool = False,
+) -> Image.Image | None:
+    """The team's mark as a PIL image (downloaded once, then cached).
+
+    Args:
+        team: One team identifier (abbreviation, name, ESPN id, ...).
+        league: The SDV league key, e.g. "nfl".
+        season: A season year; None picks the current mark.
+        variant: "default", "dark", or a named variant from ``marks()``.
+        mark_type: "logo" or "wordmark".
+        size: The longest side in pixels, an int from 1 to 4096. Rasters are only scaled down; SVGs are rasterized at
+            it (default 512). Without it a raster comes at the archive's size, up to 4096 px (64 MiB decoded): pass
+            ``size`` when the image is for a plot.
+        id_system: The id system of ``team``, as in ``resolve``: "auto" tries each in order; NHL stats ids need
+            "nhl_id".
+        strict: Raise UnresolvedTeamError instead of warning when the team does not resolve.
+
+    Returns:
+        PIL.Image.Image | None: The image, or None when the team does not resolve or has no mark.
+
+    Raises:
+        TypeError: If ``team`` is not a single value.
+        OptionalDependencyError: If the mark is an SVG and the ``svg`` extra is not installed.
+        OfflineError: If the download fails and no cached copy exists.
+        DownloadError: (an OfflineError and an OSError) If the CDN answers with an error status (a 4xx or 5xx
+            response) and no cached copy exists.
+        IntegrityError: (a DownloadError) If the download does not match the manifest's sha256, or is not an image
+            PIL can decode.
+        UnsafeDownloadError: (an OSError) If the download is refused: larger than the byte cap, past the deadline, or
+            redirected away from https.
+        UnsafeCachePathError: (a ValueError) If the manifest's sha256 or extension for the mark would put the file
+            outside the cache directory.
+        InputError: (a ValueError) If ``league`` or ``id_system`` is unknown, ``mark_type`` is not "logo"/"wordmark",
+            ``variant`` is a name no mark in the archive has, ``season`` is not a year or is outside the seasons
+            sdvplot knows for the league, or ``size`` is not an int from 1 to 4096.
+        UnresolvedTeamError: (a ValueError) If ``strict=True`` and the team does not resolve.
+        ValueError: If an SVG cannot be parsed; an ``InputError`` if it is more than 64 times longer than it is wide.
+
+    Example:
+        ::
+
+            import sdvplot
+
+            img = sdvplot.logo_image("KC", "nfl", size=64)
+            img.size   # (64, 64)
+
+    See Also:
+        sdvplotR: https://sdvplotR.sportsdataverse.org/ ;
+        sdv-py: https://py.sportsdataverse.org/
+    """
+    _check_mark_type(mark_type)
+    _check_variant(variant, league)
+    if size is not None and (
+        isinstance(size, bool) or not isinstance(size, numbers.Integral) or not 1 <= size <= MAX_SIZE
+    ):
+        raise InputError(f"size is the longest side in pixels, an int from 1 to {MAX_SIZE}, got {size!r}")
+    team_id = resolve(one_team(team, "logo_image"), league, season=season, id_system=id_system, strict=strict)
+    if team_id is None:
+        return None
+    row = select_mark(team_id, league, season, variant, mark_type)
+    if row is None:
+        warn(f"no {mark_type} archived for {team!r} ({league})")
+        return None
+    return load_mark_image(row, size)
+
+
+def mark_file(row: dict[str, Any]) -> Path:
+    """The cached file of one manifest row's image, downloaded once and checked against its sha256."""
+    sha, ext = str(row["sha256"]), str(row["ext"])
+    if not _SHA256.fullmatch(sha) or ext not in IMAGE_EXTS:
+        raise UnsafeCachePathError(f"manifest row has an invalid sha256 or ext ({sha!r}, {ext!r}); not fetched")
+    return fetch_immutable(str(row["archive_url"]), f"images/{sha[:2]}/{sha}.{ext}", sha)
+
+
+def _decode_mark(sha: str, ext: str, url: str, size: int | None) -> Image.Image:
+    """The decoded image of one mark (SVGs rasterized, rasters scaled down to ``size``)."""
+    from PIL import Image
+
+    path = mark_file({"sha256": sha, "ext": ext, "archive_url": url})
+    if ext == "svg":
+        return _rasterize(path, sha, size or DEFAULT_SVG_SIZE, ext)
+    try:
+        img: Image.Image = Image.open(path)
+    except Image.UnidentifiedImageError as e:  # the archive's own file, sha-checked: the archive is wrong
+        raise IntegrityError(f"{url}: not an image PIL can decode ({e})") from e
+    img.load()
+    if size is not None:
+        img = img.copy()
+        img.thumbnail((size, size))
+    return img
+
+
+# Decoded images kept in memory, least recently used first, bounded by pixel bytes rather than entry count: the archive
+# holds thousands of 4096 x 4096 rasters (67 MB each decoded), so a count bound alone could pin gigabytes.
+DECODED_BUDGET = 256 * 1024 * 1024
+_decoded: collections.OrderedDict[tuple[str, str, str, int | None], Image.Image] = collections.OrderedDict()
+_decoded_bytes = 0
+_decoded_lock = threading.Lock()
+
+
+def _nbytes(img: Image.Image) -> int:
+    from PIL import ImageMode
+
+    # bytes per sample from the mode's array type: 2 for I;16, 4 for I and F, 1 for the 8-bit modes
+    return img.width * img.height * len(img.getbands()) * int(ImageMode.getmode(img.mode).typestr[-1])
+
+
+def _decoded_mark(sha: str, ext: str, url: str, size: int | None) -> Image.Image:
+    """The decoded image of one mark, kept per (sha256, ext, url, size) so repeated calls decode a team's logo once.
+    An image over a quarter of the budget is decoded per call instead of pushing everything else out. Threads after the
+    same key decode it once (the others wait for it). Callers must go through ``load_mark_image``, which hands out a
+    copy."""
+    global _decoded_bytes
+    key = (sha, ext, url, size)
+    with key_lock(key):
+        with _decoded_lock:
+            if (hit := _decoded.get(key)) is not None:
+                _decoded.move_to_end(key)
+                return hit
+        img = _decode_mark(*key)
+        nbytes = _nbytes(img)
+        if nbytes <= DECODED_BUDGET // 4:
+            with _decoded_lock:
+                if key not in _decoded:
+                    _decoded[key] = img
+                    _decoded_bytes += nbytes
+                    while _decoded_bytes > DECODED_BUDGET:
+                        _, old = _decoded.popitem(last=False)
+                        _decoded_bytes -= _nbytes(old)
+    return img
+
+
+def _clear_decoded() -> None:
+    global _decoded_bytes
+    with _decoded_lock:
+        _decoded.clear()
+        _decoded_bytes = 0
+
+
+MEMORY_CACHES.append(_clear_decoded)  # clear_cache() also drops the decoded images held in memory
+
+
+def load_mark_image(row: dict[str, Any], size: int | None = None) -> Image.Image:
+    """The image for one manifest row (as ``select_mark`` returns it): fetched by sha256 once, SVGs rasterized.
+
+    ``size`` is the longest side in pixels: rasters are only scaled down; SVGs are rasterized at it (default 512).
+    Decoded images are kept in memory (up to ``DECODED_BUDGET`` bytes of pixels, least recently used dropped first);
+    the caller gets its own copy, free to modify, with the source ``format`` kept.
+    """
+    img = _decoded_mark(str(row["sha256"]), str(row["ext"]), str(row["archive_url"]), size)
+    out = img.copy()
+    out.format = img.format  # Image.copy() drops it; callers may read img.format / Image.MIME
+    return out
+
+
+def _check_image(body: bytes) -> None:
+    from PIL import Image
+
+    Image.open(io.BytesIO(body)).verify()
+
+
+def url_file(url: str) -> Path:
+    """The cached file of an image that is not content-addressed (a headshot): keyed by sha256(url), refreshed after
+    SDVPLOT_CACHE_TTL, non-images rejected."""
+    key = hashlib.sha256(url.encode()).hexdigest()
+    return fetch_cached(url, f"urlimages/{key[:2]}/{key}", validate=_check_image, max_bytes=URL_IMAGE_MAX_BYTES)
+
+
+def load_url_image(url: str) -> Image.Image:
+    """An image that is not content-addressed (a headshot): cached by sha256(url), refreshed after SDVPLOT_CACHE_TTL."""
+    from PIL import Image
+
+    path = url_file(url)
+    img: Image.Image = Image.open(path)
+    img.load()
+    return img
+
+
+def load_path_image(path: str) -> Image.Image:
+    """Any image by https URL (cached like a headshot), file:// URI or local path; raises OSError, ValueError or
+    OfflineError (an http URL is refused with UnsafeDownloadError, an OSError)."""
+    scheme = urlsplit(path).scheme.lower()  # URL schemes are case-insensitive; a Windows drive letter is no scheme
+    if scheme in ("http", "https"):
+        return load_url_image(path)
+    if scheme == "file":  # what pathlib.Path.as_uri() writes
+        path = url2pathname(urlsplit(path).path)
+    from PIL import Image
+
+    img: Image.Image = Image.open(path)
+    img.load()
+    return img

sdvplot/_index.py

@@ -0,0 +1,178 @@
+"""The bundled team index: teams.parquet and aliases.parquet, generated by tools/build_index.py."""
+
+from __future__ import annotations
+
+import datetime
+import functools
+from collections.abc import Callable
+from importlib import resources
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from sdvplot._errors import InputError
+
+if TYPE_CHECKING:
+    import polars as pl
+else:
+    from sdvplot._lazy import pl
+
+
+def _team_schema() -> dict[str, pl.DataType]:
+    return {
+        "league": pl.String(),
+        "team_id": pl.String(),
+        "abbr": pl.String(),
+        "name": pl.String(),
+        "short_name": pl.String(),
+        "location": pl.String(),
+        "program": pl.String(),
+        "conference_id": pl.String(),
+        "conference": pl.String(),
+        "color_primary": pl.String(),
+        "color_secondary": pl.String(),
+        "color_source": pl.String(),
+    }
+
+
+def _alias_schema() -> dict[str, pl.DataType]:
+    return {
+        "league": pl.String(),
+        "id_system": pl.String(),
+        "value": pl.String(),
+        "team_id": pl.String(),
+        "valid_from": pl.Int32(),
+        "valid_to": pl.Int32(),
+    }
+
+
+def __getattr__(name: str) -> dict[str, pl.DataType]:
+    # TEAM_SCHEMA / ALIAS_SCHEMA stay importable (tests, tools/build_index.py) but are built on first use
+    if name == "TEAM_SCHEMA":
+        return _team_schema()
+    if name == "ALIAS_SCHEMA":
+        return _alias_schema()
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+_RELOAD_HOOKS: list[Callable[[], None]] = []
+
+
+@functools.cache
+def data_dir() -> Path:
+    """Where the generated index lives inside the installed package (looked up once: every check_league reads it)."""
+    return Path(str(resources.files("sdvplot") / "data"))
+
+
+@functools.cache
+def _read(name: str, directory: str) -> pl.DataFrame:
+    return pl.read_parquet(Path(directory) / f"{name}.parquet")
+
+
+@functools.cache
+def _leagues(directory: str) -> frozenset[str]:
+    return frozenset(_read("teams", directory)["league"].unique().to_list())
+
+
+def check_league(league: str) -> None:
+    """The one unknown-league error every public function raises."""
+    if not isinstance(league, str):  # a list or Series here is a pre-0.1 call: team_colors(teams, league)
+        raise InputError(
+            f"league must be a league key such as 'nfl', got {type(league).__name__}; team_colors and palette take "
+            "the league first: team_colors(league, teams)"
+        )
+    known = _leagues(str(data_dir()))
+    if league not in known:
+        raise InputError(f"unknown league {league!r}; known leagues: {sorted(known)}")
+
+
+@functools.cache
+def _season_table() -> dict[str | None, tuple[int, int]]:
+    """league -> (first, last) season a season argument may name, and None -> the bounds for any league; built once per
+    index load. The first season is the earliest the aliases date (MLB's 1871 for the index), and a league's own where
+    its aliases close a range (``valid_to``), so its history is dated: the NFL's 1920, the WNBA's 1997, the XFL's 2020.
+    Aliases that only open a range (the NHL's 2026 renames) say nothing about where a league starts, so such a league
+    keeps the index's floor. The last season is the later of the latest one the aliases name and next year, for every
+    league (an older index still takes this season and the next)."""
+    a = alias_table()
+    lo = a.select(pl.min_horizontal(pl.col("valid_from").min(), pl.col("valid_to").min())).item()
+    hi = a.select(pl.max_horizontal(pl.col("valid_from").max(), pl.col("valid_to").max())).item()
+    if lo is None or hi is None:
+        return {}
+    last = max(int(hi), datetime.date.today().year + 1)
+    out: dict[str | None, tuple[int, int]] = {None: (int(lo), last)}
+    dated = set(a.filter(pl.col("valid_to").is_not_null())["league"].to_list())
+    firsts = (
+        a.filter(pl.col("league").is_in(sorted(dated)))
+        .group_by("league")
+        .agg(pl.min_horizontal(pl.col("valid_from").min(), pl.col("valid_to").min()).alias("first"))
+    )
+    for league, first in firsts.iter_rows():
+        out[league] = (int(first), last)
+    return out
+
+
+def season_bounds(league: str | None = None) -> tuple[int, int] | None:
+    """The first and last season a season argument may name for ``league`` (None: any league), or None when no alias
+    is dated; see ``_season_table``."""
+    table = _season_table()
+    return table.get(league, table.get(None))
+
+
+def on_reload(fn: Callable[[], None]) -> None:
+    """Register a cache that must be dropped when the index is reloaded (the resolver's lookup tables)."""
+    _RELOAD_HOOKS.append(fn)
+
+
+def reload_index() -> None:
+    """Forget the loaded index and everything derived from it."""
+    _read.cache_clear()
+    _leagues.cache_clear()
+    _season_table.cache_clear()
+    for fn in _RELOAD_HOOKS:
+        fn()
+
+
+def team_table() -> pl.DataFrame:
+    return _read("teams", str(data_dir()))
+
+
+def alias_table() -> pl.DataFrame:
+    return _read("aliases", str(data_dir()))
+
+
+def index_version() -> str:
+    path = data_dir() / "INDEX_VERSION"
+    return path.read_text().strip() if path.exists() else "unknown"
+
+
+def teams(league: str | None = None) -> pl.DataFrame:
+    """The bundled team index: one row per (league, team_id), with names, abbreviation, conference and colors.
+
+    Args:
+        league: An SDV league key such as "nfl"; None returns every league.
+
+    Returns:
+        polars.DataFrame: The index columns ``league``, ``team_id``, ``abbr``, ``name``, ``short_name``, ``location``,
+        ``program``, ``conference_id``, ``conference``, ``color_primary``, ``color_secondary`` and ``color_source``:
+        "nflverse" or "espn" (published colors), "logo" (derived from the team's archived logo, where no source
+        publishes any) or "fallback" (a placeholder).
+
+    Raises:
+        InputError: (a ValueError) If ``league`` is given and is not a known league key.
+
+    Example:
+        ::
+
+            import sdvplot
+
+            sdvplot.teams("nfl").shape   # (32, 12)
+
+    See Also:
+        sdvplotR: https://sdvplotR.sportsdataverse.org/ ;
+        sdv-py: https://py.sportsdataverse.org/
+    """
+    t = team_table()
+    if league is None:
+        return t.clone()  # never the cached frame: an in-place edit by the caller would leak into the session
+    check_league(league)
+    return t.filter(pl.col("league") == league)

sdvplot/_lazy.py

@@ -0,0 +1,15 @@
+"""A stand-in for ``polars`` that imports it on first attribute access, so ``import sdvplot`` stays fast."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class _LazyPolars:
+    def __getattr__(self, name: str) -> Any:
+        import polars
+
+        return getattr(polars, name)
+
+
+pl = _LazyPolars()

sdvplot/_manifest.py

@@ -0,0 +1,73 @@
+"""The sdv-assets logo manifest: every archived mark with its season range, source and CDN URL."""
+
+from __future__ import annotations
+
+import functools
+import io
+from typing import TYPE_CHECKING
+
+from sdvplot._cache import MEMORY_CACHES, SAFE_URL, fetch_cached
+from sdvplot._errors import warn
+
+if TYPE_CHECKING:
+    import polars as pl
+else:
+    from sdvplot._lazy import pl
+
+MANIFEST_URL = "https://sdv.nyc3.cdn.digitaloceanspaces.com/assets/public/manifest/marks.csv"
+# The columns sdvplot reads: a contract with sdv-assets (checked live by tests/test_manifest.py)
+REQUIRED_COLUMNS = (
+    "level",
+    "league",
+    "entity_id",
+    "entity_name",
+    "program",
+    "mark_type",
+    "variant",
+    "valid_from",
+    "valid_to",
+    "source",
+    "sha256",
+    "ext",
+    "archive_url",
+    "first_seen",
+)
+
+
+def _validate(body: bytes) -> None:
+    # parse the whole body the way _read() will, so a ragged or header-only manifest never replaces the cached one
+    m = pl.read_csv(io.BytesIO(body), infer_schema_length=0)
+    missing = [c for c in REQUIRED_COLUMNS if c not in m.columns]
+    if missing:
+        raise ValueError(f"the logo manifest is missing columns {missing}")
+    if m.is_empty():
+        raise ValueError("the logo manifest has no rows")
+
+
+# keyed by mtime so a refreshed file is read again; only the current file matters, so the previous frame (~17 MiB) is
+# dropped rather than kept for the session
+@functools.lru_cache(maxsize=1)
+def _read(path: str, mtime: float) -> pl.DataFrame:
+    # every column as text first, so ids keep leading zeros and never become floats; then type the season range
+    m = pl.read_csv(path, infer_schema_length=0)
+    # archive_url reaches the web adapters' HTML: a row whose URL is not a plain https URL is dropped, never passed on
+    ok = m["archive_url"].str.contains(f"^(?:{SAFE_URL})$").fill_null(False)
+    if not ok.all():
+        bad = m.filter(~ok)["archive_url"]
+        warn(
+            f"dropped {len(bad)} logo manifest row(s) whose archive_url is not a plain https URL, e.g. {bad[0]!r:.100}"
+        )
+        m = m.filter(ok)
+    return m.with_columns(
+        pl.col("valid_from").cast(pl.Int32, strict=False),
+        pl.col("valid_to").cast(pl.Int32, strict=False),
+    )
+
+
+MEMORY_CACHES.append(_read.cache_clear)  # clear_cache() also frees the parsed manifest
+
+
+def load_manifest() -> pl.DataFrame:
+    """The logo manifest, from the local cache (refreshed after SDVPLOT_CACHE_TTL days)."""
+    path = fetch_cached(MANIFEST_URL, "manifest/marks.csv", validate=_validate)
+    return _read(str(path), path.stat().st_mtime)