Metadata-Version: 2.4
Name: oura-toolkit
Version: 0.3.0
Summary: Oura Ring API v2 client (generated from Oura's OpenAPI spec) — part of oura-toolkit
Author: spxrogers
License: MIT
Project-URL: Repository, https://github.com/spxrogers/oura-toolkit
Keywords: oura,oura-ring,openapi
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: urllib3<3.0.0,>=2.1.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pydantic>=2
Requires-Dist: typing-extensions>=4.7.1
Dynamic: license-file

# oura-toolkit (Python)

Python SDK for the [Oura Ring API v2](https://cloud.ouraring.com/v2/docs), part of
[oura-toolkit](https://github.com/spxrogers/oura-toolkit).

```sh
pip install oura-toolkit
```

One distribution, two submodules:

- `oura_toolkit.api` — the data-plane client, generated from Oura's own OpenAPI spec
  (**do not hand-edit** — regenerated by `just gen-py`). Auth-agnostic: bring a Bearer token.
- `oura_toolkit.auth` — hand-written OAuth companion: token store, refresh with rotation,
  spec-pinned OAuth metadata. It shares the `oura` CLI's on-disk token store
  (`~/.config/oura-toolkit/` on Unix/macOS, `%LOCALAPPDATA%\oura-toolkit\` on Windows) and
  its cross-process refresh protocol, so the CLI, its MCP server, and your Python code can
  all rotate the same tokens safely.

With a token you manage yourself:

```python
from oura_toolkit.api import ApiClient, Configuration

config = Configuration(access_token="<your Oura access token>")
with ApiClient(config) as client:
    ...
```

Or let the companion keep the token fresh (run `oura auth setup` / `oura auth login`
once — interactive OAuth deliberately lives in the CLI, never in this package):

```python
from oura_toolkit.api import ApiClient
from oura_toolkit.auth import TokenManager

manager = TokenManager.load()  # reads the shared token store
with ApiClient(manager.configuration()) as client:
    ...  # every request carries a proactively refreshed Bearer token
```

On a `401`, call `manager.force_refresh()` and retry the request once.

Oura uses OAuth2 with your own registered application (personal access tokens were
deprecated in Dec 2025) — see the [toolkit README](../../README.md) for the registration
walkthrough and the `oura auth setup` flow.
