sdvplot 0.1.0__py3-none-any.whl

sdvplot/_tiers.py

@@ -0,0 +1,135 @@
+"""team_tiers' data preparation and look, ported from sdvplotR ``sdv_team_tiers()``: the matplotlib and plotnine
+adapters only draw what ``prepare()`` returns, so ranking, tier lines, labels and limits have one implementation."""
+
+from __future__ import annotations
+
+import textwrap
+from collections import Counter
+from dataclasses import dataclass
+from typing import Any, Literal
+
+import narwhals as nw
+
+from sdvplot._index import teams as teams_index
+from sdvplot._placement import _missing, _real, _warn_skipped, check_alpha, check_height
+from sdvplot._resolve import _unpack, resolve
+
+BG, LINES, MUTED = "#1e1e1e", "#e0e0e0", "#8e8e93"  # sdvplotR's dark theme: background, tier lines, subtitle/caption
+# theme -> (background, tier lines, title and labels, subtitle and caption). "light" is sdvplot's: dark logos (Ohio
+# State, Texas A&M, Penn State) vanish on sdvplotR's dark background
+THEMES: dict[str, tuple[str, str, str, str]] = {
+    "dark": (BG, LINES, "#ffffff", MUTED),
+    "light": ("#ffffff", "#3a3a3c", "#1e1e1e", "#636366"),
+}
+SUBTITLE = "created with the #sdvplot Tiermaker"
+TIER_DESC = {1: "Elite", 2: "Very Good", 3: "Medium", 4: "Bad", 5: "What are they doing?", 6: "", 7: ""}
+# About the largest logo height (a fraction of the panel height) at which 32 square logos in 5 tiers (7, 7, 6, 6,
+# 6) neither overlap nor leave the panel at matplotlib's and plotnine's default 6.4 x 4.8 in figure; it stands in for
+# sdvplotR's width = 0.075 npc. tests/test_team_tiers.py measures it.
+DEFAULT_HEIGHT = 0.1
+
+
+@dataclass(frozen=True)
+class Tiers:
+    """What a tier plot draws: one entry per resolved team in x/y/team_ids/labels, then the axes and titles."""
+
+    x: list[Any]  # tier_rank
+    y: list[Any]  # tier_no
+    team_ids: list[str]
+    labels: list[str]  # the team's abbreviation (else the value given), which devel=True draws
+    lines: list[float]  # the tier separators, at tier +- 0.5
+    breaks: list[Any]  # the tiers, top (smallest tier_no) first
+    break_labels: list[str]
+    xlim: tuple[float, float]
+    ylim: tuple[float, float]  # (top, bottom) in tier_no units
+    title: str
+    subtitle: str | None
+    caption: str | None
+    height: float
+    alpha: float
+    bg: str  # the theme's colors (THEMES)
+    line_color: str
+    text: str
+    muted: str
+
+
+def _wrap(text: str) -> str:
+    """R's ``strwrap(text, 15)``: lines under 15 characters, a longer word kept whole."""
+    return "\n".join(textwrap.wrap(text, 14, break_long_words=False, break_on_hyphens=False))
+
+
+def prepare(
+    data: Any,
+    league: str,
+    *,
+    title: str | None = None,
+    subtitle: str | None = SUBTITLE,
+    caption: str | None = None,
+    tier_desc: dict[Any, str] | None = None,
+    presort: bool = False,
+    alpha: float = 0.8,
+    height: float | None = None,
+    no_line_below_tier: Any = None,
+    theme: Literal["dark", "light"] = "dark",
+) -> Tiers:
+    """Validate ``data`` and compute everything a tier plot draws (see the adapters' ``team_tiers``)."""
+    if theme not in THEMES:
+        raise ValueError(f"theme must be one of {sorted(THEMES)}, got {theme!r}")
+    frame = nw.from_native(data, eager_only=True)  # TypeError unless a pandas/polars (narwhals-supported) frame
+    missing = [c for c in ("tier_no", "team") if c not in frame.columns]
+    if missing:
+        raise ValueError(f"data must have the columns tier_no and team; missing {', '.join(missing)}")
+    h = DEFAULT_HEIGHT if height is None else check_height(height)
+    a = check_alpha(alpha)
+    tiers, teams = frame["tier_no"].to_list(), frame["team"].to_list()
+    # a pandas column with a NaN is float: 1.0 back to 1, so tier_desc's R-style "1" keys (and the ticks) match
+    tiers = [int(t) if isinstance(t, float) and t.is_integer() else t for t in tiers]
+    given = frame["tier_rank"].to_list() if "tier_rank" in frame.columns and not presort else None
+
+    absent = {i for i, t in enumerate(tiers) if _missing(t) or (given is not None and _missing(given[i]))}
+    _warn_skipped("with a missing tier_no or tier_rank", [teams[i] for i in sorted(absent)])
+    rows = [i for i in range(len(tiers)) if i not in absent]
+    if not rows:
+        raise ValueError("data has no rows with a tier_no")
+    if not all(_real(tiers[i]) and (given is None or _real(given[i])) for i in rows):
+        raise TypeError("tier_no and tier_rank must hold numbers (tier 1 is the top tier)")
+    if presort:  # sdvplotR: arrange(tier_no, team), then rank within the tier
+        rows.sort(key=lambda i: (tiers[i], _missing(teams[i]), str(teams[i])))  # a missing team last, as R's NA
+    if given is None:
+        seen: Counter[Any] = Counter()
+        ranks = {}
+        for i in rows:
+            seen[tiers[i]] += 1
+            ranks[i] = seen[tiers[i]]
+    else:
+        ranks = {i: given[i] for i in rows}
+
+    # Rank first, then resolve, as sdvplotR does: an unknown team keeps its slot (and the x range) but draws nothing.
+    ids = resolve([teams[i] for i in rows], league)
+    kept = [(i, team_id) for i, team_id in zip(rows, ids, strict=True) if team_id is not None]
+    abbr = dict(teams_index(league).select("team_id", "abbr").iter_rows())  # devel draws it, as sdvplotR does
+    levels = sorted({tiers[i] for i in rows})
+    skip = set(_unpack(no_line_below_tier)[0]) if no_line_below_tier is not None else set()
+    desc: dict[Any, str] = TIER_DESC if tier_desc is None else tier_desc
+    lo, hi = min(ranks.values()), max(ranks.values())
+    pad = 0.5 if lo == hi else 0.05 * (hi - lo)  # a ggplot continuous scale's default expansion
+    return Tiers(
+        x=[ranks[i] for i, _ in kept],
+        y=[tiers[i] for i, _ in kept],
+        team_ids=[team_id for _, team_id in kept],
+        labels=[abbr.get(team_id) or str(teams[i]) for i, team_id in kept],
+        lines=[levels[0] - 0.5] + [t + 0.5 for t in levels if t not in skip],
+        breaks=levels,
+        break_labels=[_wrap(desc.get(t, desc.get(str(t), ""))) for t in levels],
+        xlim=(lo - pad, hi + pad),
+        ylim=(levels[0] - 0.6, levels[-1] + 0.6),  # +- 0.5 around the tiers, plus sdvplotR's expansion(add = 0.1)
+        title=f"{league.upper()} Team Tiers" if title is None else title,
+        subtitle=subtitle,
+        caption=caption,
+        height=h,
+        alpha=a,
+        bg=THEMES[theme][0],
+        line_color=THEMES[theme][1],
+        text=THEMES[theme][2],
+        muted=THEMES[theme][3],
+    )

sdvplot/_types.py

@@ -0,0 +1,38 @@
+"""The closed vocabularies of sdvplot's arguments, as ``Literal`` types a type checker can check.
+
+An alias exists only where the runtime accepts exactly that set of strings; ``tests/test_types.py`` keeps each one
+equal to the set the code validates against. Two vocabularies stay ``str`` because they are open: ``league`` (the
+leagues come from the bundled team index, which grows with each release) and ``variant`` (the names come from the logo
+archive's manifest; "default" and "dark" always work).
+"""
+
+from typing import Literal
+
+# resolve()'s id_system: "auto", then _resolve.PRIORITY in order, then _resolve.EXPLICIT_ONLY
+IdSystem = Literal[
+    "auto",
+    "team_id",
+    "espn",
+    "espn_abbr",
+    "nhl",
+    "nflverse",
+    "mlbstats",
+    "nba_api",
+    "hockeytech",
+    "ncaa",
+    "pff",
+    "cricinfo",
+    "cfbd",
+    "bref",
+    "sportsipy",
+    "fangraphs",
+    "sdvplotr",
+    "name",
+    "nhl_id",
+]
+# headshot_url()'s id_system: ESPN athlete ids (any ESPN league) or nflverse gsis ids (nfl)
+HeadshotIdSystem = Literal["espn", "gsis"]
+# palette()'s color slot: _colors._COLUMNS
+Which = Literal["primary", "secondary"]
+# logo_url() and logo_image()'s mark: _marks.MARK_TYPES
+MarkType = Literal["logo", "wordmark"]

sdvplot/_versions.py

@@ -0,0 +1,30 @@
+"""What a bug report needs: package version, bundled-index version, and the cached manifest's date."""
+
+from __future__ import annotations
+
+from sdvplot._cache import read_meta
+from sdvplot._index import index_version
+
+
+def versions() -> dict[str, str | None]:
+    """What a bug report needs: the package version, the bundled-index version, and the cached manifest's date.
+
+    Returns:
+        dict[str, str | None]: Keys ``sdvplot``, ``index`` and ``manifest_last_modified`` (None until the manifest has
+        been downloaded).
+
+    Example:
+        ::
+
+            import sdvplot
+
+            sdvplot.versions()["sdvplot"]   # '0.1.0'
+
+    See Also:
+        sdvplotR: https://sdvplotR.sportsdataverse.org/ ;
+        sdv-py: https://py.sportsdataverse.org/
+    """
+    from sdvplot import __version__
+
+    meta = read_meta("manifest/marks.csv") or {}
+    return {"sdvplot": __version__, "index": index_version(), "manifest_last_modified": meta.get("last_modified")}

sdvplot/_web.py

@@ -0,0 +1,61 @@
+"""What the web adapters (Plotly, Altair, Bokeh, HoloViews, Folium, pygal) share: image sources and aspect ratios.
+
+Browsers load images themselves, so a web adapter hands over the mark's ``archive_url`` (immutable, content-addressed),
+or with ``embed=True`` a ``data:`` URI of the cached bytes, for HTML that renders offline and for static export.
+"""
+
+from __future__ import annotations
+
+import base64
+from urllib.parse import quote
+
+from PIL import Image
+
+from sdvplot._images import mark_file, url_file
+from sdvplot._placement import Placement
+
+# ESPN's combiner serves full headshots at 600x436 (measured 2026-10-04 for NFL, NBA and MLB ids); checked by
+# tests/test_web_live.py.
+HEADSHOT_ASPECT = 600 / 436
+_URL_PUNCTUATION = "-._~:/?#[]@!$&()*+,;=%"  # SAFE_URL's characters besides letters and digits (quote keeps those)
+
+
+def aspect(p: Placement) -> float:
+    """Width / height of the placement's image: the manifest's, or HEADSHOT_ASPECT for a headshot."""
+    return p.aspect if p.aspect is not None else HEADSHOT_ASPECT
+
+
+def axis_letter(axis: str) -> str:
+    """``axis`` if it is "x" or "y", else a ValueError (the check every web adapter's axis verb starts with)."""
+    if axis not in ("x", "y"):
+        raise ValueError(f"axis must be 'x' or 'y', got {axis!r}")
+    return axis
+
+
+def image_src(p: Placement, *, embed: bool = False) -> str:
+    """The image source for a browser: ``p.url``, or with ``embed=True`` a data URI of the cached image bytes.
+
+    Embedding reads through the cache (downloading on a miss), so offline with no cached copy it raises OfflineError.
+    The URL is percent-encoded past ``SAFE_URL``'s characters, a no-op on the URLs the manifest and player table let
+    through, so an unvalidated one still cannot close the <script> block or attribute an adapter writes it into.
+    """
+    if not embed:
+        return quote(p.url, safe=_URL_PUNCTUATION)
+    path = mark_file(p.mark) if p.mark is not None else url_file(p.url)
+    if p.mark is not None and str(p.mark["ext"]).lower() == "svg":
+        mime = "image/svg+xml"
+    else:
+        with Image.open(path) as img:
+            mime = Image.MIME.get(img.format or "", "application/octet-stream")
+    return f"data:{mime};base64,{base64.b64encode(path.read_bytes()).decode('ascii')}"
+
+
+def image_sources(placements: list[Placement], *, embed: bool = False) -> list[str]:
+    """``image_src`` for each placement, reading each distinct image once."""
+    seen: dict[str, str] = {}
+    out = []
+    for p in placements:
+        if p.url not in seen:
+            seen[p.url] = image_src(p, embed=embed)
+        out.append(seen[p.url])
+    return out