Metadata-Version: 2.2
Name: utec_py_LF2b2w
Version: 0.0.4
Summary: A U-Home API client library.
Author-email: Luke Wallis <wallis.luke4@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/LF2b2w/utec-py
Project-URL: Issues, https://github.com/LF2b2w/utec-py/issues
Keywords: uhome,home automation,api client
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: aiohttp<4.0.0,>=3.7.4

# utec-py
Python API for U-Tec Devices. Primarily for Home Assistant, but should be able to be used anywhere.

## **This project is still under development. Expect rapid and functionality breaking changes.**

# 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

## UhomeApi
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')
```
## Device Abstraction
Devices are abstracted via the device type files, API requests are pre-formatted and pre-filled for simple integration with downstream integrations.
Currently Utec only fully supports all functions of locks, but there is limited functionality with switches and lights.

### 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_request**
Handles API requests, takes a clientsession websession to perform request function.

## API Manager
**create_request**
Packages request body parameters into a Utec/Uhome compliant standard.

## Install
```
pip install utec_py
```

## Usage
**Abstract Method Auth handling**
```
from utec_py import AbstractAuth
from utec_py import UtecAPI

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_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, args)
```

