Add some docs and doctests to things that have 0% coverage.

[python_utils.git] / smart_home / registry.py

diff --git a/smart_home/registry.py b/smart_home/registry.py
index d63474da56f98bc44d78a221f47c3f4fd7d04971..8ca7f3b96dad4cc25807b59d948803e95e8c72ca 100644 (file)
--- a/smart_home/registry.py
+++ b/smart_home/registry.py
@@ -83,9 +83,9 @@ class SmartHomeRegistry(object):
                 self._keywords_by_name[name] = keywords
                 self._keywords_by_mac[mac] = keywords
                 self._names_by_mac[mac] = name
-                self.index_device(name, keywords, mac)
+                self._index_device(name, keywords, mac)
 
-    def index_device(self, name: str, keywords: str, mac: str) -> None:
+    def _index_device(self, name: str, keywords: str, mac: str) -> None:
         properties = [("name", name)]
         tags = set()
         for kw in keywords.split():
@@ -111,9 +111,30 @@ class SmartHomeRegistry(object):
         return s
 
     def get_keywords_by_name(self, name: str) -> Optional[str]:
+        """Given the name of a device, get its keywords.
+
+        >>> reg = SmartHomeRegistry('/home/scott/bin/network_mac_addresses.txt')
+        >>> reg.get_keywords_by_name('near_kitchen_lamp')
+        'wifi smart light goog meross test'
+
+        >>> reg.get_keywords_by_name('unknown') is None
+        True
+
+        """
         return self._keywords_by_name.get(name, None)
 
     def get_macs_by_name(self, name: str) -> Set[str]:
+        """Given the name of a device, get its MAC address(es)
+
+        >>> reg = SmartHomeRegistry('/home/scott/bin/network_mac_addresses.txt')
+        >>> reg.get_macs_by_name('near_kitchen_lamp')
+        {'34:29:8F:12:34:8E'}
+
+        >>> reg.get_macs_by_name('unknown')
+        set()
+
+        """
+
         retval = set()
         for (mac, lname) in self._names_by_mac.items():
             if name in lname:
@@ -121,6 +142,19 @@ class SmartHomeRegistry(object):
         return retval
 
     def get_macs_by_keyword(self, keyword: str) -> Set[str]:
+        """Given a keyword, return the set of MAC address(es) that have
+        that keyword.
+
+        >>> reg = SmartHomeRegistry('/home/scott/bin/network_mac_addresses.txt')
+        >>> r = reg.get_macs_by_keyword('test')
+        >>> e = set(['34:29:8F:12:26:74' , '34:29:8F:12:34:8E'])
+        >>> r == e
+        True
+
+        >>> reg.get_macs_by_keyword('unknown')
+        set()
+
+        """
         retval = set()
         for (mac, keywords) in self._keywords_by_mac.items():
             if keyword in keywords:
@@ -128,11 +162,15 @@ class SmartHomeRegistry(object):
         return retval
 
     def get_device_by_name(self, name: str) -> Optional[device.Device]:
+        """Given a name, return its Device object."""
+
         if name in self._macs_by_name:
             return self.get_device_by_mac(self._macs_by_name[name])
         return None
 
     def get_all_devices(self) -> List[device.Device]:
+        """Return a list of all known devices."""
+
         retval = []
         for mac, _ in self._keywords_by_mac.items():
             if mac is not None:
@@ -142,6 +180,8 @@ class SmartHomeRegistry(object):
         return retval
 
     def get_device_by_mac(self, mac: str) -> Optional[device.Device]:
+        """Given a MAC address, return its Device object."""
+
         if mac in self._keywords_by_mac:
             name = self._names_by_mac[mac]
             kws = self._keywords_by_mac[mac]
@@ -197,7 +237,7 @@ class SmartHomeRegistry(object):
         return None
 
     def query(self, query: str) -> List[device.Device]:
-        """Evaluates a lighting query expression formed of keywords to search
+        """Evaluates a device query expression formed of keywords to search
         for, logical operators (and, or, not), and parenthesis.
         Returns a list of matching lights.
         """
@@ -211,3 +251,9 @@ class SmartHomeRegistry(object):
                     if dev is not None:
                         retval.append(dev)
         return retval
+
+
+if __name__ == '__main__':
+    import doctest
+
+    doctest.testmod()