Reference

Cookidoo API package.

Cookidoo

Unofficial Cookidoo API interface.

Init function for Bring API.

Parameters:

Name	Type	Description	Default
session	ClientSession	The client session for aiohttp requests	required
cfg	CookidooConfig	Cookidoo config	CookidooConfig()

Source code in cookidoo_api/cookidoo.py

def __init__(
    self,
    session: ClientSession,
    cfg: CookidooConfig = CookidooConfig(),
) -> None:
    """Init function for Bring API.

    Parameters
    ----------
    session
        The client session for aiohttp requests
    cfg
        Cookidoo config


    """
    self._session = session
    self._cfg = cfg
    self._token_headers = DEFAULT_TOKEN_HEADERS.copy()
    self._api_headers = DEFAULT_API_HEADERS.copy()
    self.__expires_in: int
    self._auth_data = None

localization property

Localization.

expires_in property writable

Refresh token expiration.

auth_data property writable

Auth data.

api_endpoint property

Get the api endpoint.

refresh_token async

Try to refresh the token.

Returns:

Type	Description
CookidooAuthResponse	The auth response object.

Raises:

Type	Description
CookidooConfigException	If no login has happened yet
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.
CookidooAuthException	If the login fails due invalid credentials. You should check your email and password.

Source code in cookidoo_api/cookidoo.py

async def refresh_token(self) -> CookidooAuthResponse:
    """Try to refresh the token.

    Returns
    -------
    CookidooAuthResponse
        The auth response object.

    Raises
    ------
    CookidooConfigException
        If no login has happened yet
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.
    CookidooAuthException
        If the login fails due invalid credentials.
        You should check your email and password.

    """
    if not self._auth_data:
        raise CookidooConfigException("No auth data available, please log in first")

    refresh_data = FormData()
    refresh_data.add_field("grant_type", "refresh_token")
    refresh_data.add_field("refresh_token", self._auth_data.refresh_token)
    refresh_data.add_field("client_id", COOKIDOO_CLIENT_ID)

    return await self._request_access_token(refresh_data)

login async

Try to login.

Returns:

Type	Description
CookidooAuthResponse	The auth response object.

Raises:

Type	Description
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.
CookidooAuthException	If the login fails due invalid credentials. You should check your email and password.

Source code in cookidoo_api/cookidoo.py

async def login(self) -> CookidooAuthResponse:
    """Try to login.

    Returns
    -------
    CookidooAuthResponse
        The auth response object.

    Raises
    ------
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.
    CookidooAuthException
        If the login fails due invalid credentials.
        You should check your email and password.

    """
    user_data = FormData()
    user_data.add_field("grant_type", "password")
    user_data.add_field("username", self._cfg.email)
    user_data.add_field("password", self._cfg.password)

    return await self._request_access_token(user_data)

get_user_info async

Get user info.

Returns:

Type	Description
CookidooUserInfo	The user info

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def get_user_info(
    self,
) -> CookidooUserInfo:
    """Get user info.

    Returns
    -------
    CookidooUserInfo
        The user info

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """

    try:
        url = self.api_endpoint / COMMUNITY_PROFILE_PATH.format(
            **self._cfg.localization.__dict__
        )
        async with self._session.get(url, headers=self._api_headers) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot get user info: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Loading user info failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()

            try:
                return cookidoo_user_info_from_json((await r.json())["userInfo"])
            except (JSONDecodeError, KeyError) as e:
                _LOGGER.debug(
                    "Exception: Cannot get user info:\n%s",
                    traceback.format_exc(),
                )
                raise CookidooParseException(
                    "Loading user info failed during parsing of request response."
                ) from e
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot get user info:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Loading user info failed due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot user info:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Loading user info failed due to request exception."
        ) from e

get_active_subscription async

Get active subscription if any.

Returns:

Type	Description
CookidooSubscription	The active subscription

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def get_active_subscription(
    self,
) -> CookidooSubscription | None:
    """Get active subscription if any.

    Returns
    -------
    CookidooSubscription
        The active subscription

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """

    try:
        url = self.api_endpoint / SUBSCRIPTIONS_PATH.format(
            **self._cfg.localization.__dict__
        )
        async with self._session.get(url, headers=self._api_headers) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot get active subscription: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Loading active subscription failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()

            try:
                if subscription := next(
                    (
                        subscription
                        for subscription in (await r.json())
                        if subscription["active"]
                    ),
                    None,
                ):
                    return cookidoo_subscription_from_json(subscription)
                else:
                    return None

            except (JSONDecodeError, KeyError) as e:
                _LOGGER.debug(
                    "Exception: Cannot get active subscription:\n%s",
                    traceback.format_exc(),
                )
                raise CookidooParseException(
                    "Loading active subscription failed during parsing of request response."
                ) from e
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot get active subscription:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Loading user info failed due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot active subscription:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Loading active subscription failed due to request exception."
        ) from e

get_recipe_details async

Get recipe details.

Parameters:

Name	Type	Description	Default
id	str	The id of the recipe	required

Returns:

Type	Description
CookidooShoppingRecipeDetails	The recipe details

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def get_recipe_details(self, id: str) -> CookidooShoppingRecipeDetails:
    """Get recipe details.

    Parameters
    ----------
    id
        The id of the recipe

    Returns
    -------
    CookidooShoppingRecipeDetails
        The recipe details

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """

    try:
        url = self.api_endpoint / RECIPE_PATH.format(
            **self._cfg.localization.__dict__, id=id
        )
        async with self._session.get(url, headers=self._api_headers) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot get recipe details: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Loading recipe details failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()

            try:
                return cookidoo_recipe_details_from_json(
                    cast(RecipeDetailsJSON, await r.json())
                )

            except (JSONDecodeError, KeyError) as e:
                _LOGGER.debug(
                    "Exception: Cannot get recipe details:\n%s",
                    traceback.format_exc(),
                )
                raise CookidooParseException(
                    "Loading recipe details failed during parsing of request response."
                ) from e
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot get recipe details:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Loading recipe details failed due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot recipe details:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Loading recipe details failed due to request exception."
        ) from e

get_shopping_list_recipes async

Get recipes.

Returns:

Type	Description
list[CookidooShoppingRecipe]	The list of the recipes

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def get_shopping_list_recipes(
    self,
) -> list[CookidooShoppingRecipe]:
    """Get recipes.

    Returns
    -------
    list[CookidooShoppingRecipe]
        The list of the recipes

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """

    try:
        url = self.api_endpoint / SHOPPING_LIST_RECIPES_PATH.format(
            **self._cfg.localization.__dict__
        )
        async with self._session.get(url, headers=self._api_headers) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot get recipes: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Loading recipes failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()

            try:
                return [
                    cookidoo_recipe_from_json(cast(RecipeJSON, recipe))
                    for recipe in (await r.json())["recipes"]
                ]

            except (JSONDecodeError, KeyError) as e:
                _LOGGER.debug(
                    "Exception: Cannot get recipes:\n%s",
                    traceback.format_exc(),
                )
                raise CookidooParseException(
                    "Loading recipes failed during parsing of request response."
                ) from e
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot get recipes:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Loading recipes failed due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot recipes:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Loading recipes failed due to request exception."
        ) from e

get_ingredient_items async

Get ingredient items.

Returns:

Type	Description
list[CookidooIngredientItem]	The list of the ingredient items

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def get_ingredient_items(
    self,
) -> list[CookidooIngredientItem]:
    """Get ingredient items.

    Returns
    -------
    list[CookidooIngredientItem]
        The list of the ingredient items

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """

    try:
        url = self.api_endpoint / INGREDIENT_ITEMS_PATH.format(
            **self._cfg.localization.__dict__
        )
        async with self._session.get(url, headers=self._api_headers) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot get ingredient items: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Loading ingredient items failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()

            try:
                return [
                    cookidoo_ingredient_item_from_json(cast(ItemJSON, ingredient))
                    for recipe in (await r.json())["recipes"]
                    for ingredient in recipe["recipeIngredientGroups"]
                ]

            except (JSONDecodeError, KeyError) as e:
                _LOGGER.debug(
                    "Exception: Cannot get ingredient items:\n%s",
                    traceback.format_exc(),
                )
                raise CookidooParseException(
                    "Loading ingredient items failed during parsing of request response."
                ) from e
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot get ingredient items:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Loading ingredient items failed due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot ingredient items:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Loading ingredient items failed due to request exception."
        ) from e

add_ingredient_items_for_recipes async

Add ingredient items for recipes.

Parameters:

Name	Type	Description	Default
recipe_ids	list[str]	The recipe ids for the ingredient items to add to the shopping list	required

Returns:

Type	Description
list[CookidooIngredientItem]	The list of the added ingredient items

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def add_ingredient_items_for_recipes(
    self,
    recipe_ids: list[str],
) -> list[CookidooIngredientItem]:
    """Add ingredient items for recipes.

    Parameters
    ----------
    recipe_ids
        The recipe ids for the ingredient items to add to the shopping list

    Returns
    -------
    list[CookidooIngredientItem]
        The list of the added ingredient items

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """
    json_data = {"recipeIDs": recipe_ids}
    try:
        url = self.api_endpoint / ADD_INGREDIENT_ITEMS_FOR_RECIPES_PATH.format(
            **self._cfg.localization.__dict__
        )
        async with self._session.post(
            url, headers=self._api_headers, json=json_data
        ) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot add ingredient items for recipes: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Add ingredient items for recipes failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()
            try:
                return [
                    cookidoo_ingredient_item_from_json(cast(ItemJSON, ingredient))
                    for recipe in (await r.json())["data"]
                    for ingredient in recipe["recipeIngredientGroups"]
                ]
            except (JSONDecodeError, KeyError) as e:
                _LOGGER.debug(
                    "Exception: Cannot get added ingredient items:\n%s",
                    traceback.format_exc(),
                )
                raise CookidooParseException(
                    "Loading added ingredient items failed during parsing of request response."
                ) from e
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot execute add ingredient items for recipes:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Add ingredient items for recipes failed due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot execute add ingredient items for recipes:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Add ingredient items for recipes failed due to request exception."
        ) from e

remove_ingredient_items_for_recipes async

Remove ingredient items for recipes.

Parameters:

Name	Type	Description	Default
recipe_ids	list[str]	The recipe ids for the ingredient items to remove to the shopping list	required

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def remove_ingredient_items_for_recipes(
    self,
    recipe_ids: list[str],
) -> None:
    """Remove ingredient items for recipes.

    Parameters
    ----------
    recipe_ids
        The recipe ids for the ingredient items to remove to the shopping list

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """
    json_data = {"recipeIDs": recipe_ids}
    try:
        url = self.api_endpoint / REMOVE_INGREDIENT_ITEMS_FOR_RECIPES_PATH.format(
            **self._cfg.localization.__dict__
        )
        async with self._session.post(
            url, headers=self._api_headers, json=json_data
        ) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot remove ingredient items for recipes: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Remove ingredient items for recipes failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot execute remove ingredient items for recipes:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Remove ingredient items for recipes failed due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot execute remove ingredient items for recipes:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Remove ingredient items for recipes failed due to request exception."
        ) from e

edit_ingredient_items_ownership async

Edit ownership ingredient items.

Parameters:

Name	Type	Description	Default
ingredient_items	list[CookidooIngredientItem]	The ingredient items to change the the is_owned value for	required

Returns:

Type	Description
list[CookidooIngredientItem]	The list of the edited ingredient items

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def edit_ingredient_items_ownership(
    self,
    ingredient_items: list[CookidooIngredientItem],
) -> list[CookidooIngredientItem]:
    """Edit ownership ingredient items.

    Parameters
    ----------
    ingredient_items
        The ingredient items to change the the `is_owned` value for

    Returns
    -------
    list[CookidooIngredientItem]
        The list of the edited ingredient items

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """
    json_data = {
        "ingredients": [
            {
                "id": ingredient_item.id,
                "isOwned": ingredient_item.is_owned,
                "ownedTimestamp": int(time.time()),
            }
            for ingredient_item in ingredient_items
        ]
    }
    try:
        url = self.api_endpoint / EDIT_OWNERSHIP_INGREDIENT_ITEMS_PATH.format(
            **self._cfg.localization.__dict__
        )
        async with self._session.post(
            url, headers=self._api_headers, json=json_data
        ) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot edit recipe ingredient items ownership: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Edit ingredient items ownership failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()
            try:
                return [
                    cookidoo_ingredient_item_from_json(cast(ItemJSON, ingredient))
                    for ingredient in (await r.json())["data"]
                ]

            except (JSONDecodeError, KeyError) as e:
                _LOGGER.debug(
                    "Exception: Cannot get edited ingredient items:\n%s",
                    traceback.format_exc(),
                )
                raise CookidooParseException(
                    "Loading edited ingredient items failed during parsing of request response."
                ) from e
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot execute edit ingredient items ownership:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Edit ingredient items ownership failed due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot execute edit ingredient items ownership:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Edit ingredient items ownership failed due to request exception."
        ) from e

get_additional_items async

Get additional items.

Returns:

Type	Description
list[CookidooAdditionalItem]	The list of the additional items

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def get_additional_items(
    self,
) -> list[CookidooAdditionalItem]:
    """Get additional items.

    Returns
    -------
    list[CookidooAdditionalItem]
        The list of the additional items

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """

    try:
        url = self.api_endpoint / ADDITIONAL_ITEMS_PATH.format(
            **self._cfg.localization.__dict__
        )
        async with self._session.get(url, headers=self._api_headers) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot get additional items: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Loading additional items failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()

            try:
                return [
                    cookidoo_additional_item_from_json(
                        cast(AdditionalItemJSON, additional_item)
                    )
                    for additional_item in (await r.json())["additionalItems"]
                ]

            except (JSONDecodeError, KeyError) as e:
                _LOGGER.debug(
                    "Exception: Cannot get additional items:\n%s",
                    traceback.format_exc(),
                )
                raise CookidooParseException(
                    "Loading additional items failed during parsing of request response."
                ) from e
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot get additional items:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Loading additional items failed due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot additional items:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Loading additional items failed due to request exception."
        ) from e

add_additional_items async

Create additional items.

Parameters:

Name	Type	Description	Default
additional_item_names	list[str]	The additional item names to create, only the label can be set, as the default state is_owned=false is forced (chain with immediate update call for work-around)	required

Returns:

Type	Description
list[CookidooAdditionalItem]	The list of the added additional items

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def add_additional_items(
    self,
    additional_item_names: list[str],
) -> list[CookidooAdditionalItem]:
    """Create additional items.

    Parameters
    ----------
    additional_item_names
        The additional item names to create, only the label can be set, as the default state `is_owned=false` is forced (chain with immediate update call for work-around)

    Returns
    -------
    list[CookidooAdditionalItem]
        The list of the added additional items

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """
    json_data = {"itemsValue": additional_item_names}
    try:
        url = self.api_endpoint / ADD_ADDITIONAL_ITEMS_PATH.format(
            **self._cfg.localization.__dict__
        )
        async with self._session.post(
            url, headers=self._api_headers, json=json_data
        ) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot add additional items: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Add additional items failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()
            try:
                return [
                    cookidoo_additional_item_from_json(
                        cast(AdditionalItemJSON, additional_item)
                    )
                    for additional_item in (await r.json())["data"]
                ]

            except (JSONDecodeError, KeyError) as e:
                _LOGGER.debug(
                    "Exception: Cannot get added additional items:\n%s",
                    traceback.format_exc(),
                )
                raise CookidooParseException(
                    "Loading added additional items failed during parsing of request response."
                ) from e
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot execute add additional items:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Add additional items failed due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot execute add additional items:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Add additional items failed due to request exception."
        ) from e

edit_additional_items async

Edit additional items.

Parameters:

Name	Type	Description	Default
additional_items	list[CookidooAdditionalItem]	The additional items to change the the name value for	required

Returns:

Type	Description
list[CookidooAdditionalItem]	The list of the edited additional items

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def edit_additional_items(
    self,
    additional_items: list[CookidooAdditionalItem],
) -> list[CookidooAdditionalItem]:
    """Edit additional items.

    Parameters
    ----------
    additional_items
        The additional items to change the the `name` value for

    Returns
    -------
    list[CookidooAdditionalItem]
        The list of the edited additional items

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """
    json_data = {
        "additionalItems": [
            {
                "id": additional_item.id,
                "name": additional_item.name,
            }
            for additional_item in additional_items
        ]
    }
    try:
        url = self.api_endpoint / EDIT_ADDITIONAL_ITEMS_PATH.format(
            **self._cfg.localization.__dict__
        )
        async with self._session.post(
            url, headers=self._api_headers, json=json_data
        ) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot edit additional items: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Edit additional items failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()
            try:
                return [
                    cookidoo_additional_item_from_json(
                        cast(AdditionalItemJSON, additional_item)
                    )
                    for additional_item in (await r.json())["data"]
                ]

            except (JSONDecodeError, KeyError) as e:
                _LOGGER.debug(
                    "Exception: Cannot get edited additional items:\n%s",
                    traceback.format_exc(),
                )
                raise CookidooParseException(
                    "Loading edited additional items failed during parsing of request response."
                ) from e
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot execute edit additional items:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Edit additional items failed due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot execute edit additional items:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Edit additional items failed due to request exception."
        ) from e

edit_additional_items_ownership async

Edit ownership additional items.

Parameters:

Name	Type	Description	Default
additional_items	list[CookidooAdditionalItem]	The additional items to change the the is_owned value for	required

Returns:

Type	Description
list[CookidooAdditionalItem]	The list of the edited additional items

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def edit_additional_items_ownership(
    self,
    additional_items: list[CookidooAdditionalItem],
) -> list[CookidooAdditionalItem]:
    """Edit ownership additional items.

    Parameters
    ----------
    additional_items
        The additional items to change the the `is_owned` value for

    Returns
    -------
    list[CookidooAdditionalItem]
        The list of the edited additional items

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """
    json_data = {
        "additionalItems": [
            {
                "id": additional_item.id,
                "isOwned": additional_item.is_owned,
                "ownedTimestamp": int(time.time()),
            }
            for additional_item in additional_items
        ]
    }
    try:
        url = self.api_endpoint / EDIT_OWNERSHIP_ADDITIONAL_ITEMS_PATH.format(
            **self._cfg.localization.__dict__
        )
        async with self._session.post(
            url, headers=self._api_headers, json=json_data
        ) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot edit additional items ownership: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Edit additional items ownership failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()
            try:
                return [
                    cookidoo_additional_item_from_json(
                        cast(AdditionalItemJSON, additional_item)
                    )
                    for additional_item in (await r.json())["data"]
                ]

            except (JSONDecodeError, KeyError) as e:
                _LOGGER.debug(
                    "Exception: Cannot get edited additional items:\n%s",
                    traceback.format_exc(),
                )
                raise CookidooParseException(
                    "Loading edited additional items failed during parsing of request response."
                ) from e
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot execute edit additional items ownership:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Edit additional items ownership failed due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot execute edit additional items ownership:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Edit additional items ownership failed due to request exception."
        ) from e

remove_additional_items async

Remove additional items.

Parameters:

Name	Type	Description	Default
additional_item_ids	list[str]	The additional item ids to remove	required

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def remove_additional_items(
    self,
    additional_item_ids: list[str],
) -> None:
    """Remove additional items.

    Parameters
    ----------
    additional_item_ids
        The additional item ids to remove

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """
    json_data = {"additionalItemIDs": additional_item_ids}
    try:
        url = self.api_endpoint / REMOVE_ADDITIONAL_ITEMS_PATH.format(
            **self._cfg.localization.__dict__
        )
        async with self._session.post(
            url, headers=self._api_headers, json=json_data
        ) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot remove additional items: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Remove additional items failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot execute remove additional items:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Remove additional items failed due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot execute remove additional items:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Remove additional items failed due to request exception."
        ) from e

clear_shopping_list async

Remove all additional items, ingredients and recipes.

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def clear_shopping_list(
    self,
) -> None:
    """Remove all additional items, ingredients and recipes.

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """
    try:
        url = self.api_endpoint / INGREDIENT_ITEMS_PATH.format(
            **self._cfg.localization.__dict__
        )
        async with self._session.delete(url, headers=self._api_headers) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot clear shopping list: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Clear shopping list failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot execute clear shopping list:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Clear shopping list failed due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot execute clear shopping list:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Clear shopping list failed due to request exception."
        ) from e

count_managed_collections async

Get managed collections.

Returns:

Type	Description
tuple[int, int]	The number of managed collections and the number of pages

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def count_managed_collections(self) -> tuple[int, int]:
    """Get managed collections.

    Returns
    -------
    tuple[int, int]
        The number of managed collections and the number of pages

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """

    try:
        url = self.api_endpoint / MANAGED_COLLECTIONS_PATH.format(
            **self._cfg.localization.__dict__
        )
        async with self._session.get(url, headers=self._api_headers) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot count managed collections: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Loading managed collections failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()

            try:
                json = await r.json()
                return (
                    int(json["page"]["totalElements"]),
                    int(json["page"]["totalPages"]),
                )

            except (JSONDecodeError, KeyError) as e:
                _LOGGER.debug(
                    "Exception: Cannot count managed collections%s",
                    traceback.format_exc(),
                )
                raise CookidooParseException(
                    "Loading managed collections during parsing of request response."
                ) from e
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot count managed collections:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Loading managed collections due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot count managed collections%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Loading managed collections due to request exception."
        ) from e

get_managed_collections async

Get managed collections.

Parameters:

Name	Type	Description	Default
page	int	The page of the managed collections	0

Returns:

Type	Description
list[CookidooCollection]	The list of the managed collections

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def get_managed_collections(self, page: int = 0) -> list[CookidooCollection]:
    """Get managed collections.

    Parameters
    ----------
    page
        The page of the managed collections

    Returns
    -------
    list[CookidooCollection]
        The list of the managed collections

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """

    try:
        url = self.api_endpoint / MANAGED_COLLECTIONS_PATH.format(
            **self._cfg.localization.__dict__
        )
        async with self._session.get(
            url, headers=self._api_headers, params={"page": page}
        ) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot get managed collections: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Loading managed collections failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()

            try:
                return [
                    cookidoo_collection_from_json(cast(ManagedCollectionJSON, list))
                    for list in (await r.json())["managedlists"]
                ]

            except (JSONDecodeError, KeyError) as e:
                _LOGGER.debug(
                    "Exception: Cannot get managed collections%s",
                    traceback.format_exc(),
                )
                raise CookidooParseException(
                    "Loading managed collections during parsing of request response."
                ) from e
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot get managed collections:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Loading managed collections due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot get managed collections%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Loading managed collections due to request exception."
        ) from e

add_managed_collection async

Add managed collections.

Parameters:

Name	Type	Description	Default
managed_collection_id	str	The managed collection id to add	required

Returns:

Type	Description
CookidooCollection	The added managed collection

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def add_managed_collection(
    self,
    managed_collection_id: str,
) -> CookidooCollection:
    """Add managed collections.

    Parameters
    ----------
    managed_collection_id
        The managed collection id to add

    Returns
    -------
    CookidooCollection
        The added managed collection

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """
    json_data = {"collectionId": managed_collection_id}
    try:
        url = self.api_endpoint / ADD_MANAGED_COLLECTION_PATH.format(
            **self._cfg.localization.__dict__
        )
        async with self._session.post(
            url, headers=self._api_headers, json=json_data
        ) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot add managed collection: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Add managed collection failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()
            try:
                return cookidoo_collection_from_json(
                    cast(ManagedCollectionJSON, (await r.json())["content"])
                )

            except (JSONDecodeError, KeyError) as e:
                _LOGGER.debug(
                    "Exception: Cannot get added managed collection:\n%s",
                    traceback.format_exc(),
                )
                raise CookidooParseException(
                    "Loading added managed collection failed during parsing of request response."
                ) from e
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot execute add managed collection:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Add managed collection failed due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot execute add managed collection:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Add managed collection failed due to request exception."
        ) from e

remove_managed_collection async

Remove managed collection.

Parameters:

Name	Type	Description	Default
managed_collection_id	str	The managed collection id to remove	required

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def remove_managed_collection(
    self,
    managed_collection_id: str,
) -> None:
    """Remove managed collection.

    Parameters
    ----------
    managed_collection_id
        The managed collection id to remove

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """
    try:
        url = self.api_endpoint / REMOVE_MANAGED_COLLECTION_PATH.format(
            **self._cfg.localization.__dict__, id=managed_collection_id
        )
        async with self._session.delete(url, headers=self._api_headers) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot remove managed collection: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Remove managed collection failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot execute remove managed collection:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Remove managed collection failed due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot execute remove managed collection:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Remove managed collection failed due to request exception."
        ) from e

count_custom_collections async

Get custom collections.

Returns:

Type	Description
tuple[int, int]	The number of custom collections and the number of pages

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def count_custom_collections(self) -> tuple[int, int]:
    """Get custom collections.

    Returns
    -------
    tuple[int, int]
        The number of custom collections and the number of pages

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """

    try:
        url = self.api_endpoint / CUSTOM_COLLECTIONS_PATH.format(
            **self._cfg.localization.__dict__
        )
        async with self._session.get(url, headers=self._api_headers) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot count custom collections: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Loading custom collections failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()

            try:
                json = await r.json()
                return (
                    int(json["page"]["totalElements"]),
                    int(json["page"]["totalPages"]),
                )

            except (JSONDecodeError, KeyError) as e:
                _LOGGER.debug(
                    "Exception: Cannot count custom collections%s",
                    traceback.format_exc(),
                )
                raise CookidooParseException(
                    "Loading custom collections during parsing of request response."
                ) from e
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot count custom collections:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Loading custom collections due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot count custom collections%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Loading custom collections due to request exception."
        ) from e

get_custom_collections async

Get custom collections.

Parameters:

Name	Type	Description	Default
page	int	The page of the custom collections	0

Returns:

Type	Description
list[CookidooCollection]	The list of the custom collections

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def get_custom_collections(self, page: int = 0) -> list[CookidooCollection]:
    """Get custom collections.

    Parameters
    ----------
    page
        The page of the custom collections

    Returns
    -------
    list[CookidooCollection]
        The list of the custom collections

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """

    try:
        url = self.api_endpoint / CUSTOM_COLLECTIONS_PATH.format(
            **self._cfg.localization.__dict__
        )
        async with self._session.get(
            url, headers=self._api_headers, params={"page": page}
        ) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot get custom collections: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Loading custom collections failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()

            try:
                return [
                    cookidoo_collection_from_json(cast(CustomCollectionJSON, list))
                    for list in (await r.json())["customlists"]
                ]

            except (JSONDecodeError, KeyError) as e:
                _LOGGER.debug(
                    "Exception: Cannot get custom collections%s",
                    traceback.format_exc(),
                )
                raise CookidooParseException(
                    "Loading custom collections during parsing of request response."
                ) from e
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot get custom collections:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Loading custom collections due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot get custom collections%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Loading custom collections due to request exception."
        ) from e

add_custom_collection async

Add custom collections.

Parameters:

Name	Type	Description	Default
custom_collection_name	str	The custom collection name to add	required

Returns:

Type	Description
CookidooCollection	The added custom collection

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def add_custom_collection(
    self,
    custom_collection_name: str,
) -> CookidooCollection:
    """Add custom collections.

    Parameters
    ----------
    custom_collection_name
        The custom collection name to add

    Returns
    -------
    CookidooCollection
        The added custom collection

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """
    json_data = {"title": custom_collection_name}
    try:
        url = self.api_endpoint / ADD_CUSTOM_COLLECTION_PATH.format(
            **self._cfg.localization.__dict__
        )
        async with self._session.post(
            url, headers=self._api_headers, json=json_data
        ) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot add custom collection: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Add custom collection failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()
            try:
                return cookidoo_collection_from_json(
                    cast(CustomCollectionJSON, (await r.json())["content"])
                )

            except (JSONDecodeError, KeyError) as e:
                _LOGGER.debug(
                    "Exception: Cannot get added custom collection:\n%s",
                    traceback.format_exc(),
                )
                raise CookidooParseException(
                    "Loading added custom collection failed during parsing of request response."
                ) from e
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot execute add custom collection:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Add custom collection failed due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot execute add custom collection:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Add custom collection failed due to request exception."
        ) from e

remove_custom_collection async

Remove custom collection.

Parameters:

Name	Type	Description	Default
custom_collection_id	str	The custom collection id to remove	required

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def remove_custom_collection(
    self,
    custom_collection_id: str,
) -> None:
    """Remove custom collection.

    Parameters
    ----------
    custom_collection_id
        The custom collection id to remove

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """
    try:
        url = self.api_endpoint / REMOVE_CUSTOM_COLLECTION_PATH.format(
            **self._cfg.localization.__dict__, id=custom_collection_id
        )
        async with self._session.delete(url, headers=self._api_headers) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot remove custom collection: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Remove custom collection failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot execute remove custom collection:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Remove custom collection failed due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot execute remove custom collection:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Remove custom collection failed due to request exception."
        ) from e

add_recipes_to_custom_collection async

Add recipes to a custom collections.

Parameters:

Name	Type	Description	Default
custom_collection_id	str	The custom collection to add the recipes to	required
recipe_ids	list[str]	The recipe ids to add to a custom collection	required

Returns:

Type	Description
CookidooCollection	The changed custom collection

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def add_recipes_to_custom_collection(
    self,
    custom_collection_id: str,
    recipe_ids: list[str],
) -> CookidooCollection:
    """Add recipes to a custom collections.

    Parameters
    ----------
    custom_collection_id
        The custom collection to add the recipes to
    recipe_ids
        The recipe ids to add to a custom collection

    Returns
    -------
    CookidooCollection
        The changed custom collection

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """
    json_data = {"recipeIds": recipe_ids}
    try:
        url = self.api_endpoint / ADD_RECIPES_TO_CUSTOM_COLLECTION_PATH.format(
            **self._cfg.localization.__dict__, id=custom_collection_id
        )
        async with self._session.put(
            url, headers=self._api_headers, json=json_data
        ) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot add recipes to custom collection: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Add recipes to custom collection failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()
            try:
                return cookidoo_collection_from_json(
                    cast(CustomCollectionJSON, (await r.json())["content"])
                )

            except (JSONDecodeError, KeyError) as e:
                _LOGGER.debug(
                    "Exception: Cannot get added recipes:\n%s",
                    traceback.format_exc(),
                )
                raise CookidooParseException(
                    "Loading added recipes failed during parsing of request response."
                ) from e
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot execute add recipes to custom collection:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Add recipes to custom collection failed due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot execute add recipes to custom collection:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Add recipes to custom collection failed due to request exception."
        ) from e

remove_recipe_from_custom_collection async

Remove recipe from a custom collections.

Parameters:

Name	Type	Description	Default
custom_collection_id	str	The custom collection to remove the recipe from	required
recipe_id	str	The recipe id to remove from a custom collection	required

Returns:

Type	Description
CookidooCollection	The changed custom collection

Raises:

Type	Description
CookidooAuthException	When the access token is not valid anymore
CookidooRequestException	If the request fails.
CookidooParseException	If the parsing of the request response fails.

Source code in cookidoo_api/cookidoo.py

async def remove_recipe_from_custom_collection(
    self,
    custom_collection_id: str,
    recipe_id: str,
) -> CookidooCollection:
    """Remove recipe from a custom collections.

    Parameters
    ----------
    custom_collection_id
        The custom collection to remove the recipe from
    recipe_id
        The recipe id to remove from a custom collection

    Returns
    -------
    CookidooCollection
        The changed custom collection

    Raises
    ------
    CookidooAuthException
        When the access token is not valid anymore
    CookidooRequestException
        If the request fails.
    CookidooParseException
        If the parsing of the request response fails.

    """
    try:
        url = self.api_endpoint / REMOVE_RECIPE_FROM_CUSTOM_COLLECTION_PATH.format(
            **self._cfg.localization.__dict__,
            id=custom_collection_id,
            recipe=recipe_id,
        )
        async with self._session.delete(url, headers=self._api_headers) as r:
            _LOGGER.debug(
                "Response from %s [%s]: %s", url, r.status, await r.text()
            )

            if r.status == HTTPStatus.UNAUTHORIZED:
                try:
                    errmsg = await r.json()
                except (JSONDecodeError, ClientError):
                    _LOGGER.debug(
                        "Exception: Cannot parse request response:\n %s",
                        traceback.format_exc(),
                    )
                else:
                    _LOGGER.debug(
                        "Exception: Cannot remove recipe from custom collection: %s",
                        errmsg["error_description"],
                    )
                raise CookidooAuthException(
                    "Remove recipe from custom collection failed due to authorization failure, "
                    "the authorization token is invalid or expired."
                )

            r.raise_for_status()
            try:
                return cookidoo_collection_from_json(
                    cast(CustomCollectionJSON, (await r.json())["content"])
                )

            except (JSONDecodeError, KeyError) as e:
                _LOGGER.debug(
                    "Exception: Cannot get removed recipe:\n%s",
                    traceback.format_exc(),
                )
                raise CookidooParseException(
                    "Loading removed recipe failed during parsing of request response."
                ) from e
    except TimeoutError as e:
        _LOGGER.debug(
            "Exception: Cannot execute add recipe from custom collection:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Remove recipe from custom collection failed due to connection timeout."
        ) from e
    except ClientError as e:
        _LOGGER.debug(
            "Exception: Cannot execute remove recipe from custom collection:\n%s",
            traceback.format_exc(),
        )
        raise CookidooRequestException(
            "Remove recipe from custom collection failed due to request exception."
        ) from e

CookidooAuthException

Bases: CookidooException

When an authentication error is encountered.

CookidooConfigException

Bases: CookidooException

When the config is invalid.

CookidooException

Bases: Exception

General exception occurred.

CookidooParseException

Bases: CookidooException

When data could not be parsed.

CookidooRequestException

Bases: CookidooException

When a request returns an error.

CookidooResponseException

Bases: CookidooException

When a response could not be parsed.

CookidooUnavailableException

Bases: CookidooException

When the network or server is not available.

CookidooAdditionalItem dataclass

Bases: CookidooItem

Cookidoo additional item type.

CookidooAuthResponse dataclass

An auth response class.

CookidooCategory dataclass

Cookidoo category type.

Attributes:

Name	Type	Description
id	str	The id of the category
name	str	The label of the category
notes	str	The additional information of the category

CookidooChapter dataclass

Cookidoo chapter type.

Attributes:

Name	Type	Description
title		The title of the chapter
recipes	list[CookidooChapterRecipe]	The recipes in the chapter

CookidooChapterRecipe dataclass

Cookidoo chapter recipe type.

Attributes:

Name	Type	Description
id	str	The id of the recipe
name	str	The label of the recipe
total_time	int	The time for the recipe

CookidooCollection dataclass

Cookidoo collection type.

Attributes:

Name	Type	Description
id	str	The id of the collection
title		The title of the collection
description	str | None	The description of the collection
chapters	list[CookidooChapter]	The recipes in the collection

CookidooConfig dataclass

Cookidoo config type.

Attributes:

Name	Type	Description
localization	CookidooLocalizationConfig	The localization for the api including country, language and url
email	str	The email to login
password	str	The password to login

CookidooIngredient dataclass

Cookidoo ingredient type.

Attributes:

Name	Type	Description
id	str	The id of the ingredient
name	str	The label of the ingredient
description	str	The description of the item, including the quantity or other helpful information

CookidooIngredientItem dataclass

Bases: CookidooItem

Cookidoo ingredient item type.

Attributes:

Name	Type	Description
description	str	The description of the item, including the quantity or other helpful information

CookidooItem dataclass

Cookidoo item type.

Attributes:

Name	Type	Description
id	str	The id of the item
name	str	The label of the item

CookidooLocalizationConfig dataclass

A localization config class.

CookidooRecipeCollection dataclass

Cookidoo recipe collection type.

Attributes:

Name	Type	Description
id	str	The id of the collection
name	str	The label of the collection
additional_information		The additional information of the collection

CookidooShoppingRecipe dataclass

Cookidoo shopping recipe type.

Attributes:

Name	Type	Description
id	str	The id of the recipe
name	str	The label of the recipe
ingredients	list[CookidooIngredient]	The ingredients of the recipe

CookidooShoppingRecipeDetails dataclass

Bases: CookidooShoppingRecipe

Cookidoo recipe details type.

Attributes:

Name	Type	Description
difficulty	str	The difficulty of the recipe
notes	list[str]	Hints and additional information about the recipe
categories	list[CookidooCategory]	The categories of the recipe
collections	list[CookidooRecipeCollection]	The collections of the recipe
utensils	list[str]	The utensils needed for the recipe
serving_size	str	The service size of the recipe
active_time	int	The time needed preparing the recipe [in seconds]
total_time	int	The time needed until the recipe is ready [in seconds]

CookidooSubscription dataclass

A subscription class.

CookidooUserInfo dataclass

A user info class.

get_country_options async

Get a list of possible country options.

Source code in cookidoo_api/helpers.py

async def get_country_options() -> list[str]:
    """Get a list of possible country options."""
    return list({option.country_code for option in await get_localization_options()})

get_language_options async

Get a list of possible language options.

Source code in cookidoo_api/helpers.py

async def get_language_options() -> list[str]:
    """Get a list of possible language options."""
    return list({option.language for option in await get_localization_options()})

get_localization_options async

Get a list of possible localization options.

Source code in cookidoo_api/helpers.py

async def get_localization_options(
    country: str | None = None,
    language: str | None = None,
) -> list[CookidooLocalizationConfig]:
    """Get a list of possible localization options."""
    return await __get_localization_options(country, language)