kitchenowl-python 0.0.1__py3-none-any.whl

kitchenowl_python/__init__.py

@@ -0,0 +1,2 @@
+"""KitchenOwl API."""
+

kitchenowl_python/const.py

@@ -0,0 +1 @@
+"""Constants for the KitchenOwl API."""

kitchenowl_python/exceptions.py

@@ -0,0 +1,13 @@
+"""KitchenOwl exceptions."""
+
+
+class KitchenOwlException(Exception):
+    """Raised when a general exception occours."""
+
+
+class KitchenOwlRequestException(KitchenOwlException):
+    """Raised on a bad request to the KitchenOwl instance."""
+
+
+class KitchenOwlAuthException(KitchenOwlException):
+    """Raised when the authentication token is not valid."""

kitchenowl_python/kitchenowl.py

@@ -0,0 +1,364 @@
+"""KitchnOwl API wrapper."""
+
+import asyncio
+import logging
+from http import HTTPStatus
+from typing import Any
+
+import aiohttp
+from aiohttp.hdrs import METH_DELETE, METH_GET, METH_HEAD, METH_POST
+
+from .exceptions import KitchenOwlAuthException, KitchenOwlRequestException
+from .types import (
+    KitchenOwlHouseholdsResponse,
+    KitchenOwlItem,
+    KitchenOwlShoppingListItem,
+    KitchenOwlShoppingListItemsResponse,
+    KitchenOwlShoppingListsResponse,
+    KitchenOwlUser,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class KitchenOwl:
+    """Unnoficial KitchenOwl API interface.
+
+    Handles communication with the KitchenOwl REST API.
+
+    Attributes:
+        session: An ClientSession that handles the communication with the KitchenOwl REST API.
+        url: A string representing the URL of the KitchenOwl instance.
+        token: A string representing the Long-Lived Access Token for accessing the KitchenOwl API.
+
+    """
+
+    def __init__(self, session: aiohttp.ClientSession, url: str, token: str) -> None:
+        """Init function for KitchenOwl API.
+
+        Args:
+            session: An ClientSession that handles the communication with the KitchenOwl REST API.
+            url: A string representing the URL of the KitchenOwl instance.
+            token: A string representing the Long-Lived Access Token for accessing the KitchenOwl API.
+
+        """
+
+        self._session = session
+
+        self._base_url = url
+        self._token = token
+        self._request_timeout = 25
+
+        self._headers = {
+            "accept": "application/json",
+            "Authorization": f"Bearer {self._token}",
+        }
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_data: dict[str, Any] | None = None,
+        return_json=False,
+    ) -> Any:
+        """Perform a HTTP request to the KitchenOwl instance."""
+
+        url = f"{self._base_url}/{path}"
+
+        try:
+            async with asyncio.timeout(self._request_timeout):
+                r = await self._session.request(
+                    method, url, headers=self._headers, params=params, json=json_data
+                )
+            if r.status == HTTPStatus.UNAUTHORIZED:
+                raise KitchenOwlAuthException("Login not possible: not authorized")
+            if r.status == HTTPStatus.UNPROCESSABLE_ENTITY:
+                raise KitchenOwlAuthException(
+                    "Login not possible: authorization incorrect, please check your authorization token."
+                )
+            r.raise_for_status()
+
+        except aiohttp.ClientError as e:
+            raise KitchenOwlRequestException("Error during request") from e
+
+        if return_json:
+            content_type = r.headers.get("Content-type", "")
+            text = await r.text()
+            if "application/json" not in content_type:
+                raise KitchenOwlRequestException(
+                    "Expected JSON response from server",
+                    {"content_type": content_type, "response": text},
+                )
+
+            return await r.json()
+
+        return r.status == HTTPStatus.OK
+
+    async def _post(self, path: str, json_data: dict, return_json=False) -> Any:
+        """Perform a POST request to the KitchenOwl instance."""
+
+        return await self._request(
+            METH_POST, path=path, json_data=json_data, return_json=return_json
+        )
+
+    async def _get(self, path: str) -> dict:
+        """Perform a GET request to the KitchenOwl instance."""
+
+        return await self._request(METH_GET, path=path, return_json=True)
+
+    async def _head(self, path: str) -> bool:
+        """Perform a HEAD request to the KitchenOwl instance."""
+
+        return await self._request(METH_HEAD, path=path, return_json=False)
+
+    async def _delete(self, path: str, json_data: dict) -> bool:
+        """Perform a DELETE request to the KitchenOwl instance."""
+
+        return await self._request(METH_DELETE, path=path, json_data=json_data, return_json=False)
+
+    async def test_connection(self) -> bool:
+        """Test the kitchenowl token by performing HEAD on the user endpoint.
+
+        Returns:
+            A True bool value if a connection to the API endpoint can be established.
+            Note: False is never returned as Errors are raised in this case.
+
+        Raises:
+            KitchenOwlTimeoutException: If the request times out
+            KitchenOwlRequestException: If there is an error during the request
+            KitchenOwlAuthException: If the token is not provided or incorrect
+
+        """
+        return await self._head("api/user")
+
+    async def get_user_info(self) -> KitchenOwlUser:
+        """Return the user informaiton.
+
+        Returns:
+            A KitchenOwlUser object containing the information about the user.
+
+        Raises:
+            TimeoutError: If the request times out
+            KitchenOwlRequestException: If there is an error during the request
+            KitchenOwlAuthException: If the token is not provided or incorrect
+
+        """
+
+        return KitchenOwlUser(await self._get("api/user"))
+
+    async def get_households(self) -> KitchenOwlHouseholdsResponse:
+        """Return all households for the user.
+
+        Returns:
+            A KitchenOwlHouseholdsResponse object containing the information about all households the user is registered for.
+
+        Raises:
+            TimeoutError: If the request times out
+            KitchenOwlRequestException: If there is an error during the request
+            KitchenOwlAuthException: If the token is not provided or incorrect
+
+        """
+
+        return KitchenOwlHouseholdsResponse(await self._get("api/household"))
+
+    async def get_shoppinglists(self, household_id) -> KitchenOwlShoppingListsResponse:
+        """Get all shopping lists for the household.
+
+        Args:
+            household_id: A positive integer value of the household id.
+
+        Returns:
+            A KitchenOwlShoppingListsResponse object containing the information about all shopping lists for the household.
+
+        Raises:
+            TimeoutError: If the request times out
+            KitchenOwlRequestException: If there is an error during the request
+            KitchenOwlAuthException: If the token is not provided or incorrect
+
+        """
+
+        return KitchenOwlShoppingListsResponse(
+            await self._get(f"api/household/{household_id}/shoppinglist")
+        )
+
+    async def get_shoppinglist_items(self, list_id: int) -> KitchenOwlShoppingListItemsResponse:
+        """Get all shopping list items on the list.
+
+        Args:
+            list_id: A positive integer value of the shopping list id.
+
+        Returns:
+            A KitchenOwlShoppingListsResponse object containing the information about all shopping lists for the household.
+
+        Raises:
+            TimeoutError: If the request times out
+            KitchenOwlRequestException: If there is an error during the request
+            KitchenOwlAuthException: If the token is not provided or incorrect
+
+        """
+
+        return KitchenOwlShoppingListItemsResponse(
+            await self._get(f"api/shoppinglist/{list_id}/items")
+        )
+
+    async def get_shoppinglist_recent_items(
+        self, list_id: int
+    ) -> KitchenOwlShoppingListItemsResponse:
+        """Get the recent shopping list items for the shopping list.
+
+        Args:
+            list_id: A positive integer value of the shopping list id.
+
+        Returns:
+            A KitchenOwlShoppingListItemsResponse object containing all items recently used on the shopping list
+
+        Raises:
+            TimeoutError: If the request times out
+            KitchenOwlRequestException: If there is an error during the request
+            KitchenOwlAuthException: If the token is not provided or incorrect
+
+        """
+
+        return KitchenOwlShoppingListItemsResponse(
+            await self._get(f"api/shoppinglist/{list_id}/recent-items")
+        )
+
+    async def get_shoppinglist_suggested_items(
+        self, list_id: int
+    ) -> KitchenOwlShoppingListItemsResponse:
+        """Get the suggested shopping list items for the shopping list.
+
+        Args:
+            list_id: A positive integer value of the shopping list id.
+
+        Returns:
+            A KitchenOwlShoppingListItemsResponse object containing all items that are suggestedfor the shopping list
+
+        Raises:
+            TimeoutError: If the request times out
+            KitchenOwlRequestException: If there is an error during the request
+            KitchenOwlAuthException: If the token is not provided or incorrect
+
+
+        """
+
+        return KitchenOwlShoppingListItemsResponse(
+            await self._get(f"api/shoppinglist/{list_id}/suggested-items")
+        )
+
+    async def add_shoppinglist_item(
+        self, list_id: int, item_name: str, item_description: str = ""
+    ) -> KitchenOwlShoppingListItem:
+        """Add an item to the shopping list by name.
+
+        Args:
+            list_id: A positive integer value of the shopping list id.
+            item_name: A string representing the name of the item to add to the list.
+            item_description: An optional string to add to the description of the item.
+
+        Returns:
+            A KitchenOwlShoppingListItem object containing the added item on success.
+
+        Raises:
+            TimeoutError: If the request times out
+            KitchenOwlRequestException: If there is an error during the request
+            KitchenOwlAuthException: If the token is not provided or incorrect
+
+
+        """
+
+        item = {"name": item_name, "description": item_description}
+        return KitchenOwlShoppingListItem(
+            await self._post(f"api/shoppinglist/{list_id}/add-item-by-name", item, True)
+        )
+
+    async def update_shoppinglist_item_description(
+        self, list_id: int, item_id: int, item_description: str
+    ) -> KitchenOwlShoppingListItem:
+        """Update the description of an item on the shopping list.
+
+        Args:
+            list_id: A positive integer value of the shopping list id.
+            item_id: An integer as the id of the item to update.
+            item_description: The description string to add to the item.
+
+        Returns:
+            A KitchenOwlShoppingListItem object containing the updated item on success.
+
+        Raises:
+            TimeoutError: If the request times out
+            KitchenOwlRequestException: If there is an error during the request
+            KitchenOwlAuthException: If the token is not provided or incorrect
+
+
+        """
+
+        json_data = {"description": item_description}
+
+        return KitchenOwlShoppingListItem(
+            await self._post(f"api/shoppinglist/{list_id}/item/{item_id}", json_data, True)
+        )
+
+    async def remove_shoppinglist_item(self, list_id: int, item_id: int) -> bool:
+        """Remove the item from the shopping list.
+
+        Args:
+            list_id: A positive integer value of the shopping list id.
+            item_id: An integer as the id of the item to update.
+
+        Returns:
+            A bool (True) in case of success.
+
+        Raises:
+            TimeoutError: If the request times out
+            KitchenOwlRequestException: If there is an error during the request
+            KitchenOwlAuthException: If the token is not provided or incorrect
+
+
+        """
+
+        json_data = {"item_id": item_id}
+
+        return await self._delete(f"api/shoppinglist/{list_id}/item", json_data)
+
+    async def update_item(self, item_id: int, item: KitchenOwlItem) -> KitchenOwlItem:
+        """Update an item.
+
+        Args:
+            item_id: An integer as the id of the item to update.
+            item: A dict containing the item data to update.
+
+
+        Returns:
+             A KitchenOwlShoppingListItem object containing the updated item on success.
+
+        Raises:
+            TimeoutError: If the request times out
+            KitchenOwlRequestException: If there is an error during the request
+            KitchenOwlAuthException: If the token is not provided or incorrect
+
+
+        """
+
+        return KitchenOwlItem(await self._post(f"api/item/{item_id}", item, True))
+
+    async def delete_item(self, item_id: int) -> KitchenOwlItem:
+        """Delete an item.
+
+        Args:
+            item_id: An integer as the id of the item to delete.
+
+
+        Returns:
+            A bool (True) in case of success.
+
+        Raises:
+            TimeoutError: If the request times out
+            KitchenOwlRequestException: If there is an error during the request
+            KitchenOwlAuthException: If the token is not provided or incorrect
+
+
+        """
+
+        return await self._delete(path=f"api/item/{item_id}", json_data={})

kitchenowl_python/types.py

@@ -0,0 +1,93 @@
+"""KitchenOwl API types."""
+
+# TypedDict for now as it allows for changes in the API return values
+
+from typing import List, NotRequired, TypedDict
+
+
+class KitchenOwlShoppingListCategory(TypedDict):
+    """A KitchenOwl category for an item for a shopping list."""
+
+    name: str
+    id: int
+    ordering: int
+    household_id: int
+    description: str
+    updated_at: int
+    created_at: int
+    default: bool
+    default_key: str
+
+
+class KitchenOwlItem(TypedDict):
+    """A KitchenOwl item for a shopping list."""
+
+    name: str
+    id: int
+    ordering: NotRequired[int]
+    category: NotRequired[KitchenOwlShoppingListCategory]
+    category_id: NotRequired[int]
+    household_id: NotRequired[int]
+    updated_at: NotRequired[int]
+    created_at: NotRequired[int]
+    default: NotRequired[bool]
+    default_key: NotRequired[str]
+    icon: NotRequired[str]
+    support: NotRequired[int]
+
+
+class KitchenOwlShoppingListItem(KitchenOwlItem):
+    """A KitchenOwl item on a shopping list."""
+
+    description: str
+
+
+class KitchenOwlShoppingList(TypedDict):
+    """A KitchenOwl shopping list."""
+
+    created_at: int
+    household_id: int
+    id: int
+    name: str
+    updated_at: int
+
+
+class KitchenOwlUser(TypedDict):
+    """A user entry."""
+
+    admin: bool
+    created_at: int
+    id: int
+    name: str
+    owner: bool
+    photo: str | None
+    updated_at: int
+    username: str
+
+
+class KitchenOwlHousehold(TypedDict):
+    """A KitchenOwl household."""
+
+    created_at: int
+    default_shopping_list: KitchenOwlShoppingList
+    expenses_feature: bool
+    id: int
+    language: str
+    member: List[KitchenOwlUser]
+    name: str
+    photo: str | None
+    planner_feature: bool
+    updated_at: int
+    view_ordering: List[str]
+
+
+class KitchenOwlHouseholdsResponse(List[KitchenOwlHousehold]):
+    """The households response from KitchenOwl."""
+
+
+class KitchenOwlShoppingListsResponse(List[KitchenOwlShoppingList]):
+    """The shopping lists response from KitchenOwl."""
+
+
+class KitchenOwlShoppingListItemsResponse(List[KitchenOwlShoppingListItem]):
+    """The response for shopping list items from KitchenOwl."""

kitchenowl_python-0.0.1.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 super-qua, Tom Bursch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kitchenowl_python-0.0.1.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.1
+Name: kitchenowl-python
+Version: 0.0.1
+Summary: A python wrapper for the KitchenOwl API
+Author: super-qua
+Author-email: Tom Bursch <tom@kitchenowl.org>
+License: MIT License
+        
+        Copyright (c) 2024 super-qua, Tom Bursch
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://kitchenowl.org
+Project-URL: Repository, https://github.com/tombursch/kitchenowl-python
+Project-URL: Issues, https://github.com/TomBursch/kitchenowl/issues
+Project-URL: Changelog, https://github.com/tombursch/kitchenowl-python/blob/main/CHANGELOG.md
+Keywords: kitchenowl
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp==3.10.5
+Provides-Extra: test
+Requires-Dist: aioresponses==0.7.6; extra == "test"
+Requires-Dist: pytest==8.2.2; extra == "test"
+Requires-Dist: pytest-asyncio==0.23.7; extra == "test"
+Requires-Dist: pytest-cov==6.0.0; extra == "test"
+Requires-Dist: syrupy==4.6.1; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff==0.6.1; extra == "lint"
+
+# kitchenowl-python 
+A simple wrapper around the KitchenOwl API.
+
+This is a small python package to be used as a wrapper for the KitchenOwl API in python.
+
+Currently, there is only support for managing shopping list items.
+
+## Installation
+
+```shell
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+Installs all required dependencies.
+
+## Usage
+
+```python
+from aiohttp import ClientSession
+from kitchenowl_python.kitchenowl import KitchenOwl
+
+async with ClientSession() as session:
+    kitchenowl = KitchenOwl(session=session, url=url, token=token)
+    await kitchenowl.test_connection()
+
+```
+
+## Development
+
+### Run tests
+
+```shell
+source .venv/bin/activate
+pip install -e .\[test\]
+pytest .
+```
+
+

kitchenowl_python-0.0.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+kitchenowl_python/__init__.py,sha256=g83X8m-ylRrorkwt16iXNIOxvFI6-ZgUacrvVlhR07o,23
+kitchenowl_python/const.py,sha256=B9mhQl6C1EN6KrzRliXI3fCg12PULIztbn9P8xBhipU,40
+kitchenowl_python/exceptions.py,sha256=VPMcefOC9dDT_Tb-8c7TGVHvVEorHlR6qZmyhrDAYX0,354
+kitchenowl_python/kitchenowl.py,sha256=r9PN4S-6-nPUz6M6KEf-EbBVuozchulrb6fgvD7nXSM,12730
+kitchenowl_python/types.py,sha256=Z4DtA0skTgeDbxywKStNIYN9ofQ4hdPOGTBmtx8dBWc,2109
+kitchenowl_python-0.0.1.dist-info/LICENSE,sha256=o7hx9SZiGRYrq2gq2LbP7scrPXEAq0aHusuSrP2MuqA,1078
+kitchenowl_python-0.0.1.dist-info/METADATA,sha256=pI_bDfsEtlZvfEajguzCt2ldBYq0J5pQEVoQm8f6MxA,2989
+kitchenowl_python-0.0.1.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+kitchenowl_python-0.0.1.dist-info/top_level.txt,sha256=NBfVqNoXQONSyXaxqYQJeQYmCQhPEi2vaQTyFx2jJWY,18
+kitchenowl_python-0.0.1.dist-info/RECORD,,

kitchenowl_python-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.6.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

kitchenowl_python-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+kitchenowl_python