speedhive-tools 0.1.0__tar.gz

speedhive_tools-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include requirements.txt
+recursive-include examples *
+recursive-include examples/processing *
+recursive-include mylaps_client *

speedhive_tools-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: speedhive-tools
+Version: 0.1.0
+Summary: Utilities for the MyLaps Event Results API
+Home-page: https://github.com/ncrosty58/speedhive-tools
+Author: Nathan Crosty
+Author-email: ncrosty58@example.com
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<0.29.0,>=0.23.0
+Requires-Dist: attrs>=22.2.0
+Requires-Dist: python-dateutil>=2.8.0
+
+# speedhive-tools
+
+Utilities and examples for interacting with the MyLaps / Event Results API using a locally-generated OpenAPI Python client.
+
+This repository contains a generated client under `mylaps_client/` and example scripts that demonstrate how to list events and export session announcements for an organization.
+
+Table of contents
+
+- Quick start
+- Examples
+- Exporter details
+- Troubleshooting
+- Regenerating the client
+- Contributing
+
+Quick start
+
+Requirements
+- Python 3.10+
+- `pip install -r requirements.txt`
+
+Create and activate a virtualenv, then install:
+
+```bash
+python -m venv .venv
+# speedhive-tools
+
+Small, practical tools for the MyLaps / Event Results API using a locally-generated OpenAPI Python client.
+
+Quick overview
+- Generated client: `mylaps_client/` (importable as `event_results_client` when running examples from the repo root).
+- Examples live in `examples/` and are runnable without installing the client.
+# 🚀 speedhive-tools
+
+Small, playful utilities for the MyLaps Event Results API — examples included ✨
+
+Why this repo
+---------------------------------
+- A locally-generated OpenAPI client lives in `mylaps_client/`.
+- Example scripts show common tasks (list events, export announcements, fetch laps/results).
+
+Quick start — get running ⚡
+---------------------------------
+Requirements: Python 3.10+
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Client usage (one-line) 🧩
+---------------------------------
+Import and construct a client:
+
+```python
+from event_results_client import AuthenticatedClient
+client = AuthenticatedClient(base_url="https://api2.mylaps.com", token="YOUR_TOKEN")
+
+Regenerating the client
+
+If the OpenAPI spec changes you can regenerate the client and drop it into `mylaps_client/`.
+
+<!-- Lightweight README for speedhive-tools -->
+# speedhive-tools
+
+Small utilities to interact with the MyLaps Event Results API using a locally-generated OpenAPI client.
+
+**Quick Start**
+- Requirements: Python 3.10+ and a virtualenv.
+- Install:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+**What’s in this repo**
+- `mylaps_client/` — generated OpenAPI Python client (importable as `event_results_client` when running examples from the repo root).
+- `examples/` — short, runnable examples that demonstrate common API tasks.
+- `examples/processing/` — small data-processing helpers (convert NDJSON -> CSV/SQLite).
+- `output/` — suggested place for example outputs (this directory is in `.gitignore`).
+
+**Common commands**
+- List events for an org:
+  ```bash
+  python examples/list_events_by_org.py 30476 --verbose
+  ```
+- Export announcements for an org (per-event JSON files):
+  ```bash
+  python examples/export_announcements_by_org.py 30476 --output ./output/announcements --verbose
+  ```
+- Full dump (stream NDJSON, gzipped by default):
+  ```bash
+  python examples/export_full_dump.py --org 30476 --output ./output/full_dump --verbose
+  ```
+
+**Process exported data**
+- Extract laps to CSV:
+  ```bash
+  python examples/processing/extract_laps_to_csv.py --input output/full_dump/30476 --out output/full_dump/30476/laps_flat.csv
+  ```
+- Import laps to SQLite:
+  ```bash
+  python examples/processing/ndjson_to_sqlite.py --input output/full_dump/30476/laps.ndjson.gz --out output/full_dump/30476/dump.db
+  sqlite3 output/full_dump/30476/dump.db "SELECT COUNT(*) FROM laps;"
+  ```
+
+**Notes & tips**
+- Run examples from the repository root so the local `mylaps_client` package is on `sys.path`.
+- Use `--token` on example CLIs when endpoints require authentication.
+- The exporter supports `--max-events`, `--max-sessions-per-event`, and `--dry-run` for low-memory testing.
+- Long runs write a checkpoint file (`outdir/.checkpoint.json`) so you can resume after interruptions.
+
+**Regenerating the client**
+If the API OpenAPI spec changes, regenerate the client and place it under `mylaps_client/`.
+
+Example using `openapi-python-client`:
+```bash
+python -m openapi_python_client generate --url https://api2.mylaps.com/v3/api-docs --output-path ./mylaps_client
+```
+
+**Need help or next steps?**
+- I can add CI tests with recorded fixtures, retries and backoff for the exporter, or more processing utilities (aggregation, progress summaries). Tell me which and I’ll implement it.
+
+High-level steps (example using `openapi-python-client`):
+
+```bash
+python -m openapi_python_client generate --url https://api2.mylaps.com/v3/api-docs --output-path ./mylaps_client
+```
+
+After regenerating, run the examples to validate and adjust any sanitization logic if payload shapes changed.
+
+Testing and CI
+
+- There is a minimal import test under `tests/` to ensure the generated package imports correctly. Add unit tests or mocks if you want to run the exporter in CI.
+
+Contributing and next steps
+
+If you'd like I can implement any of the following (pick one or more):
+
+- Add a `--concurrency` CLI flag to control parallelism.
+- Add an `--aggregate` flag to emit a single combined file for all events instead of per-event files.
+- Add a unit test that verifies exporter output using recorded fixtures (recommended for CI).
+
+
+
+

speedhive_tools-0.1.0/README.md

@@ -0,0 +1,149 @@
+# speedhive-tools
+
+Utilities and examples for interacting with the MyLaps / Event Results API using a locally-generated OpenAPI Python client.
+
+This repository contains a generated client under `mylaps_client/` and example scripts that demonstrate how to list events and export session announcements for an organization.
+
+Table of contents
+
+- Quick start
+- Examples
+- Exporter details
+- Troubleshooting
+- Regenerating the client
+- Contributing
+
+Quick start
+
+Requirements
+- Python 3.10+
+- `pip install -r requirements.txt`
+
+Create and activate a virtualenv, then install:
+
+```bash
+python -m venv .venv
+# speedhive-tools
+
+Small, practical tools for the MyLaps / Event Results API using a locally-generated OpenAPI Python client.
+
+Quick overview
+- Generated client: `mylaps_client/` (importable as `event_results_client` when running examples from the repo root).
+- Examples live in `examples/` and are runnable without installing the client.
+# 🚀 speedhive-tools
+
+Small, playful utilities for the MyLaps Event Results API — examples included ✨
+
+Why this repo
+---------------------------------
+- A locally-generated OpenAPI client lives in `mylaps_client/`.
+- Example scripts show common tasks (list events, export announcements, fetch laps/results).
+
+Quick start — get running ⚡
+---------------------------------
+Requirements: Python 3.10+
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Client usage (one-line) 🧩
+---------------------------------
+Import and construct a client:
+
+```python
+from event_results_client import AuthenticatedClient
+client = AuthenticatedClient(base_url="https://api2.mylaps.com", token="YOUR_TOKEN")
+
+Regenerating the client
+
+If the OpenAPI spec changes you can regenerate the client and drop it into `mylaps_client/`.
+
+<!-- Lightweight README for speedhive-tools -->
+# speedhive-tools
+
+Small utilities to interact with the MyLaps Event Results API using a locally-generated OpenAPI client.
+
+**Quick Start**
+- Requirements: Python 3.10+ and a virtualenv.
+- Install:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+**What’s in this repo**
+- `mylaps_client/` — generated OpenAPI Python client (importable as `event_results_client` when running examples from the repo root).
+- `examples/` — short, runnable examples that demonstrate common API tasks.
+- `examples/processing/` — small data-processing helpers (convert NDJSON -> CSV/SQLite).
+- `output/` — suggested place for example outputs (this directory is in `.gitignore`).
+
+**Common commands**
+- List events for an org:
+  ```bash
+  python examples/list_events_by_org.py 30476 --verbose
+  ```
+- Export announcements for an org (per-event JSON files):
+  ```bash
+  python examples/export_announcements_by_org.py 30476 --output ./output/announcements --verbose
+  ```
+- Full dump (stream NDJSON, gzipped by default):
+  ```bash
+  python examples/export_full_dump.py --org 30476 --output ./output/full_dump --verbose
+  ```
+
+**Process exported data**
+- Extract laps to CSV:
+  ```bash
+  python examples/processing/extract_laps_to_csv.py --input output/full_dump/30476 --out output/full_dump/30476/laps_flat.csv
+  ```
+- Import laps to SQLite:
+  ```bash
+  python examples/processing/ndjson_to_sqlite.py --input output/full_dump/30476/laps.ndjson.gz --out output/full_dump/30476/dump.db
+  sqlite3 output/full_dump/30476/dump.db "SELECT COUNT(*) FROM laps;"
+  ```
+
+**Notes & tips**
+- Run examples from the repository root so the local `mylaps_client` package is on `sys.path`.
+- Use `--token` on example CLIs when endpoints require authentication.
+- The exporter supports `--max-events`, `--max-sessions-per-event`, and `--dry-run` for low-memory testing.
+- Long runs write a checkpoint file (`outdir/.checkpoint.json`) so you can resume after interruptions.
+
+**Regenerating the client**
+If the API OpenAPI spec changes, regenerate the client and place it under `mylaps_client/`.
+
+Example using `openapi-python-client`:
+```bash
+python -m openapi_python_client generate --url https://api2.mylaps.com/v3/api-docs --output-path ./mylaps_client
+```
+
+**Need help or next steps?**
+- I can add CI tests with recorded fixtures, retries and backoff for the exporter, or more processing utilities (aggregation, progress summaries). Tell me which and I’ll implement it.
+
+High-level steps (example using `openapi-python-client`):
+
+```bash
+python -m openapi_python_client generate --url https://api2.mylaps.com/v3/api-docs --output-path ./mylaps_client
+```
+
+After regenerating, run the examples to validate and adjust any sanitization logic if payload shapes changed.
+
+Testing and CI
+
+- There is a minimal import test under `tests/` to ensure the generated package imports correctly. Add unit tests or mocks if you want to run the exporter in CI.
+
+Contributing and next steps
+
+If you'd like I can implement any of the following (pick one or more):
+
+- Add a `--concurrency` CLI flag to control parallelism.
+- Add an `--aggregate` flag to emit a single combined file for all events instead of per-event files.
+- Add a unit test that verifies exporter output using recorded fixtures (recommended for CI).
+
+
+
+

speedhive_tools-0.1.0/examples/__init__.py

@@ -0,0 +1,3 @@
+"""Package marker for examples to allow importing example modules in tests."""
+
+__all__ = []

speedhive_tools-0.1.0/examples/export_announcements_by_org.py

@@ -0,0 +1,185 @@
+"""Export track announcements for all sessions in all events for an organization.
+
+Writes one combined JSON file per event containing only sessions that have announcements.
+
+Usage:
+    python examples/export_announcements_by_org.py 30476 --output ./announcements --verbose
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import asyncio
+from pathlib import Path
+from typing import Any, Iterable, List, Optional
+
+# Make generated client importable when running from any cwd
+REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "mylaps_client"))
+
+from event_results_client import Client, AuthenticatedClient
+from event_results_client.api.organization_controller.get_event_list import asyncio_detailed as get_events_for_org_async
+from event_results_client.api.event_controller.get_session_list import asyncio_detailed as get_sessions_for_event_async
+from event_results_client.api.session_controller.get_announcements import asyncio_detailed as get_announcements_for_session_async
+from event_results_client.models.session import Session
+from event_results_client.models.run_announcements import RunAnnouncements
+
+
+def build_client(token: Optional[str] = None) -> Client:
+    if token:
+        return AuthenticatedClient(base_url="https://api2.mylaps.com", token=token)
+    return Client(base_url="https://api2.mylaps.com")
+
+
+def safe_load_json(raw: bytes) -> Any:
+    try:
+        return json.loads(raw)
+    except Exception:
+        return None
+
+
+def sanitize_for_model(d: dict) -> dict:
+    # Fix a few known API quirks: nested `sessions` or similar fields set to null
+    if d.get("sessions") is None:
+        d = dict(d)
+        d["sessions"] = {}
+    return d
+
+
+def _has_announcements(payload: Any) -> bool:
+    if payload is None:
+        return False
+    if isinstance(payload, list):
+        return len(payload) > 0
+    if isinstance(payload, dict):
+        rows = payload.get("rows")
+        if rows is None:
+            # dict payload but no rows; treat empty dict as no announcements
+            return bool(payload)
+        return bool(rows)
+    return False
+
+
+async def export_announcements_for_org_async(org_id: int, out_dir: Path, client: Client, verbose: bool = False, concurrency: int = 20) -> None:
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    # Get events for the organization (async)
+    resp = await get_events_for_org_async(org_id, client=client)
+    if verbose:
+        print(f"[DEBUG] events request status={getattr(resp,'status_code',None)} size={len(resp.content) if resp.content else 0}")
+
+    if not getattr(resp, "content", None):
+        print("No events returned for org id", org_id)
+        return
+
+    events_payload = safe_load_json(resp.content)
+    if not isinstance(events_payload, Iterable):
+        print("Unexpected events payload format")
+        return
+
+    events = list(events_payload)
+
+    sem = asyncio.Semaphore(concurrency)
+
+    async def fetch_announcements_for_session(session_dict: dict) -> Optional[dict]:
+        sid = session_dict.get("id")
+        sname = session_dict.get("name")
+        if sid is None:
+            return None
+        async with sem:
+            aresp = await get_announcements_for_session_async(sid, client=client)
+        if not getattr(aresp, "content", None):
+            return None
+        payload = safe_load_json(aresp.content)
+        if not _has_announcements(payload):
+            return None
+        # Normalize payload using generated model when possible
+        if isinstance(payload, dict) and "rows" in payload:
+            try:
+                run_ann = RunAnnouncements.from_dict(payload)
+                result = run_ann.to_dict()
+            except Exception:
+                result = payload
+        else:
+            result = payload
+        return {"id": sid, "name": sname, "announcements": result}
+
+    for ev in events:
+        ev_id = ev.get("id")
+        ev_name = ev.get("name") or f"event_{ev_id}"
+        if verbose:
+            print(f"Processing event {ev_id}: {ev_name}")
+
+        # Get sessions for event (async)
+        sresp = await get_sessions_for_event_async(ev_id, client=client)
+        if verbose:
+            print(f"[DEBUG] sessions request status={getattr(sresp,'status_code',None)} size={len(sresp.content) if sresp.content else 0}")
+        if not getattr(sresp, "content", None):
+            if verbose:
+                print(f" No sessions for event {ev_id}")
+            continue
+
+        sess_payload = safe_load_json(sresp.content)
+        if not isinstance(sess_payload, (dict, list)):
+            if verbose:
+                print(f" Unexpected sessions payload for event {ev_id}")
+            continue
+
+        raw_sessions: List[dict] = []
+        if isinstance(sess_payload, list):
+            raw_sessions = list(sess_payload)
+        elif isinstance(sess_payload, dict):
+            if isinstance(sess_payload.get("sessions"), list):
+                raw_sessions.extend(sess_payload.get("sessions", []))
+            for g in sess_payload.get("groups", []):
+                for s_item in g.get("sessions", []) if isinstance(g.get("sessions"), list) else []:
+                    raw_sessions.append(s_item)
+
+        # Launch concurrent fetches for announcements
+        tasks = [asyncio.create_task(fetch_announcements_for_session(s)) for s in raw_sessions if isinstance(s, dict) and s.get("id")]
+        results = await asyncio.gather(*tasks)
+        # Filter out sessions with no announcements
+        sessions_with_ann = [r for r in results if r]
+
+        if not sessions_with_ann:
+            if verbose:
+                print(f" No announcements found for any sessions in event {ev_id}")
+            continue
+
+        ev_out = {"id": ev_id, "name": ev_name, "sessions": sessions_with_ann}
+        out_file = out_dir / f"event_{ev_id}_announcements.json"
+        with out_file.open("w", encoding="utf-8") as f:
+            json.dump(ev_out, f, ensure_ascii=False, indent=2)
+        if verbose:
+            print(f" Wrote event announcements to {out_file}")
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description="Export announcements for all sessions in events for an org")
+    parser.add_argument("org_id", type=int, help="Organization id")
+    parser.add_argument("--output", "-o", default="./output/announcements", help="Output directory")
+    parser.add_argument("--token", help="API token for authenticated endpoints", default=None)
+    parser.add_argument("--verbose", action="store_true", help="Verbose debug output")
+    parser.add_argument("--concurrency", "-c", type=int, default=20, help="Maximum concurrent requests")
+    args = parser.parse_args(argv)
+
+    client = build_client(token=args.token)
+    out_dir = Path(args.output)
+
+    async def _run():
+        async with client:
+            await export_announcements_for_org_async(
+                args.org_id,
+                out_dir,
+                client=client,
+                verbose=args.verbose,
+                concurrency=args.concurrency,
+            )
+
+    asyncio.run(_run())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())