From 08a67e5ce489d56d53180edf46232206f9ba2f25 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Mon, 29 Jun 2020 22:10:34 +0000 Subject: [PATCH] Update documentation --- docs/account.html | 120 +++++++-------- docs/director.html | 75 ++++++++++ docs/error_handling.html | 311 +++++++++++++++++++++++++++++++++++++++ docs/index.html | 5 + 4 files changed, 446 insertions(+), 65 deletions(-) create mode 100644 docs/error_handling.html diff --git a/docs/account.html b/docs/account.html index a984042..a073d5d 100644 --- a/docs/account.html +++ b/docs/account.html @@ -34,6 +34,8 @@

Module pyControl4.account

import logging import datetime +from .error_handling import * + AUTHENTICATION_ENDPOINT = "https://apis.control4.com/authentication/v1/rest" CONTROLLER_AUTHORIZATION_ENDPOINT = ( "https://apis.control4.com/authentication/v1/rest/authorization" @@ -51,11 +53,6 @@

Module pyControl4.account

async def __sendAccountAuthRequest(self): """Used internally to retrieve an account bearer token. Returns the entire JSON response from the Control4 auth API. - - Parameters: - `username` - Control4 account username/email. - - `password` - Control4 account password. """ dataDictionary = { "clientInfo": { @@ -79,14 +76,13 @@

Module pyControl4.account

async with session.post( AUTHENTICATION_ENDPOINT, json=dataDictionary ) as resp: + await checkResponseForError(await resp.text()) return await resp.text() async def __sendAccountGetRequest(self, uri): """Used internally to send GET requests to the Control4 API, authenticated with the account bearer token. Returns the entire JSON response from the Control4 auth API. Parameters: - `account_bearer_token` - Control4 account bearer token. - `uri` - Full URI to send GET request to. """ try: @@ -98,14 +94,13 @@

Module pyControl4.account

async with aiohttp.ClientSession() as session: with async_timeout.timeout(10): async with session.get(uri, headers=headers) as resp: + await checkResponseForError(await resp.text()) return await resp.text() async def __sendControllerAuthRequest(self, controller_common_name): """Used internally to retrieve an director bearer token. Returns the entire JSON response from the Control4 auth API. Parameters: - `account_bearer_token` - Control4 account bearer token. - `controller_common_name`: Common name of the controller. See `getAccountControllers()` for details. """ try: @@ -127,15 +122,11 @@

Module pyControl4.account

headers=headers, json=dataDictionary, ) as resp: + await checkResponseForError(await resp.text()) return await resp.text() async def getAccountBearerToken(self): - """Returns an account bearer token for making Control4 online API requests. - - Parameters: - `username` - Control4 account username/email. - - `password` - Control4 account password. + """Gets an account bearer token for making Control4 online API requests. """ data = await self.__sendAccountAuthRequest() jsonDictionary = json.loads(data) @@ -150,9 +141,6 @@

Module pyControl4.account

async def getAccountControllers(self): """Returns a dictionary of the information for all controllers registered to an account. - Parameters: - `account_bearer_token` - Control4 account bearer token. - Returns: ``` { @@ -170,8 +158,6 @@

Module pyControl4.account

"""Returns a dictionary of the information of a specific controller. Parameters: - `account_bearer_token` - Control4 account bearer token. - `controller_href` - The API `href` of the controller (get this from the output of `getAccountControllers()`) Returns: @@ -213,12 +199,20 @@

Module pyControl4.account

jsonDictionary = json.loads(data) return jsonDictionary + async def getControllerOSVersion(self, controller_href): + """Returns the OS version of a controller as a string. + + Parameters: + `controller_href` - The API `href` of the controller (get this from the output of `getAccountControllers()`) + """ + data = await self.__sendAccountGetRequest(controller_href + "/controller") + jsonDictionary = json.loads(data) + return jsonDictionary["osVersion"] + async def getDirectorBearerToken(self, controller_common_name): """Returns a dictionary with a director bearer token for making Control4 Director API requests, and its expiry time (generally 86400 seconds after current time) Parameters: - `account_bearer_token` - Control4 account bearer token. - `controller_common_name`: Common name of the controller. See `getAccountControllers()` for details. """ data = await self.__sendControllerAuthRequest(controller_common_name) @@ -258,11 +252,6 @@

Classes

async def __sendAccountAuthRequest(self): """Used internally to retrieve an account bearer token. Returns the entire JSON response from the Control4 auth API. - - Parameters: - `username` - Control4 account username/email. - - `password` - Control4 account password. """ dataDictionary = { "clientInfo": { @@ -286,14 +275,13 @@

Classes

async with session.post( AUTHENTICATION_ENDPOINT, json=dataDictionary ) as resp: + await checkResponseForError(await resp.text()) return await resp.text() async def __sendAccountGetRequest(self, uri): """Used internally to send GET requests to the Control4 API, authenticated with the account bearer token. Returns the entire JSON response from the Control4 auth API. Parameters: - `account_bearer_token` - Control4 account bearer token. - `uri` - Full URI to send GET request to. """ try: @@ -305,14 +293,13 @@

Classes

async with aiohttp.ClientSession() as session: with async_timeout.timeout(10): async with session.get(uri, headers=headers) as resp: + await checkResponseForError(await resp.text()) return await resp.text() async def __sendControllerAuthRequest(self, controller_common_name): """Used internally to retrieve an director bearer token. Returns the entire JSON response from the Control4 auth API. Parameters: - `account_bearer_token` - Control4 account bearer token. - `controller_common_name`: Common name of the controller. See `getAccountControllers()` for details. """ try: @@ -334,15 +321,11 @@

Classes

headers=headers, json=dataDictionary, ) as resp: + await checkResponseForError(await resp.text()) return await resp.text() async def getAccountBearerToken(self): - """Returns an account bearer token for making Control4 online API requests. - - Parameters: - `username` - Control4 account username/email. - - `password` - Control4 account password. + """Gets an account bearer token for making Control4 online API requests. """ data = await self.__sendAccountAuthRequest() jsonDictionary = json.loads(data) @@ -357,9 +340,6 @@

Classes

async def getAccountControllers(self): """Returns a dictionary of the information for all controllers registered to an account. - Parameters: - `account_bearer_token` - Control4 account bearer token. - Returns: ``` { @@ -377,8 +357,6 @@

Classes

"""Returns a dictionary of the information of a specific controller. Parameters: - `account_bearer_token` - Control4 account bearer token. - `controller_href` - The API `href` of the controller (get this from the output of `getAccountControllers()`) Returns: @@ -420,12 +398,20 @@

Classes

jsonDictionary = json.loads(data) return jsonDictionary + async def getControllerOSVersion(self, controller_href): + """Returns the OS version of a controller as a string. + + Parameters: + `controller_href` - The API `href` of the controller (get this from the output of `getAccountControllers()`) + """ + data = await self.__sendAccountGetRequest(controller_href + "/controller") + jsonDictionary = json.loads(data) + return jsonDictionary["osVersion"] + async def getDirectorBearerToken(self, controller_common_name): """Returns a dictionary with a director bearer token for making Control4 Director API requests, and its expiry time (generally 86400 seconds after current time) Parameters: - `account_bearer_token` - Control4 account bearer token. - `controller_common_name`: Common name of the controller. See `getAccountControllers()` for details. """ data = await self.__sendControllerAuthRequest(controller_common_name) @@ -444,21 +430,13 @@

Methods

async def getAccountBearerToken(self)
-

Returns an account bearer token for making Control4 online API requests.

-

Parameters

-

username - Control4 account username/email.

-

password - Control4 account password.

+

Gets an account bearer token for making Control4 online API requests.

Expand source code 
async def getAccountBearerToken(self):
-    """Returns an account bearer token for making Control4 online API requests.
-
-    Parameters:
-        `username` - Control4 account username/email.
-
-        `password` - Control4 account password.
+    """Gets an account bearer token for making Control4 online API requests.
     """
     data = await self.__sendAccountAuthRequest()
     jsonDictionary = json.loads(data)
@@ -476,8 +454,6 @@ 
Parameters

 
 

 
Returns a dictionary of the information for all controllers registered to an account.

-
Parameters

-
account_bearer_token - Control4 account bearer token.

 
Returns

 
{    
     "controllerCommonName": "control4_MODEL_MACADDRESS",
@@ -492,9 +468,6 @@ 
Returns

 
async def getAccountControllers(self):
     """Returns a dictionary of the information for all controllers registered to an account.
 
-    Parameters:
-        `account_bearer_token` - Control4 account bearer token.
-
     Returns:
         ```
         {    
@@ -515,7 +488,6 @@ 
Returns

 

 
Returns a dictionary of the information of a specific controller.

 
Parameters

-
account_bearer_token - Control4 account bearer token.

 
controller_href - The API href of the controller (get this from the output of getAccountControllers())

 
Returns

 
{
@@ -558,8 +530,6 @@ 
Returns

     """Returns a dictionary of the information of a specific controller.
 
     Parameters:
-        `account_bearer_token` - Control4 account bearer token.
-
         `controller_href` - The API `href` of the controller (get this from the output of `getAccountControllers()`)
 
     Returns:
@@ -602,13 +572,34 @@ 
Returns

     return jsonDictionary
+
+async def getControllerOSVersion(self, controller_href) +
+
+

Returns the OS version of a controller as a string.

+

Parameters

+

controller_href - The API href of the controller (get this from the output of getAccountControllers())

+
+ +Expand source code + +
async def getControllerOSVersion(self, controller_href):
+    """Returns the OS version of a controller as a string.
+
+    Parameters:
+        `controller_href` - The API `href` of the controller (get this from the output of `getAccountControllers()`)
+    """
+    data = await self.__sendAccountGetRequest(controller_href + "/controller")
+    jsonDictionary = json.loads(data)
+    return jsonDictionary["osVersion"]
+
+
async def getDirectorBearerToken(self, controller_common_name)

Returns a dictionary with a director bearer token for making Control4 Director API requests, and its expiry time (generally 86400 seconds after current time)

Parameters

-

account_bearer_token - Control4 account bearer token.

controller_common_name: Common name of the controller. See getAccountControllers() for details.

@@ -618,8 +609,6 @@

Parameters

"""Returns a dictionary with a director bearer token for making Control4 Director API requests, and its expiry time (generally 86400 seconds after current time) Parameters: - `account_bearer_token` - Control4 account bearer token. - `controller_common_name`: Common name of the controller. See `getAccountControllers()` for details. """ data = await self.__sendControllerAuthRequest(controller_common_name) @@ -657,6 +646,7 @@

getAccountBearerToken
  • getAccountControllers
  • getControllerInfo
    • +
  • getControllerOSVersion
  • getDirectorBearerToken
    • diff --git a/docs/director.html b/docs/director.html index 55dc220..2e4ab46 100644 --- a/docs/director.html +++ b/docs/director.html @@ -32,6 +32,8 @@

    Module pyControl4.director

    import async_timeout import json +from .error_handling import * + class C4Director: def __init__(self, ip, director_bearer_token): @@ -59,6 +61,7 @@

    Module pyControl4.director

    async with session.get( self.base_url + uri, headers=self.headers ) as resp: + await checkResponseForError(await resp.text()) return await resp.text() async def sendPostRequest(self, uri, command, params): @@ -80,6 +83,7 @@

    Module pyControl4.director

    async with session.post( self.base_url + uri, headers=self.headers, json=dataDictionary ) as resp: + await checkResponseForError(await resp.text()) return await resp.text() async def getAllItemInfo(self): @@ -123,6 +127,24 @@

    Module pyControl4.director

    jsonDictionary = json.loads(data) return jsonDictionary[0]["value"] + async def getAllItemVariableValue(self, var_name): + """Returns a dictionary with the values of the specified variable for all items that have it. + + Parameters: + `var_name` - The Control4 variable name. + """ + data = await self.sendGetRequest( + "/api/v1/items/variables?varnames={}".format(var_name) + ) + if data == "[]": + raise ValueError( + "Empty response recieved from Director! The variable {} doesn't seem to exist for any items.".format( + var_name + ) + ) + jsonDictionary = json.loads(data) + return jsonDictionary + async def getItemCommands(self, item_id): """Returns a JSON list of the commands available for the specified item. @@ -196,6 +218,7 @@

    Parameters

    async with session.get( self.base_url + uri, headers=self.headers ) as resp: + await checkResponseForError(await resp.text()) return await resp.text() async def sendPostRequest(self, uri, command, params): @@ -217,6 +240,7 @@

    Parameters

    async with session.post( self.base_url + uri, headers=self.headers, json=dataDictionary ) as resp: + await checkResponseForError(await resp.text()) return await resp.text() async def getAllItemInfo(self): @@ -260,6 +284,24 @@

    Parameters

    jsonDictionary = json.loads(data) return jsonDictionary[0]["value"] + async def getAllItemVariableValue(self, var_name): + """Returns a dictionary with the values of the specified variable for all items that have it. + + Parameters: + `var_name` - The Control4 variable name. + """ + data = await self.sendGetRequest( + "/api/v1/items/variables?varnames={}".format(var_name) + ) + if data == "[]": + raise ValueError( + "Empty response recieved from Director! The variable {} doesn't seem to exist for any items.".format( + var_name + ) + ) + jsonDictionary = json.loads(data) + return jsonDictionary + async def getItemCommands(self, item_id): """Returns a JSON list of the commands available for the specified item. @@ -301,6 +343,36 @@

    Methods

    return await self.sendGetRequest("/api/v1/items")
    +
    +async def getAllItemVariableValue(self, var_name) +
    +
    +

    Returns a dictionary with the values of the specified variable for all items that have it.

    +

    Parameters

    +

    var_name - The Control4 variable name.

    +
    + +Expand source code + +
    async def getAllItemVariableValue(self, var_name):
+    """Returns a dictionary with the values of the specified variable for all items that have it.
+
+    Parameters:
+        `var_name` - The Control4 variable name.
+    """
+    data = await self.sendGetRequest(
+        "/api/v1/items/variables?varnames={}".format(var_name)
+    )
+    if data == "[]":
+        raise ValueError(
+            "Empty response recieved from Director! The variable {} doesn't seem to exist for any items.".format(
+                var_name
+            )
+        )
+    jsonDictionary = json.loads(data)
+    return jsonDictionary
    +
    +
    async def getItemBindings(self, item_id)
    @@ -460,6 +532,7 @@

    Parameters

    async with session.get( self.base_url + uri, headers=self.headers ) as resp: + await checkResponseForError(await resp.text()) return await resp.text()     @@ -496,6 +569,7 @@

    Parameters

    async with session.post( self.base_url + uri, headers=self.headers, json=dataDictionary ) as resp: + await checkResponseForError(await resp.text()) return await resp.text() @@ -521,6 +595,7 @@

    Index

    C4Director