pyrox-client 0.2.2__tar.gz → 0.2.4__tar.gz

pyrox_client-0.2.4/.gitignore

@@ -0,0 +1,25 @@
+*.pyc
+
+/src/pyrox/__pycache__/
+__pycache__/
+
+site/
+dist/
+
+.env
+
+.vscode/
+
+.idea/
+
+docs/issues/
+
+ui/.env.capacitor
+ui/.env
+ui/node_modules/
+ui/ios/DerivedData/
+
+.venv*/
+node_modules/
+pyrox_duckdb
+test.sql

pyrox_client-0.2.4/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: pyrox-client
+Version: 0.2.4
+Summary: HYROX race data client – retrieve full race results via Python
+Author: Vlad Matei
+Requires-Python: >=3.12
+Requires-Dist: fsspec>=2024.2.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: pyarrow>=22.0.0
+Provides-Extra: api
+Requires-Dist: duckdb>=1.4.3; extra == 'api'
+Requires-Dist: fastapi>=0.115.0; extra == 'api'
+Requires-Dist: numpy>=1.26.4; extra == 'api'
+Requires-Dist: uvicorn[standard]>=0.30.0; extra == 'api'
+Provides-Extra: reporting
+Requires-Dist: duckdb>=1.4.3; extra == 'reporting'
+Requires-Dist: numpy>=1.26.4; extra == 'reporting'
+Description-Content-Type: text/markdown
+
+# pyrox-client
+
+Unofficial Python client for HYROX race results.
+
+![Unit Tests](https://github.com/vmatei2/pyrox-client/actions/workflows/tests.yml/badge.svg)
+![Integration Tests](https://github.com/vmatei2/pyrox-client/actions/workflows/integration.yml/badge.svg)
+[![Docs](https://img.shields.io/badge/docs-mkdocs-0b5d4a)](https://vmatei2.github.io/pyrox-client/)
+[![PyPI - Version](https://img.shields.io/pypi/v/pyrox-client.svg)](https://pypi.org/project/pyrox-client/)
+[![Wheel](https://img.shields.io/pypi/wheel/pyrox-client.svg)](https://pypi.org/project/pyrox-client/)
+
+## Install
+
+```bash
+uv pip install pyrox-client
+```
+
+or
+
+```bash
+pip install pyrox-client
+```
+
+Reporting helpers that read the generated DuckDB database are optional:
+
+```bash
+pip install "pyrox-client[reporting]"
+```
+
+## Quickstart
+
+```python
+import pyrox
+
+client = pyrox.PyroxClient()
+
+# Discover races
+races = client.list_races()
+seasons = client.list_seasons()
+locations = client.list_locations(season=8)
+years = client.list_years(season=8, location="london")
+
+# Fetch one race
+london = client.get_race(season=7, location="london")
+
+# Optional filters
+london_male_open = client.get_race(
+    season=7,
+    location="london",
+    gender="male",
+    division="open",
+)
+
+# Total time filter in minutes
+sub60 = client.get_race(season=7, location="london", total_time=60)
+range_50_60 = client.get_race(season=7, location="london", total_time=(50, 60))
+
+# Athlete lookup in a race
+athlete = client.get_athlete_in_race(
+    season=7,
+    location="london",
+    athlete_name="surname, name",
+)
+```
+
+## Core API
+
+- `list_races(season: int | None = None, force_refresh: bool = False) -> pd.DataFrame`
+- `list_seasons(force_refresh: bool = False) -> list[int]`
+- `list_locations(season: int | None = None, force_refresh: bool = False) -> list[str]`
+- `list_years(season: int | None = None, location: str | None = None, force_refresh: bool = False) -> list[int]`
+- `get_race(season, location, year=None, gender=None, division=None, total_time=None, use_cache=True) -> pd.DataFrame`
+- `get_season(season, locations=None, gender=None, division=None, max_workers=8, use_cache=True) -> pd.DataFrame`
+- `get_athlete_in_race(season, location, athlete_name, year=None, gender=None, division=None, use_cache=True) -> pd.DataFrame`
+- `clear_cache(pattern="*") -> None`
+- `cache_info() -> dict`
+
+## Mistake Recovery
+
+`RaceNotFound` includes manifest-backed suggestions when a race cannot be found:
+
+```python
+from pyrox.errors import RaceNotFound
+
+try:
+    client.get_race(season=8, location="londn")
+except RaceNotFound as exc:
+    print(exc)
+    print(exc.suggestions)
+```
+
+## Reporting Helpers
+
+The base install keeps the public client lightweight. Install the reporting extra
+before using `ReportingClient`:
+
+```python
+from pyrox.reporting import ReportingClient
+```
+
+## Documentation
+
+- Live docs: https://vmatei2.github.io/pyrox-client/
+- Client API: `docs/api.md`
+- Error model: `docs/errors.md`
+- Filters and usage notes: `docs/filters.md`
+
+## Repository Scope
+
+The PyPI package is the `pyrox` client library.
+
+This repository also contains a reporting service and UI (`pyrox_api_service/`, `ui/`) used for project workflows. Those are not part of the published `pyrox-client` wheel.
+
+Reporting-service contract note:
+
+- Athlete profile endpoints (`/api/athletes/profile` and `/api/athletes/{athlete_id}/profile`)
+  may include optional `personal_bests[*].percentile` values in `[0, 1]`.
+- `average_times[*].percentile` may also be present with the same semantics.
+- Missing percentile data is non-fatal and returned by omitting the `percentile` key
+  for that segment.
+- Profile percentile cohorts are computed against historical results in the same
+  division and gender.
+
+Maintainer-only operational docs:
+
+- `docs/maintainers/README.md`
+- `docs/maintainers/release.md`
+- `docs/maintainers/reporting-service.md`
+
+## Disclaimer
+
+Pyrox is an independent project and is not affiliated with, endorsed, or sponsored by HYROX.
+HYROX and related marks are trademarks of their respective owners and are used only for descriptive purposes.

pyrox_client-0.2.4/README.md

@@ -0,0 +1,132 @@
+# pyrox-client
+
+Unofficial Python client for HYROX race results.
+
+![Unit Tests](https://github.com/vmatei2/pyrox-client/actions/workflows/tests.yml/badge.svg)
+![Integration Tests](https://github.com/vmatei2/pyrox-client/actions/workflows/integration.yml/badge.svg)
+[![Docs](https://img.shields.io/badge/docs-mkdocs-0b5d4a)](https://vmatei2.github.io/pyrox-client/)
+[![PyPI - Version](https://img.shields.io/pypi/v/pyrox-client.svg)](https://pypi.org/project/pyrox-client/)
+[![Wheel](https://img.shields.io/pypi/wheel/pyrox-client.svg)](https://pypi.org/project/pyrox-client/)
+
+## Install
+
+```bash
+uv pip install pyrox-client
+```
+
+or
+
+```bash
+pip install pyrox-client
+```
+
+Reporting helpers that read the generated DuckDB database are optional:
+
+```bash
+pip install "pyrox-client[reporting]"
+```
+
+## Quickstart
+
+```python
+import pyrox
+
+client = pyrox.PyroxClient()
+
+# Discover races
+races = client.list_races()
+seasons = client.list_seasons()
+locations = client.list_locations(season=8)
+years = client.list_years(season=8, location="london")
+
+# Fetch one race
+london = client.get_race(season=7, location="london")
+
+# Optional filters
+london_male_open = client.get_race(
+    season=7,
+    location="london",
+    gender="male",
+    division="open",
+)
+
+# Total time filter in minutes
+sub60 = client.get_race(season=7, location="london", total_time=60)
+range_50_60 = client.get_race(season=7, location="london", total_time=(50, 60))
+
+# Athlete lookup in a race
+athlete = client.get_athlete_in_race(
+    season=7,
+    location="london",
+    athlete_name="surname, name",
+)
+```
+
+## Core API
+
+- `list_races(season: int | None = None, force_refresh: bool = False) -> pd.DataFrame`
+- `list_seasons(force_refresh: bool = False) -> list[int]`
+- `list_locations(season: int | None = None, force_refresh: bool = False) -> list[str]`
+- `list_years(season: int | None = None, location: str | None = None, force_refresh: bool = False) -> list[int]`
+- `get_race(season, location, year=None, gender=None, division=None, total_time=None, use_cache=True) -> pd.DataFrame`
+- `get_season(season, locations=None, gender=None, division=None, max_workers=8, use_cache=True) -> pd.DataFrame`
+- `get_athlete_in_race(season, location, athlete_name, year=None, gender=None, division=None, use_cache=True) -> pd.DataFrame`
+- `clear_cache(pattern="*") -> None`
+- `cache_info() -> dict`
+
+## Mistake Recovery
+
+`RaceNotFound` includes manifest-backed suggestions when a race cannot be found:
+
+```python
+from pyrox.errors import RaceNotFound
+
+try:
+    client.get_race(season=8, location="londn")
+except RaceNotFound as exc:
+    print(exc)
+    print(exc.suggestions)
+```
+
+## Reporting Helpers
+
+The base install keeps the public client lightweight. Install the reporting extra
+before using `ReportingClient`:
+
+```python
+from pyrox.reporting import ReportingClient
+```
+
+## Documentation
+
+- Live docs: https://vmatei2.github.io/pyrox-client/
+- Client API: `docs/api.md`
+- Error model: `docs/errors.md`
+- Filters and usage notes: `docs/filters.md`
+
+## Repository Scope
+
+The PyPI package is the `pyrox` client library.
+
+This repository also contains a reporting service and UI (`pyrox_api_service/`, `ui/`) used for project workflows. Those are not part of the published `pyrox-client` wheel.
+
+Reporting-service contract note:
+
+- Athlete profile endpoints (`/api/athletes/profile` and `/api/athletes/{athlete_id}/profile`)
+  may include optional `personal_bests[*].percentile` values in `[0, 1]`.
+- `average_times[*].percentile` may also be present with the same semantics.
+- Missing percentile data is non-fatal and returned by omitting the `percentile` key
+  for that segment.
+- Profile percentile cohorts are computed against historical results in the same
+  division and gender.
+
+Maintainer-only operational docs:
+
+- `docs/maintainers/README.md`
+- `docs/maintainers/release.md`
+- `docs/maintainers/reporting-service.md`
+
+## Disclaimer
+
+Pyrox is an independent project and is not affiliated with, endorsed, or sponsored by HYROX.
+HYROX and related marks are trademarks of their respective owners and are used only for descriptive purposes.

{pyrox_client-0.2.2 → pyrox_client-0.2.4}/pyproject.toml

@@ -11,33 +11,62 @@ readme = {file="README.md", content-type = "text/markdown" }
 requires-python = ">=3.12"
 dependencies = [
     "pandas>=2.3.3",
-    "fastparquet>=2024.5.0",
     "fsspec>=2024.2.0",
-    "s3fs>=2024.2.0",
-    "platformdirs>=4.2.0",
     "httpx>=0.28.1",
     "pyarrow>=22.0.0",  #  stable versions with wheels, had issues with latest
-    "statsmodels>=0.14.6",
 ]
 
-classifiers = [
-  "Programming Language :: Python :: 3.12",
-  "License :: OSI Approved :: MIT License",
-  "Operating System :: OS Independent",
+[project.optional-dependencies]
+reporting = [
+    "duckdb>=1.4.3",
+    "numpy>=1.26.4",
 ]
 
-urls."Homepage" = "https://github.com/vmatei2/pyrox-client"
-urls."Issues"   = "https://github.com/vmatei2/pyrox-client/issues"
+# Repository-local service dependencies (FastAPI service lives in pyrox_api_service/).
+api = [
+    "duckdb>=1.4.3",
+    "fastapi>=0.115.0",
+    "numpy>=1.26.4",
+    "uvicorn[standard]>=0.30.0",
+]
+
+# classifiers = [
+#   "Programming Language :: Python :: 3.12",
+#   "License :: OSI Approved :: MIT License",
+#   "Operating System :: OS Independent",
+# ]
+
+# urls."Homepage" = "https://github.com/vmatei2/pyrox-client"
+# urls."Issues"   = "https://github.com/vmatei2/pyrox-client/issues"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/pyrox"]
 
+exclude = [
+  "src/pyrox/api/**",
+  "src/pyrox/helpers.py",
+]
+
 [tool.hatch.build.targets.sdist]
 include = [
-  "src/pyrox",
   "README.md",
   "pyproject.toml",
-  "*.png"
+  "src/pyrox/**",
+]
+exclude = [
+  "src/pyrox/api/**",
+  "src/pyrox/helpers.py",
+  "**/__pycache__/**",
+  "*.pyc",
+  "ui/**",
+  "pyrox_api_service/**",
+  "scripts/**",
+  "docs/**",
+  "example_notebooks/**",
+  ".venv*/**",
+  "node_modules/**",
+  "dist/**",
+  "pyrox_duckdb",
 ]
 
 [tool.hatch.version]
@@ -46,6 +75,8 @@ path = "src/pyrox/__init__.py"
 [dependency-groups]
 dev = [
     "black>=25.11.0",
+    "duckdb>=1.4.3",
+    "fastparquet>=2024.5.0",
     "isort>=6.1.0",
     "pylint>=3.3.9",
     "pytest>=8.4.2",
@@ -56,4 +87,10 @@ dev = [
     "seaborn>=0.13.2",
     "ipykernel>=7.1.0",
     "mkdocs>=1.6.1",
+    "python-dotenv>=1.0.0",
+    "s3fs>=2024.2.0",
+    "scikit-learn>=1.8.0",
+    "statsmodels>=0.14.6",
+    "twine>=6.2.0",
+    "bs4>=0.0.2",
 ]

pyrox_client-0.2.4/src/pyrox/__init__.py

@@ -0,0 +1,14 @@
+"""Public package exports for pyrox-client."""
+
+from .core import PyroxClient
+from .errors import AthleteNotFound, PyroxError, RaceNotFound
+
+__version__ = "0.2.4"
+
+
+__all__ = [
+    "PyroxClient",
+    "PyroxError",
+    "RaceNotFound",
+    "AthleteNotFound",
+]

{pyrox_client-0.2.2 → pyrox_client-0.2.4}/src/pyrox/core.py

@@ -9,6 +9,7 @@ import io
 import json
 import logging
 import time
+from difflib import get_close_matches
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
 from threading import RLock
@@ -195,29 +196,152 @@ class PyroxClient:
         if season is not None:
             df = df[df["season"] == int(season)]
 
-        return (
-            df[["season", "location"]]
-            .drop_duplicates()
-            .sort_values(["season", "location"])
-            .reset_index(drop=True)
-        )
+        if "file_last_modified" in df.columns:
+            races = (
+                df[["season", "location", "file_last_modified"]]
+                .groupby(["season", "location"], as_index=False)["file_last_modified"]
+                .max()
+            )
+        else:
+            races = df[["season", "location"]].drop_duplicates()
+
+        return races.sort_values(["season", "location"]).reset_index(drop=True)
+
+    def list_seasons(self, force_refresh: bool = False) -> list[int]:
+        """Return sorted season values available in the manifest."""
+        df = self._get_manifest(force_refresh=force_refresh)
+        return self._unique_int_values(df, "season")
+
+    def list_locations(
+        self,
+        season: Optional[int] = None,
+        force_refresh: bool = False,
+    ) -> list[str]:
+        """Return sorted location values available in the manifest."""
+        df = self._get_manifest(force_refresh=force_refresh)
+        if season is not None and "season" in df.columns:
+            df = df[df["season"].eq(int(season))]
+        return self._unique_str_values(df, "location")
+
+    def list_years(
+        self,
+        season: Optional[int] = None,
+        location: Optional[str] = None,
+        force_refresh: bool = False,
+    ) -> list[int]:
+        """Return sorted calendar years available in the manifest."""
+        df = self._get_manifest(force_refresh=force_refresh)
+        if season is not None and "season" in df.columns:
+            df = df[df["season"].eq(int(season))]
+        if location is not None and "location" in df.columns:
+            df = df[df["location"].astype(str).str.casefold().eq(location.casefold())]
+        return self._unique_int_values(df, "year")
+
+    @staticmethod
+    def _unique_int_values(df: pd.DataFrame, column: str) -> list[int]:
+        if column not in df.columns:
+            return []
+        values = pd.to_numeric(df[column], errors="coerce").dropna()
+        return sorted({int(value) for value in values.tolist()})
+
+    @staticmethod
+    def _unique_str_values(df: pd.DataFrame, column: str) -> list[str]:
+        if column not in df.columns:
+            return []
+        values_by_key: dict[str, str] = {}
+        for value in df[column].dropna().tolist():
+            text = str(value).strip()
+            if text:
+                values_by_key.setdefault(text.casefold(), text)
+        return sorted(values_by_key.values(), key=str.casefold)
 
     def _manifest_row(
         self, season: int, location: str, year: Optional[int] = None
     ) -> pd.Series:
         df = self._get_manifest()
 
-        mask = df["season"].eq(int(season)) & df["location"].str.casefold().eq(
-            location.casefold()
-        )
+        season_mask = df["season"].eq(int(season))
+        location_mask = df["location"].astype(str).str.casefold().eq(location.casefold())
+        mask = season_mask & location_mask
         if year is not None:
             mask &= df["year"].eq(int(year))
         if not mask.any():
-            raise RaceNotFound(
-                f"No manifest entry for season={season}, location='{location}'"
-            )
+            raise self._build_manifest_not_found_error(df, season, location, year)
         return df.loc[mask].iloc[0]
 
+    def _build_manifest_not_found_error(
+        self,
+        df: pd.DataFrame,
+        season: int,
+        location: str,
+        year: Optional[int],
+    ) -> RaceNotFound:
+        available_seasons = self._unique_int_values(df, "season")
+        season_df = (
+            df[df["season"].eq(int(season))]
+            if "season" in df.columns
+            else df.iloc[0:0]
+        )
+
+        message_parts = [f"No manifest entry for season={season}, location='{location}'"]
+        if year is not None:
+            message_parts[0] += f", year={year}"
+
+        if season_df.empty:
+            if available_seasons:
+                seasons_text = ", ".join(str(value) for value in available_seasons)
+                message_parts.append(f"Available seasons: {seasons_text}.")
+            return RaceNotFound(
+                " ".join(message_parts),
+                season=season,
+                location=location,
+                year=year,
+                available_seasons=available_seasons,
+            )
+
+        available_locations = self._unique_str_values(season_df, "location")
+        location_lookup = {value.casefold(): value for value in available_locations}
+        suggestions = [
+            location_lookup[value]
+            for value in get_close_matches(
+                location.casefold(),
+                list(location_lookup),
+                n=3,
+                cutoff=0.6,
+            )
+        ]
+
+        location_df = season_df[
+            season_df["location"].astype(str).str.casefold().eq(location.casefold())
+        ]
+        if location_df.empty:
+            if suggestions:
+                message_parts.append(f"Did you mean: {', '.join(suggestions)}?")
+            return RaceNotFound(
+                " ".join(message_parts),
+                season=season,
+                location=location,
+                year=year,
+                available_seasons=available_seasons,
+                available_locations=available_locations,
+                suggestions=suggestions,
+            )
+
+        available_years = self._unique_int_values(location_df, "year")
+        if year is not None and available_years:
+            years_text = ", ".join(str(value) for value in available_years)
+            message_parts.append(f"Available years for {location}: {years_text}.")
+
+        return RaceNotFound(
+            " ".join(message_parts),
+            season=season,
+            location=location,
+            year=year,
+            available_seasons=available_seasons,
+            available_locations=available_locations,
+            available_years=available_years,
+        )
+
     def _s3_key_from_uri(self, s3_uri: str) -> str:
         if s3_uri.startswith("s3://"):
             ##  example output from splitting ['s3:', '', 'hyrox-results', 'processed', 'parquet/season=6/S6_2023_London__JGDMS4JI62E.parquet'] -- so taking 4th (due to cdn settings for bucket)
@@ -250,6 +374,15 @@ class PyroxClient:
         division: Optional[str] = None,
     ) -> pd.DataFrame:
         url = self._cdn_url_from_manifest(season, location, year)
+        return self._get_race_from_url(url, gender, division)
+
+        
+    def _get_race_from_url(
+        self,
+        url: str,
+        gender: Optional[str] = None,
+        division: Optional[str] = None,
+    ) -> pd.DataFrame:
         filters = self._filters_for_race(gender, division)
         try:
             with fsspec.open(url, "rb") as f:
@@ -264,6 +397,7 @@ class PyroxClient:
         except Exception as e:
             raise FileNotFoundError(f"CDN read failed for {url}: {e}") from e
 
+
     def get_race(
         self,
         season: int,
@@ -332,7 +466,7 @@ class PyroxClient:
 
         try:
             df = self._get_race_from_cdn(season, location, year, gender, division)
-        except (RaceNotFound, FileNotFoundError) as e:
+        except FileNotFoundError as e:
             raise FileNotFoundError(
                 f"Read failed for season{season}, location={location} - {e}"
             ) from e
@@ -514,4 +648,4 @@ def mmss_to_minutes(s: pd.Series) -> pd.Series:
     s = s.astype(str).str.strip()
     # if it's MM:SS, promote to 0:MM:SS so pandas parses it
     s = s.where(s.str.count(":") == 2, "0:" + s)
-    return pd.to_timedelta(s, errors="coerce").dt.total_seconds() / 60.0
+    return pd.to_timedelta(s, errors="coerce").dt.total_seconds() / 60.0

{pyrox_client-0.2.2 → pyrox_client-0.2.4}/src/pyrox/errors.py

@@ -8,6 +8,8 @@ Expose a small, predictable hierarchy so users can:
 
 from __future__ import annotations
 
+from typing import Optional
+
 
 __all__ = [
     "PyroxError",
@@ -29,6 +31,27 @@ class RaceNotFound(PyroxError, LookupError):
     Inherit from LookupError to feel natural in 'lookup' code paths.
     """
 
+    def __init__(
+        self,
+        message: str,
+        *,
+        season: Optional[int] = None,
+        location: Optional[str] = None,
+        year: Optional[int] = None,
+        available_seasons: Optional[list[int]] = None,
+        available_locations: Optional[list[str]] = None,
+        available_years: Optional[list[int]] = None,
+        suggestions: Optional[list[str]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.season = season
+        self.location = location
+        self.year = year
+        self.available_seasons = available_seasons or []
+        self.available_locations = available_locations or []
+        self.available_years = available_years or []
+        self.suggestions = suggestions or []
+
 
 class AthleteNotFound(PyroxError, LookupError):
     """
@@ -37,4 +60,3 @@ class AthleteNotFound(PyroxError, LookupError):
     Inerit from LookupError to feel natural in 'lookup' code paths.
     """
 
-