Cookidoo API

An unofficial python package to access Cookidoo.

Disclaimer

The developers of this module are in no way endorsed by or affiliated with Cookidoo or Vorwerk, or any associated subsidiaries, logos or trademarks.

Installation

pip install cookidoo-api

Documentation

See below for usage examples.

Usage Example

The API is based on the aiohttp library. Authentication uses the OAuth2 authorization-code flow (with PKCE) and authenticates requests with a bearer token; tokens can be persisted with save_token/load_token. A CookieJar(unsafe=True) is still required for the session, as the login redirect chain relies on cookies.

Make sure to have stored your credentials in the top-level file .env as such, to loaded by dotenv. Alternatively, provide the environment variables by any other dotenv compatible means.

EMAIL=your@mail.com
PASSWORD=password

Your account credentials are all that is needed. The library logs in as a public OAuth2 client — authorization code with PKCE and no client secret — so there is nothing else to obtain or configure. See OAuth2 client if you want to override the client identifiers anyway.

Run the example script and have a look at the inline comments for more explanation.

Exceptions

In case something goes wrong during a request, several exceptions can be thrown, all inheriting from CookidooException.

Another asyncio event loop is

With the async calls, you might encounter an error that another asyncio event loop is already running on the same thread. This is expected behavior according to the asyncio.run() documentation. You cannot use more than one aiohttp session per thread, reuse the existing one!

Exception ignored: RuntimeError: Event loop is closed

Due to a known issue in some versions of aiohttp when using Windows, you might encounter a similar error to this:

Exception ignored in: <function _ProactorBasePipeTransport.__del__ at 0x00000000>
Traceback (most recent call last):
  File "C:\...\py38\lib\asyncio\proactor_events.py", line 116, in __del__
    self.close()
  File "C:\...\py38\lib\asyncio\proactor_events.py", line 108, in close
    self._loop.call_soon(self._call_connection_lost, None)
  File "C:\...\py38\lib\asyncio\base_events.py", line 719, in call_soon
    self._check_closed()
  File "C:\...\py38\lib\asyncio\base_events.py", line 508, in _check_closed
    raise RuntimeError('Event loop is closed')
RuntimeError: Event loop is closed

You can fix this according to this StackOverflow answer by adding the following line of code before executing the library:

asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())

Dev

Local Setup

Setup the dev environment using VSCode, it is highly recommended.

python -m venv .venv
source .venv/bin/activate
pip install -r requirements_dev.txt

Install pre-commit

pre-commit install

# Run the commit hooks manually
pre-commit run --all-files

Devcontainer & Docker Setup

For developers using VS Code, the repository includes a fully configured .devcontainer. Simply open the project in VS Code and click "Reopen in Container". All Python requirements, linters, and hooks will initialize automatically!

Alternatively, you can manually run the development environment using standard Docker Compose. First, set up your configuration:

cp .env.example .env

(Update .env with your Cookidoo credentials.)

Then, run the container:

docker-compose up -d
docker-compose exec dev bash

Inside the container, you can run the same hooks and commands as locally:

pre-commit install
pre-commit run --all-files
pytest tests/

Note: If using the Devcontainer, these VS Code extensions are automatically installed for you.

Following VSCode integrations may be helpful:

• ruff
• mypy
• markdownlint

Raw API Requests

The raw requests intercepted between the Cookidoo Android App and the backend can be found here ./docs/raw-api-requests. They have been used to reconstruct the API which is implemented in this library.

Testing

There is a set of tests based on the current behaviour of the API.

Unit tests

The unit tests base on the recorded payloads captured between the server and the android app. They are a snapshot and might change.

Smoke tests

The smoke tests implements a series of request querying the server. It tries to cover as much functionality as possible while not impacting the server too much (we want to stay nice and not get noticed ^^). Therefore, it still might be the case that something breaks without noticing. Further, as it is a github action, only non-premium are tested, as it is currently not deemed worth keeping premium subscription for this sole purpose (might change my mind with a few donations^^). Should something break for premium features, a temporary account with trial period is created easily.

Releasing

A final version can only be released from the master branch. To pass the gates of the publish workflow, the version must match in both the tag and cookidoo_api/__init__.py.

To release a prerelease version, it must be done from a feature branch (not master). Prerelease versions are explicitly marked as such on the GitHub release page.

Roadmap

• Add custom recipes to calendar and shopping list
• Edit custom recipes
• Create blank custom recipes (not copy existing)