arccos-api 0.1.4__tar.gz → 0.2.0__tar.gz

{arccos_api-0.1.4 → arccos_api-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arccos-api
-Version: 0.1.4
+Version: 0.2.0
 Summary: Unofficial Python CLI and client library for the Arccos Golf API
 Author: Paul Frederiksen
 License: MIT
@@ -76,14 +76,17 @@ arccos clubs       # smart club distances
 | Command | Description |
 |---------|-------------|
 | `arccos login` | Authenticate and cache credentials to `~/.arccos_creds.json` |
-| `arccos rounds` | List recent rounds with date, score, holes, course |
+| `arccos rounds` | List recent rounds with date, score, +/-, course name |
 | `arccos round <id>` | Hole-by-hole detail (score, putts, FIR, GIR) with totals |
 | `arccos handicap` | Handicap breakdown by category (overall, driving, approach, etc.) |
 | `arccos clubs` | Smart club distances with make/model, range, and shot count |
+| `arccos bests` | All-time personal bests (lowest score, longest drive, etc.) |
+| `arccos overview` | Performance summary — scoring avg + handicap breakdown |
+| `arccos scoring` | Scoring trend with visual bar chart |
 | `arccos courses` | List all courses you've played |
 | `arccos pace` | Pace of play analysis by course (color-coded) |
 | `arccos stats <id>` | Strokes gained analysis for a round |
-| `arccos export` | Export rounds to JSON, CSV, or NDJSON |
+| `arccos export` | Export rounds to JSON, CSV, or NDJSON (`--detail` for hole data) |
 | `arccos logout` | Clear cached credentials |
 
 Every command supports `--json` for raw JSON output and `--help` for usage info.
@@ -92,9 +95,10 @@ Every command supports `--json` for raw JSON output and `--help` for usage info.
 
 ```bash
 # Rounds
-arccos rounds                         # last 20 rounds
+arccos rounds                         # last 20 rounds (with +/- and course names)
 arccos rounds -n 50                   # last 50
 arccos rounds --after 2025-01-01      # filter by date
+arccos rounds --course "pebble"       # filter by course name (substring)
 arccos rounds --json                  # raw JSON
 
 # Round detail
@@ -108,6 +112,11 @@ arccos handicap --history             # revision history
 arccos clubs                          # active clubs with make/model
 arccos clubs --after 2025-01-01       # distances from this year only
 
+# Performance
+arccos bests                          # all-time personal bests
+arccos overview                       # scoring avg + handicap breakdown
+arccos scoring                        # scoring trend with bar chart
+
 # Courses
 arccos courses                        # all courses played
 
@@ -117,6 +126,7 @@ arccos pace -n 20                     # last 20 rounds only
 
 # Export
 arccos export -f csv -o rounds.csv    # export to CSV file
+arccos export --detail                # include hole-by-hole data
 arccos export -f json                 # dump JSON to stdout
 arccos export -f ndjson               # newline-delimited JSON
 ```
@@ -237,7 +247,7 @@ for club in bag["clubs"]:
 
 # Courses played
 for course in client.courses.played():
-    print(f"  {course.get('courseName', course['courseId'])}")
+    print(f"  {course.get('name', course['courseId'])}")
 
 # Pace of play analysis
 pace = client.rounds.pace_of_play()
@@ -289,12 +299,11 @@ All data calls go to `https://api.arccosgolf.com` with `Authorization: Bearer <t
 {
   "roundId": 18294051,
   "courseId": 12450,
-  "courseName": "Torrey Pines",
+  "courseVersion": 4,
   "startTime": "2025-09-14T15:30:00.000000Z",
   "endTime": "2025-09-14T20:15:00.000000Z",
   "noOfShots": 79,
   "noOfHoles": 18,
-  "overUnder": 7,
   "holes": [
     {
       "holeId": 1, "noOfShots": 4, "putts": 2,
@@ -334,7 +343,7 @@ python3 -m venv .venv
 source .venv/bin/activate
 pip install -e ".[dev]"
 
-pytest                  # tests with coverage (90%+, 96 tests)
+pytest                  # tests with coverage (88%+, 132 tests)
 ruff check arccos/      # lint
 mypy arccos/            # type check
 ```

{arccos_api-0.1.4 → arccos_api-0.2.0}/README.md

@@ -42,14 +42,17 @@ arccos clubs       # smart club distances
 | Command | Description |
 |---------|-------------|
 | `arccos login` | Authenticate and cache credentials to `~/.arccos_creds.json` |
-| `arccos rounds` | List recent rounds with date, score, holes, course |
+| `arccos rounds` | List recent rounds with date, score, +/-, course name |
 | `arccos round <id>` | Hole-by-hole detail (score, putts, FIR, GIR) with totals |
 | `arccos handicap` | Handicap breakdown by category (overall, driving, approach, etc.) |
 | `arccos clubs` | Smart club distances with make/model, range, and shot count |
+| `arccos bests` | All-time personal bests (lowest score, longest drive, etc.) |
+| `arccos overview` | Performance summary — scoring avg + handicap breakdown |
+| `arccos scoring` | Scoring trend with visual bar chart |
 | `arccos courses` | List all courses you've played |
 | `arccos pace` | Pace of play analysis by course (color-coded) |
 | `arccos stats <id>` | Strokes gained analysis for a round |
-| `arccos export` | Export rounds to JSON, CSV, or NDJSON |
+| `arccos export` | Export rounds to JSON, CSV, or NDJSON (`--detail` for hole data) |
 | `arccos logout` | Clear cached credentials |
 
 Every command supports `--json` for raw JSON output and `--help` for usage info.
@@ -58,9 +61,10 @@ Every command supports `--json` for raw JSON output and `--help` for usage info.
 
 ```bash
 # Rounds
-arccos rounds                         # last 20 rounds
+arccos rounds                         # last 20 rounds (with +/- and course names)
 arccos rounds -n 50                   # last 50
 arccos rounds --after 2025-01-01      # filter by date
+arccos rounds --course "pebble"       # filter by course name (substring)
 arccos rounds --json                  # raw JSON
 
 # Round detail
@@ -74,6 +78,11 @@ arccos handicap --history             # revision history
 arccos clubs                          # active clubs with make/model
 arccos clubs --after 2025-01-01       # distances from this year only
 
+# Performance
+arccos bests                          # all-time personal bests
+arccos overview                       # scoring avg + handicap breakdown
+arccos scoring                        # scoring trend with bar chart
+
 # Courses
 arccos courses                        # all courses played
 
@@ -83,6 +92,7 @@ arccos pace -n 20                     # last 20 rounds only
 
 # Export
 arccos export -f csv -o rounds.csv    # export to CSV file
+arccos export --detail                # include hole-by-hole data
 arccos export -f json                 # dump JSON to stdout
 arccos export -f ndjson               # newline-delimited JSON
 ```
@@ -203,7 +213,7 @@ for club in bag["clubs"]:
 
 # Courses played
 for course in client.courses.played():
-    print(f"  {course.get('courseName', course['courseId'])}")
+    print(f"  {course.get('name', course['courseId'])}")
 
 # Pace of play analysis
 pace = client.rounds.pace_of_play()
@@ -255,12 +265,11 @@ All data calls go to `https://api.arccosgolf.com` with `Authorization: Bearer <t
 {
   "roundId": 18294051,
   "courseId": 12450,
-  "courseName": "Torrey Pines",
+  "courseVersion": 4,
   "startTime": "2025-09-14T15:30:00.000000Z",
   "endTime": "2025-09-14T20:15:00.000000Z",
   "noOfShots": 79,
   "noOfHoles": 18,
-  "overUnder": 7,
   "holes": [
     {
       "holeId": 1, "noOfShots": 4, "putts": 2,
@@ -300,7 +309,7 @@ python3 -m venv .venv
 source .venv/bin/activate
 pip install -e ".[dev]"
 
-pytest                  # tests with coverage (90%+, 96 tests)
+pytest                  # tests with coverage (88%+, 132 tests)
 ruff check arccos/      # lint
 mypy arccos/            # type check
 ```

{arccos_api-0.1.4 → arccos_api-0.2.0}/arccos/__init__.py

@@ -9,6 +9,8 @@ Quick start:
     print(client.handicap.current())
 """
 
+from importlib.metadata import version as _pkg_version
+
 from .auth import ArccosAuth
 from .client import ArccosClient
 from .exceptions import (
@@ -19,7 +21,7 @@ from .exceptions import (
     ArccosRateLimitError,
 )
 
-__version__ = "0.1.0"
+__version__ = _pkg_version("arccos-api")
 __all__ = [
     "ArccosClient",
     "ArccosAuth",

{arccos_api-0.1.4 → arccos_api-0.2.0}/arccos/_http.py

@@ -2,11 +2,14 @@
 Internal HTTP client for the Arccos API.
 
 All API calls share a single requests.Session with automatic token refresh.
+Retries transient failures (429, 5xx, timeouts) with exponential backoff.
 """
 
 from __future__ import annotations
 
 import logging
+import os
+import time
 from typing import Any
 
 import requests
@@ -17,6 +20,9 @@ from .exceptions import raise_for_status
 logger = logging.getLogger(__name__)
 
 API_BASE = "https://api.arccosgolf.com"
+DEFAULT_TIMEOUT = 15
+MAX_RETRIES = 3
+RETRY_BACKOFF = 1.0  # seconds; doubles each retry
 
 
 class HttpClient:
@@ -26,6 +32,7 @@ class HttpClient:
     - Prepends the API base URL
     - Injects the ``Authorization: Bearer`` header on every request
     - Auto-refreshes the JWT when expired
+    - Retries on transient failures (429, 5xx, timeouts)
     - Raises typed :mod:`arccos.exceptions` for non-2xx responses
     """
 
@@ -37,6 +44,7 @@ class HttpClient:
             "Content-Type": "application/json",
             "Accept":       "application/json",
         })
+        self._timeout = int(os.environ.get("ARCCOS_TIMEOUT", DEFAULT_TIMEOUT))
 
     # ------------------------------------------------------------------
     # Public interface
@@ -90,11 +98,44 @@ class HttpClient:
         url = f"{API_BASE}{path}"
         logger.debug("%s %s", method, url)
 
-        resp = self._session.request(
-            method, url, headers=headers, timeout=15, verify=True, **kwargs
-        )
-        raise_for_status(resp)
-
-        if resp.content:
-            return resp.json()
-        return {}
+        last_exc: Exception | None = None
+        for attempt in range(MAX_RETRIES):
+            try:
+                resp = self._session.request(
+                    method, url, headers=headers,
+                    timeout=self._timeout, verify=True, **kwargs,
+                )
+            except requests.exceptions.Timeout as exc:
+                last_exc = exc
+                self._backoff(attempt)
+                continue
+            except requests.exceptions.ConnectionError as exc:
+                last_exc = exc
+                self._backoff(attempt)
+                continue
+
+            if resp.ok:
+                if resp.content:
+                    return resp.json()
+                return {}
+
+            # Retry on 429 and 5xx; raise immediately on other errors
+            if resp.status_code == 429 or resp.status_code >= 500:
+                try:
+                    raise_for_status(resp)
+                except Exception as exc:
+                    last_exc = exc
+                    self._backoff(attempt)
+                    continue
+
+            # Non-retryable error (4xx other than 429)
+            raise_for_status(resp)
+
+        # Exhausted retries
+        raise last_exc  # type: ignore[misc]
+
+    @staticmethod
+    def _backoff(attempt: int) -> None:
+        delay = RETRY_BACKOFF * (2 ** attempt)
+        logger.warning("Retrying in %.1fs (attempt %d/%d)", delay, attempt + 1, MAX_RETRIES)
+        time.sleep(delay)

arccos_api-0.2.0/arccos/cli/__init__.py

@@ -0,0 +1,54 @@
+"""
+arccos CLI — pull your Arccos Golf data from the terminal.
+
+Uses the reverse-engineered Arccos Golf API. Not affiliated with Arccos Golf LLC.
+"""
+
+from __future__ import annotations
+
+import click
+
+from . import auth, rounds, stats
+
+
+@click.group()
+@click.version_option(package_name="arccos-api", prog_name="arccos")
+def cli():
+    """
+    \b
+    arccos — Your Arccos Golf data in the terminal.
+
+    \b
+    Quick start:
+      arccos login                 Authenticate and save credentials
+      arccos rounds                Your recent rounds
+      arccos round <id>            Hole-by-hole round detail
+      arccos handicap              Current handicap index
+      arccos clubs                 Smart club distances
+      arccos courses               Courses you've played
+      arccos pace                  Pace of play by course
+      arccos stats                 Strokes gained analysis
+      arccos bests                 Personal bests (all-time records)
+      arccos overview              Overall stats summary
+      arccos scoring               Scoring trend over recent rounds
+      arccos export                Export rounds to JSON/CSV
+      arccos logout                Clear cached credentials
+
+    \b
+    Credentials are cached in ~/.arccos_creds.json after first login.
+    Set ARCCOS_EMAIL and ARCCOS_PASSWORD to skip the prompts.
+    """
+
+
+# Register all command submodules
+auth.register(cli)
+rounds.register(cli)
+stats.register(cli)
+
+
+def main():
+    cli()
+
+
+if __name__ == "__main__":
+    main()

arccos_api-0.2.0/arccos/cli/_helpers.py

@@ -0,0 +1,81 @@
+"""Shared helpers for CLI commands."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+import click
+from rich.console import Console
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def _get_client():
+    """Build an ArccosClient from env vars or cached creds, with a friendly error."""
+    from arccos import ArccosClient
+    from arccos.exceptions import ArccosAuthError
+
+    email    = os.environ.get("ARCCOS_EMAIL")
+    password = os.environ.get("ARCCOS_PASSWORD")
+
+    try:
+        return ArccosClient(email=email, password=password)
+    except ArccosAuthError as e:
+        err_console.print(f"[red]Auth failed:[/red] {e}")
+        err_console.print("Run [bold]arccos login[/bold] or set ARCCOS_EMAIL and ARCCOS_PASSWORD.")
+        sys.exit(1)
+    except ValueError:
+        err_console.print(
+            "[red]Not logged in.[/red] Run [bold]arccos login[/bold] first, or set "
+            "ARCCOS_EMAIL and ARCCOS_PASSWORD environment variables."
+        )
+        sys.exit(1)
+
+
+def _output_json(data):
+    click.echo(json.dumps(data, indent=2))
+
+
+def _flag(minutes: int) -> str:
+    if minutes > 300:
+        return "\U0001f534"
+    if minutes > 270:
+        return "\U0001f7e1"
+    return "\U0001f7e2"
+
+
+def _build_course_map(client) -> tuple[dict[int, str], dict[int, int]]:
+    """Build courseId → courseName and courseId → par lookups from played courses."""
+    try:
+        played = client.courses.played()
+        names = {
+            c["courseId"]: c.get("courseName") or c.get("name") or f"Course {c['courseId']}"
+            for c in played
+        }
+        pars = {
+            c["courseId"]: c["mensPar"]
+            for c in played
+            if c.get("mensPar")
+        }
+        return names, pars
+    except Exception:
+        return {}, {}
+
+
+def _score_color(score: int, par: int | None) -> str:
+    """Return a Rich color string based on score relative to par."""
+    if par is None:
+        return "bold"
+    diff = score - par
+    if diff <= -2:
+        return "bold yellow"  # eagle or better
+    if diff == -1:
+        return "bold green"   # birdie
+    if diff == 0:
+        return "white"        # par
+    if diff == 1:
+        return "red"          # bogey
+    return "bold red"         # double+

arccos_api-0.2.0/arccos/cli/auth.py

@@ -0,0 +1,55 @@
+"""Login and logout CLI commands."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from ._helpers import console, err_console
+
+
+def register(cli: click.Group) -> None:
+    cli.add_command(login)
+    cli.add_command(logout)
+
+
+@click.command()
+@click.option("--email", envvar="ARCCOS_EMAIL", prompt="Arccos email",
+              help="Your Arccos account email.")
+@click.option("--password", envvar="ARCCOS_PASSWORD", prompt="Password",
+              hide_input=True, help="Your Arccos password.")
+def login(email: str, password: str):
+    """Authenticate and save credentials to ~/.arccos_creds.json."""
+    from arccos import ArccosClient
+    from arccos.exceptions import ArccosAuthError
+
+    with console.status("Logging in\u2026"):
+        try:
+            client = ArccosClient(email=email, password=password)
+        except ArccosAuthError as e:
+            err_console.print(f"[red]Login failed:[/red] {e}")
+            sys.exit(1)
+
+    console.print(f"[green]\u2713[/green] Logged in as [bold]{client.email}[/bold]")
+    console.print(f"  User ID: [dim]{client.user_id}[/dim]")
+    console.print("  Credentials cached at [dim]~/.arccos_creds.json[/dim]")
+
+
+@click.command()
+def logout():
+    """Clear cached credentials (~/.arccos_creds.json)."""
+    from arccos.auth import DEFAULT_CREDS_PATH
+
+    if DEFAULT_CREDS_PATH.exists():
+        DEFAULT_CREDS_PATH.unlink()
+        console.print(
+            "[green]\u2713[/green] Credentials removed from "
+            "[bold]~/.arccos_creds.json[/bold]"
+        )
+        console.print(
+            "[dim]Note: Server-side tokens are not revoked. "
+            "The access key remains valid until it expires (~180 days).[/dim]"
+        )
+    else:
+        console.print("[dim]No cached credentials found.[/dim]")