sweatstack 0.74.0__tar.gz → 0.76.0__tar.gz

{sweatstack-0.74.0 → sweatstack-0.76.0}/.claude/skills/sweatstack-python/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: sweatstack-python
 description: >
-  Builds Python applications using the SweatStack client library (pip install sweatstack).
+  Builds Python applications using the SweatStack client library (uv add sweatstack).
   Covers authentication, activity and trace data retrieval, pandas DataFrames, Streamlit
   dashboards, FastAPI backends, user delegation, teams, and file uploads. Use when writing
   Python scripts, notebooks, Streamlit apps, or FastAPI services that access SweatStack
@@ -13,9 +13,9 @@ description: >
 
 Python client library for the SweatStack sports data platform.
 
-**Install:** `pip install sweatstack`
+**Install:** `uv add sweatstack`
 
-**Extras:** `pip install sweatstack[streamlit]` · `pip install sweatstack[fastapi]`
+**Extras:** `uv add sweatstack[streamlit]` · `uv add sweatstack[fastapi]`
 
 ## Quick Start
 

{sweatstack-0.74.0 → sweatstack-0.76.0}/.claude/skills/sweatstack-python/client.md

@@ -163,6 +163,21 @@ trace = client.create_trace(
     tags=["test"],
     notes="Lactate threshold test",
 )
+
+# Update a trace (full replace — fields not provided are set to null)
+client.update_trace(
+    trace.id,
+    timestamp=trace.timestamp,
+    lactate=2.8,               # corrected value
+    rpe=trace.rpe,             # must re-pass to keep existing values
+    heart_rate=trace.heart_rate,
+    sport=trace.sport,
+    tags=trace.tags,
+    notes=trace.notes,
+)
+
+# Delete a trace
+client.delete_trace("trace_id")
 ```
 
 ## Tests
@@ -366,6 +381,42 @@ sweatstack.authenticate()
 df = sweatstack.get_latest_activity_data()
 ```
 
+## Error Handling
+
+All errors raised by the library are subclasses of `SweatStackError`. Consumers never need to import `httpx`.
+
+```python
+from sweatstack import (
+    SweatStackError,            # base — catch-all
+    SweatStackConnectionError,  # DNS, timeout, connection refused
+    SweatStackTokenRefreshError,# token refresh failed (expired/missing)
+    SweatStackAPIError,         # HTTP error response (has status_code, url, method, body, request_id)
+    SweatStackAuthError,        # 401, 403
+    SweatStackNotFoundError,    # 404
+    SweatStackRateLimitError,   # 429 (has retry_after)
+    SweatStackBadRequestError,  # other 4xx
+    SweatStackServerError,      # 5xx
+)
+```
+
+Typical usage:
+
+```python
+try:
+    activity = client.get_activity("nonexistent_id")
+except SweatStackNotFoundError:
+    print("Activity doesn't exist")
+except SweatStackServerError as e:
+    print(f"Server error (transient): {e.status_code}")
+except SweatStackAPIError as e:
+    print(f"API error: {e.status_code} {e.body}")
+```
+
+Hierarchy:
+- `SweatStackConnectionError`, `SweatStackTokenRefreshError`, and `SweatStackAPIError` are all direct children of `SweatStackError`.
+- All HTTP-response errors (`SweatStackAuthError`, `SweatStackNotFoundError`, etc.) are subclasses of `SweatStackAPIError` and carry `status_code`, `url`, `method`, `request_id`, and `body` attributes.
+- `SweatStackRateLimitError` additionally has `retry_after: int | None`.
+
 ## Gotchas
 
 - **Sport enum uses underscores:** `Sport.cycling_road`, not `Sport("road")` or `Sport.cycling.road`. String values use dots: `"cycling.road"`.
@@ -373,6 +424,6 @@ df = sweatstack.get_latest_activity_data()
 - **`sport` (singular) vs `sports` (list):** `get_latest_activity(sport=...)` and `create_trace(sport=...)` take a single sport. All other methods that filter by sport use `sports=[...]` (list). The singular `sport` parameter on longitudinal methods is deprecated.
 - **DataFrames have standard dtypes.** The library converts API-optimized types (Int16, float16) to float64/datetime64[ns] automatically.
 - **`as_dataframe=True`** is available on `get_activities()`, `get_traces()`, `get_tests()`, and `get_dailies()`. Time-series methods (`get_activity_data`, `get_longitudinal_data`, etc.) always return DataFrames.
-- **`update_test()` is a full replace.** Omitted optional fields are set to null. Always re-pass all fields you want to keep (e.g. `results=test.results`).
+- **`update_test()` and `update_trace()` are full replaces.** Omitted optional fields are set to null. Always re-pass all fields you want to keep.
 - **`summary` fields are optional.** Always null-check: `activity.summary.power.mean if activity.summary and activity.summary.power else None`.
 - **`metrics` on ActivitySummary** lists available data streams, not the data itself. Use to check availability before calling `get_activity_data()`.

{sweatstack-0.74.0 → sweatstack-0.76.0}/CHANGELOG.md

@@ -6,6 +6,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [0.76.0] - 2026-04-27
+
+### Added
+- Typed exception hierarchy (`sweatstack.exceptions`). All API errors now raise specific exception types: `SweatStackAuthError` (401/403), `SweatStackNotFoundError` (404), `SweatStackRateLimitError` (429), `SweatStackBadRequestError` (other 4xx), `SweatStackServerError` (5xx). Transport failures raise `SweatStackConnectionError`.
+- Structured error metadata on all API exceptions: `status_code`, `url`, `method`, `request_id`, `body`.
+
+### Changed
+- **BREAKING:** All client methods now raise `SweatStackAPIError` subclasses instead of `httpx.HTTPStatusError`. Code that catches `httpx.HTTPStatusError` must switch to catching `SweatStackAPIError` (or a specific subclass).
+- **BREAKING:** `TokenRefreshError` renamed to `SweatStackTokenRefreshError` and moved to `sweatstack.exceptions`. Import path changed from `from sweatstack import TokenRefreshError` to `from sweatstack import SweatStackTokenRefreshError`.
+- **BREAKING:** 422 responses now raise `SweatStackBadRequestError` instead of `ValueError`.
+- Transport errors (DNS, timeouts, connection refused) now raise `SweatStackConnectionError` instead of leaking raw httpx exceptions.
+
+### Removed
+- `httpx` is no longer part of the public error surface. Consumers do not need to import `httpx` to handle errors.
+
+
+## [0.75.0] - 2026-04-23
+
+### Added
+- Update and delete traces: `update_trace()` and `delete_trace()` methods for full trace lifecycle management.
+
+
 ## [0.74.0] - 2026-04-22
 
 ### Added

{sweatstack-0.74.0 → sweatstack-0.76.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sweatstack
-Version: 0.74.0
+Version: 0.76.0
 Summary: The official Python client for SweatStack
 Project-URL: Homepage, https://sweatstack.no
 Project-URL: Documentation, https://developer.sweatstack.no/getting-started/

sweatstack-0.76.0/plans/002_TYPED_EXCEPTIONS.md

@@ -0,0 +1,269 @@
+# Typed exception hierarchy for the SweatStack client
+
+## Context
+
+The `sweatstack` Python client currently surfaces `httpx.HTTPStatusError`
+directly to consumers via `Client._raise_for_status` /
+`Client._print_response_and_raise` (`src/sweatstack/client.py:968-997`).
+
+This has two problems:
+
+1. **Consumers can't branch on error kind without inspecting status codes.**
+   Telling apart "upstream is down" (5xx, transient) from "you sent bad input"
+   (4xx, your bug) requires `exc.response.status_code`. That's the leaky
+   abstraction a client library exists to absorb.
+2. **`httpx` is an implementation detail.** Any consumer that wants to handle
+   errors must `import httpx` to catch `HTTPStatusError`. If the transport
+   ever changes, every consumer breaks.
+
+## Exception hierarchy
+
+```
+SweatStackError                       # base -- catch-all for anything sweatstack-related
+├── SweatStackConnectionError         # transport-level: DNS, timeout, no response
+├── SweatStackTokenRefreshError       # client-side auth failure (before any request)
+└── SweatStackAPIError                # HTTP response with error status
+    ├── SweatStackAuthError           # 401, 403
+    ├── SweatStackNotFoundError       # 404
+    ├── SweatStackRateLimitError      # 429 -- exposes retry_after
+    ├── SweatStackBadRequestError     # other 4xx
+    └── SweatStackServerError         # 5xx
+```
+
+`SweatStackTokenRefreshError` is a direct child of `SweatStackError`, not of
+`SweatStackAPIError`. Token refresh is a client-side operation that happens
+before a request is made -- it has no status code, no URL, no method. Forcing
+it under `SweatStackAPIError` would violate Liskov: every `SweatStackAPIError`
+guarantees `status_code: int`, and a token refresh failure can't provide one.
+
+### Attributes on `SweatStackAPIError`
+
+```python
+class SweatStackAPIError(SweatStackError):
+    status_code: int
+    url: str
+    method: str
+    request_id: str | None   # from X-Request-ID header, if present
+    body: dict | str | None  # parsed JSON if possible, else raw text, else None
+```
+
+`SweatStackRateLimitError` adds `retry_after: int | None` (seconds, from
+`Retry-After` header).
+
+`SweatStackConnectionError` and `SweatStackTokenRefreshError` take only a
+`message: str`.
+
+### Why these classes
+
+| Class | Reason |
+|---|---|
+| `SweatStackServerError` | The most important new class. `except SweatStackServerError` handles "upstream is unhappy" without catching consumer bugs. |
+| `SweatStackBadRequestError` | Separate from server errors: don't retry, surface to developers. Different remediation = different class. |
+| `SweatStackNotFoundError` | 404 is often domain-meaningful ("trace was deleted"), not a bug. Consumers want to handle it as a business case. |
+| `SweatStackRateLimitError` | Reserves the class even if the API isn't rate-limited today. Zero cost, prevents future refactoring. |
+| `SweatStackConnectionError` | Covers `httpx.ConnectError`, `httpx.ReadTimeout`, etc. Currently these leak through as raw httpx types. |
+| `SweatStackAuthError` | Groups 401/403 HTTP responses. |
+| `SweatStackTokenRefreshError` | Client-side auth failure. Sibling of `SweatStackAPIError`, not child -- no HTTP response data to carry. |
+
+## Implementation
+
+### 1. New module: `src/sweatstack/exceptions.py`
+
+Define the full hierarchy. Pure module -- no imports from `client.py`, no
+`httpx`. This is the public error contract.
+
+```python
+class SweatStackError(Exception):
+    """Base exception for all SweatStack errors."""
+
+class SweatStackConnectionError(SweatStackError):
+    """Transport-level failure: DNS, connect timeout, read timeout, no response."""
+
+class SweatStackTokenRefreshError(SweatStackError):
+    """Token refresh failed (expired, missing, or refresh request failed)."""
+
+class SweatStackAPIError(SweatStackError):
+    """HTTP response with an error status code."""
+    def __init__(self, *, status_code, url, method, request_id=None, body=None):
+        self.status_code = status_code
+        self.url = url
+        self.method = method
+        self.request_id = request_id
+        self.body = body
+        super().__init__(self._format_message())
+
+    def _format_message(self):
+        msg = f"{self.status_code}: {self.method} {self.url}"
+        if self.request_id:
+            msg += f" (request_id={self.request_id})"
+        if self.body:
+            msg += f" — {self.body}"
+        return msg
+
+    def __repr__(self):
+        return (
+            f"{type(self).__name__}(status_code={self.status_code!r}, "
+            f"method={self.method!r}, url={self.url!r})"
+        )
+
+class SweatStackAuthError(SweatStackAPIError):
+    """401 or 403: authentication or authorization failure."""
+
+class SweatStackNotFoundError(SweatStackAPIError):
+    """404: resource not found."""
+
+class SweatStackRateLimitError(SweatStackAPIError):
+    """429: rate limited."""
+    def __init__(self, *, retry_after=None, **kwargs):
+        self.retry_after = retry_after
+        super().__init__(**kwargs)
+
+class SweatStackBadRequestError(SweatStackAPIError):
+    """4xx (not 401, 403, 404, 429): client sent invalid input."""
+
+class SweatStackServerError(SweatStackAPIError):
+    """5xx: server-side failure, transient, safe to retry for idempotent ops."""
+```
+
+### 2. Translation in `client.py`
+
+Replace `_raise_for_status` and `_print_response_and_raise` with a single
+translation point:
+
+```python
+def _raise_for_status(self, response: httpx.Response) -> None:
+    if response.is_success:
+        return
+
+    status = response.status_code
+    body = self._parse_error_body(response)
+    request_id = response.headers.get("x-request-id")
+    common = dict(
+        status_code=status,
+        url=str(response.request.url),
+        method=response.request.method,
+        request_id=request_id,
+        body=body,
+    )
+
+    if status in (401, 403):
+        raise SweatStackAuthError(**common)
+    if status == 404:
+        raise SweatStackNotFoundError(**common)
+    if status == 429:
+        retry_after = int(response.headers.get("retry-after", "0")) or None
+        raise SweatStackRateLimitError(retry_after=retry_after, **common)
+    if 400 <= status < 500:
+        raise SweatStackBadRequestError(**common)
+    if 500 <= status < 600:
+        raise SweatStackServerError(**common)
+    # Fallback (e.g. 3xx that wasn't followed) -- shouldn't happen
+    raise SweatStackAPIError(**common)
+
+@staticmethod
+def _parse_error_body(response: httpx.Response) -> dict | str | None:
+    try:
+        return response.json()
+    except Exception:
+        text = response.text
+        return text if text else None
+```
+
+Wrap transport-level errors at the HTTP call site:
+
+```python
+try:
+    response = self._http_client.request(...)
+except httpx.HTTPError as exc:
+    raise SweatStackConnectionError(str(exc)) from exc
+self._raise_for_status(response)
+```
+
+### 3. Remove `_print_response_and_raise` and `_add_note`
+
+These exist only to annotate `httpx.HTTPStatusError` with response text.
+The new exceptions carry `body` natively, so these methods are dead code.
+
+### 4. Clean up the 422 special case
+
+The current code raises `ValueError(response.json())` for 422. This should
+raise `SweatStackBadRequestError` like any other 4xx. The parsed validation
+error body lands in `body` where consumers can inspect it.
+
+### 5. Clean up the 401/Streamlit special case
+
+`_raise_for_status` currently detects Streamlit and adds a hint note on 401.
+After this change, it raises `SweatStackAuthError`. The Streamlit hint (if
+still wanted) moves to the Streamlit integration layer, not the core error
+path.
+
+### 6. Move `TokenRefreshError` to `exceptions.py`
+
+- Rename to `SweatStackTokenRefreshError`.
+- Parent is `SweatStackError` (not `SweatStackAPIError`).
+- Remove old definition from `client.py`.
+- Import in `client.py` from `exceptions.py`.
+
+### 7. Update `__init__.py` exports
+
+```python
+from .client import *
+from .exceptions import (
+    SweatStackError,
+    SweatStackConnectionError,
+    SweatStackTokenRefreshError,
+    SweatStackAPIError,
+    SweatStackAuthError,
+    SweatStackNotFoundError,
+    SweatStackRateLimitError,
+    SweatStackBadRequestError,
+    SweatStackServerError,
+)
+```
+
+### 8. Tests
+
+Unit tests covering each status branch (401, 403, 404, 429, 400, 422, 500,
+502, 503, network error). Each test asserts:
+- Correct exception type raised
+- `status_code`, `url`, `method`, `body` populated correctly
+- `request_id` populated when header present
+- `retry_after` populated for 429
+- Inheritance: e.g. `SweatStackServerError` is caught by
+  `except SweatStackAPIError` and `except SweatStackError`
+- `__repr__` produces structured output suitable for logging
+
+## Backwards incompatibilities
+
+Since no external consumers exist yet, these are listed for completeness and
+to inform the changelog for the first stable release.
+
+| What changed | Before | After |
+|---|---|---|
+| HTTP error exceptions | `httpx.HTTPStatusError` | `SweatStackAPIError` subclasses |
+| 422 responses | `ValueError(response.json())` | `SweatStackBadRequestError` |
+| Transport errors (DNS, timeout) | Raw `httpx.ConnectError`, `httpx.ReadTimeout`, etc. | `SweatStackConnectionError` |
+| `TokenRefreshError` class name | `TokenRefreshError` | `SweatStackTokenRefreshError` |
+| `TokenRefreshError` base class | `Exception` | `SweatStackError` |
+| `TokenRefreshError` import path | `from sweatstack import TokenRefreshError` or `from sweatstack.client import TokenRefreshError` | `from sweatstack import SweatStackTokenRefreshError` or `from sweatstack.exceptions import SweatStackTokenRefreshError` |
+| 401 + Streamlit hint | Appended as exception note on `httpx.HTTPStatusError` | `SweatStackAuthError` raised; Streamlit hint moves to Streamlit integration layer |
+| `_print_response_and_raise` | Public-ish method on `Client` | Removed |
+| `_add_note` | Helper on `Client` | Removed |
+
+## Out of scope
+
+- **Built-in retry on 5xx / 429.** Clean follow-up once typed exceptions exist.
+- **Idempotency keys on POST.** Requires API-side support.
+- **Native async client.** Separate effort.
+
+## Acceptance criteria
+
+- All public client methods that previously raised `httpx.HTTPStatusError`
+  raise a `SweatStackAPIError` subclass appropriate to the status code.
+- All transport-level failures raise `SweatStackConnectionError`.
+- `httpx` types never appear in the public API surface.
+- `SweatStackTokenRefreshError` is importable from `sweatstack.exceptions`
+  and `sweatstack`.
+- Unit tests cover each status branch and verify exception type, attributes,
+  and inheritance.
+- All `SweatStackAPIError` instances have a useful `__repr__` for debugging.

{sweatstack-0.74.0 → sweatstack-0.76.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sweatstack"
-version = "0.74.0"
+version = "0.76.0"
 description = "The official Python client for SweatStack"
 readme = "README.md"
 license = "MIT"

sweatstack-0.76.0/src/sweatstack/__init__.py

@@ -0,0 +1,12 @@
+from .client import *  # noqa: F403
+from .exceptions import (
+    SweatStackError,
+    SweatStackConnectionError,
+    SweatStackTokenRefreshError,
+    SweatStackAPIError,
+    SweatStackAuthError,
+    SweatStackNotFoundError,
+    SweatStackRateLimitError,
+    SweatStackBadRequestError,
+    SweatStackServerError,
+)