sdvplot 0.1.0__py3-none-any.whl

sdvplot/_marks.py

@@ -0,0 +1,296 @@
+"""Choosing a team's mark from the manifest: variant, then season within each variant, then source preference."""
+
+from __future__ import annotations
+
+import weakref
+from typing import TYPE_CHECKING, Any
+
+from sdvplot import _index
+from sdvplot._cache import MEMORY_CACHES
+from sdvplot._errors import InputError, UnresolvedTeamError, warn
+from sdvplot._manifest import load_manifest
+from sdvplot._normalize import norm_season
+from sdvplot._resolve import _covers, one_team, resolve
+from sdvplot._types import IdSystem, MarkType
+
+if TYPE_CHECKING:
+    import polars as pl
+else:
+    from sdvplot._lazy import pl
+
+# Official sources first, then archived copies, then derived crops (sdv-assets source names)
+SOURCE_RANK: dict[str, int] = {
+    "espn": 0,
+    "nflverse": 1,
+    "nhl": 1,
+    "mlbstatic": 1,
+    "fox": 1,
+    "hockeytech": 2,
+    "cricinfo": 2,
+    "ncaa.com": 3,
+    "nwhl.co": 4,
+    "shiftstats": 4,
+    "wayback": 4,
+    "aaf.com": 5,
+    "aaf-strip-crop": 6,
+}
+
+
+MARK_TYPES = ("logo", "wordmark")
+
+
+def _check_mark_type(mark_type: str) -> None:
+    if mark_type not in MARK_TYPES:
+        raise InputError(f"mark_type must be one of {list(MARK_TYPES)}, got {mark_type!r}")
+
+
+# (the manifest frame, every variant it holds): rebuilt when a refreshed manifest is a new object, as _RANKED is. The
+# frame is held weakly here and in _RANKED, so a refreshed or cleared one is freed (_manifest keeps only the latest)
+_VARIANTS: list[tuple[weakref.ref[pl.DataFrame], frozenset[str]]] = []
+
+
+def _check_variant(variant: str, league: str) -> None:
+    """A variant no mark in the archive has is a typo, not one this team lacks (that falls back): ValueError listing
+    the league's variants. "default" and "dark" are always valid."""
+    if variant in ("default", "dark"):
+        return
+    manifest = load_manifest()
+    if not _VARIANTS or _VARIANTS[0][0]() is not manifest:
+        _VARIANTS[:] = [(weakref.ref(manifest), frozenset(manifest["variant"].drop_nulls().to_list()))]
+    if not isinstance(variant, str) or variant not in _VARIANTS[0][1]:  # a list would be unhashable in the set
+        _index.check_league(league)
+        known = sorted({"default", "dark", *_ranked(league)["variant"].drop_nulls().to_list()})
+        raise InputError(f"unknown variant {variant!r}: no mark in the archive has it; {league} marks come in {known}")
+
+
+def _union(col: str, bound: pl.Expr) -> pl.Expr:
+    """One side of the union of several ranges: null (unbounded) if any range is unbounded there."""
+    return pl.when(pl.col(col).is_null().any()).then(None).otherwise(bound).alias(f"_alias_{col}")
+
+
+def _mark_aliases(league: str) -> pl.DataFrame:
+    """key ("source:entity_id", normalized like every alias value) -> canonical team_id, unique mappings only, with
+    the season range of the mapping (R36: an old-abbreviation mark is dated by its relocation alias)."""
+    return (
+        _index.alias_table()
+        .filter((pl.col("league") == league) & (pl.col("id_system") == "mark"))
+        .with_columns(pl.col("value").str.strip_chars().str.to_lowercase().alias("_key"))
+        .group_by("_key")
+        .agg(
+            pl.col("team_id").first(),
+            pl.col("team_id").n_unique().alias("_n"),
+            _union("valid_from", pl.col("valid_from").min()),
+            _union("valid_to", pl.col("valid_to").max()),
+        )
+        .filter(pl.col("_n") == 1)
+        .drop("_n")
+    )
+
+
+# league -> (the loaded manifest frame, weakly; its rows mapped and ranked). _manifest caches that frame per
+# path+mtime, so a refreshed manifest is a new object and rebuilds; an index reload clears it (R45)
+_RANKED: dict[str, tuple[weakref.ref[pl.DataFrame], pl.DataFrame]] = {}
+_index.on_reload(_RANKED.clear)
+# league -> (its ranked table, that table's rows as dicts by team_id, filled per team on first use): select_mark's
+# lookup, a dict hit instead of a polars filter per call
+_TEAM_ROWS: dict[str, tuple[pl.DataFrame, dict[str, list[dict[str, Any]]]]] = {}
+for _clear in (_VARIANTS.clear, _RANKED.clear, _TEAM_ROWS.clear):
+    MEMORY_CACHES.append(_clear)  # clear_cache() also drops what was built from the manifest it deletes
+
+
+def _ranked(league: str) -> pl.DataFrame:
+    """Every team-level manifest row of one league that maps to one canonical team, with its effective range,
+    best first; marks() only filters it on team_id."""
+    manifest = load_manifest()
+    hit = _RANKED.get(league)
+    if hit is not None and hit[0]() is manifest:
+        return hit[1]
+    m = (
+        manifest.filter((pl.col("level") == "team") & (pl.col("league") == league))
+        .with_columns(
+            pl.concat_str(pl.col("source"), pl.lit(":"), pl.col("entity_id"))
+            .str.strip_chars()
+            .str.to_lowercase()
+            .alias("_key")
+        )
+        .join(_mark_aliases(league), on="_key", how="inner")
+        .with_columns(  # the intersection of the row's range and its alias's (null = unbounded on that side)
+            pl.max_horizontal("valid_from", "_alias_valid_from").alias("valid_from"),
+            pl.min_horizontal("valid_to", "_alias_valid_to").alias("valid_to"),
+        )
+        .drop("_key", "_alias_valid_from", "_alias_valid_to")
+    )
+    ranked = (
+        m.with_columns(
+            pl.col("source").replace_strict(SOURCE_RANK, default=5, return_dtype=pl.Int8).alias("source_rank"),
+            pl.col("valid_to").is_null().alias("_open"),
+        )
+        .sort(
+            by=["source_rank", "_open", "valid_to", "first_seen", "valid_from", "sha256"],
+            descending=[False, True, True, True, True, False],
+            nulls_last=True,
+        )
+        .drop("_open")
+    )
+    _RANKED[league] = (weakref.ref(manifest), ranked)
+    return ranked
+
+
+def _team_rows(team_id: str, league: str) -> list[dict[str, Any]]:
+    """``_ranked(league)``'s rows for one team as dicts, best first; computed once per team per manifest load."""
+    ranked = _ranked(league)
+    hit = _TEAM_ROWS.get(league)
+    if hit is None or hit[0] is not ranked:
+        hit = _TEAM_ROWS[league] = (ranked, {})
+    if team_id not in hit[1]:
+        hit[1][team_id] = ranked.filter(pl.col("team_id") == team_id).to_dicts()
+    return hit[1][team_id]
+
+
+def marks(team: Any, league: str, *, season: Any = None, id_system: IdSystem = "auto") -> pl.DataFrame:
+    """Every archived mark for one team, best first.
+
+    Manifest entity ids are per-source, so rows reach a team only through its "mark" aliases; rows without a unique
+    mapping are dropped, never matched on the raw id. ``valid_from``/``valid_to`` are each row's effective range: the
+    manifest's, narrowed by the mark alias's (an open side takes the alias's).
+
+    Args:
+        team: One team identifier (abbreviation, name, ESPN id, ...).
+        league: The SDV league key, e.g. "nfl".
+        season: A season year, used to resolve a reused code.
+        id_system: "auto" or one id-system name, as in ``resolve``.
+
+    Returns:
+        polars.DataFrame: One row per archived mark (logos and wordmarks, every variant and source) with its
+        ``variant``, ``mark_type``, ``archive_url`` and ``source_rank``.
+
+    Raises:
+        TypeError: If ``team`` is not a single value.
+        InputError: (a ValueError) If ``league`` or ``id_system`` is unknown, or ``season`` is not a year or is
+            outside the seasons sdvplot knows for the league.
+        UnresolvedTeamError: (a ValueError) If the team is null or does not resolve.
+        OfflineError: If the logo manifest cannot be downloaded and no cached copy exists (a DownloadError, also an
+            OSError, when the CDN answers with an error status).
+        UnsafeDownloadError: (an OSError) If the manifest download is refused: larger than the byte cap, past the
+            deadline, or redirected away from https.
+
+    Example:
+        ::
+
+            import sdvplot
+
+            sdvplot.marks("KC", "nfl").shape   # (19, 21)
+
+    See Also:
+        sdvplotR: https://sdvplotR.sportsdataverse.org/ ;
+        sdv-py: https://py.sportsdataverse.org/
+    """
+    team_id = resolve(one_team(team, "marks"), league, season=season, id_system=id_system, strict=True)
+    if team_id is None:  # a null team: strict resolve() lets nulls through as None
+        raise UnresolvedTeamError(f"marks() needs a team, got {team!r}")
+    return _ranked(league).filter(pl.col("team_id") == team_id)
+
+
+def select_mark(
+    team: Any, league: str, season: Any = None, variant: str = "default", mark_type: str = "logo"
+) -> dict[str, Any] | None:
+    """The best mark: the requested variant; then, keeping its polarity (R44), "default" and an on_light variant
+    ("on_light", "*_on_light"), or for "dark" an on_dark variant and then "default"; then any variant. Within each,
+    season-covering rows first (explicit ranges before open-ended ones), else any row; within a set, official
+    sources and current marks first. An unknown or ambiguous team gives None with the resolver's warning."""
+    _check_mark_type(mark_type)
+    s = norm_season(season, league)
+    _check_variant(variant, league)
+    team_id = resolve(one_team(team, "select_mark"), league, season=s)
+    if team_id is None:
+        return None
+    # a team has tens of rows: choosing in Python costs less than one polars filter per step (R45); the rows are
+    # shared with _TEAM_ROWS, so the chosen one is handed out as a copy
+    rows = [r for r in _team_rows(team_id, league) if r["mark_type"] == mark_type]
+    side = "dark" if variant == "dark" else "light"
+
+    def polarity(v: str) -> bool:
+        return v == f"on_{side}" or v.endswith(f"_on_{side}")
+
+    def requested(v: str) -> bool:
+        return v == variant
+
+    def default(v: str) -> bool:
+        return v == "default"
+
+    order = [requested, polarity, default] if side == "dark" else [requested, default, polarity]
+    # sorted best-first, so the first row of any set is its best
+    for keep in [*order, None]:
+        found = [r for r in rows if keep is None or keep(r["variant"])]
+        if s is not None:
+            covering = [r for r in found if _covers(r["valid_from"], r["valid_to"], s)]
+            dated = [r for r in covering if r["valid_from"] is not None or r["valid_to"] is not None]
+            for df in (dated, covering):
+                if df:
+                    return dict(df[0])
+        if found:
+            return dict(found[0])
+    return None
+
+
+def logo_url(
+    team: Any,
+    league: str,
+    *,
+    season: Any = None,
+    variant: str = "default",
+    mark_type: MarkType = "logo",
+    id_system: IdSystem = "auto",
+    strict: bool = False,
+) -> str | None:
+    """The CDN URL of a team's logo or wordmark, chosen for the season.
+
+    Picks the requested variant (falling back to a default or polarity variant), then within each variant the archived
+    mark whose season range covers ``season`` (relocated franchises get their era's mark), then the most
+    authoritative source. Unknown teams return None with one SdvplotWarning.
+
+    Args:
+        team: One team identifier (abbreviation, name, ESPN id, ...).
+        league: The SDV league key, e.g. "nfl", "cfb", "nhl".
+        season: A season year; None picks the current mark.
+        variant: "default", "dark", or a named variant from ``marks()``.
+        mark_type: "logo" or "wordmark".
+        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:
+        str | None: The archive URL (content-addressed, immutable), or None when no mark exists.
+
+    Raises:
+        TypeError: If ``team`` is not a single value.
+        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 (a typo; the message lists the league's variants), or
+            ``season`` is not a year or is outside the seasons sdvplot knows for the league.
+        UnresolvedTeamError: (a ValueError) If ``strict=True`` and the team does not resolve.
+        OfflineError: If the logo manifest cannot be downloaded and no cached copy exists (a DownloadError, also an
+            OSError, when the CDN answers with an error status).
+        UnsafeDownloadError: (an OSError) If the manifest download is refused: larger than the byte cap, past the
+            deadline, or redirected away from https.
+
+    Example:
+        ::
+
+            import sdvplot
+
+            sdvplot.logo_url("KC", "nfl")   # 'https://sdv.nyc3.cdn.digitaloceanspaces.com/assets/public/sha256/3d/3d77....png'
+
+    See Also:
+        sdvplotR: https://sdvplotR.sportsdataverse.org/ ;
+        sdv-py: https://py.sportsdataverse.org/
+    """
+    _check_mark_type(mark_type)
+    _check_variant(variant, league)
+    team_id = resolve(one_team(team, "logo_url"), 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 str(row["archive_url"])

sdvplot/_normalize.py

@@ -0,0 +1,82 @@
+"""How raw team values and seasons are compared: one normal form, so 14, "14", 14.0, "14.0" and " 14 " are equal."""
+
+from __future__ import annotations
+
+import math
+import numbers
+import re
+import unicodedata
+from typing import Any
+
+from sdvplot import _index
+from sdvplot._errors import InputError
+
+_FLOAT_ID = re.compile(r"-?\d+\.0+")
+# typographic punctuation providers write inconsistently (sdvplotR fold_accents): curly apostrophes, en/em dashes
+_PUNCT = str.maketrans({"\u2018": "'", "\u2019": "'", "\u2013": "-", "\u2014": "-"})
+
+
+def _is_na(value: Any) -> bool:
+    return value is None or type(value).__name__ in ("NAType", "NaTType")
+
+
+def norm_value(value: Any) -> str | None:
+    """A team value as a comparison key: trimmed, accents and typographic punctuation folded, case-folded,
+    integral numbers without a decimal point."""
+    if _is_na(value):
+        return None
+    if isinstance(value, bool):
+        return str(value).casefold()
+    if isinstance(value, numbers.Integral):
+        return str(int(value))
+    if isinstance(value, numbers.Real):
+        f = float(value)
+        if math.isnan(f):
+            return None
+        return str(int(f)) if f.is_integer() else str(f)
+    s = str(value).strip()
+    if not s.isascii():  # "San José State" == "San Jose State": decompose, then drop the combining accents
+        s = "".join(c for c in unicodedata.normalize("NFKD", s.translate(_PUNCT)) if not unicodedata.combining(c))
+    s = s.casefold()
+    if _FLOAT_ID.fullmatch(s):  # "13.0": an id that went through a float before it became text
+        s = s.split(".")[0]
+    return s or None
+
+
+_SPLIT_SEASON = re.compile(r"\s*(\d{4})\s*[-/]\s*(\d{2}|\d{4})\s*")
+
+
+def check_season(year: int, league: str | None = None) -> None:
+    """InputError unless ``year`` is a season sdvplot knows for ``league`` (any league when None): the bounds come from
+    the bundled index (``_index.season_bounds``)."""
+    bounds = _index.season_bounds(league)
+    if bounds is not None and not bounds[0] <= year <= bounds[1]:
+        scope = "" if league is None else f" for {league}"
+        raise InputError(
+            f"season {year} is outside the seasons sdvplot knows{scope} ({bounds[0]} to {bounds[1]}); pass a year such "
+            "as 2020"
+        )
+
+
+def norm_season(value: Any, league: str | None = None) -> int | None:
+    """A season as an int year. Accepts 2020, 2020.0, "2020"; None/NaN mean no season; anything else is an error, and
+    so is a year outside the seasons the bundled index holds for ``league`` (any league when None)."""
+    if _is_na(value):
+        return None
+    year = None
+    if isinstance(value, numbers.Real) and not isinstance(value, bool):
+        f = float(value)
+        if math.isnan(f):
+            return None
+        if f.is_integer():
+            year = int(f)
+    elif isinstance(value, str) and value.strip().isdigit():
+        year = int(value.strip())
+    if year is None:
+        hint = ""
+        if isinstance(value, str) and (m := _SPLIT_SEASON.fullmatch(value)):
+            end = int(m.group(1)) + 1
+            hint = f"; for a split season pass its ending year ({end} for {value.strip()!r})"
+        raise InputError(f"season must be a year such as 2020, got {value!r}{hint}")
+    check_season(year, league)
+    return year

sdvplot/_placement.py

@@ -0,0 +1,168 @@
+"""From the caller's (x, y, teams) to the marks an adapter draws: one validation and resolution step for every adapter.
+
+Every adapter calls check_height, check_alpha and place, then only draws. That keeps the shared contract (resolution,
+warn and skip, pandas/polars parity, height) in one place instead of one copy per library.
+"""
+
+from __future__ import annotations
+
+import math
+import numbers
+import os
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, cast
+
+from sdvplot._errors import InputError, warn
+from sdvplot._headshots import headshot_url
+from sdvplot._marks import select_mark
+from sdvplot._normalize import norm_value
+from sdvplot._resolve import _resolve_ids, _seasons, _unpack, resolve
+
+if TYPE_CHECKING:
+    from sdvplot._types import HeadshotIdSystem, IdSystem
+
+KINDS = ("logo", "wordmark", "headshot")
+
+
+@dataclass(frozen=True)
+class Placement:
+    """One mark to draw: whose it is, where, and which image."""
+
+    team_id: str  # canonical team id; the player id for headshots; the path for place_images
+    x: Any  # the caller's x value (number, category or datetime), read positionally
+    y: Any
+    url: str  # archive_url of the selected mark, or the headshot URL
+    aspect: float | None  # width / height from the manifest row; None for headshots
+    mark: dict[str, Any] | None  # the selected manifest row; None for headshots
+
+
+def _real(value: Any) -> bool:
+    return isinstance(value, numbers.Real) and not isinstance(value, bool) and not math.isnan(value)
+
+
+def check_height(height: Any) -> float:
+    """``height`` as a float, or ValueError unless it is a fraction of the plot height in (0, 1]."""
+    if not _real(height) or not 0 < height <= 1:
+        raise InputError(f"height is a fraction of the plot height in (0, 1], got {height!r}")
+    return float(height)
+
+
+def check_alpha(alpha: Any) -> float:
+    """``alpha`` as a float, or ValueError unless it is an opacity in [0, 1]."""
+    if not _real(alpha) or not 0 <= alpha <= 1:
+        raise InputError(f"alpha is an opacity in [0, 1], got {alpha!r}")
+    return float(alpha)
+
+
+def _missing(value: Any) -> bool:
+    if value is None or type(value).__name__ in ("NAType", "NaTType"):
+        return True
+    return isinstance(value, float) and math.isnan(value)
+
+
+def _warn_skipped(reason: str, values: list[Any]) -> None:
+    if values:
+        shown = ", ".join(repr(v) for v in values[:10]) + (f" and {len(values) - 10} more" if len(values) > 10 else "")
+        warn(f"skipped {len(values)} point(s) {reason}: {shown}")
+
+
+def place(
+    x: Any,
+    y: Any,
+    teams: Any,
+    *,
+    league: str,
+    season: Any = None,
+    kind: str = "logo",
+    variant: str = "default",
+    id_system: str = "auto",
+    strict: bool = False,
+    _warn: bool = True,
+) -> list[Placement]:
+    """The marks to draw for each (x, y, team), in input order, skipping (with one warning per reason) the points
+    whose team is unknown, whose x or y is missing, or that have no mark.
+
+    ``x``, ``y`` and ``teams`` are read positionally (a pandas index is ignored). For ``kind="headshot"``, ``teams``
+    holds player ids and ``id_system`` must be ``"espn"`` or ``"gsis"`` (as in ``headshot_url``); otherwise
+    ``strict=True`` raises UnresolvedTeamError for a team that does not resolve, as ``resolve`` does. ``_warn=False``
+    skips the same points without warning, for an adapter that already warned for them (no process-wide warning
+    filter is touched, so it is thread-safe).
+    """
+    skipped = _warn_skipped if _warn else lambda reason, values: None
+    if kind not in KINDS:
+        raise InputError(f"kind must be one of {KINDS}, got {kind!r}")
+    xs, _ = _unpack(x)
+    ys, _ = _unpack(y)
+    ts, _ = _unpack(teams)
+    if not len(xs) == len(ys) == len(ts):
+        raise ValueError(f"x, y and teams must have the same length, got {len(xs)}, {len(ys)} and {len(ts)}")
+    out: list[Placement] = []
+    missing_xy: list[Any] = []
+    if kind == "headshot":
+        no_image: list[Any] = []
+        for xi, yi, pid in zip(xs, ys, ts, strict=True):
+            if _missing(pid):
+                continue
+            if _missing(xi) or _missing(yi):
+                missing_xy.append(pid)
+                continue
+            # id_system is a team or a headshot id system by kind; the callee validates it
+            url = headshot_url(pid, league, id_system=cast("HeadshotIdSystem", id_system))
+            if url is None:
+                no_image.append(pid)
+                continue
+            # the id the URL was built from: headshot_url reads an espn id through norm_value, so an id that went
+            # through a float ("3139477.0") is 3139477; gsis ids are looked up as given
+            key = norm_value(pid) if id_system == "espn" else None
+            out.append(Placement(key or str(pid).strip(), xi, yi, url, None, None))
+        skipped("with no headshot", no_image)
+    else:
+        seasons = _seasons(season, len(ts))
+        if _warn or strict:  # one warning for unknown values, or the strict error
+            ids = resolve(ts, league, season=seasons, id_system=cast("IdSystem", id_system), strict=strict)
+        else:
+            ids, _ = _resolve_ids(ts, league, seasons, id_system)
+        rows: dict[tuple[str, int | None], dict[str, Any] | None] = {}
+        no_mark: list[Any] = []
+        for xi, yi, raw, team_id, s in zip(xs, ys, ts, ids, seasons, strict=True):
+            if team_id is None:
+                continue  # unknown or null: the resolver already warned
+            if _missing(xi) or _missing(yi):
+                missing_xy.append(raw)
+                continue
+            if (team_id, s) not in rows:
+                rows[(team_id, s)] = select_mark(team_id, league, s, variant, kind)
+            row = rows[(team_id, s)]
+            if row is None:
+                no_mark.append(raw)
+                continue
+            w, h = row.get("width"), row.get("height")
+            aspect = float(w) / float(h) if w and h else None
+            out.append(Placement(team_id, xi, yi, str(row["archive_url"]), aspect, row))
+        skipped(f"with no {kind} archived", no_mark)
+    skipped("with a missing x or y", missing_xy)
+    return out
+
+
+def place_images(x: Any, y: Any, paths: Any, *, _warn: bool = True) -> list[Placement]:
+    """``place`` for arbitrary images: one Placement per (x, y, path), keyed by the path (a local file or URL).
+
+    A null path is skipped silently (as a null team is); a missing x or y is skipped with one warning (none with
+    ``_warn=False``, as ``place``).
+    """
+    paths = os.fspath(paths) if isinstance(paths, os.PathLike) else paths  # one pathlib.Path is one point
+    xs, ys, ps = _unpack(x)[0], _unpack(y)[0], _unpack(paths)[0]
+    if not len(xs) == len(ys) == len(ps):
+        raise ValueError(f"x, y and paths must have the same length, got {len(xs)}, {len(ys)} and {len(ps)}")
+    out: list[Placement] = []
+    missing_xy: list[Any] = []
+    for xi, yi, path in zip(xs, ys, ps, strict=True):
+        if _missing(path):
+            continue
+        if _missing(xi) or _missing(yi):
+            missing_xy.append(path)
+            continue
+        out.append(Placement(str(path), xi, yi, str(path), None, None))
+    if _warn:
+        _warn_skipped("with a missing x or y", missing_xy)
+    return out