arccos-api 0.2.1__tar.gz → 0.3.0__tar.gz

{arccos_api-0.2.1 → arccos_api-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arccos-api
-Version: 0.2.1
+Version: 0.3.0
 Summary: Unofficial Python CLI and client library for the Arccos Golf API
 Author: Paul Frederiksen
 License: MIT
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -83,9 +84,11 @@ arccos clubs       # smart club distances
 | `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 courses` | List courses you've played (or `--search` any course) |
 | `arccos pace` | Pace of play analysis by course (color-coded) |
-| `arccos stats <id>` | Strokes gained analysis for a round |
+| `arccos stats` | Strokes gained analysis (defaults to latest round) |
+| `arccos club-shots <id>` | Shot history for a specific club |
+| `arccos up-and-down` | Scramble / strokes-to-get-down stats |
 | `arccos export` | Export rounds to JSON, CSV, or NDJSON (`--detail` for hole data) |
 | `arccos logout` | Clear cached credentials |
 
@@ -116,9 +119,14 @@ arccos clubs --after 2025-01-01       # distances from this year only
 arccos bests                          # all-time personal bests
 arccos overview                       # scoring avg + handicap breakdown
 arccos scoring                        # scoring trend with bar chart
+arccos up-and-down                    # scramble stats
 
 # Courses
 arccos courses                        # all courses played
+arccos courses --search "torrey"      # search any course by name
+
+# Club detail
+arccos club-shots 1                   # shot history for club ID 1
 
 # Pace of play
 arccos pace                           # all rounds, slowest courses first
@@ -208,6 +216,13 @@ export ARCCOS_PASSWORD="your_password"
 arccos rounds
 ```
 
+Other environment variables:
+
+```bash
+export ARCCOS_TIMEOUT=30       # request timeout in seconds (default: 15)
+export ARCCOS_LOG_LEVEL=DEBUG  # enable debug logging (DEBUG, INFO, WARNING)
+```
+
 > **Security note:** Environment variables may be visible in process listings (`ps`) and shell history. Prefer `arccos login` for interactive use.
 
 ## Python Library
@@ -257,6 +272,13 @@ for c in pace["course_averages"][:5]:
 
 # Personal bests
 bests = client.stats.personal_bests()
+
+# Iterate ALL rounds (auto-pagination)
+for r in client.rounds.iter_all():
+    print(r["roundId"], r["noOfShots"])
+
+# Course search
+results = client.courses.search("Torrey Pines")
 ```
 
 ## API Reference
@@ -290,7 +312,9 @@ All data calls go to `https://api.arccosgolf.com` with `Authorization: Bearer <t
 | Courses played | GET | `/users/{userId}/coursesPlayed` |
 | Course metadata | GET | `/courses/{courseId}?courseVersion=1` |
 | Course search | GET | `/v2/courses?search={query}` |
+| Club shots | GET | `/users/{userId}/bags/{bagId}/clubs/{clubId}/shots` |
 | Personal bests | GET | `/users/{userId}/personalBests?tags=allTimeBest` |
+| Strokes to get down | GET | `/v2/sga/strokes-to-get-down` |
 
 ### Key data structures
 
@@ -343,7 +367,7 @@ python3 -m venv .venv
 source .venv/bin/activate
 pip install -e ".[dev]"
 
-pytest                  # tests with coverage (88%+, 132 tests)
+pytest                  # tests with coverage (87%+, 139 tests)
 ruff check arccos/      # lint
 mypy arccos/            # type check
 ```

{arccos_api-0.2.1 → arccos_api-0.3.0}/README.md

@@ -49,9 +49,11 @@ arccos clubs       # smart club distances
 | `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 courses` | List courses you've played (or `--search` any course) |
 | `arccos pace` | Pace of play analysis by course (color-coded) |
-| `arccos stats <id>` | Strokes gained analysis for a round |
+| `arccos stats` | Strokes gained analysis (defaults to latest round) |
+| `arccos club-shots <id>` | Shot history for a specific club |
+| `arccos up-and-down` | Scramble / strokes-to-get-down stats |
 | `arccos export` | Export rounds to JSON, CSV, or NDJSON (`--detail` for hole data) |
 | `arccos logout` | Clear cached credentials |
 
@@ -82,9 +84,14 @@ arccos clubs --after 2025-01-01       # distances from this year only
 arccos bests                          # all-time personal bests
 arccos overview                       # scoring avg + handicap breakdown
 arccos scoring                        # scoring trend with bar chart
+arccos up-and-down                    # scramble stats
 
 # Courses
 arccos courses                        # all courses played
+arccos courses --search "torrey"      # search any course by name
+
+# Club detail
+arccos club-shots 1                   # shot history for club ID 1
 
 # Pace of play
 arccos pace                           # all rounds, slowest courses first
@@ -174,6 +181,13 @@ export ARCCOS_PASSWORD="your_password"
 arccos rounds
 ```
 
+Other environment variables:
+
+```bash
+export ARCCOS_TIMEOUT=30       # request timeout in seconds (default: 15)
+export ARCCOS_LOG_LEVEL=DEBUG  # enable debug logging (DEBUG, INFO, WARNING)
+```
+
 > **Security note:** Environment variables may be visible in process listings (`ps`) and shell history. Prefer `arccos login` for interactive use.
 
 ## Python Library
@@ -223,6 +237,13 @@ for c in pace["course_averages"][:5]:
 
 # Personal bests
 bests = client.stats.personal_bests()
+
+# Iterate ALL rounds (auto-pagination)
+for r in client.rounds.iter_all():
+    print(r["roundId"], r["noOfShots"])
+
+# Course search
+results = client.courses.search("Torrey Pines")
 ```
 
 ## API Reference
@@ -256,7 +277,9 @@ All data calls go to `https://api.arccosgolf.com` with `Authorization: Bearer <t
 | Courses played | GET | `/users/{userId}/coursesPlayed` |
 | Course metadata | GET | `/courses/{courseId}?courseVersion=1` |
 | Course search | GET | `/v2/courses?search={query}` |
+| Club shots | GET | `/users/{userId}/bags/{bagId}/clubs/{clubId}/shots` |
 | Personal bests | GET | `/users/{userId}/personalBests?tags=allTimeBest` |
+| Strokes to get down | GET | `/v2/sga/strokes-to-get-down` |
 
 ### Key data structures
 
@@ -309,7 +332,7 @@ python3 -m venv .venv
 source .venv/bin/activate
 pip install -e ".[dev]"
 
-pytest                  # tests with coverage (88%+, 132 tests)
+pytest                  # tests with coverage (87%+, 139 tests)
 ruff check arccos/      # lint
 mypy arccos/            # type check
 ```

{arccos_api-0.2.1 → arccos_api-0.3.0}/arccos/__init__.py

@@ -10,6 +10,7 @@ Quick start:
 """
 
 import logging as _logging
+import os as _os
 import re as _re
 from importlib.metadata import version as _pkg_version
 
@@ -40,7 +41,17 @@ class _SensitiveFilter(_logging.Filter):
         return True
 
 
-_logging.getLogger("arccos").addFilter(_SensitiveFilter())
+_logger = _logging.getLogger("arccos")
+_logger.addFilter(_SensitiveFilter())
+
+# Allow ARCCOS_LOG_LEVEL=DEBUG (or INFO, WARNING, etc.) to enable logging
+_log_level = _os.environ.get("ARCCOS_LOG_LEVEL")
+if _log_level:
+    _logger.setLevel(getattr(_logging, _log_level.upper(), _logging.WARNING))
+    if not _logger.handlers:
+        _handler = _logging.StreamHandler()
+        _handler.setFormatter(_logging.Formatter("%(name)s %(levelname)s: %(message)s"))
+        _logger.addHandler(_handler)
 
 __version__ = _pkg_version("arccos-api")
 __all__ = [

{arccos_api-0.2.1 → arccos_api-0.3.0}/arccos/cli/__init__.py

@@ -31,6 +31,8 @@ def cli():
       arccos bests                 Personal bests (all-time records)
       arccos overview              Overall stats summary
       arccos scoring               Scoring trend over recent rounds
+      arccos club-shots <id>       Shot history for a specific club
+      arccos up-and-down           Scramble / up-and-down stats
       arccos export                Export rounds to JSON/CSV
       arccos logout                Clear cached credentials
 

{arccos_api-0.2.1 → arccos_api-0.3.0}/arccos/cli/stats.py

@@ -16,10 +16,12 @@ from ._helpers import _get_client, _output_json, console, err_console
 def register(cli: click.Group) -> None:
     cli.add_command(handicap)
     cli.add_command(clubs)
+    cli.add_command(club_shots)
     cli.add_command(stats)
     cli.add_command(bests)
     cli.add_command(overview)
     cli.add_command(courses)
+    cli.add_command(up_and_down)
 
 
 # ---------------------------------------------------------------------------
@@ -462,14 +464,23 @@ def overview(limit: int, as_json: bool):
 # ---------------------------------------------------------------------------
 
 @click.command()
+@click.option("--search", "-s", default=None, help="Search for a course by name.")
 @click.option("--json", "as_json", is_flag=True, help="Output raw JSON.")
-def courses(as_json: bool):
-    """List courses you have played."""
+def courses(search: str, as_json: bool):
+    """List courses you have played, or search for any course."""
     client = _get_client()
 
     with console.status("Fetching courses\u2026"):
         data = client.courses.played()
 
+    if search:
+        needle = search.lower()
+        data = [
+            c for c in data
+            if needle in (c.get("name") or c.get("courseName") or "").lower()
+            or needle in (c.get("city") or "").lower()
+        ]
+
     if as_json:
         _output_json(data)
         return
@@ -502,3 +513,122 @@ def courses(as_json: bool):
         table.add_row(name, city, state, played, cid)
 
     console.print(table)
+
+
+# ---------------------------------------------------------------------------
+# club-shots
+# ---------------------------------------------------------------------------
+
+@click.command(name="club-shots")
+@click.argument("club_id", type=int)
+@click.option("--limit", "-n", default=20, show_default=True, help="Number of shots to show.")
+@click.option("--json", "as_json", is_flag=True, help="Output raw JSON.")
+def club_shots(club_id: int, limit: int, as_json: bool):
+    """Show individual shot history for a specific club.
+
+    CLUB_ID is the bag-specific club ID (shown in `arccos clubs --json`).
+    """
+    client = _get_client()
+
+    with console.status("Fetching shots\u2026"):
+        profile = client._http.get(f"/users/{client.user_id}")
+        bag_id = profile.get("bagId")
+        if not bag_id:
+            err_console.print("[red]Could not determine bag ID.[/red]")
+            sys.exit(1)
+        data = client.clubs.club_shots(str(bag_id), club_id, limit=limit)
+
+    if as_json:
+        _output_json(data)
+        return
+
+    if not data:
+        console.print("[dim]No shots found for this club.[/dim]")
+        return
+
+    from arccos.resources.clubs import CLUB_TYPE_NAMES
+
+    # Try to resolve club name
+    try:
+        bag = client.clubs.bag(str(bag_id))
+        bag_club = next(
+            (c for c in bag.get("clubs", []) if c["clubId"] == club_id), {}
+        )
+        club_type = bag_club.get("clubType", club_id)
+        club_name = CLUB_TYPE_NAMES.get(club_type, f"Club {club_id}")
+    except Exception:
+        club_name = f"Club {club_id}"
+
+    table = Table(
+        box=box.ROUNDED,
+        header_style="bold cyan",
+        title=f"[bold]Shot History — {club_name}[/bold] [dim]({len(data)} shots)[/dim]",
+    )
+    table.add_column("Date", style="white", no_wrap=True)
+    table.add_column("Distance", justify="right", style="green bold")
+    table.add_column("Terrain", style="dim")
+
+    for shot in data:
+        date = shot.get("shotTime", shot.get("startTime", ""))[:10]
+        dist = shot.get("distance")
+        dist_s = f"{dist:.0f}y" if dist else "\u2014"
+        terrain = str(shot.get("userStartTerrainOverride", ""))
+        table.add_row(date, dist_s, terrain)
+
+    console.print(table)
+
+
+# ---------------------------------------------------------------------------
+# up-and-down
+# ---------------------------------------------------------------------------
+
+@click.command(name="up-and-down")
+@click.option("--json", "as_json", is_flag=True, help="Output raw JSON.")
+def up_and_down(as_json: bool):
+    """Show strokes-to-get-down (up-and-down / scramble) stats."""
+    client = _get_client()
+
+    from arccos.exceptions import ArccosError
+
+    try:
+        with console.status("Fetching up-and-down stats\u2026"):
+            data = client.stats.strokes_to_get_down()
+    except ArccosError as e:
+        err_console.print(f"[red]Failed:[/red] {e}")
+        err_console.print(
+            "[dim]This endpoint may not be available for all accounts.[/dim]"
+        )
+        sys.exit(1)
+
+    if as_json:
+        _output_json(data)
+        return
+
+    if not data:
+        console.print("[dim]No up-and-down data available.[/dim]")
+        return
+
+    # Display whatever the API returns as a key-value table
+    table = Table(
+        box=box.ROUNDED,
+        header_style="bold cyan",
+        title="[bold]Strokes to Get Down[/bold]",
+    )
+    table.add_column("Stat", style="white bold")
+    table.add_column("Value", justify="right", style="bold")
+
+    for key, val in data.items():
+        if isinstance(val, (int, float)):
+            display = f"{val:.1f}" if isinstance(val, float) else str(val)
+            table.add_row(key, display)
+
+    if table.row_count == 0:
+        # Nested structure — try one level deeper
+        for section, vals in data.items():
+            if isinstance(vals, dict):
+                for k, v in vals.items():
+                    if isinstance(v, (int, float)):
+                        display = f"{v:.1f}" if isinstance(v, float) else str(v)
+                        table.add_row(f"{section}.{k}", display)
+
+    console.print(table)

{arccos_api-0.2.1 → arccos_api-0.3.0}/arccos_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arccos-api
-Version: 0.2.1
+Version: 0.3.0
 Summary: Unofficial Python CLI and client library for the Arccos Golf API
 Author: Paul Frederiksen
 License: MIT
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -83,9 +84,11 @@ arccos clubs       # smart club distances
 | `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 courses` | List courses you've played (or `--search` any course) |
 | `arccos pace` | Pace of play analysis by course (color-coded) |
-| `arccos stats <id>` | Strokes gained analysis for a round |
+| `arccos stats` | Strokes gained analysis (defaults to latest round) |
+| `arccos club-shots <id>` | Shot history for a specific club |
+| `arccos up-and-down` | Scramble / strokes-to-get-down stats |
 | `arccos export` | Export rounds to JSON, CSV, or NDJSON (`--detail` for hole data) |
 | `arccos logout` | Clear cached credentials |
 
@@ -116,9 +119,14 @@ arccos clubs --after 2025-01-01       # distances from this year only
 arccos bests                          # all-time personal bests
 arccos overview                       # scoring avg + handicap breakdown
 arccos scoring                        # scoring trend with bar chart
+arccos up-and-down                    # scramble stats
 
 # Courses
 arccos courses                        # all courses played
+arccos courses --search "torrey"      # search any course by name
+
+# Club detail
+arccos club-shots 1                   # shot history for club ID 1
 
 # Pace of play
 arccos pace                           # all rounds, slowest courses first
@@ -208,6 +216,13 @@ export ARCCOS_PASSWORD="your_password"
 arccos rounds
 ```
 
+Other environment variables:
+
+```bash
+export ARCCOS_TIMEOUT=30       # request timeout in seconds (default: 15)
+export ARCCOS_LOG_LEVEL=DEBUG  # enable debug logging (DEBUG, INFO, WARNING)
+```
+
 > **Security note:** Environment variables may be visible in process listings (`ps`) and shell history. Prefer `arccos login` for interactive use.
 
 ## Python Library
@@ -257,6 +272,13 @@ for c in pace["course_averages"][:5]:
 
 # Personal bests
 bests = client.stats.personal_bests()
+
+# Iterate ALL rounds (auto-pagination)
+for r in client.rounds.iter_all():
+    print(r["roundId"], r["noOfShots"])
+
+# Course search
+results = client.courses.search("Torrey Pines")
 ```
 
 ## API Reference
@@ -290,7 +312,9 @@ All data calls go to `https://api.arccosgolf.com` with `Authorization: Bearer <t
 | Courses played | GET | `/users/{userId}/coursesPlayed` |
 | Course metadata | GET | `/courses/{courseId}?courseVersion=1` |
 | Course search | GET | `/v2/courses?search={query}` |
+| Club shots | GET | `/users/{userId}/bags/{bagId}/clubs/{clubId}/shots` |
 | Personal bests | GET | `/users/{userId}/personalBests?tags=allTimeBest` |
+| Strokes to get down | GET | `/v2/sga/strokes-to-get-down` |
 
 ### Key data structures
 
@@ -343,7 +367,7 @@ python3 -m venv .venv
 source .venv/bin/activate
 pip install -e ".[dev]"
 
-pytest                  # tests with coverage (88%+, 132 tests)
+pytest                  # tests with coverage (87%+, 139 tests)
 ruff check arccos/      # lint
 mypy arccos/            # type check
 ```

{arccos_api-0.2.1 → arccos_api-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "arccos-api"
-version = "0.2.1"
+version = "0.3.0"
 description = "Unofficial Python CLI and client library for the Arccos Golf API"
 readme = "README.md"
 license = {text = "MIT"}
@@ -21,6 +21,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [

{arccos_api-0.2.1 → arccos_api-0.3.0}/tests/test_cli.py

@@ -726,3 +726,118 @@ class TestExportDetailFlag:
         data = json.loads(output[json_start:])
         assert "holes" in data[0]
         assert data[0]["holes"][0]["holeId"] == 1
+
+
+# ---------------------------------------------------------------------------
+# course search
+# ---------------------------------------------------------------------------
+
+class TestCourseSearchCommand:
+    @patch(_STATS_GET_CLIENT)
+    def test_courses_search(self, mock_get, runner):
+        client = _mock_client()
+        client.courses.played.return_value = [
+            {"courseId": 100, "name": "Torrey Pines South", "city": "San Diego",
+             "state": "CA"},
+            {"courseId": 101, "name": "Torrey Pines North", "city": "San Diego",
+             "state": "CA"},
+            {"courseId": 200, "name": "Augusta National", "city": "Augusta",
+             "state": "GA"},
+        ]
+        mock_get.return_value = client
+
+        result = runner.invoke(cli, ["courses", "--search", "torrey"])
+        assert result.exit_code == 0
+        assert "Torrey Pines South" in result.output
+        assert "Torrey Pines North" in result.output
+        assert "Augusta" not in result.output
+
+    @patch(_STATS_GET_CLIENT)
+    def test_courses_search_empty(self, mock_get, runner):
+        client = _mock_client()
+        client.courses.played.return_value = [
+            {"courseId": 100, "name": "Augusta National"},
+        ]
+        mock_get.return_value = client
+
+        result = runner.invoke(cli, ["courses", "--search", "xyznotfound"])
+        assert result.exit_code == 0
+        assert "No courses found" in result.output
+
+
+# ---------------------------------------------------------------------------
+# club-shots
+# ---------------------------------------------------------------------------
+
+class TestClubShotsCommand:
+    @patch(_STATS_GET_CLIENT)
+    def test_club_shots_table(self, mock_get, runner):
+        client = _mock_client()
+        client._http.get.return_value = {"bagId": "bag-1"}
+        client.clubs.club_shots.return_value = [
+            {"shotTime": "2025-06-01T12:00:00Z", "distance": 255.3,
+             "userStartTerrainOverride": 0},
+            {"shotTime": "2025-06-02T14:00:00Z", "distance": 248.1,
+             "userStartTerrainOverride": 0},
+        ]
+        client.clubs.bag.return_value = {
+            "clubs": [{"clubId": 1, "clubType": 1, "isDeleted": "F"}],
+        }
+        mock_get.return_value = client
+
+        result = runner.invoke(cli, ["club-shots", "1"])
+        assert result.exit_code == 0
+        assert "255y" in result.output
+        assert "248y" in result.output
+
+    @patch(_STATS_GET_CLIENT)
+    def test_club_shots_json(self, mock_get, runner):
+        client = _mock_client()
+        client._http.get.return_value = {"bagId": "bag-1"}
+        client.clubs.club_shots.return_value = [{"distance": 255.3}]
+        mock_get.return_value = client
+
+        result = runner.invoke(cli, ["club-shots", "--json", "1"])
+        data = json.loads(result.output)
+        assert data[0]["distance"] == 255.3
+
+    @patch(_STATS_GET_CLIENT)
+    def test_club_shots_empty(self, mock_get, runner):
+        client = _mock_client()
+        client._http.get.return_value = {"bagId": "bag-1"}
+        client.clubs.club_shots.return_value = []
+        mock_get.return_value = client
+
+        result = runner.invoke(cli, ["club-shots", "99"])
+        assert result.exit_code == 0
+        assert "No shots found" in result.output
+
+
+# ---------------------------------------------------------------------------
+# up-and-down
+# ---------------------------------------------------------------------------
+
+class TestUpAndDownCommand:
+    @patch(_STATS_GET_CLIENT)
+    def test_up_and_down_table(self, mock_get, runner):
+        client = _mock_client()
+        client.stats.strokes_to_get_down.return_value = {
+            "totalAttempts": 50,
+            "successRate": 0.42,
+            "avgProximity": 15.3,
+        }
+        mock_get.return_value = client
+
+        result = runner.invoke(cli, ["up-and-down"])
+        assert result.exit_code == 0
+        assert "50" in result.output
+
+    @patch(_STATS_GET_CLIENT)
+    def test_up_and_down_json(self, mock_get, runner):
+        client = _mock_client()
+        client.stats.strokes_to_get_down.return_value = {"totalAttempts": 50}
+        mock_get.return_value = client
+
+        result = runner.invoke(cli, ["up-and-down", "--json"])
+        data = json.loads(result.output)
+        assert data["totalAttempts"] == 50