openplay 0.1.0__tar.gz

openplay-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 Noah Bair
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openplay-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: openplay
+Version: 0.1.0
+Summary: Open men's soccer event data (every pass, shot and tackle with coordinates) with xG on every shot
+Author-email: Noah Bair <noahlbair@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nlbair/openplay-py
+Project-URL: Data, https://github.com/nlbair/openplay
+Project-URL: Issues, https://github.com/nlbair/openplay-py/issues
+Keywords: soccer,football,event data,xG,sports analytics
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Intended Audience :: Science/Research
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5
+Requires-Dist: pyarrow>=10
+Dynamic: license-file
+
+# openplay (Python)
+
+Read the [openplay](https://github.com/nlbair/openplay) soccer event data in Python. It covers 26,536 men's matches with every pass, shot and tackle, plus xG on every shot. Files download once from the data release, are checked against published SHA-256 checksums, and are cached on your computer.
+
+The R package [openplay-r](https://github.com/nlbair/openplay-r) has the same functions and returns the same numbers.
+
+## Install
+
+```bash
+pip install openplay
+```
+
+Or the latest version from GitHub: `pip install git+https://github.com/nlbair/openplay-py`
+
+## Use
+
+```python
+import openplay as op
+
+op.competitions()
+m = op.matches("eng", "2024/25")
+e = op.events("eng", "2024/25", columns=["match_id", "type", "x", "y", "player"])
+s = op.shots("eng", "2024/25")
+p = op.player_match_stats("eng", "2024/25")
+ps = op.player_season_stats("eng", "2024/25", per90=True, min_minutes=900)
+op.player_season_stats("esp", "2016/17", player="Cristiano Ronaldo")
+op.player_career("Lionel Messi")
+t = op.team_match_stats("eng", "2024/25")
+op.lineups("ucl", "2425")
+op.players()
+op.teams()
+op.coverage_report("nla")
+op.known_gaps()
+op.data_issues()
+```
+
+- **Seasons.** You can write a season as `"2024/25"`, `"2024-25"` or `"2425"`. Tournaments use the year, for example `"2022"`.
+- **Players.** `player=` takes the full name. Capitals and accents don't matter (`"kylian mbappe"` works). A misspelling gets a warning like *No player named 'Lionel Messsi'. Did you mean: Lionel Messi?* If two players share a name, use `player_id=`. The functions that take `player=` are `player_season_stats`, `player_match_stats`, `player_career`, `shots`, `lineups` and `events`.
+- **Gaps.** When a request includes matches that have no event data, or have a known data issue, you get a `CoverageWarning`. It never stops your code with an error.
+- **Local copy.** If you already have the files on disk, `op.set_data_dir(path)` reads them from there. Setting the `OPENPLAY_DATA_DIR` environment variable does the same.
+- **Cache.** Downloads are kept in `op.cache_dir()`. `op.clear_cache()` frees the space.
+
+## Functions
+
+| Function | Returns |
+|---|---|
+| `competitions()` | one row per competition |
+| `matches(comp, season)` | one row per match |
+| `events(comp, season, columns)` | one row per event (`comp` is required) |
+| `shots(comp, season)` | one row per shot, with xG and the player who set it up |
+| `lineups(comp, season)` | one row per player in each matchday squad |
+| `player_match_stats(comp, season)` | one row per player per match played, about 80 counts |
+| `player_season_stats(comp, season, per90, min_minutes, player)` | season totals or per-90 numbers per player and team |
+| `player_career(player, per90)` | one player's whole career: one row per competition, season and team |
+| `suggest_players(name)` | the closest full names to what was typed |
+| `team_match_stats(comp, season)` | one row per team per match |
+| `players()`, `teams()` | one row per player or team |
+| `formations(comp, season)`, `cards(comp, season)` | formation spells and cards |
+| `coverage_report(comp, season)`, `known_gaps()`, `data_issues()` | what's covered and what's missing |
+
+## Tests
+
+The tests run on a small sample dataset (every UEFA Super Cup plus Nations League A 2022/23), with no download needed:
+
+```bash
+python -m unittest discover -s tests
+```
+
+## License
+
+Code: MIT. Data: CC-BY 4.0; credit "openplay (Noah Bair)".

openplay-0.1.0/README.md

@@ -0,0 +1,71 @@
+# openplay (Python)
+
+Read the [openplay](https://github.com/nlbair/openplay) soccer event data in Python. It covers 26,536 men's matches with every pass, shot and tackle, plus xG on every shot. Files download once from the data release, are checked against published SHA-256 checksums, and are cached on your computer.
+
+The R package [openplay-r](https://github.com/nlbair/openplay-r) has the same functions and returns the same numbers.
+
+## Install
+
+```bash
+pip install openplay
+```
+
+Or the latest version from GitHub: `pip install git+https://github.com/nlbair/openplay-py`
+
+## Use
+
+```python
+import openplay as op
+
+op.competitions()
+m = op.matches("eng", "2024/25")
+e = op.events("eng", "2024/25", columns=["match_id", "type", "x", "y", "player"])
+s = op.shots("eng", "2024/25")
+p = op.player_match_stats("eng", "2024/25")
+ps = op.player_season_stats("eng", "2024/25", per90=True, min_minutes=900)
+op.player_season_stats("esp", "2016/17", player="Cristiano Ronaldo")
+op.player_career("Lionel Messi")
+t = op.team_match_stats("eng", "2024/25")
+op.lineups("ucl", "2425")
+op.players()
+op.teams()
+op.coverage_report("nla")
+op.known_gaps()
+op.data_issues()
+```
+
+- **Seasons.** You can write a season as `"2024/25"`, `"2024-25"` or `"2425"`. Tournaments use the year, for example `"2022"`.
+- **Players.** `player=` takes the full name. Capitals and accents don't matter (`"kylian mbappe"` works). A misspelling gets a warning like *No player named 'Lionel Messsi'. Did you mean: Lionel Messi?* If two players share a name, use `player_id=`. The functions that take `player=` are `player_season_stats`, `player_match_stats`, `player_career`, `shots`, `lineups` and `events`.
+- **Gaps.** When a request includes matches that have no event data, or have a known data issue, you get a `CoverageWarning`. It never stops your code with an error.
+- **Local copy.** If you already have the files on disk, `op.set_data_dir(path)` reads them from there. Setting the `OPENPLAY_DATA_DIR` environment variable does the same.
+- **Cache.** Downloads are kept in `op.cache_dir()`. `op.clear_cache()` frees the space.
+
+## Functions
+
+| Function | Returns |
+|---|---|
+| `competitions()` | one row per competition |
+| `matches(comp, season)` | one row per match |
+| `events(comp, season, columns)` | one row per event (`comp` is required) |
+| `shots(comp, season)` | one row per shot, with xG and the player who set it up |
+| `lineups(comp, season)` | one row per player in each matchday squad |
+| `player_match_stats(comp, season)` | one row per player per match played, about 80 counts |
+| `player_season_stats(comp, season, per90, min_minutes, player)` | season totals or per-90 numbers per player and team |
+| `player_career(player, per90)` | one player's whole career: one row per competition, season and team |
+| `suggest_players(name)` | the closest full names to what was typed |
+| `team_match_stats(comp, season)` | one row per team per match |
+| `players()`, `teams()` | one row per player or team |
+| `formations(comp, season)`, `cards(comp, season)` | formation spells and cards |
+| `coverage_report(comp, season)`, `known_gaps()`, `data_issues()` | what's covered and what's missing |
+
+## Tests
+
+The tests run on a small sample dataset (every UEFA Super Cup plus Nations League A 2022/23), with no download needed:
+
+```bash
+python -m unittest discover -s tests
+```
+
+## License
+
+Code: MIT. Data: CC-BY 4.0; credit "openplay (Noah Bair)".

openplay-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openplay"
+version = "0.1.0"
+description = "Open men's soccer event data (every pass, shot and tackle with coordinates) with xG on every shot"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Noah Bair", email = "noahlbair@gmail.com"}]
+requires-python = ">=3.9"
+dependencies = ["pandas>=1.5", "pyarrow>=10"]
+keywords = ["soccer", "football", "event data", "xG", "sports analytics"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+    "Intended Audience :: Science/Research",
+    "Development Status :: 4 - Beta",
+]
+
+[project.urls]
+Homepage = "https://github.com/nlbair/openplay-py"
+Data = "https://github.com/nlbair/openplay"
+Issues = "https://github.com/nlbair/openplay-py/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

openplay-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

openplay-0.1.0/src/openplay/__init__.py

@@ -0,0 +1,34 @@
+"""openplay: open men's soccer event data with xG on every shot."""
+
+from ._data import cache_dir, clear_cache, set_data_dir, DATA_REPO, DATA_TAG
+from .api import (
+    CoverageWarning,
+    PlayerWarning,
+    cards,
+    competitions,
+    coverage_report,
+    data_issues,
+    events,
+    formations,
+    known_gaps,
+    lineups,
+    matches,
+    name_key,
+    normalize_season,
+    player_career,
+    player_match_stats,
+    player_season_stats,
+    players,
+    shots,
+    suggest_players,
+    team_match_stats,
+    teams,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CoverageWarning", "PlayerWarning", "name_key", "player_career", "suggest_players", "cache_dir", "cards", "clear_cache", "competitions", "coverage_report", "data_issues", "events",
+    "formations", "known_gaps", "lineups", "matches", "normalize_season", "player_match_stats", "player_season_stats", "players", "set_data_dir",
+    "shots", "team_match_stats", "teams", "DATA_REPO", "DATA_TAG", "__version__",
+]

openplay-0.1.0/src/openplay/_data.py

@@ -0,0 +1,147 @@
+import hashlib
+import json
+import os
+import shutil
+import tempfile
+import urllib.request
+from pathlib import Path
+
+DATA_REPO = os.environ.get("OPENPLAY_REPO", "nlbair/openplay")
+DATA_TAG = os.environ.get("OPENPLAY_DATA_TAG", "data-v0.1.0")
+CHECKSUM_FILE = "checksums.json"
+
+_state = {"data_dir": None, "checksums": None}
+
+
+def set_data_dir(path):
+    """Read tables from a local folder instead of downloading them.
+
+    The folder must hold the release files side by side, for example
+    ``matches.parquet`` and ``events_eng_2425.parquet``. Pass ``None`` to go
+    back to downloading from the GitHub release.
+    """
+    _state["data_dir"] = None if path is None else Path(path)
+    _state["checksums"] = None
+
+
+def data_dir():
+    if _state["data_dir"] is not None:
+        return _state["data_dir"]
+    env = os.environ.get("OPENPLAY_DATA_DIR")
+    return Path(env) if env else None
+
+
+def cache_dir():
+    """Folder where downloaded files are kept between sessions."""
+    env = os.environ.get("OPENPLAY_CACHE_DIR")
+    if env:
+        base = Path(env)
+    elif os.name == "nt":
+        base = Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local")) / "openplay" / "cache"
+    else:
+        base = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) / "openplay"
+    path = base / DATA_TAG
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def clear_cache():
+    """Delete every downloaded file for the current data release."""
+    path = cache_dir()
+    shutil.rmtree(path, ignore_errors=True)
+    _state["checksums"] = None
+
+
+def _token():
+    return os.environ.get("OPENPLAY_GITHUB_TOKEN") or os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+
+
+def _request(url, accept=None):
+    req = urllib.request.Request(url, headers={"User-Agent": "openplay-python"})
+    token = _token()
+    if token:
+        req.add_header("Authorization", "Bearer " + token)
+    if accept:
+        req.add_header("Accept", accept)
+    return urllib.request.urlopen(req, timeout=120)
+
+
+def _asset_urls():
+    if "assets" in _state and _state.get("assets_tag") == DATA_TAG:
+        return _state["assets"]
+    api = f"https://api.github.com/repos/{DATA_REPO}/releases/tags/{DATA_TAG}"
+    with _request(api, accept="application/vnd.github+json") as r:
+        release = json.load(r)
+    _state["assets"] = {a["name"]: a["url"] for a in release.get("assets", [])}
+    _state["assets_tag"] = DATA_TAG
+    return _state["assets"]
+
+
+def _download(name, dest):
+    if _token():
+        urls = _asset_urls()
+        if name not in urls:
+            raise FileNotFoundError(f"{name} is not in release {DATA_TAG} of {DATA_REPO}")
+        resp = _request(urls[name], accept="application/octet-stream")
+    else:
+        resp = _request(f"https://github.com/{DATA_REPO}/releases/download/{DATA_TAG}/{name}")
+    fd, tmp = tempfile.mkstemp(dir=dest.parent, suffix=".part")
+    try:
+        with os.fdopen(fd, "wb") as fh, resp:
+            shutil.copyfileobj(resp, fh, length=1 << 20)
+        os.replace(tmp, dest)
+    finally:
+        if os.path.exists(tmp):
+            os.remove(tmp)
+
+
+def _sha256(path):
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def checksums():
+    if _state["checksums"] is not None:
+        return _state["checksums"]
+    local = data_dir()
+    if local is not None:
+        path = local / CHECKSUM_FILE
+        _state["checksums"] = json.loads(path.read_text()) if path.exists() else {}
+        return _state["checksums"]
+    path = cache_dir() / CHECKSUM_FILE
+    if not path.exists():
+        _download(CHECKSUM_FILE, path)
+    _state["checksums"] = json.loads(path.read_text())
+    return _state["checksums"]
+
+
+def available_files():
+    local = data_dir()
+    if local is not None:
+        return sorted(p.name for p in local.iterdir() if p.is_file())
+    return sorted(checksums())
+
+
+def fetch(name):
+    """Return a local path to one release file, downloading it if needed."""
+    local = data_dir()
+    if local is not None:
+        path = local / name
+        if not path.exists():
+            raise FileNotFoundError(f"{name} not found in {local}")
+        return path
+    sums = checksums()
+    if name not in sums:
+        raise FileNotFoundError(f"{name} is not part of data release {DATA_TAG}")
+    path = cache_dir() / name
+    if path.exists() and _sha256(path) == sums[name]["sha256"]:
+        return path
+    _download(name, path)
+    got = _sha256(path)
+    if got != sums[name]["sha256"]:
+        path.unlink(missing_ok=True)
+        raise IOError(f"checksum mismatch for {name}; the download was removed, please try again")
+    return path

openplay-0.1.0/src/openplay/api.py

@@ -0,0 +1,374 @@
+import re
+import unicodedata
+import warnings
+
+import numpy as np
+import pandas as pd
+import pyarrow.parquet as pq
+
+from . import _data
+
+
+class CoverageWarning(UserWarning):
+    """Raised as a warning when a request touches matches with no event data."""
+
+
+class PlayerWarning(UserWarning):
+    """Raised as a warning when a player name has no exact match or matches several players."""
+
+
+_FOLD = str.maketrans({"\u00f8": "o", "\u00d8": "O", "\u0142": "l", "\u0141": "L", "\u0111": "d", "\u0110": "D", "\u00df": "ss",
+                       "\u00e6": "ae", "\u00c6": "AE", "\u0153": "oe", "\u0152": "OE", "\u0131": "i", "\u00fe": "th", "\u00de": "TH",
+                       "\u00f0": "d", "\u00d0": "D", "\u0127": "h", "\u0126": "H", "\u2019": "'", "\u2018": "'"})
+
+
+def name_key(name):
+    """Lower-case a name and strip accents, so 'Kylian Mbapp\u00e9' and 'kylian mbappe' match."""
+    s = unicodedata.normalize("NFKD", str(name).translate(_FOLD))
+    s = "".join(c for c in s if not unicodedata.combining(c))
+    return re.sub(r"\s+", " ", s).strip().lower()
+
+
+def _edit_distance(a, b):
+    prev = list(range(len(b) + 1))
+    for i, ca in enumerate(a, 1):
+        cur = [i]
+        for j, cb in enumerate(b, 1):
+            cur.append(min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (ca != cb)))
+        prev = cur
+    return prev[-1]
+
+
+def _player_keys():
+    pl = players()[["player_id", "player"]].dropna()
+    return pl.assign(key=pl["player"].astype(str).map(name_key))
+
+
+def suggest_players(name, n=5):
+    """Full names closest to ``name``: small spelling mistakes, or names that contain every word typed."""
+    key = name_key(name)
+    pl = _player_keys().drop_duplicates("key")
+    limit = max(2, len(key) // 4)
+    words = set(key.split())
+    hits = []
+    for k, full in zip(pl["key"], pl["player"]):
+        partial = bool(words) and words <= set(k.split())
+        if partial or abs(len(k) - len(key)) <= limit:
+            d = _edit_distance(key, k)
+            if partial or d <= limit:
+                hits.append((0 if partial else 1, d, k, str(full)))
+    hits.sort()
+    return [h[3] for h in hits[:n]]
+
+
+def _player_ids(player, player_id):
+    if player_id is not None:
+        return {int(x) for x in _as_list(player_id)}
+    if player is None:
+        return None
+    pl = _player_keys()
+    ids = set()
+    for name in _as_list(player):
+        found = pl[pl["key"] == name_key(name)]
+        if found.empty:
+            sug = suggest_players(name)
+            if sug:
+                msg = f"No player named '{name}'. Did you mean: " + ", ".join(sug) + "?"
+            else:
+                msg = f"No player named '{name}'. Check the spelling (use the full name) or search players()."
+            warnings.warn(msg, PlayerWarning, stacklevel=3)
+            continue
+        found_ids = sorted(int(i) for i in found["player_id"].unique())
+        if len(found_ids) > 1:
+            warnings.warn(f"{len(found_ids)} players are named '{name}' (player_id " + ", ".join(str(i) for i in found_ids) + "); all are included. Use player_id= to pick one.", PlayerWarning, stacklevel=3)
+        ids |= set(found_ids)
+    return ids
+
+
+def _keep_players(df, ids, col="player_id"):
+    if ids is None:
+        return df
+    out = df[df[col].isin(ids)].reset_index(drop=True)
+    if ids and out.empty:
+        pl = players()
+        names = ", ".join(f"{n} (player_id {int(i)})" for i, n in zip(pl["player_id"], pl["player"]) if int(i) in ids)
+        warnings.warn(f"Found {names}, but there are no rows for them in this selection (they may not have played in this competition or season); try player_career().", PlayerWarning, stacklevel=3)
+    return out
+
+
+def _as_list(x):
+    if x is None:
+        return None
+    if isinstance(x, (list, tuple, set, pd.Series)):
+        return [str(v) for v in x]
+    return [str(x)]
+
+
+def normalize_season(season):
+    """Turn '2024/25', '2024-25', '2024/2025' or '2425' into the stored form '2425'.
+
+    Tournament years such as '2022' are returned unchanged.
+    """
+    s = str(season).strip()
+    m = re.fullmatch(r"(\d{4})\s*[/-]\s*(\d{2}|\d{4})", s)
+    if m:
+        return m.group(1)[2:] + m.group(2)[-2:]
+    return s
+
+
+def _seasons(season):
+    v = _as_list(season)
+    return None if v is None else [normalize_season(x) for x in v]
+
+
+def _read_table(name, comp=None, season=None, columns=None):
+    df = pd.read_parquet(_data.fetch(name + ".parquet"), columns=columns)
+    comps, seasons = _as_list(comp), _seasons(season)
+    if comps is not None and "comp" in df.columns:
+        df = df[df["comp"].astype(str).isin(comps)]
+    if seasons is not None and "season" in df.columns:
+        df = df[df["season"].astype(str).isin(seasons)]
+    return df.reset_index(drop=True)
+
+
+def competitions():
+    """All competitions with their names, type, seasons and whether they are in the v1 scope."""
+    return _read_table("competitions")
+
+
+def coverage_report(comp=None, season=None, warn=True):
+    """Matches played, matches with event data, and known gaps per competition-season.
+
+    Never raises for gaps. With ``warn=True`` it issues a ``CoverageWarning``
+    when the selection includes matches that have no event data or have a
+    known data issue.
+    """
+    cov = pd.read_csv(_data.fetch("coverage.csv"), dtype={"season": str})
+    comps, seasons = _as_list(comp), _seasons(season)
+    if comps is not None:
+        cov = cov[cov["comp"].isin(comps)]
+    if seasons is not None:
+        cov = cov[cov["season"].isin(seasons)]
+    cov = cov.reset_index(drop=True)
+    if warn and len(cov):
+        gaps = int(cov["gaps"].sum())
+        issues = int(cov["matches_with_data_issues"].sum())
+        if gaps:
+            warnings.warn(f"{gaps} played match(es) in this selection have no event data; see known_gaps()", CoverageWarning, stacklevel=2)
+        if issues:
+            warnings.warn(f"{issues} match(es) in this selection have known data issues; see data_issues()", CoverageWarning, stacklevel=2)
+    return cov
+
+
+def _check(comp, season, ids=None):
+    if ids is not None and not ids:
+        return
+    try:
+        coverage_report(comp, season, warn=True)
+    except Exception:
+        pass
+
+
+def known_gaps(comp=None, season=None):
+    """Played matches that have no event data, with date, teams and score where known."""
+    df = pd.read_csv(_data.fetch("known_gaps.csv"), dtype={"season": str})
+    comps, seasons = _as_list(comp), _seasons(season)
+    if comps is not None:
+        df = df[df["comp"].isin(comps)]
+    if seasons is not None:
+        df = df[df["season"].isin(seasons)]
+    return df.reset_index(drop=True)
+
+
+def data_issues(comp=None, season=None):
+    """Matches whose events are partial, whose lineups are incomplete, or whose events disagree with the official score."""
+    df = pd.read_csv(_data.fetch("data_issues.csv"), dtype={"season": str})
+    comps, seasons = _as_list(comp), _seasons(season)
+    if comps is not None:
+        df = df[df["comp"].isin(comps)]
+    if seasons is not None:
+        df = df[df["season"].isin(seasons)]
+    return df.reset_index(drop=True)
+
+
+def matches(comp=None, season=None, in_scope_only=False):
+    """One row per match with teams, scores, venue, referee, managers and formations."""
+    df = _read_table("matches", comp, season)
+    if in_scope_only:
+        df = df[df["in_v1_scope"]].reset_index(drop=True)
+    _check(comp, season)
+    return df
+
+
+def events(comp, season=None, columns=None, player=None, player_id=None):
+    """Every event for one or more competition-seasons.
+
+    ``comp`` is required because the full dataset has about 42 million rows.
+    ``season`` may be one season, a list, or ``None`` for every season of the
+    competition. ``columns`` limits the columns read, which saves memory.
+    ``player`` keeps one player's events (full name; capitals and accents are ignored).
+    """
+    ids = _player_ids(player, player_id)
+    if ids is not None and columns is not None and "player_id" not in columns:
+        columns = list(columns) + ["player_id"]
+    comps = _as_list(comp)
+    if not comps:
+        raise ValueError("events() needs at least one competition code, for example events('eng', '2425')")
+    seasons = _seasons(season)
+    names = []
+    for f in _data.available_files():
+        m = re.fullmatch(r"events_([a-z]+)_(\d+)\.parquet", f)
+        if m and m.group(1) in comps and (seasons is None or m.group(2) in seasons):
+            names.append(f)
+    if not names:
+        raise ValueError(f"no event files for comp={comps} season={seasons}; see competitions() for what exists")
+    frames = []
+    for n in sorted(names):
+        path = _data.fetch(n)
+        cols = None
+        if columns is not None:
+            have = set(pq.read_schema(path).names)
+            cols = [c for c in columns if c in have]
+        frames.append(_keep_players(pd.read_parquet(path, columns=cols), ids))
+    _check(comp, season, ids)
+    if len(frames) == 1:
+        return frames[0]
+    return pd.concat(frames, ignore_index=True, sort=False)
+
+
+def shots(comp=None, season=None, player=None, player_id=None):
+    """Every shot with location, body part, situation, outcome, xG and the player who set it up.
+
+    ``player`` keeps one player's shots (full name; capitals and accents are ignored).
+    """
+    ids = _player_ids(player, player_id)
+    df = _keep_players(_read_table("shots", comp, season), ids)
+    _check(comp, season, ids)
+    return df
+
+
+def lineups(comp=None, season=None, player=None, player_id=None):
+    """Every player in every matchday squad: starter or sub, minutes, position.
+
+    ``player`` keeps one player's rows (full name; capitals and accents are ignored).
+    """
+    ids = _player_ids(player, player_id)
+    df = _keep_players(_read_table("lineups", comp, season), ids)
+    _check(comp, season, ids)
+    return df
+
+
+def player_match_stats(comp=None, season=None, player=None, player_id=None):
+    """One row per player per match played, with about 80 counts built from the events.
+
+    ``player`` keeps one player's matches (full name; capitals and accents are ignored).
+    """
+    ids = _player_ids(player, player_id)
+    df = _keep_players(_read_table("player_match_stats", comp, season), ids)
+    _check(comp, season, ids)
+    return df
+
+
+def team_match_stats(comp=None, season=None):
+    """One row per team per match, with the same counts plus goals, xG and shots against."""
+    df = _read_table("team_match_stats", comp, season)
+    _check(comp, season)
+    return df
+
+
+def players():
+    """One row per player: name, height, weight, estimated birth year, main position, appearances and minutes."""
+    return _read_table("players")
+
+
+def teams():
+    """One row per team: name, country, club or national team, and competitions played."""
+    return _read_table("teams")
+
+
+def formations(comp=None, season=None):
+    """Every formation a team used in a match, with the minutes it was used."""
+    df = _read_table("formations")
+    if comp is not None or season is not None:
+        ids = matches(comp, season)["match_id"]
+        df = df[df["match_id"].isin(ids)].reset_index(drop=True)
+    return df
+
+
+def cards(comp=None, season=None):
+    """Every card shown, with player, team and minute."""
+    df = _read_table("cards")
+    if comp is not None or season is not None:
+        ids = matches(comp, season)["match_id"]
+        df = df[df["match_id"].isin(ids)].reset_index(drop=True)
+    return df
+
+
+_ID_COLS = ["comp", "season", "player_id", "player", "team_id", "team"]
+_NOT_SUMMED = {"match_id", "date", "opponent_id", "opponent", "side", "position", "is_starter", "played", "in_lineup", "minute_on", "minute_off", "pass_pct"}
+
+
+def player_season_stats(comp=None, season=None, per90=False, min_minutes=0, player=None, player_id=None):
+    """Season totals per player and team, built from player_match_stats.
+
+    A player who moved clubs mid-season gets one row per team. With
+    ``per90=True`` every count is divided by minutes played and multiplied by
+    90. ``min_minutes`` drops rows below that many minutes. ``player`` keeps
+    one player (full name; capitals and accents are ignored).
+    """
+    ids = _player_ids(player, player_id)
+    p = player_match_stats(comp, season, player_id=None if ids is None else sorted(ids))
+    p = p.assign(comp=p["comp"].astype(str), season=p["season"].astype(str))
+    p = p.sort_values(["comp", "season", "player_id", "team_id", "date", "match_id"], kind="mergesort")
+    p["is_starter"] = p["is_starter"].fillna(False).astype(bool)
+    counts = [c for c in p.columns if c not in _ID_COLS and c not in _NOT_SUMMED and c != "minutes_played" and pd.api.types.is_numeric_dtype(p[c])]
+    p[counts] = p[counts].astype("float64")
+    g = p.groupby(["comp", "season", "player_id", "team_id"], sort=True)
+    out = g[counts].sum()
+    out.insert(0, "minutes_played", g["minutes_played"].sum())
+    out.insert(0, "starts", g["is_starter"].sum().astype("int64"))
+    out.insert(0, "matches", g["match_id"].nunique())
+    out.insert(0, "team", g["team"].last())
+    out.insert(0, "player", g["player"].last())
+    out = out.reset_index()
+    out["pass_pct"] = np.floor(1000 * out["passes_completed"] / out["passes"].where(out["passes"] > 0) + 0.5) / 10
+    out["minutes_played"] = out["minutes_played"].astype("float64")
+    out = out[out["minutes_played"] >= min_minutes].reset_index(drop=True)
+    if per90:
+        mins = out["minutes_played"].where(out["minutes_played"] > 0)
+        for c in counts:
+            out[c] = out[c].astype("float64") / mins * 90
+    for c in counts:
+        if not per90 and c not in ("xg", "npxg", "xa"):
+            out[c] = out[c].astype("int64")
+        else:
+            out[c] = out[c].astype("float64")
+    return out
+
+
+def player_career(player=None, player_id=None, per90=False):
+    """One player's whole career in the data: one row per competition, season and team, oldest first.
+
+    ``player`` is the full name (capitals and accents are ignored). A close
+    misspelling gets a "did you mean" warning and an empty result.
+    """
+    if player is None and player_id is None:
+        raise ValueError("player_career() needs a full player name or a player_id, for example player_career('Lionel Messi')")
+    ids = _player_ids(player, player_id)
+    if not ids:
+        return pd.DataFrame(columns=["player_id", "player", "comp", "season", "team_id", "team", "first_match"])
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", CoverageWarning)
+        out = player_season_stats(per90=per90, player_id=sorted(ids))
+        pm = player_match_stats(player_id=sorted(ids))
+    pm = pm.assign(comp=pm["comp"].astype(str), season=pm["season"].astype(str))
+    first = pm.groupby(["comp", "season", "player_id", "team_id"])["date"].min().rename("first_match").reset_index()
+    out = out.merge(first, on=["comp", "season", "player_id", "team_id"], how="left")
+    out = out.sort_values(["player_id", "first_match", "comp", "team_id"], kind="mergesort").reset_index(drop=True)
+    cov = coverage_report(warn=False)
+    pairs = set(zip(out["comp"], out["season"]))
+    cov = cov[[(c, x) in pairs for c, x in zip(cov["comp"], cov["season"])]]
+    if int(cov["gaps"].sum()):
+        warnings.warn(f"{int(cov['gaps'].sum())} played match(es) in this player's competition-seasons have no event data, so the totals may miss some of their matches; see known_gaps()", CoverageWarning, stacklevel=2)
+    cols = ["player_id", "player", "comp", "season", "team_id", "team", "first_match"]
+    return out[cols + [c for c in out.columns if c not in cols]]

openplay-0.1.0/src/openplay.egg-info/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: openplay
+Version: 0.1.0
+Summary: Open men's soccer event data (every pass, shot and tackle with coordinates) with xG on every shot
+Author-email: Noah Bair <noahlbair@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nlbair/openplay-py
+Project-URL: Data, https://github.com/nlbair/openplay
+Project-URL: Issues, https://github.com/nlbair/openplay-py/issues
+Keywords: soccer,football,event data,xG,sports analytics
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Intended Audience :: Science/Research
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5
+Requires-Dist: pyarrow>=10
+Dynamic: license-file
+
+# openplay (Python)
+
+Read the [openplay](https://github.com/nlbair/openplay) soccer event data in Python. It covers 26,536 men's matches with every pass, shot and tackle, plus xG on every shot. Files download once from the data release, are checked against published SHA-256 checksums, and are cached on your computer.
+
+The R package [openplay-r](https://github.com/nlbair/openplay-r) has the same functions and returns the same numbers.
+
+## Install
+
+```bash
+pip install openplay
+```
+
+Or the latest version from GitHub: `pip install git+https://github.com/nlbair/openplay-py`
+
+## Use
+
+```python
+import openplay as op
+
+op.competitions()
+m = op.matches("eng", "2024/25")
+e = op.events("eng", "2024/25", columns=["match_id", "type", "x", "y", "player"])
+s = op.shots("eng", "2024/25")
+p = op.player_match_stats("eng", "2024/25")
+ps = op.player_season_stats("eng", "2024/25", per90=True, min_minutes=900)
+op.player_season_stats("esp", "2016/17", player="Cristiano Ronaldo")
+op.player_career("Lionel Messi")
+t = op.team_match_stats("eng", "2024/25")
+op.lineups("ucl", "2425")
+op.players()
+op.teams()
+op.coverage_report("nla")
+op.known_gaps()
+op.data_issues()
+```
+
+- **Seasons.** You can write a season as `"2024/25"`, `"2024-25"` or `"2425"`. Tournaments use the year, for example `"2022"`.
+- **Players.** `player=` takes the full name. Capitals and accents don't matter (`"kylian mbappe"` works). A misspelling gets a warning like *No player named 'Lionel Messsi'. Did you mean: Lionel Messi?* If two players share a name, use `player_id=`. The functions that take `player=` are `player_season_stats`, `player_match_stats`, `player_career`, `shots`, `lineups` and `events`.
+- **Gaps.** When a request includes matches that have no event data, or have a known data issue, you get a `CoverageWarning`. It never stops your code with an error.
+- **Local copy.** If you already have the files on disk, `op.set_data_dir(path)` reads them from there. Setting the `OPENPLAY_DATA_DIR` environment variable does the same.
+- **Cache.** Downloads are kept in `op.cache_dir()`. `op.clear_cache()` frees the space.
+
+## Functions
+
+| Function | Returns |
+|---|---|
+| `competitions()` | one row per competition |
+| `matches(comp, season)` | one row per match |
+| `events(comp, season, columns)` | one row per event (`comp` is required) |
+| `shots(comp, season)` | one row per shot, with xG and the player who set it up |
+| `lineups(comp, season)` | one row per player in each matchday squad |
+| `player_match_stats(comp, season)` | one row per player per match played, about 80 counts |
+| `player_season_stats(comp, season, per90, min_minutes, player)` | season totals or per-90 numbers per player and team |
+| `player_career(player, per90)` | one player's whole career: one row per competition, season and team |
+| `suggest_players(name)` | the closest full names to what was typed |
+| `team_match_stats(comp, season)` | one row per team per match |
+| `players()`, `teams()` | one row per player or team |
+| `formations(comp, season)`, `cards(comp, season)` | formation spells and cards |
+| `coverage_report(comp, season)`, `known_gaps()`, `data_issues()` | what's covered and what's missing |
+
+## Tests
+
+The tests run on a small sample dataset (every UEFA Super Cup plus Nations League A 2022/23), with no download needed:
+
+```bash
+python -m unittest discover -s tests
+```
+
+## License
+
+Code: MIT. Data: CC-BY 4.0; credit "openplay (Noah Bair)".

openplay-0.1.0/src/openplay.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/openplay/__init__.py
+src/openplay/_data.py
+src/openplay/api.py
+src/openplay.egg-info/PKG-INFO
+src/openplay.egg-info/SOURCES.txt
+src/openplay.egg-info/dependency_links.txt
+src/openplay.egg-info/requires.txt
+src/openplay.egg-info/top_level.txt
+tests/test_api.py

openplay-0.1.0/src/openplay.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openplay-0.1.0/src/openplay.egg-info/requires.txt

@@ -0,0 +1,2 @@
+pandas>=1.5
+pyarrow>=10

openplay-0.1.0/src/openplay.egg-info/top_level.txt

@@ -0,0 +1 @@
+openplay

openplay-0.1.0/tests/test_api.py

@@ -0,0 +1,145 @@
+import json
+import os
+import unittest
+import warnings
+from pathlib import Path
+
+import openplay as op
+
+SAMPLE = Path(os.environ.get("OPENPLAY_SAMPLE_DIR", Path(__file__).parent / "data"))
+EXPECTED = json.loads((SAMPLE / "expected.json").read_text())
+
+
+class SampleTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        op.set_data_dir(SAMPLE)
+
+    @classmethod
+    def tearDownClass(cls):
+        op.set_data_dir(None)
+
+    def test_normalize_season(self):
+        self.assertEqual(op.normalize_season("2024/25"), "2425")
+        self.assertEqual(op.normalize_season("2024-2025"), "2425")
+        self.assertEqual(op.normalize_season("2425"), "2425")
+        self.assertEqual(op.normalize_season(2022), "2022")
+
+    def test_competitions(self):
+        self.assertEqual(len(op.competitions()), EXPECTED["n_competitions"])
+
+    def test_matches(self):
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            m = op.matches()
+        self.assertEqual(len(m), EXPECTED["n_matches"])
+        self.assertEqual(int(m["home_score"].sum() + m["away_score"].sum()), EXPECTED["total_goals"])
+        self.assertEqual(len(op.matches("usc")), EXPECTED["n_matches_usc"])
+
+    def test_events(self):
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            e = op.events("nla", "2022/23")
+        self.assertEqual(len(e), EXPECTED["n_events_nla_2223"])
+        self.assertEqual(int((e["type"].astype(str) == "Pass").sum()), EXPECTED["n_passes_nla_2223"])
+        small = op.events("usc", columns=["match_id", "type", "xg", "not_a_column"])
+        self.assertEqual(list(small.columns), ["match_id", "type", "xg"])
+
+    def test_events_needs_comp(self):
+        with self.assertRaises(ValueError):
+            op.events(None)
+
+    def test_shots(self):
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            s = op.shots()
+        self.assertEqual(len(s), EXPECTED["n_shots"])
+        self.assertAlmostEqual(float(s["xg"].astype("float64").sum()), EXPECTED["sum_xg"], places=3)
+
+    def test_player_stats(self):
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            p = op.player_match_stats()
+            lu = op.lineups()
+        self.assertEqual(len(lu), EXPECTED["n_lineup_rows"])
+        self.assertEqual(len(p), EXPECTED["n_player_match_rows"])
+        self.assertEqual(int(p["minutes_played"].sum()), EXPECTED["sum_minutes"])
+        self.assertEqual(int(p["goals"].sum()), EXPECTED["sum_player_goals"])
+        self.assertEqual(int(p["assists"].sum()), EXPECTED["sum_player_assists"])
+        self.assertAlmostEqual(float(p["xa"].astype("float64").sum()), EXPECTED["sum_player_xa"], places=3)
+        top = p.groupby("player_id")["goals"].sum().reset_index().sort_values(["goals", "player_id"], ascending=[False, True]).iloc[0]
+        self.assertEqual(int(top["player_id"]), EXPECTED["top_scorer_player_id"])
+        self.assertEqual(int(top["goals"]), EXPECTED["top_scorer_goals"])
+
+    def test_team_stats(self):
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            t = op.team_match_stats()
+        self.assertEqual(int(t["passes"].sum()), EXPECTED["sum_team_passes"])
+        self.assertEqual(len(t), 2 * EXPECTED["n_matches"])
+
+    def test_coverage_warns_never_errors(self):
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            cov = op.coverage_report("nla", "2223")
+        self.assertEqual(int(cov["gaps"].sum()), EXPECTED["gaps_nla_2223"])
+        self.assertTrue(any(issubclass(x.category, op.CoverageWarning) for x in w))
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            op.matches("nla", "2223")
+        self.assertTrue(any(issubclass(x.category, op.CoverageWarning) for x in w))
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            op.coverage_report("not_a_comp")
+        self.assertFalse(any(issubclass(x.category, op.CoverageWarning) for x in w))
+
+    def test_player_season_stats(self):
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            s = op.player_season_stats("nla", "2223")
+            s90 = op.player_season_stats("nla", "2223", per90=True, min_minutes=180)
+        self.assertEqual(len(s), EXPECTED["n_season_rows_nla_2223"])
+        self.assertEqual(int(s["minutes_played"].sum()), EXPECTED["sum_season_minutes_nla_2223"])
+        self.assertEqual(int(s["goals"].sum()), EXPECTED["sum_season_goals_nla_2223"])
+        self.assertEqual(len(s90), EXPECTED["n_season_rows_nla_2223_min180"])
+        best = s90.sort_values(["xg", "player_id"], ascending=[False, True]).iloc[0]
+        self.assertEqual(int(best["player_id"]), EXPECTED["top_xg90_player_id_nla_2223"])
+        self.assertAlmostEqual(float(best["xg"]), EXPECTED["top_xg90_nla_2223"], places=4)
+
+    def test_player_filter_and_career(self):
+        self.assertEqual(op.name_key("  Kylian  Mbappé "), "kylian mbappe")
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            m = op.player_match_stats("nla", "2022/23", player="kylian mbappe")
+            s = op.shots("usc", player="Lionel Messi")
+            c = op.player_career("Luka Modric")
+        self.assertEqual(len(m), EXPECTED["mbappe_matches_nla_2223"])
+        self.assertEqual(len(s), EXPECTED["messi_shots_usc"])
+        self.assertEqual(len(c), EXPECTED["modric_career_rows"])
+        self.assertEqual(int(c["goals"].sum()), EXPECTED["modric_career_goals"])
+        self.assertEqual(int(c["minutes_played"].sum()), EXPECTED["modric_career_minutes"])
+        self.assertTrue(c["first_match"].is_monotonic_increasing)
+
+    def test_misspelled_player_suggests(self):
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            r = op.player_season_stats(player="Lionel Messsi")
+        self.assertEqual(len(r), 0)
+        msgs = [str(x.message) for x in w if issubclass(x.category, op.PlayerWarning)]
+        self.assertTrue(any("Did you mean: Lionel Messi" in m for m in msgs))
+        self.assertEqual(op.suggest_players("Messi")[0], "Lionel Messi")
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            self.assertEqual(len(op.player_career("Zzzz Qqqq")), 0)
+        self.assertTrue(any("Check the spelling" in str(x.message) for x in w))
+
+    def test_known_gaps(self):
+        self.assertEqual(len(op.known_gaps()), EXPECTED["n_known_gaps"])
+
+    def test_players_teams(self):
+        self.assertGreater(len(op.players()), 0)
+        self.assertGreater(len(op.teams()), 0)
+
+
+if __name__ == "__main__":
+    unittest.main()