whoopy


Namewhoopy JSON
Version 0.2.1 PyPI version JSON
download
home_pagehttps://github.com/felixnext/whoopy
SummaryUnofficial Client for the Whoop API
upload_time2024-06-16 13:17:37
maintainerNone
docs_urlNone
authorFelix Geilert
requires_pythonNone
licenseMIT License
keywords whoop api
VCS
bugtrack_url
requirements pydantic python_dateutil requests pandas numpy time_helper
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Whoop Python Client

This is an unofficial implementation of the [official Whoop API](https://developer.whoop.com/docs/introduction).

## Getting Started

First you will need to install the library:

```bash
# either from pypi
pip install whoopy
# or by local build
pip install .
```

For development you can install the `requirements.txt` or the `env.yaml` conda environment:

```bash
pip install -r requirements.txt
# or
conda env create -f env.yaml
```

In order to use the API, you will need to register your application [here](https://developer-dashboard.whoop.com/) and
enter the `client_id`, `client_secret` and `redirect_uri` in the `config.json` file (you can use the template provided in `config.sample.json`):

```json
{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "YOUR_REDIRECT_URI"
}
```

> Note: For the purposes of local use, you can simply provide `http://localhost:1234` as redirect_uri in the app registration

### Authorization

You can then the config to run through the client authentication and save the token:

```python
import json
from whoopy import WhoopClient

# load the config
conf = json.load(open("config.json", "r"))

# either run through full auth process (useful in jupyter notebooks)
# note: This will open the web browser and require you to copy the code parameter from the resulting uri back
client = WhoopClient.auth_flow(conf["client_id"], conf["client_secret"], conf["redirect_uri"])

# or run through the steps manually (useful in backend)
url = WhoopClient.auth_url(conf["client_id"], conf["client_secret"], conf["redirect_uri"])
# (open here or run a redirect on your backend)
webbrowser.open(url)
# retrieve code
code = input("Auth Code")
client = WhoopClient.authorize(code, conf["client_id"], conf["client_secret"], conf["redirect_uri"])
```

The code can be copied from the address in the browser (marked in bold):

`http://localhost:1234/?code=`**`j54Y9X...m4`**`&scope=offline%20read...&state=9f..05`

> **Note** If you want to know more about this, see [OAuth Flows](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow)

You can also provide a `scope` argument to limit what your client can read.

The system also allows to store, load and refresh your token (given that the `offline` scope is set):

```python
# store the token
client.store_token(".tokens/token.json")

# load the token
client_new = WhoopClient.from_token(".tokens/token.json", config["client_id"], config["client_secret"])

# refresh the current token
client.refresh()
```

### Data Retrieval

Once you have the client registered you can retrieve the data through the different sub-functions:

```python
# user info
user_data = client.user.profile()
print(f"Name: {user_data.first_name} {user_data.last_name}")

# other data includes recovery, workout, cycle, sleep (all share the same interface)
# retrieve by single id
item = client.cycle.single("1234")
# this retrieves a list of items
items, _ = client.cycle.collection(start="2022-05-10", end="2022-07-03")
# note: whoop paginates these items - if you want to control the page yourself you can use the token
items1, token = client.cycle.collection(start="2022-05-10", end="2022-07-03", get_all_pages=False)
items2, token = client.cycle.collection(start="2022-05-10", end="2022-07-03", next=token, get_all_pages=False)
# retrieve data as pandas dataframe
df, _ = client.cycle.collection_df(start="2022-05-10", end="2022-07-03")
```

For a full description of the available routes, see [official docs](https://developer.whoop.com/api).

## Tools

The repo also contains a dashboard to explore and download your whoop data using streamlit.

To get started, simply install the requirements in the `tools/explorer` folder:

```bash
pip install -r requirements.txt
```

Then run the streamlit app:

```bash
streamlit run explorer.py
```

This should give you the dashboard:
![Dashboard](assets/explorer.jpeg)

It also allows you to download your data directly:
![Download](assets/download.jpeg)

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/felixnext/whoopy",
    "name": "whoopy",
    "maintainer": null,
    "docs_url": null,
    "requires_python": null,
    "maintainer_email": null,
    "keywords": "whoop api",
    "author": "Felix Geilert",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/cc/4a/3e0596697464008b8500a3bae1ead2b32c57a2aee420a40c3d6f188d960a/whoopy-0.2.1.tar.gz",
    "platform": null,
    "description": "# Whoop Python Client\n\nThis is an unofficial implementation of the [official Whoop API](https://developer.whoop.com/docs/introduction).\n\n## Getting Started\n\nFirst you will need to install the library:\n\n```bash\n# either from pypi\npip install whoopy\n# or by local build\npip install .\n```\n\nFor development you can install the `requirements.txt` or the `env.yaml` conda environment:\n\n```bash\npip install -r requirements.txt\n# or\nconda env create -f env.yaml\n```\n\nIn order to use the API, you will need to register your application [here](https://developer-dashboard.whoop.com/) and\nenter the `client_id`, `client_secret` and `redirect_uri` in the `config.json` file (you can use the template provided in `config.sample.json`):\n\n```json\n{\n    \"client_id\": \"YOUR_CLIENT_ID\",\n    \"client_secret\": \"YOUR_CLIENT_SECRET\",\n    \"redirect_uri\": \"YOUR_REDIRECT_URI\"\n}\n```\n\n> Note: For the purposes of local use, you can simply provide `http://localhost:1234` as redirect_uri in the app registration\n\n### Authorization\n\nYou can then the config to run through the client authentication and save the token:\n\n```python\nimport json\nfrom whoopy import WhoopClient\n\n# load the config\nconf = json.load(open(\"config.json\", \"r\"))\n\n# either run through full auth process (useful in jupyter notebooks)\n# note: This will open the web browser and require you to copy the code parameter from the resulting uri back\nclient = WhoopClient.auth_flow(conf[\"client_id\"], conf[\"client_secret\"], conf[\"redirect_uri\"])\n\n# or run through the steps manually (useful in backend)\nurl = WhoopClient.auth_url(conf[\"client_id\"], conf[\"client_secret\"], conf[\"redirect_uri\"])\n# (open here or run a redirect on your backend)\nwebbrowser.open(url)\n# retrieve code\ncode = input(\"Auth Code\")\nclient = WhoopClient.authorize(code, conf[\"client_id\"], conf[\"client_secret\"], conf[\"redirect_uri\"])\n```\n\nThe code can be copied from the address in the browser (marked in bold):\n\n`http://localhost:1234/?code=`**`j54Y9X...m4`**`&scope=offline%20read...&state=9f..05`\n\n> **Note** If you want to know more about this, see [OAuth Flows](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow)\n\nYou can also provide a `scope` argument to limit what your client can read.\n\nThe system also allows to store, load and refresh your token (given that the `offline` scope is set):\n\n```python\n# store the token\nclient.store_token(\".tokens/token.json\")\n\n# load the token\nclient_new = WhoopClient.from_token(\".tokens/token.json\", config[\"client_id\"], config[\"client_secret\"])\n\n# refresh the current token\nclient.refresh()\n```\n\n### Data Retrieval\n\nOnce you have the client registered you can retrieve the data through the different sub-functions:\n\n```python\n# user info\nuser_data = client.user.profile()\nprint(f\"Name: {user_data.first_name} {user_data.last_name}\")\n\n# other data includes recovery, workout, cycle, sleep (all share the same interface)\n# retrieve by single id\nitem = client.cycle.single(\"1234\")\n# this retrieves a list of items\nitems, _ = client.cycle.collection(start=\"2022-05-10\", end=\"2022-07-03\")\n# note: whoop paginates these items - if you want to control the page yourself you can use the token\nitems1, token = client.cycle.collection(start=\"2022-05-10\", end=\"2022-07-03\", get_all_pages=False)\nitems2, token = client.cycle.collection(start=\"2022-05-10\", end=\"2022-07-03\", next=token, get_all_pages=False)\n# retrieve data as pandas dataframe\ndf, _ = client.cycle.collection_df(start=\"2022-05-10\", end=\"2022-07-03\")\n```\n\nFor a full description of the available routes, see [official docs](https://developer.whoop.com/api).\n\n## Tools\n\nThe repo also contains a dashboard to explore and download your whoop data using streamlit.\n\nTo get started, simply install the requirements in the `tools/explorer` folder:\n\n```bash\npip install -r requirements.txt\n```\n\nThen run the streamlit app:\n\n```bash\nstreamlit run explorer.py\n```\n\nThis should give you the dashboard:\n![Dashboard](assets/explorer.jpeg)\n\nIt also allows you to download your data directly:\n![Download](assets/download.jpeg)\n",
    "bugtrack_url": null,
    "license": "MIT License",
    "summary": "Unofficial Client for the Whoop API",
    "version": "0.2.1",
    "project_urls": {
        "Download": "https://github.com/felixnext/whoopy/releases/tag/v0.2.1",
        "Homepage": "https://github.com/felixnext/whoopy"
    },
    "split_keywords": [
        "whoop",
        "api"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "04ece0384c9e263b8e88aa1bd50fb3b95eedd79e0f7f24d317690265ec5640ef",
                "md5": "a7e00c21988c4c82df7c04e04322e5e8",
                "sha256": "07a1755c998fcabd2717421702e77cf208624b65790abb6dd11e78540be92fe9"
            },
            "downloads": -1,
            "filename": "whoopy-0.2.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "a7e00c21988c4c82df7c04e04322e5e8",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 17509,
            "upload_time": "2024-06-16T13:17:35",
            "upload_time_iso_8601": "2024-06-16T13:17:35.554140Z",
            "url": "https://files.pythonhosted.org/packages/04/ec/e0384c9e263b8e88aa1bd50fb3b95eedd79e0f7f24d317690265ec5640ef/whoopy-0.2.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "cc4a3e0596697464008b8500a3bae1ead2b32c57a2aee420a40c3d6f188d960a",
                "md5": "655a3e6a2d0af7eaf52f45775cf663e1",
                "sha256": "8bbb96ec84d3a77cc8244dc7d61a1b279a3aa050a4bee2553488c7696775bdba"
            },
            "downloads": -1,
            "filename": "whoopy-0.2.1.tar.gz",
            "has_sig": false,
            "md5_digest": "655a3e6a2d0af7eaf52f45775cf663e1",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 18375,
            "upload_time": "2024-06-16T13:17:37",
            "upload_time_iso_8601": "2024-06-16T13:17:37.931713Z",
            "url": "https://files.pythonhosted.org/packages/cc/4a/3e0596697464008b8500a3bae1ead2b32c57a2aee420a40c3d6f188d960a/whoopy-0.2.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-06-16 13:17:37",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "felixnext",
    "github_project": "whoopy",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [
        {
            "name": "pydantic",
            "specs": [
                [
                    ">=",
                    "1.10.2"
                ]
            ]
        },
        {
            "name": "python_dateutil",
            "specs": [
                [
                    ">=",
                    "2.8.2"
                ]
            ]
        },
        {
            "name": "requests",
            "specs": [
                [
                    ">=",
                    "2.28.1"
                ]
            ]
        },
        {
            "name": "pandas",
            "specs": [
                [
                    ">=",
                    "1.4.0"
                ]
            ]
        },
        {
            "name": "numpy",
            "specs": [
                [
                    ">=",
                    "1.23.0"
                ]
            ]
        },
        {
            "name": "time_helper",
            "specs": [
                [
                    ">=",
                    "0.1.4"
                ]
            ]
        }
    ],
    "lcname": "whoopy"
}
        
Elapsed time: 0.24073s