python-polsen 0.1.1__tar.gz → 0.2.0__tar.gz

{python_polsen-0.1.1 → python_polsen-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-polsen
-Version: 0.1.1
+Version: 0.2.0
 Summary: An asynchronous Python client for the [Polsen Health API](https://docs.research-api.nowatch.com/), the service exposing physiological and contextual data collected by Polsen devices and processed by the Polsen App for scientific and research use.
 Author: Matt Moore
 Author-email: Matt Moore <matt.d.moore@outlook.com>
@@ -58,7 +58,8 @@ async def main() -> None:
         heart_rate = await client.get_timeseries(
             user_ids[0],
             TimeseriesType.HEART_RATE,
-            params={"start_date": "2026-10-17", "end_date": "2026-10-17"},
+            start_date="2026-10-17",
+            end_date="2026-10-17",
         )
         print(user, heart_rate)
 
@@ -76,14 +77,14 @@ argument and call `await client.close()` manually.
 | --- | --- | --- |
 | `get_user_ids()` | `GET /v1/keys/users` | User ids (`uid_...`) reachable by the key |
 | `get_user(user_id)` | `GET /v1/user/{user_id}` | User profile |
-| `get_timeseries(user_id, timeseries_type, **kw)` | `GET /v1/timeline/timeseries/{user_id}/{mtype}` | Columnar `MeasurementJSONPage` |
-| `get_sleep(user_id, **kw)` | `GET /v1/timeline/events/sleep/{user_id}` | `Page[Sleep]` |
-| `get_activities(user_id, **kw)` | `GET /v1/timeline/events/activities/{user_id}` | `Page[ActivityModel]` |
-| `get_checkins(user_id, **kw)` | `GET /v1/timeline/events/checkins/{user_id}` | `Page[CheckinModel]` |
-| `get_timezone(user_id, **kw)` | `GET /v1/timeline/events/timezones/{user_id}` | `Page[TimezoneResponse]` |
-| `get_crown_presses(user_id, **kw)` | `GET /v1/timeline/events/crown_presses/{user_id}` | `Page[CrownPressResponse]` |
-| `get_overview(user_id, overview_metric, **kw)` | `GET /v1/overview/{user_id}/{stype}` | List of per-day metrics |
-| `get_feelings(user_id, feeling_type, **kw)` | `GET /v1/feelings/{user_id}/{ftype}` | `Page[FeelingsModel]` |
+| `get_timeseries(user_id, timeseries_type, *, start_date, end_date, days=None, cursor=None)` | `GET /v1/timeline/timeseries/{user_id}/{mtype}` | Columnar `MeasurementJSONPage` |
+| `get_sleep(user_id, *, start_date, end_date, days=None, cursor=None)` | `GET /v1/timeline/events/sleep/{user_id}` | `Page[Sleep]` |
+| `get_activities(user_id, *, start_date, end_date, days=None, cursor=None)` | `GET /v1/timeline/events/activities/{user_id}` | `Page[ActivityModel]` |
+| `get_checkins(user_id, *, start_date, end_date, days=None, cursor=None)` | `GET /v1/timeline/events/checkins/{user_id}` | `Page[CheckinModel]` |
+| `get_timezone(user_id, *, start_date, end_date, days=None, cursor=None)` | `GET /v1/timeline/events/timezones/{user_id}` | `Page[TimezoneResponse]` |
+| `get_crown_presses(user_id, *, start_date, end_date, days=None, cursor=None)` | `GET /v1/timeline/events/crown_presses/{user_id}` | `Page[CrownPressResponse]` |
+| `get_overview(user_id, overview_metric, *, start_date, end_date)` | `GET /v1/overview/{user_id}/{stype}` | List of per-day metrics |
+| `get_feelings(user_id, feeling_type, *, start_date, end_date, days=None, cursor=None)` | `GET /v1/feelings/{user_id}/{ftype}` | `Page[FeelingsModel]` |
 
 ### Enums
 
@@ -99,22 +100,22 @@ members in `python_polsen.types`:
 ### Pagination
 
 Event and feelings endpoints return a `{ "data": [...], "next_cursor": ... }`
-envelope. Pass dates via the request `params`:
+envelope. The `start_date` and `end_date` range is required; pass it as keyword
+arguments:
 
 ```python
 page = await client.get_sleep(
     user_id,
-    params={"start_date": "2026-10-01", "end_date": "2026-10-07"},
+    start_date="2026-10-01",
+    end_date="2026-10-07",
 )
 
-while page["next_cursor"]:
+while page.get("next_cursor"):
     page = await client.get_sleep(
         user_id,
-        params={
-            "start_date": "2026-10-01",
-            "end_date": "2026-10-07",
-            "cursor": page["next_cursor"],
-        },
+        start_date="2026-10-01",
+        end_date="2026-10-07",
+        cursor=page["next_cursor"],
     )
 ```
 

{python_polsen-0.1.1 → python_polsen-0.2.0}/README.md

@@ -43,7 +43,8 @@ async def main() -> None:
         heart_rate = await client.get_timeseries(
             user_ids[0],
             TimeseriesType.HEART_RATE,
-            params={"start_date": "2026-10-17", "end_date": "2026-10-17"},
+            start_date="2026-10-17",
+            end_date="2026-10-17",
         )
         print(user, heart_rate)
 
@@ -61,14 +62,14 @@ argument and call `await client.close()` manually.
 | --- | --- | --- |
 | `get_user_ids()` | `GET /v1/keys/users` | User ids (`uid_...`) reachable by the key |
 | `get_user(user_id)` | `GET /v1/user/{user_id}` | User profile |
-| `get_timeseries(user_id, timeseries_type, **kw)` | `GET /v1/timeline/timeseries/{user_id}/{mtype}` | Columnar `MeasurementJSONPage` |
-| `get_sleep(user_id, **kw)` | `GET /v1/timeline/events/sleep/{user_id}` | `Page[Sleep]` |
-| `get_activities(user_id, **kw)` | `GET /v1/timeline/events/activities/{user_id}` | `Page[ActivityModel]` |
-| `get_checkins(user_id, **kw)` | `GET /v1/timeline/events/checkins/{user_id}` | `Page[CheckinModel]` |
-| `get_timezone(user_id, **kw)` | `GET /v1/timeline/events/timezones/{user_id}` | `Page[TimezoneResponse]` |
-| `get_crown_presses(user_id, **kw)` | `GET /v1/timeline/events/crown_presses/{user_id}` | `Page[CrownPressResponse]` |
-| `get_overview(user_id, overview_metric, **kw)` | `GET /v1/overview/{user_id}/{stype}` | List of per-day metrics |
-| `get_feelings(user_id, feeling_type, **kw)` | `GET /v1/feelings/{user_id}/{ftype}` | `Page[FeelingsModel]` |
+| `get_timeseries(user_id, timeseries_type, *, start_date, end_date, days=None, cursor=None)` | `GET /v1/timeline/timeseries/{user_id}/{mtype}` | Columnar `MeasurementJSONPage` |
+| `get_sleep(user_id, *, start_date, end_date, days=None, cursor=None)` | `GET /v1/timeline/events/sleep/{user_id}` | `Page[Sleep]` |
+| `get_activities(user_id, *, start_date, end_date, days=None, cursor=None)` | `GET /v1/timeline/events/activities/{user_id}` | `Page[ActivityModel]` |
+| `get_checkins(user_id, *, start_date, end_date, days=None, cursor=None)` | `GET /v1/timeline/events/checkins/{user_id}` | `Page[CheckinModel]` |
+| `get_timezone(user_id, *, start_date, end_date, days=None, cursor=None)` | `GET /v1/timeline/events/timezones/{user_id}` | `Page[TimezoneResponse]` |
+| `get_crown_presses(user_id, *, start_date, end_date, days=None, cursor=None)` | `GET /v1/timeline/events/crown_presses/{user_id}` | `Page[CrownPressResponse]` |
+| `get_overview(user_id, overview_metric, *, start_date, end_date)` | `GET /v1/overview/{user_id}/{stype}` | List of per-day metrics |
+| `get_feelings(user_id, feeling_type, *, start_date, end_date, days=None, cursor=None)` | `GET /v1/feelings/{user_id}/{ftype}` | `Page[FeelingsModel]` |
 
 ### Enums
 
@@ -84,22 +85,22 @@ members in `python_polsen.types`:
 ### Pagination
 
 Event and feelings endpoints return a `{ "data": [...], "next_cursor": ... }`
-envelope. Pass dates via the request `params`:
+envelope. The `start_date` and `end_date` range is required; pass it as keyword
+arguments:
 
 ```python
 page = await client.get_sleep(
     user_id,
-    params={"start_date": "2026-10-01", "end_date": "2026-10-07"},
+    start_date="2026-10-01",
+    end_date="2026-10-07",
 )
 
-while page["next_cursor"]:
+while page.get("next_cursor"):
     page = await client.get_sleep(
         user_id,
-        params={
-            "start_date": "2026-10-01",
-            "end_date": "2026-10-07",
-            "cursor": page["next_cursor"],
-        },
+        start_date="2026-10-01",
+        end_date="2026-10-07",
+        cursor=page["next_cursor"],
     )
 ```
 

{python_polsen-0.1.1 → python_polsen-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-polsen"
-version = "0.1.1"
+version = "0.2.0"
 license = "MIT"
 license-files = ["LICENSE"]
 description = "An asynchronous Python client for the [Polsen Health API](https://docs.research-api.nowatch.com/), the service exposing physiological and contextual data collected by Polsen devices and processed by the Polsen App for scientific and research use."
@@ -17,9 +17,6 @@ dependencies = [
 name = "Matt Moore"
 email = "matt.d.moore@outlook.com"
 
-[project.scripts]
-python-polsen = "python_polsen:main"
-
 [build-system]
 requires = ["uv_build>=0.12.5,<0.13.0"]
 build-backend = "uv_build"

{python_polsen-0.1.1 → python_polsen-0.2.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "python-polsen"
-version = "0.1.1"
+version = "0.2.0"
 license = "MIT"
 license-files = [
     "LICENSE"
@@ -18,9 +18,6 @@ dependencies = [
     "yarl>=1.25.1",
 ]
 
-[project.scripts]
-python-polsen = "python_polsen:main"
-
 [build-system]
 requires = ["uv_build>=0.12.5,<0.13.0"]
 build-backend = "uv_build"

{python_polsen-0.1.1 → python_polsen-0.2.0}/src/python_polsen/__init__.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from importlib.metadata import PackageNotFoundError, version
+
 from .exceptions import (
     APIError,
     AuthenticationError,
@@ -11,10 +13,13 @@ from .exceptions import (
     ValidationError,
 )
 from .polsen import PolsenClient
-from .types import FeelingType, OverviewMetric, TimelineMetric, TimeseriesType
+from .types import FeelingType, OverviewMetric, TimeseriesType
 
-__version__ = "0.1.0"
-"""Version of the installed ``python-polsen`` distribution."""
+#: Version of the installed ``python-polsen`` distribution.
+try:
+    __version__ = version("python-polsen")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
 
 __all__ = [
     "APIError",
@@ -25,7 +30,6 @@ __all__ = [
     "PolsenClient",
     "PolsenError",
     "RateLimitError",
-    "TimelineMetric",
     "TimeseriesType",
     "ValidationError",
     "__version__",

{python_polsen-0.1.1 → python_polsen-0.2.0}/src/python_polsen/api/v1/__init__.py

@@ -42,27 +42,27 @@ def keys() -> str:
     return "v1/keys/users"
 
 
-def overview(user_id: str, stype: OverviewMetric) -> str:
+def overview(user_id: str, overview_metric: OverviewMetric) -> str:
     """Build the path for ``GET /v1/overview/{user_id}/{stype}``.
 
     Args:
         user_id: Identifier of the user (``uid_...``).
-        stype: Overview metric to retrieve.
+        overview_metric: Overview metric to retrieve.
 
     Returns:
         The relative request path.
     """
-    return f"v1/overview/{user_id}/{stype}"
+    return f"v1/overview/{user_id}/{overview_metric}"
 
 
-def feelings(user_id: str, ftype: FeelingType) -> str:
+def feelings(user_id: str, feeling_type: FeelingType) -> str:
     """Build the path for ``GET /v1/feelings/{user_id}/{ftype}``.
 
     Args:
         user_id: Identifier of the user (``uid_...``).
-        ftype: Feelings category (``DAY`` or ``SLEEP``).
+        feeling_type: Feelings category (``DAY`` or ``SLEEP``).
 
     Returns:
         The relative request path.
     """
-    return f"v1/feelings/{user_id}/{ftype}"
+    return f"v1/feelings/{user_id}/{feeling_type}"

{python_polsen-0.1.1 → python_polsen-0.2.0}/src/python_polsen/api/v1/timeline/__init__.py

@@ -1,13 +1,13 @@
 """Route builders for the ``v1`` timeline endpoints.
 
-Covers high-frequency time-series paths plus the event paths re-exported from
+Covers high-frequency time-series paths plus the event paths in
 :mod:`python_polsen.api.v1.timeline.events`.
 """
 
 from __future__ import annotations
 
 from ....types import TimeseriesType
-from .events import *
+from . import events
 
 __all__ = [
     "events",
@@ -17,14 +17,14 @@ __all__ = [
 _BASE = "v1/timeline/timeseries"
 
 
-def timeseries(user_id: str, mtype: TimeseriesType) -> str:
+def timeseries(user_id: str, timeseries_type: TimeseriesType) -> str:
     """Build the path for ``GET /v1/timeline/timeseries/{user_id}/{mtype}``.
 
     Args:
         user_id: Identifier of the user (``uid_...``).
-        mtype: Measurement type to retrieve.
+        timeseries_type: Measurement type to retrieve.
 
     Returns:
         The relative request path.
     """
-    return f"{_BASE}/{user_id}/{mtype}"
+    return f"{_BASE}/{user_id}/{timeseries_type}"

{python_polsen-0.1.1 → python_polsen-0.2.0}/src/python_polsen/api/v1/timeline/events.py

@@ -3,6 +3,19 @@
 _BASE = "v1/timeline/events"
 
 
+def _path(segment: str, user_id: str) -> str:
+    """Build the path for ``GET /v1/timeline/events/{segment}/{user_id}``.
+
+    Args:
+        segment: Event segment (e.g. ``sleep``).
+        user_id: Identifier of the user (``uid_...``).
+
+    Returns:
+        The relative request path.
+    """
+    return f"{_BASE}/{segment}/{user_id}"
+
+
 def sleep(user_id: str) -> str:
     """Build the path for ``GET /v1/timeline/events/sleep/{user_id}``.
 
@@ -12,7 +25,7 @@ def sleep(user_id: str) -> str:
     Returns:
         The relative request path.
     """
-    return f"{_BASE}/sleep/{user_id}"
+    return _path("sleep", user_id)
 
 
 def checkins(user_id: str) -> str:
@@ -24,7 +37,7 @@ def checkins(user_id: str) -> str:
     Returns:
         The relative request path.
     """
-    return f"{_BASE}/checkins/{user_id}"
+    return _path("checkins", user_id)
 
 
 def activities(user_id: str) -> str:
@@ -36,7 +49,7 @@ def activities(user_id: str) -> str:
     Returns:
         The relative request path.
     """
-    return f"{_BASE}/activities/{user_id}"
+    return _path("activities", user_id)
 
 
 def timezones(user_id: str) -> str:
@@ -48,7 +61,7 @@ def timezones(user_id: str) -> str:
     Returns:
         The relative request path.
     """
-    return f"{_BASE}/timezones/{user_id}"
+    return _path("timezones", user_id)
 
 
 def crown_presses(user_id: str) -> str:
@@ -60,4 +73,4 @@ def crown_presses(user_id: str) -> str:
     Returns:
         The relative request path.
     """
-    return f"{_BASE}/crown_presses/{user_id}"
+    return _path("crown_presses", user_id)

{python_polsen-0.1.1 → python_polsen-0.2.0}/src/python_polsen/const.py

@@ -1,4 +1,4 @@
 """Package-wide constants for the Polsen Health API client."""
 
-API_URL = "api.polsen.health"
+API_HOST = "api.polsen.health"
 """Host of the production Polsen Health API (the ``servers`` entry in the spec)."""

{python_polsen-0.1.1 → python_polsen-0.2.0}/src/python_polsen/exceptions.py

@@ -6,6 +6,8 @@ members (``title``, ``detail``, ``code``, ``request_id``, ...) are attached to
 the exception instance as attributes.
 """
 
+from http import HTTPStatus
+
 
 class PolsenError(Exception):
     """Base class for all Polsen API errors.
@@ -83,3 +85,29 @@ class RateLimitError(PolsenError):
 
 class APIError(PolsenError):
     """Raised for any other non-2xx HTTP response."""
+
+
+_STATUS_TO_ERROR: dict[int, type[PolsenError]] = {
+    HTTPStatus.UNAUTHORIZED: AuthenticationError,
+    HTTPStatus.FORBIDDEN: AuthenticationError,
+    HTTPStatus.NOT_FOUND: NotFoundError,
+    HTTPStatus.UNPROCESSABLE_ENTITY: ValidationError,
+    HTTPStatus.TOO_MANY_REQUESTS: RateLimitError,
+}
+
+
+def error_for_status(
+    status: int,
+    body: dict[str, int | str],
+) -> PolsenError:
+    """Build the :class:`PolsenError` matching an HTTP status code.
+
+    Args:
+        status: HTTP status code returned by the API.
+        body: Decoded ``ProblemDetail`` JSON body.
+
+    Returns:
+        The error subclass mapped to ``status``, or :class:`APIError` when no
+        subclass applies.
+    """
+    return _STATUS_TO_ERROR.get(status, APIError)(body, status_code=status)

{python_polsen-0.1.1 → python_polsen-0.2.0}/src/python_polsen/polsen.py

@@ -9,9 +9,10 @@ from __future__ import annotations
 
 import asyncio
 import ssl
+from collections.abc import Callable
 from dataclasses import dataclass, field
 from http import HTTPMethod, HTTPStatus
-from typing import Any, Self
+from typing import Any, ClassVar, Self
 
 import certifi
 from aiohttp import ClientSession, ContentTypeError, TCPConnector
@@ -20,17 +21,26 @@ from yarl import URL
 from python_polsen.types import FeelingType, OverviewMetric, TimeseriesType
 
 from .api import v1
-from .const import API_URL
-from .exceptions import (
-    APIError,
-    AuthenticationError,
-    NotFoundError,
-    RateLimitError,
-    ValidationError,
-)
+from .const import API_HOST
+from .exceptions import RateLimitError, error_for_status
 from .utils import retry_on_rate_limit
 
 
+def _query_params(
+    start_date: str,
+    end_date: str,
+    days: int | None = None,
+    cursor: str | None = None,
+) -> dict[str, str | int]:
+    """Build the ``start_date``/``end_date``/``days``/``cursor`` query params."""
+    params: dict[str, str | int] = {"start_date": start_date, "end_date": end_date}
+    if days is not None:
+        params["days"] = days
+    if cursor is not None:
+        params["cursor"] = cursor
+    return params
+
+
 @dataclass
 class PolsenClient:
     """Async client for the Polsen Health API.
@@ -41,28 +51,31 @@ class PolsenClient:
     Attributes:
         api_key: API key sent in the ``X-API-KEY`` header.
         session: Optional pre-existing ``aiohttp`` session to reuse.
-        base_url: Host of the API; defaults to :data:`~python_polsen.const.API_URL`.
+        host: Host of the API; defaults to :data:`~python_polsen.const.API_HOST`.
         api: Route-builder namespace, defaulting to :mod:`python_polsen.api.v1`.
         _close_session: Whether this client created (and must close) the session.
-        _max_retries: Maximum number of retries after a rate-limit response.
+        _max_retries: Class-level maximum retries after a rate-limit response.
     """
 
     api_key: str = field(repr=False)
     session: ClientSession | None = None
-    base_url: str = field(default=API_URL)
+    host: str = field(default=API_HOST)
     api: Any = field(default=v1, repr=False)
     _close_session: bool = False
-    _max_retries: int = 3
+    _max_retries: ClassVar[int] = 3
     _lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False, init=False)
 
-    @retry_on_rate_limit
+    @retry_on_rate_limit(_max_retries)
     async def _request(
-        self, uri: str, *, headers: dict[str, str] | None = None, **kwargs
+        self, path: str, *, headers: dict[str, str] | None = None, **kwargs
     ) -> dict[str, Any]:
         """Perform an authenticated GET request and decode the JSON response.
 
+        Retries rate-limited requests up to ``_max_retries`` times before the
+        error propagates.
+
         Args:
-            uri: Path to request, relative to ``base_url``.
+            path: Path to request, relative to ``host``.
             headers: Optional headers merged over the default API-key header.
             **kwargs: Forwarded to the underlying ``aiohttp`` request.
 
@@ -78,9 +91,9 @@ class PolsenClient:
         """
         url = URL.build(
             scheme="https",
-            host=self.base_url,
+            host=self.host,
             port=443,
-        ).joinpath(uri)
+        ).joinpath(path)
 
         _headers = {
             "X-API-KEY": f"{self.api_key}",
@@ -102,20 +115,13 @@ class PolsenClient:
             if 200 <= response.status < 300:
                 return body or {}
 
-            match response.status:
-                case HTTPStatus.UNAUTHORIZED | HTTPStatus.FORBIDDEN:
-                    raise AuthenticationError(body, status_code=response.status)
-                case HTTPStatus.NOT_FOUND:
-                    raise NotFoundError(body, status_code=response.status)
-                case HTTPStatus.UNPROCESSABLE_ENTITY:
-                    raise ValidationError(body, status_code=response.status)
-                case HTTPStatus.TOO_MANY_REQUESTS:
-                    retry_after = int(response.headers.get("Retry-After", 2))
-                    raise RateLimitError(
-                        body, status_code=response.status, retry_after=retry_after
-                    )
-                case _:
-                    raise APIError(body, status_code=response.status)
+            if response.status == HTTPStatus.TOO_MANY_REQUESTS:
+                retry_after = int(response.headers.get("Retry-After", 2))
+                raise RateLimitError(
+                    body, status_code=response.status, retry_after=retry_after
+                )
+
+            raise error_for_status(response.status, body)
 
     async def _get_session(self) -> ClientSession:
         """Return the shared session, creating one if necessary.
@@ -134,6 +140,22 @@ class PolsenClient:
                 self._close_session = True
         return self.session
 
+    async def _get_event_page(
+        self, builder: Callable[[str], str], user_id: str, **kwargs
+    ) -> Any:
+        """Fetch a paginated timeline event page for a user.
+
+        Args:
+            builder: Route builder for the event segment (e.g. ``events.sleep``).
+            user_id: Identifier of the user (``uid_...``).
+            **kwargs: Forwarded to :meth:`_request`; typically ``params`` with
+                ``start_date``, ``end_date``, ``days`` and ``cursor``.
+
+        Returns:
+            The decoded ``Page[...]`` envelope with events and ``next_cursor``.
+        """
+        return await self._request(builder(user_id), **kwargs)
+
     async def get_user_ids(self) -> list[str]:
         """List the users accessible with the configured API key.
 
@@ -159,7 +181,14 @@ class PolsenClient:
         return await self._request(self.api.user(user_id))
 
     async def get_timeseries(
-        self, user_id: str, timeseries_type: TimeseriesType, **kwargs
+        self,
+        user_id: str,
+        timeseries_type: TimeseriesType,
+        *,
+        start_date: str,
+        end_date: str,
+        days: int | None = None,
+        cursor: str | None = None,
     ) -> Any:
         """Fetch high-frequency time-series data for a user.
 
@@ -168,104 +197,176 @@ class PolsenClient:
         Args:
             user_id: Identifier of the user (``uid_...``).
             timeseries_type: Measurement to fetch (e.g. ``HEART_RATE``).
-            **kwargs: Forwarded to :meth:`_request`; typically ``params`` with
-                ``start_date``, ``end_date``, ``days`` and ``cursor``.
+            start_date: First date to include (ISO 8601 ``YYYY-MM-DD``).
+            end_date: Last date to include (ISO 8601 ``YYYY-MM-DD``).
+            days: Days per page (default 7, max 30).
+            cursor: Opaque cursor from a previous page.
 
         Returns:
             The columnar ``MeasurementJSONPage`` envelope (time-stamped series
             plus ``next_cursor``).
         """
         return await self._request(
-            self.api.timeline.timeseries(user_id, timeseries_type), **kwargs
+            self.api.timeline.timeseries(user_id, timeseries_type),
+            params=_query_params(start_date, end_date, days, cursor),
         )
 
-    async def get_sleep(self, user_id: str, **kwargs) -> Any:
+    async def get_sleep(
+        self,
+        user_id: str,
+        *,
+        start_date: str,
+        end_date: str,
+        days: int | None = None,
+        cursor: str | None = None,
+    ) -> Any:
         """Fetch paginated sleep events for a user.
 
         Calls ``GET /v1/timeline/events/sleep/{user_id}``.
 
         Args:
             user_id: Identifier of the user (``uid_...``).
-            **kwargs: Forwarded to :meth:`_request`; typically ``params`` with
-                ``start_date``, ``end_date``, ``days`` and ``cursor``.
+            start_date: First date to include (ISO 8601 ``YYYY-MM-DD``).
+            end_date: Last date to include (ISO 8601 ``YYYY-MM-DD``).
+            days: Days per page (default 7, max 30).
+            cursor: Opaque cursor from a previous page.
 
         Returns:
             A ``Page[Sleep]`` envelope with sleep events and ``next_cursor``.
         """
-        return await self._request(self.api.timeline.events.sleep(user_id), **kwargs)
+        return await self._get_event_page(
+            self.api.timeline.events.sleep,
+            user_id,
+            params=_query_params(start_date, end_date, days, cursor),
+        )
 
-    async def get_activities(self, user_id: str, **kwargs) -> Any:
+    async def get_activities(
+        self,
+        user_id: str,
+        *,
+        start_date: str,
+        end_date: str,
+        days: int | None = None,
+        cursor: str | None = None,
+    ) -> Any:
         """Fetch paginated activity events for a user.
 
         Calls ``GET /v1/timeline/events/activities/{user_id}``.
 
         Args:
             user_id: Identifier of the user (``uid_...``).
-            **kwargs: Forwarded to :meth:`_request`; typically ``params`` with
-                ``start_date``, ``end_date``, ``days`` and ``cursor``.
+            start_date: First date to include (ISO 8601 ``YYYY-MM-DD``).
+            end_date: Last date to include (ISO 8601 ``YYYY-MM-DD``).
+            days: Days per page (default 7, max 30).
+            cursor: Opaque cursor from a previous page.
 
         Returns:
             A ``Page[ActivityModel]`` envelope with activity events and
             ``next_cursor``.
         """
-        return await self._request(
-            self.api.timeline.events.activities(user_id), **kwargs
+        return await self._get_event_page(
+            self.api.timeline.events.activities,
+            user_id,
+            params=_query_params(start_date, end_date, days, cursor),
         )
 
-    async def get_checkins(self, user_id: str, **kwargs) -> Any:
+    async def get_checkins(
+        self,
+        user_id: str,
+        *,
+        start_date: str,
+        end_date: str,
+        days: int | None = None,
+        cursor: str | None = None,
+    ) -> Any:
         """Fetch paginated check-in events for a user.
 
         Calls ``GET /v1/timeline/events/checkins/{user_id}``.
 
         Args:
             user_id: Identifier of the user (``uid_...``).
-            **kwargs: Forwarded to :meth:`_request`; typically ``params`` with
-                ``start_date``, ``end_date``, ``days`` and ``cursor``.
+            start_date: First date to include (ISO 8601 ``YYYY-MM-DD``).
+            end_date: Last date to include (ISO 8601 ``YYYY-MM-DD``).
+            days: Days per page (default 7, max 30).
+            cursor: Opaque cursor from a previous page.
 
         Returns:
             A ``Page[CheckinModel]`` envelope with check-in events and
             ``next_cursor``.
         """
-        return await self._request(self.api.timeline.events.checkins(user_id), **kwargs)
+        return await self._get_event_page(
+            self.api.timeline.events.checkins,
+            user_id,
+            params=_query_params(start_date, end_date, days, cursor),
+        )
 
-    async def get_timezone(self, user_id: str, **kwargs) -> Any:
+    async def get_timezone(
+        self,
+        user_id: str,
+        *,
+        start_date: str,
+        end_date: str,
+        days: int | None = None,
+        cursor: str | None = None,
+    ) -> Any:
         """Fetch paginated timezone-change events for a user.
 
         Calls ``GET /v1/timeline/events/timezones/{user_id}``.
 
         Args:
             user_id: Identifier of the user (``uid_...``).
-            **kwargs: Forwarded to :meth:`_request`; typically ``params`` with
-                ``start_date``, ``end_date``, ``days`` and ``cursor``.
+            start_date: First date to include (ISO 8601 ``YYYY-MM-DD``).
+            end_date: Last date to include (ISO 8601 ``YYYY-MM-DD``).
+            days: Days per page (default 7, max 30).
+            cursor: Opaque cursor from a previous page.
 
         Returns:
             A ``Page[TimezoneResponse]`` envelope with timezone events and
             ``next_cursor``.
         """
-        return await self._request(
-            self.api.timeline.events.timezones(user_id), **kwargs
+        return await self._get_event_page(
+            self.api.timeline.events.timezones,
+            user_id,
+            params=_query_params(start_date, end_date, days, cursor),
         )
 
-    async def get_crown_presses(self, user_id: str, **kwargs) -> Any:
+    async def get_crown_presses(
+        self,
+        user_id: str,
+        *,
+        start_date: str,
+        end_date: str,
+        days: int | None = None,
+        cursor: str | None = None,
+    ) -> Any:
         """Fetch paginated crown-press events for a user.
 
         Calls ``GET /v1/timeline/events/crown_presses/{user_id}``.
 
         Args:
             user_id: Identifier of the user (``uid_...``).
-            **kwargs: Forwarded to :meth:`_request`; typically ``params`` with
-                ``start_date``, ``end_date``, ``days`` and ``cursor``.
+            start_date: First date to include (ISO 8601 ``YYYY-MM-DD``).
+            end_date: Last date to include (ISO 8601 ``YYYY-MM-DD``).
+            days: Days per page (default 7, max 30).
+            cursor: Opaque cursor from a previous page.
 
         Returns:
             A ``Page[CrownPressResponse]`` envelope with crown-press events and
             ``next_cursor``.
         """
-        return await self._request(
-            self.api.timeline.events.crown_presses(user_id), **kwargs
+        return await self._get_event_page(
+            self.api.timeline.events.crown_presses,
+            user_id,
+            params=_query_params(start_date, end_date, days, cursor),
         )
 
     async def get_overview(
-        self, user_id: str, overview_metric: OverviewMetric, **kwargs
+        self,
+        user_id: str,
+        overview_metric: OverviewMetric,
+        *,
+        start_date: str,
+        end_date: str,
     ) -> Any:
         """Fetch daily/typical statistics for one overview metric.
 
@@ -274,18 +375,26 @@ class PolsenClient:
         Args:
             user_id: Identifier of the user (``uid_...``).
             overview_metric: Metric to summarise (e.g. ``HRV``, ``RHR``).
-            **kwargs: Forwarded to :meth:`_request`; typically ``params`` with
-                ``start_date`` and ``end_date``.
+            start_date: First date to include (ISO 8601 ``YYYY-MM-DD``).
+            end_date: Last date to include (ISO 8601 ``YYYY-MM-DD``).
 
         Returns:
             A list of per-day metric objects for the requested range.
         """
         return await self._request(
-            self.api.overview(user_id, overview_metric), **kwargs
+            self.api.overview(user_id, overview_metric),
+            params=_query_params(start_date, end_date),
         )
 
     async def get_feelings(
-        self, user_id: str, feeling_type: FeelingType, **kwargs
+        self,
+        user_id: str,
+        feeling_type: FeelingType,
+        *,
+        start_date: str,
+        end_date: str,
+        days: int | None = None,
+        cursor: str | None = None,
     ) -> Any:
         """Fetch self-reported feelings for a user.
 
@@ -295,14 +404,19 @@ class PolsenClient:
             user_id: Identifier of the user (``uid_...``).
             feeling_type: ``DAY`` for waking-day feelings or ``SLEEP`` for the
                 preceding night.
-            **kwargs: Forwarded to :meth:`_request`; typically ``params`` with
-                ``start_date``, ``end_date``, ``days`` and ``cursor``.
+            start_date: First date to include (ISO 8601 ``YYYY-MM-DD``).
+            end_date: Last date to include (ISO 8601 ``YYYY-MM-DD``).
+            days: Days per page (default 7, max 30).
+            cursor: Opaque cursor from a previous page.
 
         Returns:
             A ``Page[FeelingsModel]`` envelope with dated feeling values and
             ``next_cursor``.
         """
-        return await self._request(self.api.feelings(user_id, feeling_type), **kwargs)
+        return await self._request(
+            self.api.feelings(user_id, feeling_type),
+            params=_query_params(start_date, end_date, days, cursor),
+        )
 
     async def close(self) -> None:
         """Close the underlying session if this client created it."""

{python_polsen-0.1.1 → python_polsen-0.2.0}/src/python_polsen/types.py

@@ -28,17 +28,6 @@ class OverviewMetric(StrEnum):
     SKIN_TEMPERATURE = "SKIN_TEMPERATURE"
 
 
-class TimelineMetric(StrEnum):
-    """Top-level timeline category.
-
-    Distinguishes high-frequency time-series measurements (``TIMESERIES``) from
-    discrete timeline events such as sleep or check-ins (``EVENTS``).
-    """
-
-    TIMESERIES = "TIMESERIES"
-    EVENTS = "EVENTS"
-
-
 class TimeseriesType(StrEnum):
     """Measurement type accepted by ``/v1/timeline/timeseries/{user_id}/{mtype}``.
 

python_polsen-0.2.0/src/python_polsen/utils.py

@@ -0,0 +1,44 @@
+"""Helpers shared by the Polsen API client."""
+
+import asyncio
+import functools
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+from .exceptions import RateLimitError
+
+
+def retry_on_rate_limit(
+    max_retries: int,
+) -> Callable[
+    [Callable[..., Coroutine[Any, Any, Any]]],
+    Callable[..., Coroutine[Any, Any, Any]],
+]:
+    """Build a decorator that retries an async method on ``RateLimitError``.
+
+    Args:
+        max_retries: Number of retries allowed before the error propagates.
+
+    Returns:
+        A decorator wrapping an async method so that rate-limited calls are
+        re-attempted up to ``max_retries`` times.
+    """
+
+    def decorator(
+        func: Callable[..., Coroutine[Any, Any, Any]],
+    ) -> Callable[..., Coroutine[Any, Any, Any]]:
+        @functools.wraps(func)
+        async def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+            attempts = 0
+            while True:
+                try:
+                    return await func(self, *args, **kwargs)
+                except RateLimitError as e:
+                    if attempts >= max_retries:
+                        raise
+                    attempts += 1
+                    await asyncio.sleep(e.retry_after)
+
+        return wrapper
+
+    return decorator

python_polsen-0.1.1/src/python_polsen/utils.py

@@ -1,29 +0,0 @@
-"""Helpers shared by the Polsen API client."""
-
-import asyncio
-import functools
-from collections.abc import Callable, Coroutine
-from typing import Any
-
-from .exceptions import RateLimitError
-
-
-def retry_on_rate_limit(
-    func: Callable[..., Coroutine[Any, Any, Any]],
-) -> Callable[..., Coroutine[Any, Any, Any]]:
-    """Decorator that retries an async method when a RateLimitError is caught."""
-
-    @functools.wraps(func)
-    async def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
-        """Await ``func``, retrying up to ``self._max_retries`` on rate limits."""
-        attempts = 0
-        while True:
-            try:
-                return await func(self, *args, **kwargs)
-            except RateLimitError as e:
-                if attempts >= self._max_retries:
-                    raise
-                attempts += 1
-                await asyncio.sleep(e.retry_after)
-
-    return wrapper