openwec 0.1.0__py3-none-any.whl

openwec/__init__.py

@@ -0,0 +1,45 @@
+"""
+OpenWEC SDK — Alpha
+
+A FastF1-style Python interface for endurance racing data
+(WEC, ELMS, ALMS, Le Mans Cup, IMSA).
+
+Usage:
+    import openwec
+
+    # Optional: configure API URL and key
+    openwec.configure(base_url="http://localhost:8000/api/v1", api_key="your-key")
+
+    # Load a session
+    session = openwec.Session("WEC", 2024, "Le Mans", "Race")
+
+    # Results (public, no API key needed)
+    results = session.results()
+    print(results.head())
+
+    # Laps (requires API key)
+    laps = session.laps()
+    laps_50 = session.laps(car="50")
+
+    # Analytics (requires API key)
+    stints = session.stints()
+    pace   = session.pace()
+
+    # Plots (requires matplotlib + API key)
+    session.plot_lap_evolution(car="50")
+    session.plot_stint_chart()
+    session.plot_gap_to_leader()
+"""
+
+from .client import configure, OpenWECError, OpenWECNotFoundError, OpenWECAuthError
+from .session import Session
+
+__version__ = "0.1.0-alpha"
+
+__all__ = [
+    "Session",
+    "configure",
+    "OpenWECError",
+    "OpenWECNotFoundError",
+    "OpenWECAuthError",
+]

openwec/client.py

@@ -0,0 +1,62 @@
+"""
+OpenWEC SDK — Client configuration and HTTP wrapper.
+"""
+
+import requests
+
+
+class _Config:
+    base_url: str = "http://localhost:8000/api/v1"
+    api_key:  str | None = None
+
+
+_config = _Config()
+
+
+def configure(base_url: str | None = None, api_key: str | None = None):
+    """
+    Configure the SDK.
+
+    Args:
+        base_url: API base URL (default: http://localhost:8000/api/v1)
+        api_key:  API key for protected endpoints (laps, analytics)
+    """
+    if base_url:
+        _config.base_url = base_url.rstrip("/")
+    if api_key:
+        _config.api_key = api_key
+
+
+def _headers() -> dict:
+    headers = {}
+    if _config.api_key:
+        headers["X-API-Key"] = _config.api_key
+    return headers
+
+
+def _get(path: str, params: dict | None = None) -> dict | list:
+    """Performs a GET request to the OpenWEC API. Raises on error."""
+    url = f"{_config.base_url}{path}"
+    resp = requests.get(url, params=params, headers=_headers(), timeout=30)
+
+    if resp.status_code == 404:
+        raise OpenWECNotFoundError(f"Not found: {path} ({resp.text})")
+    if resp.status_code == 401:
+        raise OpenWECAuthError(
+            "Unauthorized — this endpoint requires an API key. "
+            "Call openwec.configure(api_key='...') first."
+        )
+    resp.raise_for_status()
+    return resp.json()
+
+
+class OpenWECError(Exception):
+    """Base exception for OpenWEC SDK errors."""
+
+
+class OpenWECNotFoundError(OpenWECError):
+    """Raised when a resource is not found (404)."""
+
+
+class OpenWECAuthError(OpenWECError):
+    """Raised when an API key is required but missing/invalid (401)."""

openwec/plotting.py

@@ -0,0 +1,124 @@
+"""
+OpenWEC SDK — Plotting
+Basic matplotlib charts, inspired by FastF1's plotting helpers.
+
+These are intentionally simple — alpha quality. Returns a matplotlib
+Figure so users can further customize (fig.savefig, etc).
+"""
+
+from __future__ import annotations
+import matplotlib.pyplot as plt
+import matplotlib.colors as mcolors
+import pandas as pd
+
+
+def plot_lap_evolution(laps: pd.DataFrame, car: str | None = None, ax=None):
+    """
+    Plots lap time evolution over the race.
+
+    Args:
+        laps: DataFrame from session.laps(car=...)
+        car:  car number, used for the plot title
+        ax:   optional matplotlib axes to plot on
+    """
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(10, 5))
+    else:
+        fig = ax.figure
+
+    df = laps.copy()
+    df = df[df["lap_time_s"].notna()]
+    df = df[df["lap_time_s"] < 600]  # exclude formation/SC laps with huge times
+
+    # Highlight pit laps
+    pit_laps = df[df["crossing_finish_in_pit"] == True]
+    clean    = df[df["crossing_finish_in_pit"] == False]
+
+    ax.plot(clean["lap_number"], clean["lap_time_s"],
+            marker="o", markersize=3, linewidth=1, label="Lap time")
+
+    if not pit_laps.empty:
+        ax.scatter(pit_laps["lap_number"], pit_laps["lap_time_s"],
+                    color="red", marker="x", s=50, label="Pit lap", zorder=5)
+
+    ax.set_xlabel("Lap")
+    ax.set_ylabel("Lap time (s)")
+    title = f"Lap Evolution — Car #{car}" if car else "Lap Evolution"
+    ax.set_title(title)
+    ax.legend()
+    ax.grid(alpha=0.3)
+
+    fig.tight_layout()
+    return fig
+
+
+def plot_stint_chart(stints: pd.DataFrame, ax=None):
+    """
+    Plots a horizontal stint chart — one row per car, colored bars per stint.
+    Similar to FastF1's strategy chart.
+
+    Args:
+        stints: DataFrame from session.stints() (all cars)
+        ax:     optional matplotlib axes to plot on
+    """
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(12, max(4, len(stints["car_number"].unique()) * 0.3)))
+    else:
+        fig = ax.figure
+
+    cars = sorted(stints["car_number"].unique(), key=lambda x: int(x) if x.isdigit() else 999)
+
+    # Color map by stint number (cycles)
+    cmap = plt.get_cmap("tab10")
+
+    for i, car in enumerate(cars):
+        car_stints = stints[stints["car_number"] == car].sort_values("stint_number")
+        for _, stint in car_stints.iterrows():
+            duration = stint["end_lap"] - stint["start_lap"] + 1
+            color = cmap(int(stint["stint_number"]) % 10)
+            ax.barh(i, duration, left=stint["start_lap"], color=color,
+                    edgecolor="white", height=0.6)
+
+    ax.set_yticks(range(len(cars)))
+    ax.set_yticklabels([f"#{c}" for c in cars])
+    ax.set_xlabel("Lap")
+    ax.set_title("Stint Chart")
+    ax.invert_yaxis()
+    ax.grid(axis="x", alpha=0.3)
+
+    fig.tight_layout()
+    return fig
+
+
+def plot_gap_to_leader(gaps: pd.DataFrame, ax=None):
+    """
+    Plots gap to leader over race distance.
+
+    Args:
+        gaps: DataFrame from session.gaps() — needs lap_number, car_number, cumulative_s
+        ax:   optional matplotlib axes to plot on
+    """
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(10, 6))
+    else:
+        fig = ax.figure
+
+    df = gaps.copy()
+    df = df[df["cumulative_s"].notna()]
+
+    # Leader = minimum cumulative_s per lap
+    leader_per_lap = df.groupby("lap_number")["cumulative_s"].min()
+
+    for car, group in df.groupby("car_number"):
+        group = group.set_index("lap_number")
+        gap = group["cumulative_s"] - leader_per_lap.reindex(group.index)
+        ax.plot(gap.index, gap.values, label=f"#{car}", linewidth=1)
+
+    ax.set_xlabel("Lap")
+    ax.set_ylabel("Gap to leader (s)")
+    ax.set_title("Gap to Leader")
+    ax.legend(fontsize=8, ncol=2)
+    ax.grid(alpha=0.3)
+
+    fig.tight_layout()
+    return fig

openwec/session.py

@@ -0,0 +1,304 @@
+"""
+OpenWEC SDK — Session
+The main object-style interface, inspired by FastF1.
+
+Usage:
+    import openwec
+
+    session = openwec.Session("WEC", 2024, "Le Mans", "Race")
+    results = session.results()
+    laps    = session.laps()
+    laps_50 = session.laps(car="50")
+"""
+
+from __future__ import annotations
+import pandas as pd
+
+from .client import _get, OpenWECNotFoundError
+
+
+class Session:
+    """
+    Represents a single session (e.g. WEC 2024 Le Mans Race).
+
+    Resolution is done by matching series/season/event/session names
+    against the OpenWEC catalog — matching is case-insensitive and
+    substring-based for event and session names.
+
+    Args:
+        series:  series key, e.g. "WEC", "ELMS", "IMSA"
+        year:    season year, e.g. 2024
+        event:   event name or substring, e.g. "Le Mans"
+        session: session name or substring, e.g. "Race", "Qualifying"
+    """
+
+    def __init__(self, series: str, year: int, event: str, session: str):
+        self.series_key   = series.upper()
+        self.year         = year
+        self.event_query  = event
+        self.session_query = session
+
+        self._session_id: int | None = None
+        self._event_id:   int | None = None
+        self._event_name: str | None = None
+        self._session_name: str | None = None
+        self._session_type: str | None = None
+        self._session_at:  str | None = None
+
+        self._results_cache: pd.DataFrame | None = None
+        self._laps_cache:    dict[str | None, pd.DataFrame] = {}
+
+        self._resolve()
+
+    # ── Resolution ────────────────────────────────────────────
+
+    def _resolve(self):
+        """Resolves series/year/event/session to a session_id via the API."""
+
+        # 1. Find the event
+        events = _get(f"/series/{self.series_key}/seasons/{self.year}/events")
+        if not isinstance(events, list):
+            raise OpenWECNotFoundError(f"No events found for {self.series_key} {self.year}")
+
+        event_match = _find_best_match(events, "name", self.event_query)
+        if not event_match:
+            available = ", ".join(e["name"] for e in events)
+            raise OpenWECNotFoundError(
+                f"No event matching '{self.event_query}' in {self.series_key} {self.year}. "
+                f"Available: {available}"
+            )
+
+        self._event_id   = event_match["id"]
+        self._event_name = event_match["name"]
+
+        # 2. Find the session within that event
+        sessions = _get(
+            f"/series/{self.series_key}/seasons/{self.year}/events/{self._event_id}/sessions"
+        )
+        if not isinstance(sessions, list):
+            raise OpenWECNotFoundError(f"No sessions found for event {self._event_name}")
+
+        session_match = _find_best_match(sessions, "name", self.session_query)
+        if not session_match:
+            available = ", ".join(s["name"] for s in sessions)
+            raise OpenWECNotFoundError(
+                f"No session matching '{self.session_query}' in {self._event_name}. "
+                f"Available: {available}"
+            )
+
+        self._session_id   = session_match["id"]
+        self._session_name = session_match["name"]
+        self._session_type = session_match["session_type"]
+        self._session_at   = session_match.get("session_at")
+
+    # ── Properties ────────────────────────────────────────────
+
+    @property
+    def id(self) -> int:
+        """The resolved session_id."""
+        return self._session_id
+
+    @property
+    def event_name(self) -> str:
+        return self._event_name
+
+    @property
+    def name(self) -> str:
+        return self._session_name
+
+    @property
+    def session_type(self) -> str:
+        return self._session_type
+
+    def __repr__(self) -> str:
+        return (
+            f"Session({self.series_key} {self.year} "
+            f"{self._event_name} — {self._session_name}, id={self._session_id})"
+        )
+
+    # ── Data ──────────────────────────────────────────────────
+
+    def results(self) -> pd.DataFrame:
+        """
+        Returns the final classification as a DataFrame.
+        One row per car, sorted by position.
+        Public endpoint — no API key required.
+        """
+        if self._results_cache is not None:
+            return self._results_cache
+
+        data = _get(f"/sessions/{self._session_id}/results")
+        df = pd.json_normalize(data)
+
+        # Flatten drivers list into a readable column
+        if "drivers" in df.columns:
+            df["drivers"] = df["drivers"].apply(_format_drivers)
+
+        self._results_cache = df
+        return df
+
+    def laps(self, car: str | None = None) -> pd.DataFrame:
+        """
+        Returns lap-by-lap data as a DataFrame.
+        Requires API key — call openwec.configure(api_key=...) first.
+
+        Args:
+            car: optional car number to filter (e.g. "50").
+                 If None, returns all laps (paginated automatically).
+        """
+        cache_key = car
+        if cache_key in self._laps_cache:
+            return self._laps_cache[cache_key]
+
+        if car:
+            data = _get(f"/sessions/{self._session_id}/laps/{car}")
+            df = pd.DataFrame(data)
+        else:
+            # Paginate through all laps
+            all_rows = []
+            page = 1
+            while True:
+                resp = _get(f"/sessions/{self._session_id}/laps", params={
+                    "page": page, "page_size": 500
+                })
+                rows = resp.get("results", [])
+                all_rows.extend(rows)
+                if len(rows) < 500:
+                    break
+                page += 1
+            df = pd.DataFrame(all_rows)
+
+        self._laps_cache[cache_key] = df
+        return df
+
+    # ── Analytics ─────────────────────────────────────────────
+
+    def stints(self, car: str | None = None, car_class: str | None = None) -> pd.DataFrame:
+        """
+        Returns stint breakdown (baseline pace, degradation, consistency) per car.
+        Requires API key.
+        """
+        params = {}
+        if car:
+            params["car"] = car
+        if car_class:
+            params["car_class"] = car_class
+        data = _get(f"/sessions/{self._session_id}/stints", params=params)
+        return pd.DataFrame(data)
+
+    def pace(self, car_class: str | None = None) -> pd.DataFrame:
+        """
+        Returns average green-flag pace per car, sorted fastest first.
+        Requires API key.
+        """
+        params = {}
+        if car_class:
+            params["car_class"] = car_class
+        data = _get(f"/sessions/{self._session_id}/pace", params=params)
+        return pd.DataFrame(data)
+
+    def gaps(self, car: str | None = None, car_class: str | None = None,
+             max_laps: int = 50) -> pd.DataFrame:
+        """
+        Returns cumulative lap time evolution — useful for gap-to-leader charts.
+        Requires API key.
+        """
+        params = {"max_laps": max_laps}
+        if car:
+            params["car"] = car
+        if car_class:
+            params["car_class"] = car_class
+        data = _get(f"/sessions/{self._session_id}/gaps", params=params)
+        return pd.DataFrame(data)
+
+    def pit_window(self, car: str | None = None, car_class: str | None = None,
+                    pit_loss_s: float | None = None) -> pd.DataFrame:
+        """
+        Returns estimated optimal pit window per stint per car.
+        Requires API key.
+        """
+        params = {}
+        if car:
+            params["car"] = car
+        if car_class:
+            params["car_class"] = car_class
+        if pit_loss_s:
+            params["pit_loss_s"] = pit_loss_s
+
+        data = _get(f"/sessions/{self._session_id}/pit-window", params=params)
+
+        # Flatten nested stints into rows
+        rows = []
+        for car_data in data:
+            for stint in car_data["stints"]:
+                rows.append({
+                    "car_number": car_data["car_number"],
+                    "car_class":  car_data["car_class"],
+                    "team":       car_data["team"],
+                    "pit_loss_s": car_data["pit_loss_s"],
+                    **stint,
+                })
+        return pd.DataFrame(rows)
+
+    # ── Plots ─────────────────────────────────────────────────
+
+    def plot_lap_evolution(self, car: str, ax=None):
+        """
+        Plots lap time evolution for a car. Requires matplotlib.
+        Requires API key (uses session.laps()).
+        """
+        from . import plotting
+        laps = self.laps(car=car)
+        return plotting.plot_lap_evolution(laps, car=car, ax=ax)
+
+    def plot_stint_chart(self, car_class: str | None = None, ax=None):
+        """
+        Plots a stint chart (strategy overview) for all cars.
+        Requires matplotlib and API key.
+        """
+        from . import plotting
+        stints = self.stints(car_class=car_class)
+        return plotting.plot_stint_chart(stints, ax=ax)
+
+    def plot_gap_to_leader(self, car_class: str | None = None, max_laps: int = 50, ax=None):
+        """
+        Plots gap to leader over race distance.
+        Requires matplotlib and API key.
+        """
+        from . import plotting
+        gaps = self.gaps(car_class=car_class, max_laps=max_laps)
+        return plotting.plot_gap_to_leader(gaps, ax=ax)
+
+
+# ── Helpers ───────────────────────────────────────────────────
+
+def _find_best_match(items: list[dict], key: str, query: str) -> dict | None:
+    """
+    Finds the best match for `query` against `item[key]`.
+    Priority: exact match (case-insensitive) > substring match.
+    """
+    query_lower = query.strip().lower()
+
+    # Exact match first
+    for item in items:
+        if item[key].strip().lower() == query_lower:
+            return item
+
+    # Substring match
+    for item in items:
+        if query_lower in item[key].strip().lower():
+            return item
+
+    return None
+
+
+def _format_drivers(drivers: list[dict]) -> str:
+    """Formats a list of driver dicts into 'First Last / First Last' string."""
+    if not drivers:
+        return ""
+    names = []
+    for d in sorted(drivers, key=lambda x: x.get("slot", 0)):
+        first = d.get("first_name", "")
+        last  = d.get("last_name", "")
+        names.append(f"{first} {last}".strip())
+    return " / ".join(names)

openwec-0.1.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: openwec
+Version: 0.1.0
+Summary: Python SDK for endurance racing data — WEC, ELMS, ALMS, Le Mans Cup, IMSA
+Author: Paloma C.
+License-Expression: MIT
+Project-URL: Homepage, https://openwec.com
+Project-URL: Documentation, https://api.openwec.com/docs
+Project-URL: Repository, https://github.com/palomacdev/openwec
+Project-URL: Bug Tracker, https://github.com/palomacdev/openwec/issues
+Keywords: motorsport,endurance racing,WEC,Le Mans,ELMS,IMSA,timing data,lap times,pandas
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31
+Requires-Dist: pandas>=2.0
+Provides-Extra: plotting
+Requires-Dist: matplotlib>=3.7; extra == "plotting"
+Provides-Extra: dev
+Requires-Dist: matplotlib>=3.7; extra == "dev"
+Requires-Dist: jupyter>=1.0; extra == "dev"
+Requires-Dist: ipykernel>=6.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+
+# openwec
+
+**Python SDK for endurance racing data — WEC, ELMS, ALMS, Le Mans Cup, IMSA.**
+
+Inspired by [FastF1](https://github.com/theOehrly/Fast-F1), OpenWEC gives you lap-by-lap timing data, stint analytics, and race results from endurance racing as pandas DataFrames — in one line.
+
+→ **[openwec.com](https://openwec.com)** — Live dashboard  
+→ **[api.openwec.com/docs](https://api.openwec.com/docs)** — API reference  
+→ **[github.com/palomacdev/openwec](https://github.com/palomacdev/openwec)** — Source
+
+---
+
+## Installation
+
+```bash
+pip install openwec
+
+# With plotting support
+pip install openwec[plotting]
+```
+
+---
+
+## Quick start
+
+```python
+import openwec
+
+# Configure — public endpoints work without a key
+# Request a free key at https://openwec.com/api-keys
+openwec.configure(
+    base_url="https://api.openwec.com/api/v1",
+    api_key="your-key-here"  # required for laps and analytics
+)
+
+# Load any session
+session = openwec.Session("WEC", 2026, "Le Mans", "Race")
+print(session)
+# Session(WEC 2026 LE MANS — Race, id=6556)
+
+# Results as a DataFrame (no key needed)
+results = session.results()
+print(results[["position", "car_number", "car_class", "team", "drivers"]].head(10))
+
+# Lap-by-lap data (key required)
+laps = session.laps(car="7")
+print(laps[["lap_number", "lap_time_s", "s1_s", "s2_s", "s3_s"]].head())
+
+# Stints and pace (key required)
+stints = session.stints(car_class="HYPERCAR")
+pace   = session.pace(car_class="HYPERCAR")
+
+# Pit window estimate
+pit_window = session.pit_window(car="7")
+
+# Plots (requires matplotlib)
+session.plot_lap_evolution(car="7")
+session.plot_stint_chart(car_class="HYPERCAR")
+session.plot_gap_to_leader(car_class="HYPERCAR")
+```
+
+---
+
+## Coverage
+
+| Series | Seasons |
+|--------|---------|
+| FIA WEC | 2012–2026 |
+| ELMS | 2012–2026 |
+| ALMS (Asian) | 2022–2026 |
+| Le Mans Cup | 2017–2026 |
+| IMSA | 2014–2026 |
+
+**1.77M+ laps** across all series.
+
+---
+
+## API key
+
+Public endpoints (results, driver profiles, team profiles) require no key.  
+Lap-by-lap data and analytics endpoints require a free API key.
+
+→ **[Request a key at openwec.com/api-keys](https://openwec.com/api-keys)**
+
+---
+
+## Session methods
+
+| Method | Returns | Key required |
+|--------|---------|-------------|
+| `.results()` | DataFrame | No |
+| `.laps(car=None)` | DataFrame | Yes |
+| `.stints(car_class=None)` | DataFrame | Yes |
+| `.pace(car_class=None)` | DataFrame | Yes |
+| `.gaps(car_class=None)` | DataFrame | Yes |
+| `.pit_window(car=None)` | DataFrame | Yes |
+| `.plot_lap_evolution(car)` | Figure | Yes |
+| `.plot_stint_chart()` | Figure | Yes |
+| `.plot_gap_to_leader()` | Figure | Yes |
+
+---
+
+## License
+
+MIT — data sourced from Al Kamel Systems public timing exports.  
+Not affiliated with ACO, FIA, or any racing organization.

openwec-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+openwec/__init__.py,sha256=wJJc3T6sGgKbPLo7L3BVJU3Hgc_d8c-GqXDvja9cljs,1108
+openwec/client.py,sha256=1xwcBXIrHF0m4i3-KvT23xKPSr6AtgNefq4Sg3ZeQ9Q,1669
+openwec/plotting.py,sha256=iAsA8a7PhYB4ybUoRok9i0jXV4b6ssEmlC22kg4nFk4,3943
+openwec/session.py,sha256=8cQ7a-WR6Qkgv59ymYQJWFtt10OCWzfX2LY9Oc4YLzs,11106
+openwec-0.1.0.dist-info/METADATA,sha256=7FDjcf_9Z7Rpt9_wTUqNZ24vsz7zFDIVIJMcdh2YWKQ,4362
+openwec-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+openwec-0.1.0.dist-info/top_level.txt,sha256=zWvhMMbttx58mLwB47zGzQn0uIvWqg56F027jpgK19k,8
+openwec-0.1.0.dist-info/RECORD,,

openwec-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

openwec-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+openwec