# Home Assistant Bring! Shopping Lists API
[](https://badge.fury.io/py/homeassistant-bring-api)
An unofficial python package to access the Bring! shopping lists API.
## Credits
> This home assistant focused implementation of the api is derived from the generic python implementation by [eliasball](https://github.com/eliasball/python-bring-api). This fork has been synced last time on 2024-02-11 and diverges from that point on to focus on home assistant. The implementation of [eliasball](https://github.com/eliasball/python-bring-api) is a **minimal** python port of the [node-bring-api](https://github.com/foxriver76/node-bring-api) by [foxriver76](https://github.com/foxriver76). All credit goes to him for making this awesome API possible!
## Disclaimer
The developers of this module are in no way endorsed by or affiliated with Bring! Labs AG, or any associated subsidiaries, logos or trademarks.
## Installation
`pip install homeassistant-bring-api`
## Documentation
See below for usage examples. See [Exceptions](#exceptions) for API-specific exceptions and mitigation strategies for common exceptions.
## Usage Example
The API is based on the async HTTP library `aiohttp`, which is the preferred method by home assistant.
```python
import aiohttp
import asyncio
import logging
import sys
from homeassistant_bring_api.bring import Bring
logging.basicConfig(stream=sys.stdout, level=logging.DEBUG)
async def main():
async with aiohttp.ClientSession() as session:
# Create Bring instance with email and password
bring = Bring(session, "MAIL", "PASSWORD")
# Login
await bring.login()
# Get information about all available shopping lists
lists = (await bring.loadLists())["lists"]
# Save an item with specifications to a certain shopping list
await bring.saveItem(lists[0]['listUuid'], 'Milk', 'low fat')
# Save another item
await bring.saveItem(lists[0]['listUuid'], 'Carrots')
# Get all the items of a list
items = await bring.getItems(lists[0]['listUuid'])
print(items)
# Check off an item
await bring.completeItem(lists[0]['listUuid'], 'Carrots')
# Remove an item from a list
await bring.removeItem(lists[0]['listUuid'], 'Milk')
asyncio.run(main())
```
## Exceptions
In case something goes wrong during a request, several exceptions can be thrown.
They will either be BringRequestException, BringParseException, or BringAuthException, depending on the context. All inherit from BringException.
### Another asyncio event loop is already running
Because even the sync methods use async calls under the hood, you might encounter an error that another asyncio event loop is already running on the same thread. This is expected behavior according to the asyncio.run() [documentation](https://docs.python.org/3/library/asyncio-runner.html#asyncio.run). You cannot call the sync methods when another event loop is already running. When you are already inside an async function, you should use the async methods instead.
### Exception ignored: RuntimeError: Event loop is closed
Due to a known issue in some versions of aiohttp when using Windows, you might encounter a similar error to this:
```python
Exception ignored in: <function _ProactorBasePipeTransport.__del__ at 0x00000000>
Traceback (most recent call last):
File "C:\...\py38\lib\asyncio\proactor_events.py", line 116, in __del__
self.close()
File "C:\...\py38\lib\asyncio\proactor_events.py", line 108, in close
self._loop.call_soon(self._call_connection_lost, None)
File "C:\...\py38\lib\asyncio\base_events.py", line 719, in call_soon
self._check_closed()
File "C:\...\py38\lib\asyncio\base_events.py", line 508, in _check_closed
raise RuntimeError('Event loop is closed')
RuntimeError: Event loop is closed
```
You can fix this according to [this](https://stackoverflow.com/questions/68123296/asyncio-throws-runtime-error-with-exception-ignored) stackoverflow answer by adding the following line of code before executing the library:
```python
asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
```
# CHANGELOG
## 0.0.1
Initial commit based on `3.0.0` from [eliasball](https://github.com/eliasball/python-bring-api).
Raw data
{
"_id": null,
"home_page": "https://github.com/miaucl/python-bring-api",
"name": "homeassistant-bring-api",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Cyrill Raccaud",
"author_email": "cyrill.raccaud+pypi@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/db/ae/1a58e3e1954c3357262d4984ead3fcc3fc62908c9f7fdba73bc3c46e3a7b/homeassistant-bring-api-0.1.0.tar.gz",
"platform": null,
"description": "# Home Assistant Bring! Shopping Lists API\n\n[](https://badge.fury.io/py/homeassistant-bring-api)\n\nAn unofficial python package to access the Bring! shopping lists API.\n\n## Credits\n\n> This home assistant focused implementation of the api is derived from the generic python implementation by [eliasball](https://github.com/eliasball/python-bring-api). This fork has been synced last time on 2024-02-11 and diverges from that point on to focus on home assistant. The implementation of [eliasball](https://github.com/eliasball/python-bring-api) is a **minimal** python port of the [node-bring-api](https://github.com/foxriver76/node-bring-api) by [foxriver76](https://github.com/foxriver76). All credit goes to him for making this awesome API possible!\n\n## Disclaimer\n\nThe developers of this module are in no way endorsed by or affiliated with Bring! Labs AG, or any associated subsidiaries, logos or trademarks.\n\n## Installation\n\n`pip install homeassistant-bring-api`\n\n## Documentation\n\nSee below for usage examples. See [Exceptions](#exceptions) for API-specific exceptions and mitigation strategies for common exceptions.\n\n## Usage Example\n\nThe API is based on the async HTTP library `aiohttp`, which is the preferred method by home assistant.\n\n```python\nimport aiohttp\nimport asyncio\nimport logging\nimport sys\n\nfrom homeassistant_bring_api.bring import Bring\n\nlogging.basicConfig(stream=sys.stdout, level=logging.DEBUG)\n\nasync def main():\n async with aiohttp.ClientSession() as session:\n # Create Bring instance with email and password\n bring = Bring(session, \"MAIL\", \"PASSWORD\")\n # Login\n await bring.login()\n\n # Get information about all available shopping lists\n lists = (await bring.loadLists())[\"lists\"]\n\n # Save an item with specifications to a certain shopping list\n await bring.saveItem(lists[0]['listUuid'], 'Milk', 'low fat')\n\n # Save another item\n await bring.saveItem(lists[0]['listUuid'], 'Carrots')\n\n # Get all the items of a list\n items = await bring.getItems(lists[0]['listUuid'])\n print(items)\n\n # Check off an item\n await bring.completeItem(lists[0]['listUuid'], 'Carrots')\n\n # Remove an item from a list\n await bring.removeItem(lists[0]['listUuid'], 'Milk')\n\nasyncio.run(main())\n```\n\n## Exceptions\n\nIn case something goes wrong during a request, several exceptions can be thrown.\nThey will either be BringRequestException, BringParseException, or BringAuthException, depending on the context. All inherit from BringException.\n\n### Another asyncio event loop is already running\n\nBecause even the sync methods use async calls under the hood, you might encounter an error that another asyncio event loop is already running on the same thread. This is expected behavior according to the asyncio.run() [documentation](https://docs.python.org/3/library/asyncio-runner.html#asyncio.run). You cannot call the sync methods when another event loop is already running. When you are already inside an async function, you should use the async methods instead.\n\n### Exception ignored: RuntimeError: Event loop is closed\n\nDue to a known issue in some versions of aiohttp when using Windows, you might encounter a similar error to this:\n\n```python\nException ignored in: <function _ProactorBasePipeTransport.__del__ at 0x00000000>\nTraceback (most recent call last):\n File \"C:\\...\\py38\\lib\\asyncio\\proactor_events.py\", line 116, in __del__\n self.close()\n File \"C:\\...\\py38\\lib\\asyncio\\proactor_events.py\", line 108, in close\n self._loop.call_soon(self._call_connection_lost, None)\n File \"C:\\...\\py38\\lib\\asyncio\\base_events.py\", line 719, in call_soon\n self._check_closed()\n File \"C:\\...\\py38\\lib\\asyncio\\base_events.py\", line 508, in _check_closed\n raise RuntimeError('Event loop is closed')\nRuntimeError: Event loop is closed\n```\n\nYou can fix this according to [this](https://stackoverflow.com/questions/68123296/asyncio-throws-runtime-error-with-exception-ignored) stackoverflow answer by adding the following line of code before executing the library:\n\n```python\nasyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())\n```\n\n# CHANGELOG\n\n## 0.0.1\n\nInitial commit based on `3.0.0` from [eliasball](https://github.com/eliasball/python-bring-api).\n",
"bugtrack_url": null,
"license": "",
"summary": "Unofficial home assistant python package to access Bring! shopping lists API.",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/miaucl/python-bring-api"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8b5ae0150304eb108f099f97685c10e7704e1af496bff2a1bafd968ab1aaa706",
"md5": "891ad31064c3a8f81f09aa7bdcd82560",
"sha256": "cecf58377489219876af2cb95a3db0995c08cd8cc041b22be46166522ff6774f"
},
"downloads": -1,
"filename": "homeassistant_bring_api-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "891ad31064c3a8f81f09aa7bdcd82560",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8109,
"upload_time": "2024-02-11T23:00:24",
"upload_time_iso_8601": "2024-02-11T23:00:24.299063Z",
"url": "https://files.pythonhosted.org/packages/8b/5a/e0150304eb108f099f97685c10e7704e1af496bff2a1bafd968ab1aaa706/homeassistant_bring_api-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dbae1a58e3e1954c3357262d4984ead3fcc3fc62908c9f7fdba73bc3c46e3a7b",
"md5": "b9638bd6683bef8243c9c3b3fe996c8e",
"sha256": "6d244da778f577f81bcb0e94c76d3bd153c81abc748c870c9dcd7c77c31d9b63"
},
"downloads": -1,
"filename": "homeassistant-bring-api-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "b9638bd6683bef8243c9c3b3fe996c8e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 9164,
"upload_time": "2024-02-11T23:00:26",
"upload_time_iso_8601": "2024-02-11T23:00:26.159772Z",
"url": "https://files.pythonhosted.org/packages/db/ae/1a58e3e1954c3357262d4984ead3fcc3fc62908c9f7fdba73bc3c46e3a7b/homeassistant-bring-api-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-11 23:00:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "miaucl",
"github_project": "python-bring-api",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "homeassistant-bring-api"
}
JSON
