ControllerDevice: implement new ABC for controler devices (issue #111)

* NEWS: make note of new ABC.
* microscope/devices.py: new ControllerDevice class.
* microscope/deviceserver.py: if the device being served is a
  ControllerDevice, also register its controlled devices with Pyro.

Author: carandraug

NEWS

@@ -27,6 +27,8 @@ Version 0.3.0 (upcoming)
 
 * Changes to device ABCs:
 
+  * New ABC `ControllerDevice` for controller devices.
+
   * Laser devices:
 
     * New abstract methods:

microscope/devices.py

@@ -1109,3 +1109,39 @@ def set_position(self, position):
 
     def get_filters(self):
         return [(k,v) for k,v in self._filters.items()]
+
+
+class ControllerDevice(Device, metaclass=abc.ABCMeta):
+    """Device that controls multiple devices.
+
+    Controller devices usually control multiple stage devices,
+    typically a XY and Z stage, a filterwheel, and a light source.
+    Controller devices also include multi light source engines.
+
+    Each of the controlled devices requires a name.  The choice of
+    name and its documentation is left to the concrete class.
+
+    Initialising and shutting down a controller device must initialise
+    and shutdown the controlled devices.  Concrete classes should be
+    careful to prevent that the shutdown of a controlled device does
+    not shutdown the controller and the other controlled devices.
+    This might require that controlled devices do nothing as part of
+    their shutdown and initialisation.
+
+    """
+
+    def initialize(self) -> None:
+        super().initialize()
+        for d in self.devices.values():
+            d.initialize()
+
+    @property
+    @abc.abstractmethod
+    def devices(self) -> typing.Mapping[str, Device]:
+        """Map of names to the controlled devices."""
+        raise NotImplementedError()
+
+    def _on_shutdown(self) -> None:
+        for d in self.devices.values():
+            d.shutdown()
+        super()._on_shutdown()

microscope/deviceserver.py

@@ -36,7 +36,7 @@
 
 import Pyro4
 
-from microscope.devices import FloatingDeviceMixin
+import microscope.devices
 
 # Pyro configuration. Use pickle because it can serialize numpy ndarrays.
 Pyro4.config.SERIALIZERS_ACCEPTED.add('pickle')
@@ -147,7 +147,7 @@ def run(self):
                 time.sleep(5)
             else:
                 break
-        if (isinstance(self._device, FloatingDeviceMixin)
+        if (isinstance(self._device, microscope.devices.FloatingDeviceMixin)
             and len(self._id_to_host) > 1):
             uid = str(self._device.get_id())
             if uid not in self._id_to_host or uid not in self._id_to_port:
@@ -168,11 +168,33 @@ def run(self):
         # Run the Pyro daemon in a separate thread so that we can do
         # clean shutdown under Windows.
         pyro_daemon.register(self._device, type(self._device).__name__)
+        if isinstance(self._device, microscope.devices.ControllerDevice):
+            # AUTOPROXY should be enabled by default.  If we find it
+            # disabled, there must be a reason why, so raise an error
+            # instead of silently enabling it.
+            if not Pyro4.config.AUTOPROXY:
+                raise RuntimeError('serving of a ControllerDevice requires'
+                                   ' Pyro4 AUTOPROXY option enabled')
+
+            # Autoproxy does not work with marshal serializer.
+            Pyro4.config.SERIALIZERS_ACCEPTED.discard('marshal')
+
+            for sub_device in self._device.devices.values():
+                # FIXME: by the time we do this the device has already
+                # been created and initialised and that won't be
+                # logged.  We need to rethink having a log per device
+                # (issue #110)
+                sub_device._logger.addHandler(stderr_handler)
+                sub_device._logger.addHandler(log_handler)
+                sub_device._logger.addFilter(Filter())
+                # This requires 
+                pyro_daemon.register(sub_device)
+
         pyro_thread = Thread(target = pyro_daemon.requestLoop)
         pyro_thread.daemon = True
         pyro_thread.start()
         logger.info('Serving %s' % pyro_daemon.uriFor(self._device))
-        if isinstance(self._device, FloatingDeviceMixin):
+        if isinstance(self._device, microscope.devices.FloatingDeviceMixin):
             logger.info('Device UID on port %s is %s' % (port, self._device.get_id()))
         # Wait for termination event. We should just be able to call
         # wait() on the exit_event, but this causes issues with locks
@@ -239,7 +261,7 @@ def term_func(sig, frame):
         # Keep track of how many of these classes we have set up.
         # Some SDKs need this information to index devices.
         count = 0
-        if issubclass(cls, FloatingDeviceMixin):
+        if issubclass(cls, microscope.devices.FloatingDeviceMixin):
             # Need to provide maps of uid to host and port.
             uid_to_host = {}
             uid_to_port = {}