python-openhab-rest-client 0.1.0__py3-none-any.whl

openhab/Actions.py

@@ -0,0 +1,43 @@
+from .Client import OpenHABClient
+import json
+
+class Actions:
+    def __init__(self, client: OpenHABClient):
+        """
+        Initializes the Actions class with an OpenHABClient object.
+
+        :param client: An instance of OpenHABClient that is used for REST-API communication.
+        """
+        self.client = client
+
+    def getAllActions(self, thingUID: str, language: str = None) -> list:
+        """
+        Get all available actions for provided thing UID.
+
+        :param thingUID: The UID of the thing for which actions are to be retrieved.
+        :param language: (Optional) Language setting for the Accept-Language header.
+
+        :return: A list of actions.
+        """
+        header = {"Content-Type": "application/json"}
+        if language:
+            header["Accept-Language"] = language
+
+        return self.client.get(f"/actions/{thingUID}", header=header)
+
+    def executeAction(self, thingUID: str, actionUID: str, actionInputs: dict, language: str = None) -> str:
+        """
+        Executes a thing action.
+
+        :param thingUID: The UID of the thing on which the action is to be executed.
+        :param actionUID: The UID of the action to be executed.
+        :param actionInputs: The inputs for the action as a dictionary.
+        :param language: (Optional) Language setting for the Accept-Language header.
+
+        :return: A response from the server.
+        """
+        header = {"Content-Type": "application/json"}
+        if language:
+            header["Accept-Language"] = language
+
+        return self.client.post(f"/actions/{thingUID}/{actionUID}", header=header, data=json.dumps(actionInputs))

openhab/Addons.py

@@ -0,0 +1,163 @@
+import json
+from .Client import OpenHABClient
+import urllib.parse
+
+class Addons:
+    def __init__(self, client: OpenHABClient):
+        """
+        Initializes the Addons class with an OpenHABClient instance.
+
+        :param client: An instance of OpenHABClient used for REST API communication.
+        """
+        self.client = client  
+
+    def getAddons(self, serviceID: str = None, language: str = None) -> dict:
+        """
+        Retrieves a list of all available add-ons.
+
+        :param serviceID: Optional service ID to filter the results.
+        :param language: Optional language preference for the response.
+
+        :return: A dictionary containing the add-ons data.
+        """
+        params = {"serviceId": serviceID} if serviceID else {}
+        header = {"Content-Type": "application/json"}
+        if language:
+            header["Accept-Language"] = language
+
+        return self.client.get("/addons", header=header, params=params)
+
+    def getAddon(self, addonID: str, serviceID: str = None, language: str = None) -> dict:
+        """
+        Retrieves details of a specific add-on by its ID.
+
+        :param addonID: The unique identifier of the add-on.
+        :param serviceID: Optional service ID to filter the results.
+        :param language: Optional language preference for the response.
+
+        :return: A dictionary containing details of the specified add-on.
+        """
+        params = {"serviceId": serviceID} if serviceID else {}
+        header = {"Content-Type": "application/json"}
+        if language:
+            header["Accept-Language"] = language
+
+        return self.client.get(f"/addons/{addonID}", header=header, params=params)
+
+    def getAddonConfig(self, addonID: str, serviceID: str = None) -> dict:
+        """
+        Retrieves the configuration of a specific add-on.
+
+        :param addonID: The unique identifier of the add-on.
+        :param serviceID: Optional service ID to filter the results.
+
+        :return: A dictionary containing the configuration of the specified add-on.
+        """
+        params = {"serviceId": serviceID} if serviceID else {}
+        
+        return self.client.get(f"/addons/{addonID}/config", header={"Content-Type": "application/json"}, params=params)
+
+    def updateAddonConfig(self, addonID: str, configData: dict, serviceID: str = None) -> dict:
+        """
+        Updates the configuration of a specific add-on and returns the updated configuration.
+
+        :param addonID: The unique identifier of the add-on.
+        :param configData: A dictionary containing the new configuration settings.
+        :param serviceID: Optional service ID to specify the target service.
+        
+        :return: A dictionary containing the updated configuration.
+        """
+        data = {**configData}  # Create a copy to avoid modifying the original dictionary
+        if serviceID:
+            data["serviceId"] = serviceID
+
+        return self.client.put(f"/addons/{addonID}/config", header={"Content-Type": "application/json"}, data=json.dumps(data))
+
+    def installAddon(self, addonID: str, serviceID: str = None, language: str = None) -> dict:
+        """
+        Installs an add-on by its ID.
+
+        :param addonID: The unique identifier of the add-on.
+        :param serviceID: Optional service ID to specify the target service.
+        :param language: Optional language preference for the response.
+        
+        :return: A dictionary containing the installation status.
+        """
+        data = {"serviceId": serviceID} if serviceID else {}
+        header = {"Content-Type": "application/json"}
+        if language:
+            header["Accept-Language"] = language
+
+        return self.client.post(f"/addons/{addonID}/install", header=header, data=data)
+
+    def uninstallAddon(self, addonID: str, serviceID: str = None, language: str = None) -> dict:
+        """
+        Uninstalls an add-on by its ID.
+
+        :param addonID: The unique identifier of the add-on.
+        :param serviceID: Optional service ID to specify the target service.
+        :param language: Optional language preference for the response.
+
+        :return: A dictionary containing the uninstallation status.
+        """
+        data = {"serviceId": serviceID} if serviceID else {}
+        header = {"Content-Type": "application/json"}
+        if language:
+            header["Accept-Language"] = language
+
+        return self.client.post(f"/addons/{addonID}/uninstall", header=header, data=data)
+
+    def getAddonServices(self, language: str = None) -> dict:
+        """
+        Retrieves a list of all available add-on services.
+
+        :param language: Optional language preference for the response.
+
+        :return: A dictionary containing the available add-on services.
+        """
+        header = {"Content-Type": "application/json"}
+        if language:
+            header["Accept-Language"] = language
+
+        return self.client.get("/addons/services", header=header, params=None)
+
+    def getAddonSuggestions(self, language: str = None) -> dict:
+        """
+        Retrieves a list of suggested add-ons for installation.
+
+        :param language: Optional language preference for the response.
+
+        :return: A dictionary containing suggested add-ons.
+        """
+        header = {"Content-Type": "application/json"}
+        if language:
+            header["Accept-Language"] = language
+
+        return self.client.get("/addons/suggestions", header=header, params=None)
+
+    def getAddonTypes(self, language: str = None) -> dict:
+        """
+        Retrieves a list of all available add-on types.
+
+        :param language: Optional language preference for the response.
+
+        :return: A dictionary containing available add-on types.
+        """
+        header = {"Content-Type": "application/json"}
+        if language:
+            header["Accept-Language"] = language
+
+        return self.client.get("/addons/types", header=header, params=None)
+
+    def installAddonFromUrl(self, url: str) -> dict:
+        """
+        Installs an add-on from a given URL.
+
+        :param url: The URL of the add-on to install.
+        
+        :return: A dictionary containing the installation status.
+        """
+        encoded_url = urllib.parse.quote(url, safe='')  # Encode the URL
+        endpoint = f"/addons/url/{encoded_url}/install"
+
+        return self.client.post(endpoint, header={"Content-Type": "text/plain"}, data=None)

openhab/Audio.py

@@ -0,0 +1,66 @@
+from .Client import OpenHABClient
+
+class Audio:
+    def __init__(self, client: OpenHABClient):
+        """
+        Initializes the Audio class with an OpenHABClient object.
+
+        :param client: An instance of OpenHABClient used for REST API communication.
+        """
+        self.client = client
+
+    def getDefaultSink(self, language: str = None):
+        """
+        Retrieves the default sink if defined, or the first available sink.
+
+        :param language: (Optional) Language setting for the Accept-Language header.
+
+        :return: A dictionary containing information about the default sink.
+        """
+        header = {"Content-Type": "application/json"}
+        if language:
+            header["Accept-Language"] = language
+
+        return self.client.get("/audio/defaultsink", header=header)
+
+    def getDefaultSource(self, language: str = None):
+        """
+        Retrieves the default source if defined, or the first available source.
+
+        :param language: (Optional) Language setting for the Accept-Language header.
+
+        :return: A dictionary containing information about the default source.
+        """
+        header = {"Content-Type": "application/json"}
+        if language:
+            header["Accept-Language"] = language
+
+        return self.client.get("/audio/defaultsource", header=header)
+
+    def getSinks(self, language: str = None):
+        """
+        Retrieves a list of all available sinks.
+
+        :param language: (Optional) Language setting for the Accept-Language header.
+
+        :return: A list of available sinks.
+        """
+        header = {"Content-Type": "application/json"}
+        if language:
+            header["Accept-Language"] = language
+
+        return self.client.get("/audio/sinks", header=header)
+
+    def getSources(self, language: str = None):
+        """
+        Retrieves a list of all available sources.
+
+        :param language: (Optional) Language setting for the Accept-Language header.
+
+        :return: A list of available sources.
+        """
+        header = {"Content-Type": "application/json"}
+        if language:
+            header["Accept-Language"] = language
+
+        return self.client.get("/audio/sources", header=header)

openhab/Auth.py

@@ -0,0 +1,105 @@
+from urllib.parse import urlencode
+from .Client import OpenHABClient
+import json
+
+class Auth:
+    def __init__(self, client: OpenHABClient):
+        """
+        Initializes the Auth class with an OpenHABClient instance.
+
+        :param client: An instance of OpenHABClient used for REST API communication.
+        """
+        self.client = client
+
+    def getApiTokens(self, language: str = None) -> dict:
+        """
+        Retrieve the API tokens associated with the authenticated user.
+
+        :param language: (Optional) Language setting for the API request.
+
+        :return: JSON response from the server.
+        """
+        header = {"Content-Type": "application/json"}
+        if language:
+            header["Accept-Language"] = language
+
+        return self.client.get("/auth/apitokens", header=header)
+
+    def revokeApiToken(self, tokenName: str, language: str = None) -> dict:
+        """
+        Revoke a specific API token associated with the authenticated user.
+
+        :param tokenName: Name of the API token to be revoked.
+        :param language: (Optional) Language setting for the API request.
+
+        :return: JSON response from the server.
+        """
+        header = {"Content-Type": "application/json"}
+        if language:
+            header["Accept-Language"] = language
+
+        return self.client.delete(f"/auth/apitokens/{tokenName}", header=header)
+
+    def logout(self, refreshToken: str, language: str = None) -> dict:
+        """
+        Terminate the session associated with a refresh token.
+
+        :param refreshToken: The refresh token used to delete the session.
+        :param language: (Optional) Language setting for the API request.
+
+        :return: JSON response from the server.
+        """
+        header = {"Content-Type": "application/x-www-form-urlencoded"}
+        if language:
+            header["Accept-Language"] = language
+
+        return self.client.post("/auth/logout", header=header, data=json.dumps({"refresh_token": refreshToken}))
+
+    def getSessions(self, language: str = None) -> dict:
+        """
+        Retrieve the sessions associated with the authenticated user.
+
+        :param language: (Optional) Language setting for the API request.
+
+        :return: JSON response from the server.
+        """
+        header = {"Content-Type": "application/json"}
+        if language:
+            header["Accept-Language"] = language
+
+        return self.client.get("/auth/sessions", header=header)
+
+    def getToken(self, grantType: str, code: str = None, redirectUri: str = None, clientID: str = None, refreshToken: str = None, codeVerifier: str = None, language: str = None) -> dict:
+        """
+        Obtain access and refresh tokens.
+
+        :param grantType: The type of grant being requested.
+        :param code: (Optional) Authorization code for authentication.
+        :param redirectUri: (Optional) Redirect URI for OAuth authentication.
+        :param clientID: (Optional) Client ID for authentication.
+        :param refreshToken: (Optional) Refresh token for token renewal.
+        :param codeVerifier: (Optional) Code verifier for PKCE authentication.
+        :param language: (Optional) Language setting for the API request.
+
+        :return: JSON response from the server.
+        """
+        header = {
+            "Content-Type": "application/x-www-form-urlencoded",
+            "Accept": "application/json"
+        }
+
+        body = {
+            "grant_type": grantType,
+            "code": code,
+            "redirect_uri": redirectUri,
+            "client_id": clientID,
+            "refresh_token": refreshToken,
+            "code_verifier": codeVerifier
+        }
+        # Remove all None values
+        body = {k: v for k, v in body.items() if v is not None}
+
+        # Encode as application/x-www-form-urlencoded
+        encodedBody = urlencode(body)
+
+        return self.client.post("/auth/token", header=header, data=encodedBody)

openhab/ChannelTypes.py

@@ -0,0 +1,54 @@
+from .Client import OpenHABClient
+
+class ChannelTypes:
+    def __init__(self, client: OpenHABClient):
+        """
+        Initializes the ChannelTypes class with an OpenHABClient instance.
+
+        :param client: An instance of OpenHABClient used for REST API communication.
+        """
+        self.client = client
+
+    def getAllChannelTypes(self, language: str = None, prefixes: str = None) -> list:
+        """
+        Retrieves all available channel types.
+
+        :param language: Optional header 'Accept-Language' to specify the preferred language.
+        :param prefixes: Optional query parameter to filter channel types by prefix.
+
+        :return: A list of channel types.
+        """
+        header = {}
+        if language:
+            header["Accept-Language"] = language
+
+        params = {}
+        if prefixes:
+            params["prefixes"] = prefixes
+
+        return self.client.get("/channel-types", header=header, params=params)
+
+    def getChannelTypeByUid(self, channelTypeUid: str, language: str = None) -> dict:
+        """
+        Retrieves the item types the given trigger channel type UID can be linked to.
+
+        :param channelTypeUid: The unique UID of the channel type.
+        :param language: Optional header 'Accept-Language' to specify the preferred language.
+
+        :return: Details of the specific channel type.
+        """
+        header = {}
+        if language:
+            header["Accept-Language"] = language
+
+        return self.client.get(f"/channel-types/{channelTypeUid}", header=header)
+
+    def getLinkableItemTypes(self, channelTypeUid: str) -> list:
+        """
+        Retrieves the item types that can be linked to the specified trigger channel type.
+
+        :param channelTypeUid: The unique UID of the channel type.
+
+        :return: A list of item types.
+        """
+        return self.client.get(f"/channel-types/{channelTypeUid}/linkableItemTypes")

openhab/Client.py

@@ -0,0 +1,197 @@
+import requests
+import json
+
+class OpenHABClient:
+    def __init__(self, url: str, username: str = None, password: str = None, token: str = None):
+        """
+        Initializes the OpenHABClient instance.
+
+        :param url: The base URL of the OpenHAB server (e.g., "http://127.0.0.1:8080").
+        :param username: Optional; The username for Basic Authentication (default is None).
+        :param password: Optional; The password for Basic Authentication (default is None).
+        :param token: Optional; The Bearer Token for Token-based Authentication (default is None).
+        """
+        self.url = url.rstrip("/")  # Remove trailing slash if present
+        self.username = username
+        self.password = password
+        self.token = token
+        self.isCloud = False
+        self.isLoggedIn = False
+
+        self.session = requests.Session()
+
+        if self.token:
+            # Use Token-based authentication
+            self.session.headers.update({
+                "Authorization": f"Bearer {self.token}",
+                "Content-Type": "application/json"
+            })
+        elif self.username and self.password:
+            # Use Basic Authentication
+            self.auth = (self.username, self.password)
+            self.session.auth = self.auth
+        else:
+            self.auth = None
+
+        self.__login()
+
+    def __login(self):
+        """
+        Attempts to log in to the openHAB server.
+
+        If the server is "myopenhab.org", it sets the connection to the cloud service.
+        Otherwise, it prepares a local connection and verifies login credentials.
+        """
+        if self.url == "https://myopenhab.org":
+            self.isCloud = True
+        else:
+            self.isCloud = False
+
+        # Check connection and authentication
+        try:
+            loginResponse = self.session.get(self.url + "/rest", timeout=8)
+            loginResponse.raise_for_status()
+
+            if loginResponse.ok or loginResponse.status_code == 200:
+                self.isLoggedIn = True
+        except requests.exceptions.HTTPError as errh:
+            print(f"HTTP error occurred: {errh}")
+        except requests.exceptions.ConnectionError as errc:
+            print(f"Connection error occurred: {errc}")
+        except requests.exceptions.Timeout as errt:
+            print(f"Timeout occurred: {errt}")
+        except requests.exceptions.RequestException as err:
+            print(f"Request exception occurred: {err}")
+
+    def __executeRequest(self, header: dict = None, resourcePath: str = None, method: str = None, data=None, params=None):
+        """
+        Executes an HTTP request to the openHAB server.
+
+        :param header: Optional; A dictionary of headers to be sent with the request.
+        :param resourcePath: The path of the resource to interact with.
+        :param method: The HTTP method (GET, POST, PUT, DELETE).
+        :param data: Optional; The data to send in the request (for POST and PUT requests).
+        :return: The response of the request, either as JSON or plain text.
+
+        :raises ValueError: If the method is invalid or if the resource path is not provided.
+        """
+        if not resourcePath or not method:
+            raise ValueError('You must specify a valid resource path and HTTP method!')
+
+        method = method.lower()
+        header = header or {}
+
+        if resourcePath[0] != "/":
+            resourcePath = "/" + resourcePath
+
+        # Ensure resource path starts with "/rest"
+        if not resourcePath.startswith("/rest"):
+            resourcePath = f"/rest{resourcePath}"
+
+        # Update session headers
+        self.session.headers.update(header)
+
+        try:
+            url = f"{self.url}{resourcePath}"
+            if method == "get":
+                response = self.session.get(url, params=params, timeout=5)
+            elif method == "post":
+                response = self.session.post(url, data=data, params=params, timeout=5)
+            elif method == "put":
+                response = self.session.put(url, data=data, params=params, timeout=5)
+            elif method == "delete":
+                response = self.session.delete(url, data=data, params=params, timeout=5)
+            else:
+                raise ValueError("Invalid HTTP method provided!")
+
+            response.raise_for_status()
+
+            # Prüfen, ob die Antwort JSON enthält
+            if response.text.strip():  # Wenn die Antwort nicht leer ist
+                if "application/json" in response.headers.get("Content-Type", ""):
+                    return response.json()  # JSON dekodieren
+                else:
+                    return response.text  # Anderen Text zurückgeben
+
+            return {"status": response.status_code}  # Nur Status zurückgeben, wenn keine Antwort vorhanden ist
+        except requests.exceptions.RequestException as err:
+            print(f"Request error occurred: {err}")
+            raise
+
+    def __executeSSE(self, url: str):
+        """
+        Executes a Server-Sent Events (SSE) request.
+
+        :param url: The URL to connect to for the SSE stream.
+
+        :return: The response object with the SSE stream.
+        """
+        if self.username is not None and self.password is not None:
+            return self.session.get(url, auth=self.auth, stream=True)
+        else:
+            return self.session.get(url, stream=True)
+
+    def __executeSSE(self, url: str, header: dict = {}):
+        """
+        Executes a Server-Sent Events (SSE) request with custom headers.
+
+        :param url: The URL to connect to for the SSE stream.
+        :param header: A dictionary of headers to include in the request.
+
+        :return: The response object with the SSE stream.
+        """
+        if self.username is not None and self.password is not None:
+            return self.session.get(url, auth=self.auth, headers=header, stream=True)
+        else:
+            return self.session.get(url, headers=header, stream=True)
+
+    def get(self, endpoint: str, header: dict = None, params: dict = None):
+        """
+        Sends a GET request to the openHAB server.
+
+        :param endpoint: The endpoint for the GET request (e.g., "/items").
+        :param header: Optional; Headers to be sent with the request.
+        :param params: Optional; Query parameters for the GET request.
+
+        :return: The response from the GET request, either as JSON or plain text.
+        """
+        return self.__executeRequest(header, endpoint, "get", params=params)
+
+    def post(self, endpoint: str, header: dict = None, data=None, params: dict = None):
+        """
+        Sends a POST request to the openHAB server.
+
+        :param endpoint: The endpoint for the POST request (e.g., "/items").
+        :param header: Optional; Headers to be sent with the request.
+        :param data: Optional; The data to send in the POST request.
+        :param params: Optional; Query parameters for the request.
+
+        :return: The response from the POST request.
+        """
+        return self.__executeRequest(header, endpoint, "post", data=data, params=params)
+
+    def put(self, endpoint: str, header: dict = None, data=None, params: dict = None):
+        """
+        Sends a PUT request to the openHAB server.
+
+        :param endpoint: The endpoint for the PUT request (e.g., "/items").
+        :param header: Optional; Headers to be sent with the request.
+        :param data: Optional; The data to send in the PUT request.
+        :param params: Optional; Query parameters for the request.
+
+        :return: The response from the PUT request.
+        """
+        return self.__executeRequest(header, endpoint, "put", data=data)
+
+    def delete(self, endpoint: str, header: dict = None, data=None, params: dict = None):
+        """
+        Sends a DELETE request to the openHAB server.
+
+        :param endpoint: The endpoint for the DELETE request (e.g., "/items").
+        :param header: Optional; Headers to be sent with the request.
+        :param data: Optional; The data to send in the DELETE request.
+        :param params: Optional; Query parameters for the request.
+
+        :return: The response from the DELETE request.
+        """
+        return self.__executeRequest(header, endpoint, "delete", data=data, params=params)

openhab/ConfigDescriptions.py

@@ -0,0 +1,44 @@
+from .Client import OpenHABClient
+
+class ConfigDescriptions:
+    def __init__(self, client: OpenHABClient):
+        """
+        Initializes the ConfigDescriptions class with an OpenHABClient instance.
+
+        :param client: An instance of OpenHABClient used for REST API communication.
+        """
+        self.client = client
+
+    def getAllConfigDescriptions(self, language: str = None, scheme: str = None) -> list:
+        """
+        Retrieves all available config descriptions.
+
+        :param language: Optional header 'Accept-Language' to specify the preferred language.
+        :param scheme: Optional query parameter to filter results by a specific scheme.
+
+        :return: A list of configuration descriptions.
+        """
+        header = {}
+        if language:
+            header["Accept-Language"] = language
+
+        params = {}
+        if scheme:
+            params["scheme"] = scheme
+
+        return self.client.get("/config-descriptions", header=header, params=params)
+
+    def getConfigDescriptionByUri(self, uri: str, language: str = None) -> dict:
+        """
+        Retrieves a config description by URI.
+
+        :param uri: The URI of the requested configuration description.
+        :param language: Optional header 'Accept-Language' to specify the preferred language.
+
+        :return: Details of the specific configuration description.
+        """
+        header = {}
+        if language:
+            header["Accept-Language"] = language
+
+        return self.client.get(f"/config-descriptions/{uri}", header=header)