# Onyx Client
[](LICENSE)
[](https://github.com/muhlba91/onyx-client/actions/workflows/release.yml)
[](https://github.com/muhlba91/onyx-client/)
[](https://pypi.org/project/onyx-client/)
[](https://pypi.org/project/onyx-client/)
[](https://github.com/muhlba91/onyx-client/releases)
[](https://pypi.org/project/onyx-client/)
[](#contributors)
<a href="https://www.buymeacoffee.com/muhlba91" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="28" width="150"></a>
This repository contains a **Python HTTP client** for [Hella](https://www.hella.info)'
s [ONYX.CENTER API](https://github.com/hella-info/onyx_api).
---
## API Versions
It is encouraged to always update Hella devices to the latest software. This will, mostly, also enforce using the newest
API. In below table you can find an indication of what Hella API version is supported.
| Hella API Version | Client Version |
|-------------------|-------------------|
| v3 | >= 3.1.0 |
| v2 | >= 2.5.0 < 3.0.0 |
## Installation
The package is published in **(Test)PyPi** and can be installed via:
```bash
pip install onyx-client
```
## Configuration
The configuration defines **connection properties** as a `dict` for the application running.
**Attention**: make sure to **read**
the [Onyx API Access Control](https://github.com/hella-info/onyx_api#access-control) description to **retrieve the
fingerprint and access token**!
| Option | Description |
|----------------|---------------------------------------------------------------------------------|
| fingerprint | The fingerprint of the ONYX.CENTER. |
| access_token | The permanent access token. |
| client_session | The initialized `aiohttp.ClientSession`. (Default: `None`, create new session.) |
### Access Control Helper
The method `onyx_client.authorizer.exchange_code` takes the **API code** and performs the exchange to a **fingerprint
and access token**. Please follow the **aforementioned documentation** to retrieve the code.
## Usage
### Initalization
You can instantiate the client using the `onyx_client.client.create` method like:
```python
import aiohttp
from onyx_client.client import create
from onyx_client.authorizer import exchange_code
# by providing the fingerprint and access token only
client = create(fingerprint="fingerprint", access_token="access_token")
# by providing the fingerprint, access token and aiohttp client session
client = create(fingerprint="fingerprint", access_token="access_token", client_session=aiohttp.ClientSession())
# by providing the configuration object
client_session = aiohttp.ClientSession()
# e.g. by exchanging the code first
config = exchange_code("code", client_session)
client = create(config=config, client_session=client_session) if client_session is not None else None
```
### Events
You can register a event callback which will be triggered if the client receives a device update:
```python
# all imports and a client exists...
def received_update(device):
print(device)
client.set_event_callback(received_update)
client.start()
# you can stop the client listening for updates using:
client.stop()
```
Each device update will be pushed to your `callback` and will create an event loop in the background.
### Streaming
You can stream device updates directly and process them through, e.g., an `async for` loop:
```python
# all imports and a client exists...
async for device in client.events():
print(device)
```
### Examples
The following examples are available in the [`examples`](examples/) directory:
- [`events`](examples/events/): uses the callback mechanism (`start()`, `stop()`)
- [`streaming`](examples/streaming/): uses the streaming mechanism (`events()`)
---
## Development
The project uses [poetry](https://poetry.eustace.io/) and to install all dependencies and the build environment, run:
```bash
pip install poetry
poetry install
```
### Testing
1) Install all dependencies as shown above.
2) Run `pytest` by:
```bash
poetry run pytest
# or
pytest
```
### Linting and Code Style
The project uses [ruff](https://github.com/astral-sh/ruff) for automated code linting and fixing, also using [pre-commit](https://pre-commit.com/).
1) Install all dependencies as shown above.
2) (Optional) Install pre-commit hooks:
```bash
poetry run pre-commit install
```
3) Run ruff:
```bash
poetry run ruff check .
# poetry run ruff format .
```
### Building
This package uses [poetry-dynamic-versioning](https://github.com/mtkennerly/poetry-dynamic-versioning) which infers the
version number based on the Git tags. Hence, to have a proper versioning for the distribution, use Python's build system
like:
```bash
pip install build
python -m build
```
Your distribution will be in the `dist` directory.
### Commit Message
This project follows [Conventional Commits](https://www.conventionalcommits.org/), and your commit message must also
adhere to the additional rules outlined in `.conform.yaml`.
---
## Contributors
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
<tbody>
<tr>
<td align="center" valign="top" width="14.28%"><a href="https://muehlbachler.io/"><img src="https://avatars.githubusercontent.com/u/653739?v=4?s=100" width="100px;" alt="Daniel Mühlbachler-Pietrzykowski"/><br /><sub><b>Daniel Mühlbachler-Pietrzykowski</b></sub></a><br /><a href="#maintenance-muhlba91" title="Maintenance">🚧</a> <a href="https://github.com/muhlba91/pulumi-proxmoxve/commits?author=muhlba91" title="Code">💻</a> <a href="https://github.com/muhlba91/pulumi-proxmoxve/commits?author=muhlba91" title="Documentation">📖</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/MitterdorferMathias"><img src="https://avatars.githubusercontent.com/u/32190212?v=4?s=100" width="100px;" alt="Mathias Mitterdorfer"/><br /><sub><b>Mathias Mitterdorfer</b></sub></a><br /><a href="https://github.com/muhlba91/pulumi-proxmoxve/commits?author=MitterdorferMathias" title="Code">💻</a></td>
</tr>
</tbody>
</table>
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- ALL-CONTRIBUTORS-LIST:END -->
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
## Supporting
If you enjoy the application and want to support my efforts, please feel free to buy me a coffe. :)
<a href="https://www.buymeacoffee.com/muhlba91" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="75" width="300"></a>
Raw data
{
"_id": null,
"home_page": "https://github.com/muhlba91/onyx-client",
"name": "onyx-client",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.12,<4.0",
"maintainer_email": "",
"keywords": "hella-info,onyx,onyx-center",
"author": "Daniel Muehlbachler-Pietrzykowski",
"author_email": "daniel.muehlbachler@niftyside.io",
"download_url": "https://files.pythonhosted.org/packages/d0/75/dbc145fe17529c9bf4ca4604817157902ba43cd19ab4ec02116ddbd4d0ef/onyx_client-9.0.0.tar.gz",
"platform": null,
"description": "# Onyx Client\n\n[](LICENSE)\n[](https://github.com/muhlba91/onyx-client/actions/workflows/release.yml)\n[](https://github.com/muhlba91/onyx-client/)\n[](https://pypi.org/project/onyx-client/)\n[](https://pypi.org/project/onyx-client/)\n[](https://github.com/muhlba91/onyx-client/releases)\n[](https://pypi.org/project/onyx-client/)\n[](#contributors)\n<a href=\"https://www.buymeacoffee.com/muhlba91\" target=\"_blank\"><img src=\"https://cdn.buymeacoffee.com/buttons/default-orange.png\" alt=\"Buy Me A Coffee\" height=\"28\" width=\"150\"></a>\n\nThis repository contains a **Python HTTP client** for [Hella](https://www.hella.info)'\ns [ONYX.CENTER API](https://github.com/hella-info/onyx_api).\n\n---\n\n## API Versions\n\nIt is encouraged to always update Hella devices to the latest software. This will, mostly, also enforce using the newest\nAPI. In below table you can find an indication of what Hella API version is supported.\n\n| Hella API Version | Client Version |\n|-------------------|-------------------|\n| v3 | >= 3.1.0 |\n| v2 | >= 2.5.0 < 3.0.0 |\n\n## Installation\n\nThe package is published in **(Test)PyPi** and can be installed via:\n\n```bash\npip install onyx-client\n```\n\n## Configuration\n\nThe configuration defines **connection properties** as a `dict` for the application running.\n\n**Attention**: make sure to **read**\nthe [Onyx API Access Control](https://github.com/hella-info/onyx_api#access-control) description to **retrieve the\nfingerprint and access token**!\n\n| Option | Description |\n|----------------|---------------------------------------------------------------------------------|\n| fingerprint | The fingerprint of the ONYX.CENTER. |\n| access_token | The permanent access token. |\n| client_session | The initialized `aiohttp.ClientSession`. (Default: `None`, create new session.) |\n\n### Access Control Helper\n\nThe method `onyx_client.authorizer.exchange_code` takes the **API code** and performs the exchange to a **fingerprint\nand access token**. Please follow the **aforementioned documentation** to retrieve the code.\n\n## Usage\n\n### Initalization\n\nYou can instantiate the client using the `onyx_client.client.create` method like:\n\n```python\nimport aiohttp\nfrom onyx_client.client import create\nfrom onyx_client.authorizer import exchange_code\n\n# by providing the fingerprint and access token only\nclient = create(fingerprint=\"fingerprint\", access_token=\"access_token\")\n\n# by providing the fingerprint, access token and aiohttp client session\nclient = create(fingerprint=\"fingerprint\", access_token=\"access_token\", client_session=aiohttp.ClientSession())\n\n# by providing the configuration object\nclient_session = aiohttp.ClientSession()\n# e.g. by exchanging the code first\nconfig = exchange_code(\"code\", client_session)\nclient = create(config=config, client_session=client_session) if client_session is not None else None\n```\n\n### Events\n\nYou can register a event callback which will be triggered if the client receives a device update:\n\n```python\n# all imports and a client exists...\n\ndef received_update(device):\n print(device)\n\nclient.set_event_callback(received_update)\nclient.start()\n\n# you can stop the client listening for updates using:\nclient.stop()\n```\n\nEach device update will be pushed to your `callback` and will create an event loop in the background.\n\n### Streaming\n\nYou can stream device updates directly and process them through, e.g., an `async for` loop:\n\n```python\n# all imports and a client exists...\n\nasync for device in client.events():\n print(device)\n```\n\n### Examples\n\nThe following examples are available in the [`examples`](examples/) directory:\n\n- [`events`](examples/events/): uses the callback mechanism (`start()`, `stop()`)\n- [`streaming`](examples/streaming/): uses the streaming mechanism (`events()`)\n\n---\n\n## Development\n\nThe project uses [poetry](https://poetry.eustace.io/) and to install all dependencies and the build environment, run:\n\n```bash\npip install poetry\npoetry install\n```\n\n### Testing\n\n1) Install all dependencies as shown above.\n2) Run `pytest` by:\n\n```bash\npoetry run pytest\n# or\npytest\n```\n\n### Linting and Code Style\n\nThe project uses [ruff](https://github.com/astral-sh/ruff) for automated code linting and fixing, also using [pre-commit](https://pre-commit.com/).\n\n1) Install all dependencies as shown above.\n2) (Optional) Install pre-commit hooks:\n\n```bash\npoetry run pre-commit install\n```\n\n3) Run ruff:\n\n```bash\npoetry run ruff check .\n# poetry run ruff format .\n```\n\n### Building\n\nThis package uses [poetry-dynamic-versioning](https://github.com/mtkennerly/poetry-dynamic-versioning) which infers the\nversion number based on the Git tags. Hence, to have a proper versioning for the distribution, use Python's build system\nlike:\n\n```bash\npip install build\npython -m build\n```\n\nYour distribution will be in the `dist` directory.\n\n### Commit Message\n\nThis project follows [Conventional Commits](https://www.conventionalcommits.org/), and your commit message must also\nadhere to the additional rules outlined in `.conform.yaml`.\n\n---\n\n## Contributors\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->\n<!-- prettier-ignore-start -->\n<!-- markdownlint-disable -->\n<table>\n <tbody>\n <tr>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://muehlbachler.io/\"><img src=\"https://avatars.githubusercontent.com/u/653739?v=4?s=100\" width=\"100px;\" alt=\"Daniel M\u00fchlbachler-Pietrzykowski\"/><br /><sub><b>Daniel M\u00fchlbachler-Pietrzykowski</b></sub></a><br /><a href=\"#maintenance-muhlba91\" title=\"Maintenance\">\ud83d\udea7</a> <a href=\"https://github.com/muhlba91/pulumi-proxmoxve/commits?author=muhlba91\" title=\"Code\">\ud83d\udcbb</a> <a href=\"https://github.com/muhlba91/pulumi-proxmoxve/commits?author=muhlba91\" title=\"Documentation\">\ud83d\udcd6</a></td>\n <td align=\"center\" valign=\"top\" width=\"14.28%\"><a href=\"https://github.com/MitterdorferMathias\"><img src=\"https://avatars.githubusercontent.com/u/32190212?v=4?s=100\" width=\"100px;\" alt=\"Mathias Mitterdorfer\"/><br /><sub><b>Mathias Mitterdorfer</b></sub></a><br /><a href=\"https://github.com/muhlba91/pulumi-proxmoxve/commits?author=MitterdorferMathias\" title=\"Code\">\ud83d\udcbb</a></td>\n </tr>\n </tbody>\n</table>\n\n<!-- markdownlint-restore -->\n<!-- prettier-ignore-end -->\n\n<!-- ALL-CONTRIBUTORS-LIST:END -->\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n\n## Supporting\n\nIf you enjoy the application and want to support my efforts, please feel free to buy me a coffe. :)\n\n<a href=\"https://www.buymeacoffee.com/muhlba91\" target=\"_blank\"><img src=\"https://cdn.buymeacoffee.com/buttons/default-orange.png\" alt=\"Buy Me A Coffee\" height=\"75\" width=\"300\"></a>\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "HTTP Client for Hella's ONYX.CENTER API.",
"version": "9.0.0",
"project_urls": {
"Homepage": "https://github.com/muhlba91/onyx-client",
"Repository": "https://github.com/muhlba91/onyx-client"
},
"split_keywords": [
"hella-info",
"onyx",
"onyx-center"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e3dfe819321c7d82b238f87261c9a359f2cc6bb2a4d913db79977fc7b19791ed",
"md5": "233b2aeef8ccee0abfece98cbc531f60",
"sha256": "07f5b4f43bbdf2ae21d6e4bf2ac63c3281e7748638e25b6f83e6b3a6927206e5"
},
"downloads": -1,
"filename": "onyx_client-9.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "233b2aeef8ccee0abfece98cbc531f60",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12,<4.0",
"size": 26446,
"upload_time": "2024-02-14T19:51:18",
"upload_time_iso_8601": "2024-02-14T19:51:18.095488Z",
"url": "https://files.pythonhosted.org/packages/e3/df/e819321c7d82b238f87261c9a359f2cc6bb2a4d913db79977fc7b19791ed/onyx_client-9.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d075dbc145fe17529c9bf4ca4604817157902ba43cd19ab4ec02116ddbd4d0ef",
"md5": "eb863014f9291df845e644ee221eb22f",
"sha256": "7571110ef0878d65b6a3303d162517a0ccdb1381ec5ec065a28481379056bc44"
},
"downloads": -1,
"filename": "onyx_client-9.0.0.tar.gz",
"has_sig": false,
"md5_digest": "eb863014f9291df845e644ee221eb22f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12,<4.0",
"size": 18178,
"upload_time": "2024-02-14T19:51:20",
"upload_time_iso_8601": "2024-02-14T19:51:20.006846Z",
"url": "https://files.pythonhosted.org/packages/d0/75/dbc145fe17529c9bf4ca4604817157902ba43cd19ab4ec02116ddbd4d0ef/onyx_client-9.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-14 19:51:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "muhlba91",
"github_project": "onyx-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "onyx-client"
}
JSON
