| Name | python-openhab JSON |
| Version |
2.19.0
JSON |
| download |
| home_page | |
| Summary | python library for accessing the openHAB REST API |
| upload_time | 2023-10-23 23:22:01 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | AGPLv3+ |
| keywords |
openhab
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](http://python-openhab.readthedocs.io/en/latest/?badge=latest)
[](https://pypi.org/project/python-openhab/)
# python library for accessing the openHAB REST API
This library allows for easily accessing the openHAB REST API. A number of features are implemented but not all, this is
work in progress.
# Requirements
- python >= 3.8
- python :: dateutil
- python :: httpx
- python :: authlib
- openHAB version 3 / 4
# Installation
Install the latest version using pip:
```shell
pip install python-openhab
```
# Example
Example usage of the library:
```python
from openhab import OpenHAB
base_url = 'http://localhost:8080/rest'
openhab = OpenHAB(base_url)
# fetch all items
items = openhab.fetch_all_items()
sunset = items.get('Sunset')
print(sunset.state)
# fetch a single item
item = openhab.get_item('light_switch')
# turn a switch on
item.on()
# send a state update (this only update the state)
item.state = 'OFF'
# send a command
item.command('ON')
# check if item state is NULL
if item.state is None and item.is_state_null():
pass
# check if item state is UNDEF
if item.state is None and item.is_state_undef():
pass
# fetch some group
lights_group = openhab.get_item('lights_group')
# send command to group
lights_group.on()
# send update to each member
for v in lights_group.members.values():
v.update('OFF')
```
# Note on NULL and UNDEF
In openHAB items may have two states named NULL and UNDEF, which have distinct meanings but basically indicate that an
item has no usable value. This library sets the state of an item, regardless of their openHAB value being NULL or UNDEF,
to None. This in order to ease working with the library as we do cast certain types to native types.
In order to check if an item's state is either NULL or UNDEF, you can use the helper functions:
```python
item.is_state_null()
item.is_state_undef()
```
# Experimental OAuth2 Support
In order to try out OAuth2 authentication, you first need to register with the openHAB endpoint in order to retrieve a
token and refresh token.
Assuming your openHAB instance runs at *http://127.0.0.1:8080* (replace with the correct one), use the following snippet
to retrieve a token:
```python
import pathlib
import openhab.oauth2_helper
import os
import json
url_base = 'http://127.0.0.1:8080'
api_username = 'admin'
api_password = 'admin'
oauth2_client_id = 'http://127.0.0.1/auth'
oauth2_token_cache = pathlib.Path(__file__).resolve().parent / '.oauth2_token_test'
# this must be set for oauthlib to work on http (do not set for https!)
os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'
oauth2_token = openhab.oauth2_helper.get_oauth2_token(url_base, username=api_username, password=api_password)
with oauth2_token_cache.open('w') as fhdl:
json.dump(oauth2_token, fhdl, indent=2, sort_keys=True)
```
The JSON that is returned is required for authenticating to openHAB using OAuth2 as well as a refresh token which is
used for refreshing a session.
Next try connecting to openHAB using this library as follows:
```python
import openhab
import pathlib
import json
import os
url_base = 'http://127.0.0.1:8080'
url_rest = f'{url_base}/rest'
oauth2_client_id = 'http://127.0.0.1/auth'
oauth2_token_cache = pathlib.Path(__file__).resolve().parent / '.oauth2_token_test'
# this must be set for oauthlib to work on http (do not set for https!)
os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'
oauth2_config = {'client_id': oauth2_client_id,
'token_cache': str(oauth2_token_cache)
}
with oauth2_token_cache.open('r') as fhdl:
oauth2_config['token'] = json.load(fhdl)
oh = openhab.OpenHAB(base_url=url_rest, oauth2_config=oauth2_config)
o = oh.get_item('test_item')
print(o)
```
Raw data
{
"_id": null,
"home_page": "",
"name": "python-openhab",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "openHAB",
"author": "",
"author_email": "Georges Toth <georges@trypill.org>",
"download_url": "https://files.pythonhosted.org/packages/da/08/ef9e05ce8297b5d244e6786e495c78bc75fc0518d65a34dc6f40cc925efc/python-openhab-2.19.0.tar.gz",
"platform": null,
"description": "[](http://python-openhab.readthedocs.io/en/latest/?badge=latest)\n[](https://pypi.org/project/python-openhab/)\n\n\n\n# python library for accessing the openHAB REST API\n\nThis library allows for easily accessing the openHAB REST API. A number of features are implemented but not all, this is\nwork in progress.\n\n# Requirements\n\n- python >= 3.8\n- python :: dateutil\n- python :: httpx\n- python :: authlib\n- openHAB version 3 / 4\n\n# Installation\n\n\nInstall the latest version using pip:\n\n```shell\npip install python-openhab\n```\n\n# Example\n\nExample usage of the library:\n\n```python\n\nfrom openhab import OpenHAB\n\nbase_url = 'http://localhost:8080/rest'\nopenhab = OpenHAB(base_url)\n\n# fetch all items\nitems = openhab.fetch_all_items()\n\nsunset = items.get('Sunset')\nprint(sunset.state)\n\n# fetch a single item\nitem = openhab.get_item('light_switch')\n\n# turn a switch on\nitem.on()\n\n# send a state update (this only update the state)\nitem.state = 'OFF'\n\n# send a command\nitem.command('ON')\n\n# check if item state is NULL\nif item.state is None and item.is_state_null():\n pass\n\n# check if item state is UNDEF\nif item.state is None and item.is_state_undef():\n pass\n\n# fetch some group\nlights_group = openhab.get_item('lights_group')\n\n# send command to group\nlights_group.on()\n\n# send update to each member\nfor v in lights_group.members.values():\n v.update('OFF')\n```\n\n# Note on NULL and UNDEF\n\nIn openHAB items may have two states named NULL and UNDEF, which have distinct meanings but basically indicate that an\nitem has no usable value. This library sets the state of an item, regardless of their openHAB value being NULL or UNDEF,\nto None. This in order to ease working with the library as we do cast certain types to native types.\n\nIn order to check if an item's state is either NULL or UNDEF, you can use the helper functions:\n\n```python\nitem.is_state_null()\nitem.is_state_undef()\n```\n\n# Experimental OAuth2 Support\n\nIn order to try out OAuth2 authentication, you first need to register with the openHAB endpoint in order to retrieve a\ntoken and refresh token.\n\nAssuming your openHAB instance runs at *http://127.0.0.1:8080* (replace with the correct one), use the following snippet\nto retrieve a token:\n\n```python\nimport pathlib\nimport openhab.oauth2_helper\nimport os\nimport json\n\nurl_base = 'http://127.0.0.1:8080'\napi_username = 'admin'\napi_password = 'admin'\noauth2_client_id = 'http://127.0.0.1/auth'\noauth2_token_cache = pathlib.Path(__file__).resolve().parent / '.oauth2_token_test'\n\n# this must be set for oauthlib to work on http (do not set for https!)\nos.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'\n\noauth2_token = openhab.oauth2_helper.get_oauth2_token(url_base, username=api_username, password=api_password)\n\nwith oauth2_token_cache.open('w') as fhdl:\n json.dump(oauth2_token, fhdl, indent=2, sort_keys=True)\n```\n\nThe JSON that is returned is required for authenticating to openHAB using OAuth2 as well as a refresh token which is\nused for refreshing a session.\n\nNext try connecting to openHAB using this library as follows:\n\n```python\nimport openhab\nimport pathlib\nimport json\nimport os\n\nurl_base = 'http://127.0.0.1:8080'\nurl_rest = f'{url_base}/rest'\noauth2_client_id = 'http://127.0.0.1/auth'\noauth2_token_cache = pathlib.Path(__file__).resolve().parent / '.oauth2_token_test'\n\n# this must be set for oauthlib to work on http (do not set for https!)\nos.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'\n\noauth2_config = {'client_id': oauth2_client_id,\n 'token_cache': str(oauth2_token_cache)\n }\n\nwith oauth2_token_cache.open('r') as fhdl:\n oauth2_config['token'] = json.load(fhdl)\n\noh = openhab.OpenHAB(base_url=url_rest, oauth2_config=oauth2_config)\n\no = oh.get_item('test_item')\nprint(o)\n```\n",
"bugtrack_url": null,
"license": "AGPLv3+",
"summary": "python library for accessing the openHAB REST API",
"version": "2.19.0",
"project_urls": {
"Documentation": "http://python-openhab.readthedocs.io/en/latest/?badge=latest",
"Download": "https://github.com/sim0nx/python-openhab",
"Homepage": "https://github.com/sim0nx/python-openhab",
"Source": "https://github.com/sim0nx/python-openhab",
"Tracker": "https://github.com/sim0nx/python-openhab/issues"
},
"split_keywords": [
"openhab"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7d6400e5d4f6b3b887ef4c4d1e9b6ecfa51efb79d4fcf63a8254d8da9d9f25e7",
"md5": "b0de8f7aeb1711ef0428013b036543b3",
"sha256": "7c22a41e8849a1de33099daf09f4faca186e1762f9eeb298387afc9cb89f72f5"
},
"downloads": -1,
"filename": "python_openhab-2.19.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b0de8f7aeb1711ef0428013b036543b3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 34788,
"upload_time": "2023-10-23T23:21:59",
"upload_time_iso_8601": "2023-10-23T23:21:59.539086Z",
"url": "https://files.pythonhosted.org/packages/7d/64/00e5d4f6b3b887ef4c4d1e9b6ecfa51efb79d4fcf63a8254d8da9d9f25e7/python_openhab-2.19.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "da08ef9e05ce8297b5d244e6786e495c78bc75fc0518d65a34dc6f40cc925efc",
"md5": "71571a67c182c245c8826dc406e9810b",
"sha256": "2aee8264588be3b5d9a5d870a73cbfca157097b9dc7438c76bf57876ed0cd265"
},
"downloads": -1,
"filename": "python-openhab-2.19.0.tar.gz",
"has_sig": false,
"md5_digest": "71571a67c182c245c8826dc406e9810b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 32566,
"upload_time": "2023-10-23T23:22:01",
"upload_time_iso_8601": "2023-10-23T23:22:01.068746Z",
"url": "https://files.pythonhosted.org/packages/da/08/ef9e05ce8297b5d244e6786e495c78bc75fc0518d65a34dc6f40cc925efc/python-openhab-2.19.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-23 23:22:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sim0nx",
"github_project": "python-openhab",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "python-openhab"
}
