feat: Added single device get classes and updated readme

Jelloeater · May 31, 2023 · a453f51 · a453f51
1 parent e644ce5
commit a453f51
Show file tree

Hide file tree

Showing 6 changed files with 80 additions and 64 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,7 @@
 n.n.n / 2023-05-31
 ==================
 
+  * Added single device methods
   * wip: Started refactor for docs
   * feat: Finished updating unit tests
   * test: Unit test CICD

diff --git a/README.md b/README.md
@@ -44,31 +44,30 @@ pip install git+https://github.com/Jelloeater/hubitatcontrol.git
 **Local Example**
 
 ```python
-import __main__ as hc
+import hubitatcontrol as hc
 
-hub = hc.get_hub(host='http://192.168.1.100', token='Maker_Token',
-                 app_id='Maker_App_ID')
-device = hc.lookup_device(hub, 'Device_Name')
+hub = hc.Hub(host='http://192.168.1.100', token='Maker_Token',
+app_id='Maker_App_ID') # Get Hub object to auth and poll against
 
-print(device.switch)
-device.turn_on()
-print(device.switch)
-```
+# If you have a cloud based maker API, you can include the cloud token
+# hub = hc.get_hub(host='https://cloud.hubitat.com', token='Maker_Token',
+#                  app_id='Maker_App_ID', cloud_token='Cloud_API_token')
 
-**Cloud Example**
-
-```python
-import __main__ as hc
+TEST_DEVICE = '1RGB'
 
-hub = hc.get_hub(host='https://cloud.hubitat.com', token='Maker_Token',
-                 app_id='Maker_App_ID', cloud_token='Cloud_API_token')
-device = hc.lookup_device(hub, 'Device_Name')
+device = hc.GetSingleDevice(hub).name(TEST_DEVICE)
 
+# Turn on all the switches (includes lights)
+device.turn_on() # Send command to device
 print(device.switch)
-device.turn_on()
-print(device.switch)
+
+# Get temprature from all sensors
+for i in hc.GetDevices(hub).TemperatureSensor():
+    print(f"{i.name} - {i.temperature}")
+
 ```
 
+
 ### CLI Interface
 - If you have all the needed API keys added to your .env file, all you need to do is add them to your keyring
 - Once loaded into the keyring, you can run the CLI from anywhere on your system

diff --git a/docs/hubitatcontrol/index.md b/docs/hubitatcontrol/index.md
@@ -18,7 +18,7 @@ Hubitat Maker API
 ## Classes
 
 `DeviceInit(hub_in: hubitatcontrol.hub.Hub, device_in: hubitatcontrol.hub.Device)`
-:
+:   This class is normally not used, as it's for dynamically casting devices
 
 ```
 ### Methods
@@ -29,7 +29,7 @@ Hubitat Maker API
 ```
 
 `GetDevices(hub_in: hubitatcontrol.hub.Hub)`
-:
+:   Get a list of pre-casted devices you can search though
 
 ```
 ### Methods
@@ -60,14 +60,14 @@ Hubitat Maker API
 ```
 
 `GetSingleDevice(hub_in: hubitatcontrol.hub.Hub)`
-:
+:   Used to get a single device based on lookup
 
 ```
 ### Methods
 
 `id(self, device_id: int)`
-:
+:   Get a device by id and cast to the matched spec
 
 `name(self, device_name: str)`
-:
+:   Get a device by name and cast to the matched spec
 ```
diff --git a/docs/index.rst b/docs/index.rst
@@ -63,42 +63,40 @@ pip install git+https://github.com/Jelloeater/hubitatcontrol.git
 
 ```python
 
-import **main** as hc
+import hubitatcontrol as hc
 
-hub = hc.get*hub(host='http://192.168.1.100', token='Maker*Token',
+hub = hc.Hub(host='http://192.168.1.100', token='Maker_Token',
 
-				 app\_id='Maker\_App\_ID')
+app*id='Maker*App_ID') # Get Hub object to auth and poll against
 
-device = hc.lookup*device(hub, 'Device*Name')
-
-print(device.switch)
-
-device.turn_on()
-
-print(device.switch)
-
-```
-
-**Cloud Example**
-
-```python
+If you have a cloud based maker API, you can include the cloud token
+====================================================================
+hub = hc.get*hub(host='https://cloud.hubitat.com', token='Maker*Token',
+=======================================================================
+app*id='Maker*App*ID', cloud*token='Cloud*API*token')
+=====================================================
 
-import **main** as hc
+TEST_DEVICE = '1RGB'
 
-hub = hc.get*hub(host='https://cloud.hubitat.com', token='Maker*Token',
+device = hc.GetSingleDevice(hub).name(TEST_DEVICE)
 
-				 app\_id='Maker\_App\_ID', cloud\_token='Cloud\_API\_token')
+Turn on all the switches (includes lights)
+==========================================
 
-device = hc.lookup*device(hub, 'Device*Name')
+device.turn_on() # Send command to device
 
 print(device.switch)
 
-device.turn_on()
+Get temprature from all sensors
+===============================
 
-print(device.switch)
+for i in hc.GetDevices(hub).TemperatureSensor():
+
+	print(f"{i.name} \- {i.temperature}")
 
 ```
 
+
 ## CLI Interface
 ================
 - If you have all the needed API keys added to your .env file, all you need to do is add them to your keyring

diff --git a/hubitatcontrol/__init__.py b/hubitatcontrol/__init__.py
@@ -11,21 +11,33 @@
 
 class GetSingleDevice:
     def __init__(self, hub_in: Hub):
+        """
+        Used to get a single device based on lookup
+        """
         self.hub = hub_in
 
     def name(self, device_name: str):
+        """
+        Get a device by name and cast to the matched spec
+        """
         for i in self.hub.devices:
             if i["name"] == device_name:
                 return DeviceInit(device_in=i, hub_in=self.hub).cast_device()
 
     def id(self, device_id: int):
+        """
+        Get a device by id and cast to the matched spec
+        """
         for i in self.hub.devices:
             if i["id"] == str(device_id):
                 return DeviceInit(device_in=i, hub_in=self.hub).cast_device()
 
 
 class GetDevices:
     def __init__(self, hub_in: Hub):
+        """
+        Get a list of pre-casted devices you can search though
+        """
         self.hub = hub_in
 
     def __get_devices_from_capabilities__(self, capabilities_list: [str]):
@@ -37,6 +49,8 @@ def __get_devices_from_capabilities__(self, capabilities_list: [str]):
         return device_list
 
     def TemperatureSensor(self) -> list[sensors.TemperatureSensor]:
+        # TODO -> Fix temp data get from EcoBee <-
+
         return self.__get_devices_from_capabilities__(sensors.TemperatureSensor.spec)
 
     def EnvironmentalSensor(self) -> list[sensors.EnvironmentalSensor]:
@@ -63,6 +77,9 @@ def RGBWBulb(self) -> list[lights.RGBWBulb]:
 
 class DeviceInit:
     def __init__(self, hub_in: Hub, device_in: generic.Device):
+        """
+        This class is normally not used, as it's for dynamically casting devices
+        """
         self.hub = hub_in
         self.device = device_in
 

diff --git a/tests/test_main.py b/tests/test_main.py
@@ -1,3 +1,4 @@
+import logging
 import random
 import time
 
@@ -21,26 +22,6 @@ def test_creds():
     assert os.getenv("HUBITAT_API_TOKEN") is not None
 
 
-class TestMisc:
-    def test_get_all_temperature_sensors(self):
-        h = get_hub_envs()
-        x = hubitatcontrol.GetDevices(h).TemperatureSensor()
-        # TODO -> Fix temp data get from EcoBee <-
-        assert x is not None
-
-    def test_get_by_name(self):
-        h = get_hub_envs()
-        TEST_DEVICE = '1RGB'
-        x = hubitatcontrol.GetSingleDevice(h).name(TEST_DEVICE)
-        assert x.name == TEST_DEVICE
-
-    def test_get_by_id(self):
-        h = get_hub_envs()
-        TEST_DEVICE = 261
-        x = hubitatcontrol.GetSingleDevice(h).id(TEST_DEVICE)
-        assert x.id == TEST_DEVICE
-
-
 class TestDevices:
     def test_device_bulb(self):
         t = get_device_of_type("Virtual RGBW Light")
@@ -126,3 +107,23 @@ def test_set_color_map(self):
         assert d.level == level
         assert d.hue == hue
         assert d.saturation == saturation
+
+
+class TestMisc:
+    def test_get_all_temperature_sensors(self):
+        h = get_hub_envs()
+        for z in hubitatcontrol.GetDevices(h).TemperatureSensor():
+            logging.info(f"{z.name} - {z.temperature}")
+            assert z.temperature > -100  # Make sure we have a valid temperature
+
+    def test_get_by_name(self):
+        h = get_hub_envs()
+        TEST_DEVICE = '1RGB'
+        x = hubitatcontrol.GetSingleDevice(h).name(TEST_DEVICE)
+        assert x.name == TEST_DEVICE
+
+    def test_get_by_id(self):
+        h = get_hub_envs()
+        TEST_DEVICE = 261
+        x = hubitatcontrol.GetSingleDevice(h).id(TEST_DEVICE)
+        assert x.id == TEST_DEVICE