# utec-py
Python API for U-Tec Devices. Primarily for Home Assistant, but should be able to be used anywhere.
# Classes
## Oauth2.0 Authenticator
Handles most of the Oauth2 authentication process. Generates auth request URL for webauth, and token exchange. Includes token management methods, expiry validation, token refresh. Contains an Abstract method for retrieving initial token to allow for varyation of initial auth request handling.
### UtecOauth2 Constructor
## UtecAPI
U-Tec's API is a single endpoint (https://api.utec.com/action) that uses variable header information in the JSON payload to reach different API interfaces. So this class just handles packaging the variables responsible for different interfaces/actions correctly within the payload of the request.
## Device module
Provides an easy way to organise/ingest device info without much significant change to the raw response. With devices stored in the format:
```
id=data['id'],
name=data.get('name', ''),
category=data.get('category', ''),
handleType=data.get('handleType', ''),
deviceInfo=device_info,
capabilities=capabilities,
customData=data.get('customData'),
attributes=data.get('attributes'),
state=data.get('state')
```
### Methods
#### Token Management
**exchange_code**
Exchanges access token recieved by Oauth2 callback via redirect URI for an access token and a refresh token. Checks to see if client is already authenticated via checking if current token state.
**get_access_token**
Verifies current token validity before returning either a new token obtained via refresh token, or stored token that is still valid.
**_update_from_token**
Updates current token parameters, stores expires_in time and calculates expires_at with a 30s grace period.
#### API Requests
**make_auth_request**
Handles configuring auth header, via validation method, and performing API webession request. Returns a async context manager ClientResponse variable.
## API Manager
**package_and_perform_request**
Is the main function for performing API requests, takes name and namespace for the header object, which corresponds to the Device/User/Config interface, and their various sub functionalities. All device manipulation/command data is passed as a single dict variable via the different specific request functions.
Also includes the API request with error and response handling, returning the response as a dict.
## Install
```
pip install utec_py
```
## Usage
**Abstract Method Auth handling**
```
from utec_py import AbstractAuth
from utec_py import UtecAPI
from utec_py import DeviceList
API = api()
class customAuthImplementation(AbstractAuth):
"""Handle Custom Auth request handling""
def __init__(self, websession, client_id, client_secret, token=None):
super().__init__(websession, host=API_BASE_URL)
async def async_get_auth_implementation():
"""Return authentication for a custom auth implementation""
## API requests can be run with or without custom implementation as API class uses Abstract Auth as a parent to define request processess.
async def async_make_auth_request():
"""Perform API Request"""
```
**In built Auth Handling**
```
from utec_py import UtecOAuth2
from utec_py import UtecAPI
from utec_py import DeviceList
API = api()
Authenticator = UtecOAuth2(client_id, client_secret) # If you already have an access token stored via an application credential manager, you can pass this token to the class or it can be omitted entirely on first run
# Handle oauth web auth flow and obtain access code
Authenticator.exchange_access_code("access_code")
# Which will handle obtaining access tokens and update the stored self token values and then all token management from then on.
# Once Authenication has been completed devices can be called via API
API._discover() # Perform device discovery
API._query_device(device_id) # Query a specific devcie
API._send_command(device_id, capability, command) # Send a device command without arguments
API._send_command_with_arg(device_id, capability, command, arguments: dict) # For commands with arguments ie light brightness or colourtemperature
# Devices can then be managed from raw api responses or translated into more readable formats via device module.
Discover_devices = DeviceList.From_dict(api_data) # Parses device info which can then be called via print or other functions
for device in device_list.devices:
print(f"ID: {device.id}, Name: {device.name}")
```
Raw data
{
"_id": null,
"home_page": null,
"name": "utec-py-LF2b2w",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "uhome, home automation, api client",
"author": null,
"author_email": "Luke Wallis <wallis.luke4@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/64/6a/a96b117e113ea6439aa64f168160febb5943f6a8dedd7de182548aacf73e/utec_py_lf2b2w-0.1.11.tar.gz",
"platform": null,
"description": "# utec-py\r\nPython API for U-Tec Devices. Primarily for Home Assistant, but should be able to be used anywhere.\r\n\r\n# Classes\r\n## Oauth2.0 Authenticator\r\nHandles most of the Oauth2 authentication process. Generates auth request URL for webauth, and token exchange. Includes token management methods, expiry validation, token refresh. Contains an Abstract method for retrieving initial token to allow for varyation of initial auth request handling.\r\n### UtecOauth2 Constructor\r\n\r\n## UtecAPI\r\nU-Tec's API is a single endpoint (https://api.utec.com/action) that uses variable header information in the JSON payload to reach different API interfaces. So this class just handles packaging the variables responsible for different interfaces/actions correctly within the payload of the request.\r\n\r\n## Device module\r\nProvides an easy way to organise/ingest device info without much significant change to the raw response. With devices stored in the format:\r\n```\r\n id=data['id'],\r\n name=data.get('name', ''),\r\n category=data.get('category', ''),\r\n handleType=data.get('handleType', ''),\r\n deviceInfo=device_info,\r\n capabilities=capabilities,\r\n customData=data.get('customData'),\r\n attributes=data.get('attributes'),\r\n state=data.get('state')\r\n```\r\n### Methods\r\n#### Token Management\r\n**exchange_code**\r\nExchanges access token recieved by Oauth2 callback via redirect URI for an access token and a refresh token. Checks to see if client is already authenticated via checking if current token state.\r\n\r\n**get_access_token**\r\nVerifies current token validity before returning either a new token obtained via refresh token, or stored token that is still valid.\r\n\r\n**_update_from_token**\r\nUpdates current token parameters, stores expires_in time and calculates expires_at with a 30s grace period.\r\n\r\n#### API Requests\r\n**make_auth_request**\r\nHandles configuring auth header, via validation method, and performing API webession request. Returns a async context manager ClientResponse variable.\r\n\r\n## API Manager\r\n**package_and_perform_request**\r\nIs the main function for performing API requests, takes name and namespace for the header object, which corresponds to the Device/User/Config interface, and their various sub functionalities. All device manipulation/command data is passed as a single dict variable via the different specific request functions.\r\nAlso includes the API request with error and response handling, returning the response as a dict.\r\n\r\n## Install\r\n```\r\npip install utec_py\r\n```\r\n\r\n## Usage\r\n**Abstract Method Auth handling**\r\n```\r\nfrom utec_py import AbstractAuth\r\nfrom utec_py import UtecAPI\r\nfrom utec_py import DeviceList\r\n\r\nAPI = api()\r\n\r\nclass customAuthImplementation(AbstractAuth):\r\n\"\"\"Handle Custom Auth request handling\"\"\r\n def __init__(self, websession, client_id, client_secret, token=None):\r\n super().__init__(websession, host=API_BASE_URL)\r\n\r\n async def async_get_auth_implementation():\r\n \"\"\"Return authentication for a custom auth implementation\"\"\r\n## API requests can be run with or without custom implementation as API class uses Abstract Auth as a parent to define request processess.\r\n \r\n async def async_make_auth_request():\r\n \"\"\"Perform API Request\"\"\"\r\n```\r\n**In built Auth Handling**\r\n```\r\nfrom utec_py import UtecOAuth2\r\nfrom utec_py import UtecAPI\r\nfrom utec_py import DeviceList\r\n\r\nAPI = api()\r\nAuthenticator = UtecOAuth2(client_id, client_secret) # If you already have an access token stored via an application credential manager, you can pass this token to the class or it can be omitted entirely on first run\r\n# Handle oauth web auth flow and obtain access code\r\nAuthenticator.exchange_access_code(\"access_code\")\r\n# Which will handle obtaining access tokens and update the stored self token values and then all token management from then on.\r\n\r\n# Once Authenication has been completed devices can be called via API\r\nAPI._discover() # Perform device discovery\r\nAPI._query_device(device_id) # Query a specific devcie\r\nAPI._send_command(device_id, capability, command) # Send a device command without arguments\r\nAPI._send_command_with_arg(device_id, capability, command, arguments: dict) # For commands with arguments ie light brightness or colourtemperature\r\n\r\n# Devices can then be managed from raw api responses or translated into more readable formats via device module.\r\nDiscover_devices = DeviceList.From_dict(api_data) # Parses device info which can then be called via print or other functions\r\nfor device in device_list.devices:\r\n print(f\"ID: {device.id}, Name: {device.name}\")\r\n```\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A U-Home API client library.",
"version": "0.1.11",
"project_urls": {
"Homepage": "https://github.com/LF2b2w/utec-py",
"Issues": "https://github.com/LF2b2w/utec-py/issues"
},
"split_keywords": [
"uhome",
" home automation",
" api client"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "19785df63d4bb18b05099b06deeab5ba6fe2270e38e8292c5b00c288f0a67f2a",
"md5": "9921e3e3c541db8dec8510eef8e1a43d",
"sha256": "55f26a8c944d3a9dfcaa2d6c9da468bd96b09dbe2a25c4bd1adff0e3bf1e8406"
},
"downloads": -1,
"filename": "utec_py_LF2b2w-0.1.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9921e3e3c541db8dec8510eef8e1a43d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 13384,
"upload_time": "2025-02-19T10:40:33",
"upload_time_iso_8601": "2025-02-19T10:40:33.638801Z",
"url": "https://files.pythonhosted.org/packages/19/78/5df63d4bb18b05099b06deeab5ba6fe2270e38e8292c5b00c288f0a67f2a/utec_py_LF2b2w-0.1.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "646aa96b117e113ea6439aa64f168160febb5943f6a8dedd7de182548aacf73e",
"md5": "9214757b90c09d899140ae023b28e79e",
"sha256": "ccfbe875278d9d1e21bde0d976a7b62761856cea9f9e0104baf04cd9f1b74c5a"
},
"downloads": -1,
"filename": "utec_py_lf2b2w-0.1.11.tar.gz",
"has_sig": false,
"md5_digest": "9214757b90c09d899140ae023b28e79e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 13727,
"upload_time": "2025-02-19T10:40:39",
"upload_time_iso_8601": "2025-02-19T10:40:39.519895Z",
"url": "https://files.pythonhosted.org/packages/64/6a/a96b117e113ea6439aa64f168160febb5943f6a8dedd7de182548aacf73e/utec_py_lf2b2w-0.1.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-19 10:40:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LF2b2w",
"github_project": "utec-py",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "utec-py-lf2b2w"
}
JSON
