python-polsen 0.1.0__py3-none-any.whl

python_polsen/__init__.py

@@ -0,0 +1,32 @@
+"""An asynchronous Python client for the Polsen Health API (v1)."""
+
+from __future__ import annotations
+
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    PolsenError,
+    RateLimitError,
+    ValidationError,
+)
+from .polsen import PolsenClient
+from .types import FeelingType, OverviewMetric, TimelineMetric, TimeseriesType
+
+__version__ = "0.1.0"
+"""Version of the installed ``python-polsen`` distribution."""
+
+__all__ = [
+    "APIError",
+    "AuthenticationError",
+    "FeelingType",
+    "NotFoundError",
+    "OverviewMetric",
+    "PolsenClient",
+    "PolsenError",
+    "RateLimitError",
+    "TimelineMetric",
+    "TimeseriesType",
+    "ValidationError",
+    "__version__",
+]

python_polsen/api/__init__.py

@@ -0,0 +1,12 @@
+"""Versioned route builders for the Polsen Health API.
+
+The subpackages expose pure functions that assemble request paths and contain
+no HTTP logic; :mod:`python_polsen.api.v1` mirrors the ``v1`` paths described in
+``openapi.json``.
+"""
+
+from __future__ import annotations
+
+from . import v1
+
+__all__ = ["v1"]

python_polsen/api/v1/__init__.py

@@ -0,0 +1,68 @@
+"""Route builders for the ``v1`` Polsen Health API endpoints.
+
+These helpers return request paths for endpoints with simple parameters;
+timeline-specific paths live in :mod:`python_polsen.api.v1.timeline`.
+"""
+
+from __future__ import annotations
+
+from ...types import FeelingType, OverviewMetric
+from . import timeline
+
+__all__ = [
+    "VERSION",
+    "feelings",
+    "keys",
+    "overview",
+    "timeline",
+    "user",
+]
+
+VERSION = "v1"
+
+
+def user(user_id: str) -> str:
+    """Build the path for ``GET /v1/user/{user_id}`` (Get User Data).
+
+    Args:
+        user_id: Identifier of the user (``uid_...``).
+
+    Returns:
+        The relative request path.
+    """
+    return f"v1/user/{user_id}"
+
+
+def keys() -> str:
+    """Build the path for ``GET /v1/keys/users`` (Get Key Users).
+
+    Returns:
+        The relative request path.
+    """
+    return "v1/keys/users"
+
+
+def overview(user_id: str, stype: 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.
+
+    Returns:
+        The relative request path.
+    """
+    return f"v1/overview/{user_id}/{stype}"
+
+
+def feelings(user_id: str, ftype: 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``).
+
+    Returns:
+        The relative request path.
+    """
+    return f"v1/feelings/{user_id}/{ftype}"

python_polsen/api/v1/timeline/__init__.py

@@ -0,0 +1,30 @@
+"""Route builders for the ``v1`` timeline endpoints.
+
+Covers high-frequency time-series paths plus the event paths re-exported from
+:mod:`python_polsen.api.v1.timeline.events`.
+"""
+
+from __future__ import annotations
+
+from ....types import TimeseriesType
+from .events import *
+
+__all__ = [
+    "events",
+    "timeseries",
+]
+
+_BASE = "v1/timeline/timeseries"
+
+
+def timeseries(user_id: str, mtype: 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.
+
+    Returns:
+        The relative request path.
+    """
+    return f"{_BASE}/{user_id}/{mtype}"

python_polsen/api/v1/timeline/events.py

@@ -0,0 +1,63 @@
+"""Route builders for the ``v1`` timeline event endpoints."""
+
+_BASE = "v1/timeline/events"
+
+
+def sleep(user_id: str) -> str:
+    """Build the path for ``GET /v1/timeline/events/sleep/{user_id}``.
+
+    Args:
+        user_id: Identifier of the user (``uid_...``).
+
+    Returns:
+        The relative request path.
+    """
+    return f"{_BASE}/sleep/{user_id}"
+
+
+def checkins(user_id: str) -> str:
+    """Build the path for ``GET /v1/timeline/events/checkins/{user_id}``.
+
+    Args:
+        user_id: Identifier of the user (``uid_...``).
+
+    Returns:
+        The relative request path.
+    """
+    return f"{_BASE}/checkins/{user_id}"
+
+
+def activities(user_id: str) -> str:
+    """Build the path for ``GET /v1/timeline/events/activities/{user_id}``.
+
+    Args:
+        user_id: Identifier of the user (``uid_...``).
+
+    Returns:
+        The relative request path.
+    """
+    return f"{_BASE}/activities/{user_id}"
+
+
+def timezones(user_id: str) -> str:
+    """Build the path for ``GET /v1/timeline/events/timezones/{user_id}``.
+
+    Args:
+        user_id: Identifier of the user (``uid_...``).
+
+    Returns:
+        The relative request path.
+    """
+    return f"{_BASE}/timezones/{user_id}"
+
+
+def crown_presses(user_id: str) -> str:
+    """Build the path for ``GET /v1/timeline/events/crown_presses/{user_id}``.
+
+    Args:
+        user_id: Identifier of the user (``uid_...``).
+
+    Returns:
+        The relative request path.
+    """
+    return f"{_BASE}/crown_presses/{user_id}"

python_polsen/const.py

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

python_polsen/exceptions.py

@@ -0,0 +1,85 @@
+"""Exception hierarchy for the Polsen Health API.
+
+The API reports errors as RFC 7807 ``ProblemDetail`` documents. Each subclass
+maps a distinct HTTP status to an exception type, and any additional problem
+members (``title``, ``detail``, ``code``, ``request_id``, ...) are attached to
+the exception instance as attributes.
+"""
+
+
+class PolsenError(Exception):
+    """Base class for all Polsen API errors.
+
+    Attributes:
+        status_code: HTTP status code returned by the API, if any.
+        title: Short, human-readable summary from the problem document.
+        detail: Explanation specific to this occurrence, if provided.
+        code: Stable, machine-readable error code, if provided.
+        request_id: Request identifier also returned in ``X-Request-Id``.
+    """
+
+    def __init__(
+        self,
+        body: dict[str, int | str],
+        status_code: int | None,
+    ):
+        """Initialise the error from a decoded problem document.
+
+        Args:
+            body: Decoded ``ProblemDetail`` JSON body; each key is copied onto
+                the instance as an attribute.
+            status_code: HTTP status code that produced the error.
+        """
+        for k, v in body.items():
+            setattr(self, k, v)
+
+        self.status_code = status_code
+
+        title = getattr(self, "title", None)
+        detail = getattr(self, "detail", None)
+        if title is not None and detail is not None:
+            message = f"{title}: {detail}"
+        else:
+            message = f"Unknown Polsen API error: {body}"
+
+        super().__init__(message)
+
+
+class AuthenticationError(PolsenError):
+    """Raised for HTTP 401/403 responses (missing or invalid API key)."""
+
+
+class NotFoundError(PolsenError):
+    """Raised for HTTP 404 responses (unknown user or resource)."""
+
+
+class ValidationError(PolsenError):
+    """Raised for HTTP 422 responses (invalid query or path parameters)."""
+
+
+class RateLimitError(PolsenError):
+    """Raised for HTTP 429 responses, carrying how long to wait before retrying.
+
+    Attributes:
+        retry_after: Seconds to wait, taken from the ``Retry-After`` header.
+    """
+
+    def __init__(
+        self,
+        body: dict[str, int | str],
+        status_code: int,
+        retry_after: int = 2,
+    ):
+        """Initialise the error and record the retry delay.
+
+        Args:
+            body: Decoded ``ProblemDetail`` JSON body.
+            status_code: HTTP status code (expected to be 429).
+            retry_after: Seconds to wait before retrying the request.
+        """
+        super().__init__(body, status_code=status_code)
+        self.retry_after = retry_after
+
+
+class APIError(PolsenError):
+    """Raised for any other non-2xx HTTP response."""

python_polsen/polsen.py

@@ -0,0 +1,318 @@
+"""Asynchronous client for the Polsen Health API (v1).
+
+:class:`PolsenClient` wraps the endpoints described in ``openapi.json`` behind
+typed coroutines. Every request is authenticated with the ``X-API-KEY`` header,
+and URLs are assembled from the route builders in :mod:`python_polsen.api.v1`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import ssl
+from dataclasses import dataclass, field
+from http import HTTPMethod, HTTPStatus
+from typing import Any, Self
+
+import certifi
+from aiohttp import ClientSession, ContentTypeError, TCPConnector
+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 .utils import retry_on_rate_limit
+
+
+@dataclass
+class PolsenClient:
+    """Async client for the Polsen Health API.
+
+    The client is an async context manager; use ``async with`` to guarantee the
+    underlying session is closed.
+
+    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`.
+        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.
+    """
+
+    api_key: str = field(repr=False)
+    session: ClientSession | None = None
+    base_url: str = field(default=API_URL)
+    api: Any = field(default=v1, repr=False)
+    _close_session: bool = False
+    _max_retries: int = 3
+    _lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False, init=False)
+
+    @retry_on_rate_limit
+    async def _request(
+        self, uri: str, *, headers: dict[str, str] | None = None, **kwargs
+    ) -> dict[str, Any]:
+        """Perform an authenticated GET request and decode the JSON response.
+
+        Args:
+            uri: Path to request, relative to ``base_url``.
+            headers: Optional headers merged over the default API-key header.
+            **kwargs: Forwarded to the underlying ``aiohttp`` request.
+
+        Returns:
+            The decoded JSON body, or an empty dict for empty/non-JSON responses.
+
+        Raises:
+            AuthenticationError: On 401/403 responses.
+            NotFoundError: On 404 responses.
+            ValidationError: On 422 responses.
+            RateLimitError: On 429 responses.
+            APIError: On any other non-2xx response.
+        """
+        url = URL.build(
+            scheme="https",
+            host=self.base_url,
+            port=443,
+        ).joinpath(uri)
+
+        _headers = {
+            "X-API-KEY": f"{self.api_key}",
+        }
+
+        if headers:
+            _headers.update(headers)
+
+        session = await self._get_session()
+
+        async with session.request(
+            HTTPMethod.GET, url, headers=_headers, **kwargs
+        ) as response:
+            try:
+                body = await response.json()
+            except ContentTypeError:
+                body = {}
+
+            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)
+
+    async def _get_session(self) -> ClientSession:
+        """Return the shared session, creating one if necessary.
+
+        The lazily created session uses a ``certifi`` CA bundle for TLS
+        verification.
+
+        Returns:
+            The active ``aiohttp`` client session.
+        """
+        if self.session is None:
+            async with self._lock:
+                ssl_context = ssl.create_default_context(cafile=certifi.where())
+                connector = TCPConnector(ssl=ssl_context)
+                self.session = ClientSession(connector=connector)
+                self._close_session = True
+        return self.session
+
+    async def get_user_ids(self) -> list[str]:
+        """List the users accessible with the configured API key.
+
+        Calls ``GET /v1/keys/users``.
+
+        Returns:
+            Encrypted user ids (``uid_...``) the key can access.
+        """
+        response = await self._request(self.api.keys())
+        return response.get("user_ids", [])
+
+    async def get_user(self, user_id: str) -> dict[str, str | int]:
+        """Fetch the profile of a single user.
+
+        Calls ``GET /v1/user/{user_id}``.
+
+        Args:
+            user_id: Identifier of the user (``uid_...``).
+
+        Returns:
+            The user's profile fields (name, age, sex, height, weight, ...).
+        """
+        return await self._request(self.api.user(user_id))
+
+    async def get_timeseries(
+        self, user_id: str, timeseries_type: TimeseriesType, **kwargs
+    ) -> Any:
+        """Fetch high-frequency time-series data for a user.
+
+        Calls ``GET /v1/timeline/timeseries/{user_id}/{mtype}``.
+
+        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``.
+
+        Returns:
+            The columnar ``MeasurementJSONPage`` envelope (time-stamped series
+            plus ``next_cursor``).
+        """
+        return await self._request(
+            self.api.timeline.timeseries(user_id, timeseries_type), **kwargs
+        )
+
+    async def get_sleep(self, user_id: str, **kwargs) -> 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``.
+
+        Returns:
+            A ``Page[Sleep]`` envelope with sleep events and ``next_cursor``.
+        """
+        return await self._request(self.api.timeline.events.sleep(user_id), **kwargs)
+
+    async def get_activities(self, user_id: str, **kwargs) -> 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``.
+
+        Returns:
+            A ``Page[ActivityModel]`` envelope with activity events and
+            ``next_cursor``.
+        """
+        return await self._request(
+            self.api.timeline.events.activities(user_id), **kwargs
+        )
+
+    async def get_checkins(self, user_id: str, **kwargs) -> 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``.
+
+        Returns:
+            A ``Page[CheckinModel]`` envelope with check-in events and
+            ``next_cursor``.
+        """
+        return await self._request(self.api.timeline.events.checkins(user_id), **kwargs)
+
+    async def get_timezone(self, user_id: str, **kwargs) -> 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``.
+
+        Returns:
+            A ``Page[TimezoneResponse]`` envelope with timezone events and
+            ``next_cursor``.
+        """
+        return await self._request(
+            self.api.timeline.events.timezones(user_id), **kwargs
+        )
+
+    async def get_crown_presses(self, user_id: str, **kwargs) -> 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``.
+
+        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
+        )
+
+    async def get_overview(
+        self, user_id: str, overview_metric: OverviewMetric, **kwargs
+    ) -> Any:
+        """Fetch daily/typical statistics for one overview metric.
+
+        Calls ``GET /v1/overview/{user_id}/{stype}``.
+
+        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``.
+
+        Returns:
+            A list of per-day metric objects for the requested range.
+        """
+        return await self._request(
+            self.api.overview(user_id, overview_metric), **kwargs
+        )
+
+    async def get_feelings(
+        self, user_id: str, feeling_type: FeelingType, **kwargs
+    ) -> Any:
+        """Fetch self-reported feelings for a user.
+
+        Calls ``GET /v1/feelings/{user_id}/{ftype}``.
+
+        Args:
+            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``.
+
+        Returns:
+            A ``Page[FeelingsModel]`` envelope with dated feeling values and
+            ``next_cursor``.
+        """
+        return await self._request(self.api.feelings(user_id, feeling_type), **kwargs)
+
+    async def close(self) -> None:
+        """Close the underlying session if this client created it."""
+        if self.session and self._close_session:
+            await self.session.close()
+
+    async def __aenter__(self) -> Self:
+        """Enter the async context manager and return the client."""
+        return self
+
+    async def __aexit__(self, *_exc_info: object) -> None:
+        """Close the client when leaving the async context manager."""
+        await self.close()

python_polsen/types.py

@@ -0,0 +1,67 @@
+"""Typed enumerations for the Polsen Health API request parameters.
+
+The members mirror the ``enum`` values declared under ``components.schemas`` in
+``openapi.json`` for the path and query parameters that select a metric,
+timeline or feelings type. As :class:`~enum.StrEnum` subclasses their values
+serialise directly into the request URL.
+"""
+
+from enum import StrEnum
+
+
+class OverviewMetric(StrEnum):
+    """Statistical overview metric accepted by ``/v1/overview/{user_id}/{stype}``.
+
+    Passed as the ``stype`` path parameter; each member maps to one of the
+    overview schemas in ``openapi.json`` (``HRV``, ``RHR``, ``SLEEP_DURATION``,
+    ...).
+    """
+
+    HRV = "HRV"
+    SLEEP_DURATION = "SLEEP_DURATION"
+    SLEEP_REGULARITY = "SLEEP_REGULARITY"
+    INTENSE_ACTIVITY = "INTENSE_ACTIVITY"
+    RHR = "RHR"
+    STRESS_DURATION = "STRESS_DURATION"
+    STRESS_RECOVERY = "STRESS_RECOVERY"
+    STRESS_FREQUENCY = "STRESS_FREQUENCY"
+    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}``.
+
+    Passed as the ``mtype`` path parameter.
+    """
+
+    HEART_RATE = "HEART_RATE"
+    ACTIVITY_COUNT = "ACTIVITY_COUNT"
+    ACTIVITY_TYPE = "ACTIVITY_TYPE"
+    STEPS = "STEPS"
+    MOTION = "MOTION"
+    SKIN_TEMPERATURE = "SKIN_TEMPERATURE"
+    REACTIVITY_MONITOR = "REACTIVITY_MONITOR"
+    SKIN_CONDUCTANCE_LEVEL = "SKIN_CONDUCTANCE_LEVEL"
+    INTERBEAT_INTERVALS = "INTERBEAT_INTERVALS"
+
+
+class FeelingType(StrEnum):
+    """Feelings category accepted by ``/v1/feelings/{user_id}/{ftype}``.
+
+    ``DAY`` selects self-reported feelings for the waking day and ``SLEEP``
+    those recorded for the preceding night.
+    """
+
+    DAY = "DAY"
+    SLEEP = "SLEEP"

python_polsen/utils.py

@@ -0,0 +1,29 @@
+"""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

python_polsen-0.1.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.3
+Name: python-polsen
+Version: 0.1.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>
+Requires-Dist: aiohttp>=3.14.5
+Requires-Dist: certifi>=2026.7.22
+Requires-Dist: dotenv>=0.9.9
+Requires-Dist: yarl>=1.25.1
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# python-polsen
+
+An asynchronous Python client for the [Polsen Health API](https://docs.research-api.nowatch.com/)
+(v1), the service exposing physiological and contextual data collected by Polsen
+devices and processed by the Polsen App for scientific and research use.
+
+The client wraps the endpoints described in the official
+[OpenAPI specification](https://api.polsen.health/openapi.json). Every request is
+authenticated with an `X-API-KEY` header, and responses are decoded to plain
+Python objects.
+
+Requires Python 3.14 or newer.
+
+## Getting an API key
+
+Access is gated by groups and user-controlled sharing, both managed in the
+Polsen Health Together Dashboard. In short:
+
+1. Create an account.
+2. Enable data sharing in your account settings.
+3. Create a group.
+4. Generate an API key linked to that group.
+
+See the [Data sharing & access](https://docs.research-api.nowatch.com/getting-started/data-sharing/)
+guide for the full details, including how to request access to another user's
+data.
+
+## Quickstart
+
+```python
+import asyncio
+
+from python_polsen.polsen import PolsenClient
+from python_polsen.types import TimeseriesType
+
+
+async def main() -> None:
+    async with PolsenClient(api_key="YOUR_API_KEY") as client:
+        user_ids = await client.get_user_ids()
+
+        user = await client.get_user(user_ids[0])
+
+        heart_rate = await client.get_timeseries(
+            user_ids[0],
+            TimeseriesType.HEART_RATE,
+            params={"start_date": "2026-10-17", "end_date": "2026-10-17"},
+        )
+        print(user, heart_rate)
+
+
+asyncio.run(main())
+```
+
+`PolsenClient` is an async context manager, so the underlying `aiohttp` session
+is always closed on exit. You may also inject your own session via the `session`
+argument and call `await client.close()` manually.
+
+## Endpoints
+
+| Method | Endpoint | Returns |
+| --- | --- | --- |
+| `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]` |
+
+### Enums
+
+Request parameters that select a metric or category are exposed as `StrEnum`
+members in `python_polsen.types`:
+
+| Enum | Used by |
+| --- | --- |
+| `TimeseriesType` | `get_timeseries` (`HEART_RATE`, `STEPS`, `MOTION`, ...) |
+| `OverviewMetric` | `get_overview` (`HRV`, `RHR`, `SLEEP_DURATION`, ...) |
+| `FeelingType` | `get_feelings` (`DAY`, `SLEEP`) |
+
+### Pagination
+
+Event and feelings endpoints return a `{ "data": [...], "next_cursor": ... }`
+envelope. Pass dates via the request `params`:
+
+```python
+page = await client.get_sleep(
+    user_id,
+    params={"start_date": "2026-10-01", "end_date": "2026-10-07"},
+)
+
+while page["next_cursor"]:
+    page = await client.get_sleep(
+        user_id,
+        params={
+            "start_date": "2026-10-01",
+            "end_date": "2026-10-07",
+            "cursor": page["next_cursor"],
+        },
+    )
+```
+
+Time-series responses use a columnar `MeasurementJSONPage`
+(`{"data": {"datetime": [...], "value": [...]}, "next_cursor": ...}`) rather
+than a list of rows.
+
+## Error handling
+
+Non-2xx responses are raised as exceptions derived from `PolsenError`:
+
+| Exception | HTTP status |
+| --- | --- |
+| `AuthenticationError` | 401 / 403 |
+| `NotFoundError` | 404 |
+| `ValidationError` | 422 |
+| `RateLimitError` | 429 |
+| `APIError` | any other non-2xx |
+
+Each exception carries the RFC 7807 problem members (`title`, `detail`, `code`,
+`request_id`, ...) as attributes. `RateLimitError` also exposes `retry_after`;
+requests are retried automatically up to `_max_retries` (default 3) before the
+error propagates.
+
+```python
+from python_polsen.exceptions import NotFoundError
+
+try:
+    user = await client.get_user("uid_unknown")
+except NotFoundError as exc:
+    print(exc.code, exc.request_id)
+```

python_polsen-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+python_polsen/__init__.py,sha256=Uo_bZ0X-fN0P8iUaqtaB2JAVLbqbiGDMzX7yNmRgvL4,714
+python_polsen/api/__init__.py,sha256=8EQSD37JgvAFkVH_DgFrsBUAU6K8KTXWDvEIrQmb5Jc,309
+python_polsen/api/v1/__init__.py,sha256=IifCLWAuLNi00z9ADskRSLnMPRFi4LDJAbqdUXcKXgs,1550
+python_polsen/api/v1/timeline/__init__.py,sha256=adyCx9L_5VEbQhTS_1Rq7jSDOzYhZuXNOeg9hjEO9ds,705
+python_polsen/api/v1/timeline/events.py,sha256=GUpExYjA_2ZZ4iVU4AE5jb3MC2aWGYxCJ31SjYsMAKc,1482
+python_polsen/const.py,sha256=rK9ybyahbwP8foUcxZrYBmSzzEGPWYlcqBrDis7tZ-M,178
+python_polsen/exceptions.py,sha256=K6QW8EP0NNdo-MSCocSvKc9cTJNpqNgZ1sWM7w6wlvA,2713
+python_polsen/polsen.py,sha256=zA4fTpRmujljTpZB4t6vA996xKuZFY3Zrx6Y1LKTPw0,11499
+python_polsen/types.py,sha256=FKpZtlTW9S3fXwNyaj4OPNxBIQ2Xf2yZLRbfS0_I6SM,2035
+python_polsen/utils.py,sha256=Z1hFyffyk_SnSEI3atG6xQP32zgeFghsEBW8-YXn9jo,908
+python_polsen-0.1.0.dist-info/WHEEL,sha256=9IUYslYuG_asT4WlWvfk_K76nveuLvSTKDoLeL0cV-Q,80
+python_polsen-0.1.0.dist-info/entry_points.txt,sha256=pgvAjwejYhQBJIFHUysTDlLPBJ-Ol9ieHmrwgJ8TT3Q,54
+python_polsen-0.1.0.dist-info/METADATA,sha256=FUHa3FUcUq2nOoXhMOxh21x-1UejN1Wjj8RnLkMzKeU,5239
+python_polsen-0.1.0.dist-info/RECORD,,

python_polsen-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.1
+Root-Is-Purelib: true
+Tag: py3-none-any

python_polsen-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+python-polsen = python_polsen:main
+