endurancepy 0.1.0__py3-none-any.whl

endurancepy/__init__.py

@@ -0,0 +1,59 @@
+"""EndurancePy — endurance racing timing & results data in Python.
+
+Inspired by `FastF1 <https://github.com/theOehrly/Fast-F1>`_, EndurancePy
+provides convenient, pandas-based access to timing and results data for endurance
+racing series (WEC, ELMS, Asian Le Mans Series, Le Mans Cup, IMSA), built on top
+of the publicly available Al Kamel Systems archives.
+
+Quick start::
+
+    import endurancepy as ep
+
+    ep.Cache.enable_cache("./cache")
+    session = ep.get_session(2019, "WEC", "Spa", "Race")
+    session.load(season="08_2018-2019")   # discover + download automatically
+    session.laps, session.results, session.weather_data
+
+Or parse a local Analysis CSV directly with :func:`read_analysis`.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from endurancepy.alkamel.analysis import read_analysis
+from endurancepy.alkamel.classification import read_classification
+from endurancepy.alkamel.weather import read_weather
+from endurancepy.cache import Cache
+from endurancepy.events import (
+    Event,
+    EventSchedule,
+    Series,
+    get_event,
+    get_event_schedule,
+    get_session,
+)
+from endurancepy.logger import set_log_level
+from endurancepy.standings import Standings, compute_standings
+
+try:
+    __version__ = version("endurancepy")
+except PackageNotFoundError:  # pragma: no cover - not installed (e.g. source tree)
+    __version__ = "0.0.0"
+
+__all__ = [
+    "Cache",
+    "Event",
+    "EventSchedule",
+    "Series",
+    "Standings",
+    "__version__",
+    "compute_standings",
+    "get_event",
+    "get_event_schedule",
+    "get_session",
+    "read_analysis",
+    "read_classification",
+    "read_weather",
+    "set_log_level",
+]

endurancepy/_types.py

@@ -0,0 +1,110 @@
+"""Reference column schemas (names and dtypes) for the EndurancePy data objects.
+
+These mirror FastF1's data model where it makes sense and add endurance-specific
+columns (car number, class, manufacturer, per-class position, gaps...). They are
+the single source of truth for the parsers (milestones 2.2+) and guarantee that
+the columns always exist with a stable dtype, even when a given session does not
+populate them.
+
+See ``docs/analyse_fastf1.md`` (§5, §7) and ``docs/plan_implementation.md`` (§4).
+"""
+
+from __future__ import annotations
+
+# --- Laps -------------------------------------------------------------------
+# Columns reused from FastF1 (same names/dtypes) plus endurance additions.
+LAPS_COLUMNS: dict[str, str] = {
+    # timing
+    "Time": "timedelta64[ns]",
+    "LapTime": "timedelta64[ns]",
+    "LapNumber": "float64",
+    "Stint": "float64",
+    "Sector1Time": "timedelta64[ns]",
+    "Sector2Time": "timedelta64[ns]",
+    "Sector3Time": "timedelta64[ns]",
+    "Sector1SessionTime": "timedelta64[ns]",
+    "Sector2SessionTime": "timedelta64[ns]",
+    "Sector3SessionTime": "timedelta64[ns]",
+    "PitInTime": "timedelta64[ns]",
+    "PitOutTime": "timedelta64[ns]",
+    "LapStartTime": "timedelta64[ns]",
+    "LapStartDate": "datetime64[ns]",
+    # speeds
+    "SpeedST": "float64",  # top speed at the speed-trap (from TOP_SPEED)
+    "LapAvgSpeed": "float64",  # average lap speed in km/h (from KPH) -- NOT top speed
+    # identity (endurance unit is the car/crew)
+    "CarNumber": "string",  # keep leading zeros -> string, never int
+    "Driver": "string",
+    "DriverNumber": "string",
+    "Team": "string",
+    "Class": "string",
+    "Manufacturer": "string",
+    # position
+    "Position": "float64",
+    "PositionInClass": "float64",
+    "GapToLeader": "timedelta64[ns]",
+    "GapToLeaderInClass": "timedelta64[ns]",
+    # status / flags
+    "TrackStatus": "string",
+    "IsPersonalBest": "boolean",
+    "IsAccurate": "boolean",
+    "Generated": "boolean",
+    "DriverChange": "boolean",
+    "Hour": "float64",
+}
+
+# Columns kept for FastF1 compatibility but not populated for endurance data.
+LAPS_COMPAT_COLUMNS: dict[str, str] = {
+    "Compound": "string",
+    "TyreLife": "float64",
+    "FreshTyre": "boolean",
+    "SpeedI1": "float64",
+    "SpeedI2": "float64",
+    "SpeedFL": "float64",
+    "Deleted": "boolean",
+    "DeletedReason": "string",
+}
+
+# --- Session results --------------------------------------------------------
+RESULTS_COLUMNS: dict[str, str] = {
+    "CarNumber": "string",
+    "Class": "string",
+    "Manufacturer": "string",
+    "TeamName": "string",
+    "Crew": "string",  # the car's drivers, "; "-joined
+    "Position": "float64",
+    "PositionInClass": "float64",
+    "ClassifiedPosition": "string",
+    "ClassifiedPositionInClass": "string",
+    "GridPosition": "float64",
+    "Time": "timedelta64[ns]",
+    "BestLapTime": "timedelta64[ns]",
+    "Status": "string",
+    "Points": "float64",
+    "Laps": "float64",
+    # driver-level fields (the crew is a list of these)
+    "DriverNumber": "string",
+    "Abbreviation": "string",
+    "FirstName": "string",
+    "LastName": "string",
+    "FullName": "string",
+}
+
+# --- Weather ----------------------------------------------------------------
+WEATHER_COLUMNS: dict[str, str] = {
+    "Time": "timedelta64[ns]",
+    "AirTemp": "float64",
+    "TrackTemp": "float64",
+    "Humidity": "float64",
+    "Pressure": "float64",
+    "Rainfall": "boolean",
+    "WindSpeed": "float64",
+    "WindDirection": "float64",
+}
+
+# --- Track status -----------------------------------------------------------
+TRACK_STATUS_COLUMNS: dict[str, str] = {
+    "Time": "timedelta64[ns]",
+    "Status": "string",
+    "Message": "string",
+}

endurancepy/alkamel/__init__.py

@@ -0,0 +1,12 @@
+"""Al Kamel Systems data layer.
+
+This sub-package contains everything specific to the Al Kamel timing archives:
+the HTTP client and URL building, results discovery, and the parsers that turn
+the published CSV files into EndurancePy data objects.
+
+The same parser covers WEC, ELMS, Asian Le Mans Series, Le Mans Cup and IMSA —
+only the base host and minor URL details differ. See
+``docs/analyse_fastf1.md`` §14 for the verified file formats and URL structure.
+"""
+
+from __future__ import annotations

endurancepy/alkamel/analysis.py

@@ -0,0 +1,209 @@
+"""Parser for the Al Kamel "Analysis" CSV (``23_Analysis*.CSV``) -> ``Laps``.
+
+This is the primary data product: one row per car-lap, with lap/sector times,
+average and top speed, a pit indicator, class/team/manufacturer, and the flag at
+the finish line. From these raw fields a number of FastF1-style columns are
+derived here:
+
+* ``Stint`` (segment between pit stops) and ``PitInTime`` / ``PitOutTime``
+* ``LapStartTime`` and the cumulative ``SectorNSessionTime`` columns
+* ``Position`` and ``PositionInClass`` (reconstructed from line crossings)
+* ``IsPersonalBest``, ``IsAccurate`` and ``DriverChange``
+
+Gaps (``GapToLeader*``), ``Hour`` and ``LapStartDate`` need session-level
+context and are left empty here; they are filled in a later step.
+
+See ``docs/analyse_fastf1.md`` §14.4 for the verified CSV format.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+import numpy as np
+import pandas as pd
+
+from endurancepy._types import LAPS_COLUMNS, LAPS_COMPAT_COLUMNS
+from endurancepy.alkamel.headers import read_alkamel_csv
+from endurancepy.alkamel.timeparse import parse_duration
+from endurancepy.core import Laps
+
+if TYPE_CHECKING:
+    from endurancepy.core import Session
+
+#: Tolerance for the "sum of sectors ≈ lap time" accuracy check.
+_SECTOR_SUM_TOLERANCE = pd.Timedelta(seconds=0.5)
+
+
+def read_analysis(
+    source: bytes | str | os.PathLike[str], *, session: Session | None = None
+) -> Laps:
+    """Read and parse an Analysis CSV file (bytes or path) into ``Laps``."""
+    return to_laps(read_alkamel_csv(source), session=session)
+
+
+def to_laps(raw: pd.DataFrame, *, session: Session | None = None) -> Laps:
+    """Convert a normalised Analysis DataFrame into a :class:`Laps`."""
+    n = len(raw)
+    index = pd.RangeIndex(n)
+
+    def text(name: str) -> pd.Series:
+        if name in raw.columns:
+            return raw[name].reset_index(drop=True).replace("", pd.NA).astype("string")
+        return pd.Series(pd.NA, index=index, dtype="string")
+
+    def number(name: str) -> pd.Series:
+        if name in raw.columns:
+            return pd.to_numeric(raw[name].reset_index(drop=True), errors="coerce")
+        return pd.Series(np.nan, index=index)
+
+    def duration(name: str) -> pd.Series:
+        if name in raw.columns:
+            return pd.to_timedelta(raw[name].reset_index(drop=True).map(parse_duration))
+        return pd.Series(pd.NaT, index=index, dtype="timedelta64[ns]")
+
+    def sector(idx: int) -> pd.Series:
+        seconds_col = f"S{idx}_SECONDS"
+        if seconds_col in raw.columns:
+            return pd.to_timedelta(number(seconds_col), unit="s")
+        return duration(f"S{idx}")
+
+    df = pd.DataFrame(index=index)
+    df["CarNumber"] = text("NUMBER")
+    df["DriverNumber"] = text("DRIVER_NUMBER")
+    df["Driver"] = text("DRIVER_NAME")
+    df["Team"] = text("TEAM")
+    df["Class"] = text("CLASS")
+    df["Manufacturer"] = text("MANUFACTURER")
+    df["LapNumber"] = number("LAP_NUMBER").astype("float64")
+    df["LapTime"] = duration("LAP_TIME")
+    df["Sector1Time"] = sector(1)
+    df["Sector2Time"] = sector(2)
+    df["Sector3Time"] = sector(3)
+    df["Time"] = duration("ELAPSED")
+    df["SpeedST"] = number("TOP_SPEED").astype("float64")
+    df["LapAvgSpeed"] = number("KPH").astype("float64")
+    df["TrackStatus"] = text("FLAG_AT_FL")
+    df["IsPersonalBest"] = number("LAP_IMPROVEMENT").isin([1, 2])
+
+    # Helper columns (dropped before returning).
+    crossing = (
+        raw["CROSSING_FINISH_LINE_IN_PIT"].reset_index(drop=True).str.upper()
+        if "CROSSING_FINISH_LINE_IN_PIT" in raw.columns
+        else pd.Series("", index=index)
+    )
+    df["_PitTime"] = duration("PIT_TIME")
+    df["_Pitted"] = (crossing == "B") | df["_PitTime"].notna()
+
+    # Order per car/lap so the shift-based derivations are correct.
+    df = df.sort_values(["CarNumber", "LapNumber"]).reset_index(drop=True)
+
+    _derive_stints_and_pits(df)
+    _derive_sector_session_times(df)
+    _derive_driver_change(df)
+    _derive_positions(df)
+    _derive_accuracy(df)
+
+    df = df.drop(columns=["_PitTime", "_Pitted"])
+    return _finalize(df, session=session)
+
+
+def _derive_stints_and_pits(df: pd.DataFrame) -> None:
+    pitted = df["_Pitted"]
+    car = df["CarNumber"]
+    # A new stint starts on the lap *after* a pit-in lap.
+    df["Stint"] = (
+        pitted.groupby(car).transform(lambda s: s.shift(fill_value=False).cumsum()) + 1
+    ).astype("float64")
+    df["PitInTime"] = df["Time"].where(pitted)
+    df["LapStartTime"] = df["Time"] - df["LapTime"]
+    stint_start = df.groupby("CarNumber")["Stint"].transform(lambda s: s != s.shift())
+    df["PitOutTime"] = df["LapStartTime"].where(stint_start & (df["Stint"] > 1))
+
+
+def _derive_sector_session_times(df: pd.DataFrame) -> None:
+    df["Sector3SessionTime"] = df["Time"]
+    df["Sector2SessionTime"] = df["Time"] - df["Sector3Time"]
+    df["Sector1SessionTime"] = df["Time"] - df["Sector3Time"] - df["Sector2Time"]
+
+
+def _derive_driver_change(df: pd.DataFrame) -> None:
+    def changed(s: pd.Series) -> pd.Series:
+        return (s != s.shift()) & s.shift().notna()
+
+    df["DriverChange"] = df.groupby("CarNumber")["DriverNumber"].transform(changed)
+
+
+def _derive_positions(df: pd.DataFrame) -> None:
+    """Reconstruct overall and in-class position at each line crossing."""
+    car_class = dict(zip(df["CarNumber"], df["Class"], strict=False))
+    laps_done: dict[object, float] = {}
+    last_time: dict[object, pd.Timedelta] = {}
+    position = pd.Series(np.nan, index=df.index, dtype="float64")
+    position_in_class = pd.Series(np.nan, index=df.index, dtype="float64")
+
+    order = df.sort_values("Time", kind="stable")
+    for idx in order.index:
+        car = df.at[idx, "CarNumber"]
+        lap = df.at[idx, "LapNumber"]
+        time = df.at[idx, "Time"]
+        if pd.isna(time) or pd.isna(lap):
+            continue
+        laps_done[car] = lap
+        last_time[car] = time
+        cls = car_class.get(car)
+        rank = 1
+        rank_in_class = 1
+        for other, other_lap in laps_done.items():
+            if other == car:
+                continue
+            other_time = last_time[other]
+            ahead = (other_lap > lap) or (other_lap == lap and other_time < time)
+            if ahead:
+                rank += 1
+                if car_class.get(other) == cls:
+                    rank_in_class += 1
+        position.at[idx] = rank
+        position_in_class.at[idx] = rank_in_class
+
+    df["Position"] = position
+    df["PositionInClass"] = position_in_class
+
+
+def _derive_accuracy(df: pd.DataFrame) -> None:
+    sector_sum = df[["Sector1Time", "Sector2Time", "Sector3Time"]].sum(
+        axis=1, min_count=3
+    )
+    consistent = (df["LapTime"] - sector_sum).abs() <= _SECTOR_SUM_TOLERANCE
+    flag = df["TrackStatus"].fillna("").str.upper()
+    accurate = (
+        df["LapTime"].notna()
+        & df["PitInTime"].isna()
+        & df["PitOutTime"].isna()
+        & (flag == "GF")
+        & (consistent | sector_sum.isna())
+    )
+    df["IsAccurate"] = accurate
+
+
+def _empty_column(dtype: str, index: pd.Index) -> pd.Series:
+    if dtype.startswith("timedelta"):
+        return pd.Series(pd.NaT, index=index, dtype="timedelta64[ns]")
+    if dtype.startswith("datetime"):
+        return pd.Series(pd.NaT, index=index, dtype="datetime64[ns]")
+    if dtype == "float64":
+        return pd.Series(np.nan, index=index, dtype="float64")
+    if dtype == "boolean":
+        return pd.Series(pd.NA, index=index, dtype="boolean")
+    return pd.Series(pd.NA, index=index, dtype="string")
+
+
+def _finalize(df: pd.DataFrame, *, session: Session | None) -> Laps:
+    schema = {**LAPS_COLUMNS, **LAPS_COMPAT_COLUMNS}
+    df["Generated"] = False
+    columns: dict[str, pd.Series] = {}
+    for name, dtype in schema.items():
+        series = df[name] if name in df.columns else _empty_column(dtype, df.index)
+        columns[name] = series.astype(dtype)
+    return Laps(columns, session=session)

endurancepy/alkamel/classification.py

@@ -0,0 +1,143 @@
+"""Parser for the Al Kamel Classification CSV -> ``SessionResults``.
+
+Targets the race classification layout (verified real header)::
+
+    POSITION;NUMBER;TEAM;DRIVER_1;DRIVER_2;DRIVER_3;DRIVER_4;VEHICLE;TYRES;
+    CLASS;GROUP;DIVISION;STATUS;LAPS;TOTAL_TIME;GAP_FIRST;GAP_PREVIOUS;
+    FL_LAPNUM;FL_TIME;FL_KPH;DRIVER_5;
+
+Times use an apostrophe for minutes (e.g. ``5:44'41.101``, ``1'58.056``). The
+parser is tolerant: practice/qualifying classifications use a different, wider
+schema, so missing columns are simply left empty. When a Classification CSV is
+not available, results are instead derived from the laps (see
+:mod:`endurancepy.results`).
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+import numpy as np
+import pandas as pd
+
+from endurancepy._types import RESULTS_COLUMNS
+from endurancepy.alkamel.headers import read_alkamel_csv
+from endurancepy.alkamel.timeparse import parse_duration
+from endurancepy.core import SessionResults
+
+if TYPE_CHECKING:
+    from endurancepy.core import Session
+
+_DRIVER_COLUMNS = ["DRIVER_1", "DRIVER_2", "DRIVER_3", "DRIVER_4", "DRIVER_5"]
+
+
+def _empty_column(dtype: str, index: pd.Index) -> pd.Series:
+    if dtype.startswith("timedelta"):
+        return pd.Series(pd.NaT, index=index, dtype="timedelta64[ns]")
+    if dtype.startswith("datetime"):
+        return pd.Series(pd.NaT, index=index, dtype="datetime64[ns]")
+    if dtype == "float64":
+        return pd.Series(np.nan, index=index, dtype="float64")
+    if dtype == "boolean":
+        return pd.Series(pd.NA, index=index, dtype="boolean")
+    return pd.Series(pd.NA, index=index, dtype="string")
+
+
+def _parse_clock(value: object) -> pd.Timedelta:
+    """Parse an Al Kamel classification time (minutes use an apostrophe)."""
+    return parse_duration(str(value).replace("'", ":"))
+
+
+def read_classification(
+    source: bytes | str | os.PathLike[str], *, session: Session | None = None
+) -> SessionResults:
+    """Read and parse a Classification CSV (bytes or path) into ``SessionResults``."""
+    return to_results(read_alkamel_csv(source), session=session)
+
+
+def to_results(raw: pd.DataFrame, *, session: Session | None = None) -> SessionResults:
+    """Convert a normalised Classification DataFrame into ``SessionResults``."""
+    cols = set(raw.columns)
+
+    def get(*names: str) -> pd.Series | None:
+        for name in names:
+            if name in cols:
+                return raw[name].reset_index(drop=True)
+        return None
+
+    if len(raw) == 0:
+        empty = {
+            name: _empty_column(dtype, pd.RangeIndex(0))
+            for name, dtype in RESULTS_COLUMNS.items()
+        }
+        return SessionResults(empty, session=session)
+
+    index = pd.RangeIndex(len(raw))
+
+    def text(series: pd.Series | None) -> pd.Series:
+        if series is None:
+            return pd.Series(pd.NA, index=index, dtype="string")
+        return series.replace("", pd.NA).astype("string")
+
+    def clock(series: pd.Series | None) -> pd.Series:
+        if series is None:
+            return pd.Series(pd.NaT, index=index, dtype="timedelta64[ns]")
+        return pd.to_timedelta(series.map(_parse_clock))
+
+    position = pd.to_numeric(get("POSITION", "POS"), errors="coerce").astype("float64")
+
+    driver_cols = [c for c in _DRIVER_COLUMNS if c in cols]
+    if driver_cols:
+        crew = (
+            raw[driver_cols]
+            .apply(
+                lambda row: "; ".join(
+                    v for v in row if isinstance(v, str) and v.strip()
+                ),
+                axis=1,
+            )
+            .reset_index(drop=True)
+        )
+    else:
+        crew = pd.Series("", index=index)
+
+    vehicle = get("VEHICLE")
+    manufacturer = get("MANUFACTURER")
+    if manufacturer is None and vehicle is not None:
+        manufacturer = vehicle.map(
+            lambda v: v.split()[0] if isinstance(v, str) and v.strip() else pd.NA
+        )
+
+    summary = pd.DataFrame(
+        {
+            "CarNumber": text(get("NUMBER")),
+            "Class": text(get("CLASS")),
+            "Manufacturer": text(manufacturer),
+            "TeamName": text(get("TEAM")),
+            "Crew": crew.astype("string"),
+            "Position": position,
+            "Time": clock(get("TOTAL_TIME")),
+            "BestLapTime": clock(get("FL_TIME", "TIME")),
+            "Status": text(get("STATUS")),
+            "Laps": pd.to_numeric(get("LAPS"), errors="coerce").astype("float64"),
+        }
+    )
+    summary = summary.sort_values("Position").reset_index(drop=True)
+    summary["PositionInClass"] = (
+        summary.groupby("Class", sort=False).cumcount() + 1
+    ).astype("float64")
+    summary["ClassifiedPosition"] = summary["Position"].map(
+        lambda p: str(int(p)) if pd.notna(p) else pd.NA
+    )
+    summary["ClassifiedPositionInClass"] = summary["PositionInClass"].map(
+        lambda p: str(int(p)) if pd.notna(p) else pd.NA
+    )
+
+    columns: dict[str, pd.Series] = {}
+    for name, dtype in RESULTS_COLUMNS.items():
+        if name in summary.columns:
+            columns[name] = summary[name].reset_index(drop=True).astype(dtype)
+        else:
+            columns[name] = _empty_column(dtype, pd.RangeIndex(len(summary)))
+    return SessionResults(columns, session=session)

endurancepy/alkamel/client.py

@@ -0,0 +1,69 @@
+"""HTTP client and URL construction for the Al Kamel results portals.
+
+Verified file-URL template (see ``docs/analyse_fastf1.md`` §14.2)::
+
+    https://<host>/Results/<NN_YYYY>/<NN_EVENT>/
+        <NNN_SERIES>/<YYYYMMDDHHMM_SESSION>/[Hour N/]<FILE>
+
+The same structure serves every Al Kamel championship; only the host differs.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+from endurancepy.cache import Cache
+from endurancepy.logger import LOGGER
+
+#: Default request headers (identify the client honestly; be a good citizen).
+DEFAULT_HEADERS = {
+    "User-Agent": "EndurancePy (+https://github.com/RomainFl50/EndurancePy)"
+}
+
+#: Default per-request timeout, in seconds.
+REQUEST_TIMEOUT = 30
+
+
+def build_results_url(
+    host: str,
+    season: str,
+    event: str,
+    series_folder: str,
+    session: str,
+    filename: str,
+    *,
+    hour: int | str | None = None,
+) -> str:
+    """Build a download URL into a portal's ``Results`` tree.
+
+    Parameters
+    ----------
+    host:
+        Portal host, e.g. ``"fiawec.alkamelsystems.com"``.
+    season, event, series_folder, session:
+        Path components, e.g. ``"13_2024"``, ``"04_LE MANS"``, ``"267_FIA WEC"``,
+        ``"201905041330_Race"``. Spaces are URL-encoded.
+    filename:
+        The file to fetch, e.g. ``"23_Analysis_Race.CSV"``.
+    hour:
+        For races, the hour sub-folder (e.g. ``6`` -> ``"Hour 6"``).
+    """
+    parts = ["Results", season, event, series_folder, session]
+    if hour is not None:
+        parts.append(f"Hour {hour}")
+    parts.append(filename)
+    encoded = "/".join(quote(part, safe="") for part in parts)
+    return f"https://{host}/{encoded}"
+
+
+def download(url: str) -> bytes:
+    """Download a file's bytes, honouring the cache.
+
+    Uses the session returned by :meth:`endurancepy.cache.Cache.requests_session`
+    (cached unless caching is disabled).
+    """
+    LOGGER.debug("Downloading %s", url)
+    session = Cache.requests_session()
+    response = session.get(url, headers=DEFAULT_HEADERS, timeout=REQUEST_TIMEOUT)
+    response.raise_for_status()
+    return response.content