Initial commit

Author: Joel Collins

README.md

@@ -0,0 +1,54 @@
+# LabThings Python Client
+
+This is an (extremely early) minimal Python client for LabThings devices
+
+## Usage example
+
+```
+import atexit
+from labthings_client.discovery import ThingBrowser
+
+# Create a Thing discoverer
+browser = ThingBrowser().open()
+# Close the discoverer when this script exits
+atexit.register(browser.close)
+
+# Wait for the first found LabThing on the network
+thing = browser.wait_for_first()
+```
+
+### Managing properties
+
+```
+>>> thing.properties
+{'pdfComponentMagicDenoise': <affordances.Property object at 0x00000288F4095548>}
+>>> thing.properties.pdfComponentMagicDenoise.set(500) 
+500
+>>> thing.properties.pdfComponentMagicDenoise.get()    
+500
+>>> 
+```
+
+
+### Managing actions
+
+```
+>>> thing.actions
+{'averageDataAction': <affordances.Action object at 0x00000288F40955C8>}
+>>> thing.actions.averageDataAction.args
+{'type': <class 'dict'>,
+ 'properties': {'n': {'format': 'int32',
+                      'required': True,
+                      'type': <class 'int'>},
+                'optlist': {'example': [1, 2, 3],
+                            'items': {'format': 'int32', 'type': <class 'int'>},
+                            'nullable': True,
+                            'required': False,
+                            'type': <class 'list'>}},
+}
+>>> thing.actions.averageDataAction(n=10)       
+<tasks.ActionTask object at 0x00000288F40D1348>
+>>> thing.actions.averageDataAction(n=10).wait()
+[0.0013352326078147302, 0.0008734229673564006, 0.0009756767699519994, 0.0008614760409831329, ...
+>>> 
+```

labthings_client/__init__.py

@@ -0,0 +1,103 @@
+import requests
+
+from td_parsers import find_self_link
+from json_typing import json_to_typing_basic
+from tasks import ActionTask
+
+class Affordance:
+    def __init__(self, affordance_description: dict, base_url: str = ""):
+        self.base_url = base_url.strip("/")
+        self.affordance_description = affordance_description
+
+        self.url_suffix = find_self_link(self.affordance_description.get("links"))
+        self.self_url = f"{self.base_url}{self.url_suffix}"
+
+        self.description = self.affordance_description.get("description")
+
+    
+    def find_verbs(self):
+        """Verify available HTTP methods
+
+        Returns:
+            [list] -- List of HTTP verb strings
+        """
+        return requests.options(self.self_url).headers['allow'].split(", ")
+
+
+class Property(Affordance):
+    def __init__(self, affordance_description: dict, base_url: str = ""):
+        Affordance.__init__(self, affordance_description, base_url=base_url)
+
+        self.read_only = self.affordance_description.get("readOnly")
+        self.write_only = self.affordance_description.get("writeOnly")
+
+    def __call__(self, *args, **kwargs): 
+        return self.get(*args, **kwargs)
+
+    def get(self):
+        if not self.write_only:
+            r = requests.get(self.self_url)
+            r.raise_for_status()
+            return r.json()
+        else:
+            raise AttributeError("Can't read attribute, is write-only")
+
+    def set(self, *args, **kwargs):
+        return self.put(*args, **kwargs)
+
+    def put(self, value):
+        if not self.read_only:
+            r = requests.put(self.self_url, json=value or {})
+            r.raise_for_status()
+            return r.json()
+        else:
+            raise AttributeError("Can't set attribute, is read-only")
+
+    def post(self, value):
+        if not self.read_only:
+            r = requests.post(self.self_url, json=value or {})
+            r.raise_for_status()
+            return r.json()
+        else:
+            raise AttributeError("Can't set attribute, is read-only")
+
+    def delete(self):
+        if not self.read_only:
+            r = requests.delete(self.self_url)
+            r.raise_for_status()
+            return r.json()
+        else:
+            raise AttributeError("Can't delete attribute, is read-only")
+
+
+class Action(Affordance):
+    def __init__(self, affordance_description: dict, base_url: str = ""):
+        Affordance.__init__(self, affordance_description, base_url=base_url)
+
+        self.args = json_to_typing_basic(self.affordance_description.get("input", {}))
+
+    def __call__(self, *args, **kwargs): 
+        return self.post(*args, **kwargs)
+
+    def post(self, *args, **kwargs):
+
+        # Only accept a single positional argument, at most
+        if len(args) > 1:
+            raise ValueError("If passing parameters as a positional argument, the only argument must be a single dictionary")
+
+        # Single positional argument MUST be a dictionary
+        if args and not isinstance(args[0], dict):
+            raise TypeError("If passing parameters as a positional argument, the argument must be a dictionary")
+
+        # Use positional dictionary as parameters base
+        if args:
+            params = args[0]
+        else:
+            params = {}
+
+        params.update(kwargs)
+
+        r = requests.post(self.self_url, json=params or {})
+        r.raise_for_status()
+
+        return ActionTask(r.json())

labthings_client/affordances.py

@@ -0,0 +1,124 @@
+from zeroconf import ServiceBrowser, Zeroconf
+import ipaddress
+import logging
+import time
+
+from pprint import pprint
+
+from thing import FoundThing
+
+class Browser:
+    def __init__(self, service="labthing", protocol="tcp"):
+        self.service_record = f"_{service}._{protocol}.local."
+
+        self.services = {}
+
+        self.add_service_callbacks = set()
+        self.remove_service_callbacks = set()
+
+        self._zeroconf = Zeroconf()
+        self._browser = None
+
+    def __enter__(self):
+        self.open()
+        return self
+
+    def __exit__(self ,type, value, traceback):
+        return self.close()
+
+    def open(self):
+        self._browser = ServiceBrowser(self._zeroconf, self.service_record, self)
+        return self
+
+    def close(self, *args, **kwargs):
+        logging.info(f"Closing browser {self}")
+        return self._zeroconf.close(*args, **kwargs)
+
+    def remove_service(self, zeroconf, type, name):
+        service = zeroconf.get_service_info(type, name)
+        if name in self.services:
+            for callback in self.remove_service_callbacks:
+                callback(self.services[name])
+            del self.services[name]
+
+    def add_service(self, zeroconf, type, name):
+        service = zeroconf.get_service_info(type, name)
+        self.services[name] = parse_service(service)
+        for callback in self.add_service_callbacks:
+            callback(self.services[name])
+
+    ### TODO: The names of these functions are an abomination and should be renamed
+    def add_add_service_callback(self, callback, run_on_existing: bool = True):
+        self.add_service_callbacks.add(callback)
+        if run_on_existing:
+            for service in self.services:
+                callback(service)
+
+    def remove_add_service_callback(self, callback):
+        self.add_service_callbacks.discard(callback)
+
+    def add_remove_service_callback(self, callback):
+        self.remove_service_callbacks.add(callback)
+
+    def remove_add_service_callback(self, callback):
+        self.remove_service_callbacks.discard(callback)
+
+
+class ThingBrowser(Browser):
+    def __init__(self, *args, **kwargs):
+        Browser.__init__(self, *args, **kwargs)
+        self._things = set()
+        self.add_add_service_callback(self.add_service_to_things)
+        self.add_remove_service_callback(self.remove_service_from_things)
+        
+    @property
+    def things(self):
+        return list(self._things)
+
+    def add_service_to_things(self, service):
+        self._things.add(service_to_thing(service))
+
+    def remove_service_from_things(self, service):
+        discards = set()
+        for thing in self._things:
+            if thing.name == service.get("name"):
+                discards.add(thing)
+        for discard_thing in discards:
+            self._things.discard(discard_thing)
+
+    def wait_for_first(self):
+        while len(self.things) == 0:
+            time.sleep(0.1)
+        return self.things[0]
+
+def parse_service(service):
+    properties = {}
+    for k, v in service.properties.items():
+        properties[k.decode()] = v.decode()
+
+    return {
+        "address": ipaddress.ip_address(service.address),
+        "addresses": {ipaddress.ip_address(a) for a in service.addresses},
+        "port": service.port,
+        "name": service.name,
+        "server": service.server,
+        "properties": properties,
+    }
+
+
+def service_to_thing(service: dict):
+    if not ("addresses" in service or "port" in service or "path" in service.get("properties", {})):
+        raise KeyError("Invalid service. Missing keys.")
+    return FoundThing(service.get("name"), service.get("addresses"), service.get("port"), service.get("properties").get("path"))
+
+
+if __name__ == "__main__":
+    import atexit
+    import time
+
+    logging.getLogger().setLevel(logging.DEBUG)
+
+    browser = ThingBrowser().open()
+    atexit.register(browser.close)
+
+    thing = browser.wait_for_first()

labthings_client/discovery.py

@@ -0,0 +1,37 @@
+from typing import Any
+import copy
+
+def json_to_typing_basic(schema: dict):
+
+    # Copy so we don't start popping keys from the main description
+    working_schema = copy.deepcopy(schema)
+
+    # Get basic type (will be recursive for objects/arrays)
+    json_type = working_schema.pop("type", "any")
+    python_type = Any
+
+    description = {}
+
+    if json_type == "boolean":
+        python_type = bool
+    elif json_type == "integer":
+        python_type = int
+    elif json_type == "number":
+        python_type = float
+    elif json_type == "null":
+        python_type = NoneType
+    elif json_type == "string":
+        python_type = str
+    elif json_type == "object":
+        python_type = dict
+        description["properties"] = {k: json_to_typing_basic(v) for k, v in working_schema.pop("properties", {}).items()}
+    elif json_type == "array":
+        python_type = list
+        description["items"] = json_to_typing_basic(working_schema.pop("items",{}))
+
+    description["type"] = python_type
+
+    # Add in extra unused parameters
+    description.update(working_schema)
+
+    return description

labthings_client/json_typing.py

@@ -0,0 +1,40 @@
+import requests
+
+class ActionTask:
+    def __init__(self, task_description: dict):
+        self.task_description = task_description
+        self.self_url = self.task_description.get("href")
+
+        self._value = None
+
+    def update(self):
+        r = requests.get(self.self_url)
+        r.raise_for_status()
+        self.task_description = r.json()
+
+    @property
+    def status(self):
+        return self.task_description.get("status")
+
+    @property
+    def log(self):
+        return self.task_description.get("log")
+
+    @property
+    def value(self):
+        if not self._value:
+            if not self.task_description.get("return"):
+                self.update()
+            self._value = self.task_description.get("return")
+        return self._value
+
+    def wait(self):
+        """Poll the task until it finishes, and return the return value"""
+        log_n = 0
+        while self.status in ["running", "idle"]:
+            self.update()
+            while len(self.log) > log_n:
+                d = self.log[log_n]
+                logging.log(d["levelno"], d["message"])
+                log_n += 1
+        return self.value

labthings_client/tasks.py

@@ -0,0 +1,16 @@
+def find_self_link(links_list: list):
+    return_link = ""
+    print(links_list)
+    # Look for an explicit "self" link
+    for link in links_list:
+        if link.get("rel") == "self":
+            return link.get("href")
+    # Failing that, look for a link with no rel
+    for link in links_list:
+        if link.get("rel") is None:
+            return link.get("href")
+    # Failing that, return the first link
+    if len(links_list) > 0:
+        return links_list[0].get("href")
+    # Failing even that, return empty string
+    return ""