microscope.device_server Namespace Reference

Classes
class	DeviceServer
class	DeviceServerOptions
class	Filter

Functions
	device (typing.Callable cls, str host, int port, typing.Mapping[str, typing.Any] conf={}, typing.Optional[str] uid=None)
	_create_log_formatter (str name)
None	_check_autoproxy_feature ()
None	_register_device (pyro_daemon, device, obj_id=None)
	serve_devices (devices, DeviceServerOptions options, exit_event=None)
DeviceServerOptions	_parse_cmd_line_args (typing.Sequence[str] args)
	_load_source (filepath)
	validate_devices (configfile)
int	main (typing.Sequence[str] argv)
int	_setuptools_entry_point ()
None	__main__ ()

Variables
	_logger = logging.getLogger(__name__)
	multiprocessing = multiprocessing.get_context("spawn")
	SERIALIZER
	REQUIRE_EXPOSE

Function Documentation

__main__()

None microscope.device_server.__main__

(

)

Definition at line 624 of file device_server.py.

def __main__() -> None:
    # Kept for backwards compatibility.  It keeps the setuptools
    # scripts from older editable mode installations.  Will be safe to
    # remove soon.
    _setuptools_entry_point()
 
 

_check_autoproxy_feature()

None microscope.device_server._check_autoproxy_feature ( )

protected

Definition at line 202 of file device_server.py.

def _check_autoproxy_feature() -> None:
    # AUTOPROXY is enabled by default.  If it is disabled there must
    # be a reason so raise an error instead of silently enabling it.
    if not Pyro4.config.AUTOPROXY:
        raise Exception(
            "serving of a ControllerDevice requires"
            " Pyro4 AUTOPROXY option enabled"
        )
 
    # AUTOPROXY does not work with the marshal serializer.  marshal is
    # not the default serializer so if it is the current serializer
    # there must be a reason so we don't just change it.
    if Pyro4.config.SERIALIZER == "marshal":
        raise Exception(
            "Pyro's AUTOPROXY feature is required but the"
            " 'marshal' serializer is currently selected"
        )
    if "marshal" in Pyro4.config.SERIALIZERS_ACCEPTED:
        Pyro4.config.SERIALIZERS_ACCEPTED.remove("marshal")
        _logger.info("marshal was removed from accepted serializers")
    return None
 
 

_create_log_formatter()

microscope.device_server._create_log_formatter ( str name )

protected

Create a logging.Formatter for the device server.

Each device is served on its own process and each device has its
own log file.  But the logs from all device servers also appear on
stderr where it will be difficult to figure out from which device
server a log message comes.  This creates a logging.Formatter
which includes the device server name.

Args:
    name: device name to be used on the log output.

Definition at line 133 of file device_server.py.

def _create_log_formatter(name: str):
    """Create a logging.Formatter for the device server.
 
    Each device is served on its own process and each device has its
    own log file.  But the logs from all device servers also appear on
    stderr where it will be difficult to figure out from which device
    server a log message comes.  This creates a logging.Formatter
    which includes the device server name.
 
    Args:
        name: device name to be used on the log output.
 
    """
    return logging.Formatter(
        "%%(asctime)s:%s (%%(name)s):%%(levelname)s"
        ":PID %%(process)s: %%(message)s" % name
    )
 
 

_load_source()

microscope.device_server._load_source ( filepath )

protected

Definition at line 575 of file device_server.py.

def _load_source(filepath):
    loader = importlib.machinery.SourceFileLoader("config", filepath)
    spec = importlib.util.spec_from_loader("config", loader)
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    return module
 
 

_parse_cmd_line_args()

DeviceServerOptions microscope.device_server._parse_cmd_line_args ( typing.Sequence[str] args )

protected

Definition at line 551 of file device_server.py.

def _parse_cmd_line_args(args: typing.Sequence[str]) -> DeviceServerOptions:
    parser = argparse.ArgumentParser(prog="device-server")
    parser.add_argument(
        "--logging-level",
        action="store",
        type=str,
        default="info",
        choices=["debug", "info", "warning", "error", "critical"],
        help="Set logging level",
    )
    parser.add_argument(
        "config_fpath",
        action="store",
        type=str,
        metavar="CONFIG-FILEPATH",
        help="Path to the configuration file",
    )
    parsed = parser.parse_args(args)
    return DeviceServerOptions(
        config_fpath=parsed.config_fpath,
        logging_level=getattr(logging, parsed.logging_level.upper()),
    )
 
 

_register_device()

None microscope.device_server._register_device ( pyro_daemon, device, obj_id = None )

protected

Definition at line 225 of file device_server.py.

def _register_device(pyro_daemon, device, obj_id=None) -> None:
    pyro_daemon.register(device, obj_id)
 
    if isinstance(device, microscope.abc.Controller):
        _check_autoproxy_feature()
        for sub_device in device.devices.values():
            _register_device(pyro_daemon, sub_device, obj_id=None)
 
    if isinstance(device, microscope.abc.Stage):
        _check_autoproxy_feature()
        for axis in device.axes.values():
            _register_device(pyro_daemon, axis, obj_id=None)
 
    return None
 
 

_setuptools_entry_point()

int microscope.device_server._setuptools_entry_point ( )

protected

Definition at line 613 of file device_server.py.

def _setuptools_entry_point() -> int:
    # The setuptools entry point must be a function, we can't simply
    # name this module even if this module does work as a script.  We
    # also do not want to set the default of main() to sys.argv
    # because when the documentation is generated (with Sphinx's
    # autodoc extension), then sys.argv gets replaced with the
    # sys.argv value at the time docs were generated (see
    # https://stackoverflow.com/a/12087750 )
    return main(sys.argv)
 
 

device()

microscope.device_server.device	(	typing.Callable	cls,
		str	host,
		int	port,
		typing.Mapping[str, typing.Any]	conf = {},
		typing.Optional[str]	uid = None )

Define devices and where to serve them.

A device definition for use in deviceserver config files.

Args:
    cls: :class:`Device` class of device to serve or function that
        returns a map of `Device` instances to wanted Pyro ID.
        The device class will be constructed, or the function will
        be called, with the arguments in ``conf``.
    host: hostname or ip address serving the devices.
    port: port number used to serve the devices.
    conf: keyword arguments for ``cls``.  The device or function
        are effectively constructed or called with `cls(**conf)`.
    uid: used to identify "floating" devices (see documentation
        for :class:`FloatingDeviceMixin`).  This must be specified
        if ``cls`` is a floating device.

Example

.. code-block:: python

    def construct_devices() -> typing.Dict[str, Device]:
        camera = Camera(some, arguments)
        # ... any other configuration that might be wanted
        return {'RedCamera': camera}

    DEVICES = [
        # passing a function that returns devices
        device(construct_devices, '127.0.0.1', 8000),
        # passing a Device class
        device(Camera, '127.0.0.1', 8001,
               conf={'kwarg1': some, 'kwarg2': arguments})
    ]

Definition at line 81 of file device_server.py.

):
    """Define devices and where to serve them.
 
    A device definition for use in deviceserver config files.
 
    Args:
        cls: :class:`Device` class of device to serve or function that
            returns a map of `Device` instances to wanted Pyro ID.
            The device class will be constructed, or the function will
            be called, with the arguments in ``conf``.
        host: hostname or ip address serving the devices.
        port: port number used to serve the devices.
        conf: keyword arguments for ``cls``.  The device or function
            are effectively constructed or called with `cls(**conf)`.
        uid: used to identify "floating" devices (see documentation
            for :class:`FloatingDeviceMixin`).  This must be specified
            if ``cls`` is a floating device.
 
    Example
 
    .. code-block:: python
 
        def construct_devices() -> typing.Dict[str, Device]:
            camera = Camera(some, arguments)
            # ... any other configuration that might be wanted
            return {'RedCamera': camera}
 
        DEVICES = [
            # passing a function that returns devices
            device(construct_devices, '127.0.0.1', 8000),
            # passing a Device class
            device(Camera, '127.0.0.1', 8001,
                   conf={'kwarg1': some, 'kwarg2': arguments})
        ]
 
    """
    if not callable(cls):
        raise TypeError("cls must be a callable")
    elif isinstance(cls, type):
        if issubclass(cls, FloatingDeviceMixin) and uid is None:
            raise TypeError("uid must be specified for floating devices")
        elif not issubclass(cls, FloatingDeviceMixin) and uid is not None:
            raise TypeError("uid must not be given for non floating devices")
    return dict(cls=cls, host=host, port=int(port), uid=uid, conf=conf)
 
 

main()

int microscope.device_server.main

(

typing.Sequence[str]

argv

)

Definition at line 594 of file device_server.py.

def main(argv: typing.Sequence[str]) -> int:
    options = _parse_cmd_line_args(argv[1:])
 
    root_logger = logging.getLogger()
    root_logger.setLevel(options.logging_level)
 
    stderr_handler = StreamHandler(sys.stderr)
    stderr_handler.setFormatter(_create_log_formatter("device-server"))
    root_logger.addHandler(stderr_handler)
 
    root_logger.addFilter(Filter())
 
    devices = validate_devices(options.config_fpath)
 
    serve_devices(devices, options)
 
    return 0
 
 

serve_devices()

microscope.device_server.serve_devices	(		devices,
		DeviceServerOptions	options,
			exit_event = None )

Definition at line 393 of file device_server.py.

def serve_devices(devices, options: DeviceServerOptions, exit_event=None):
    # We make changes to `devices` (would be great if we didn't had
    # to) so make a a copy of it because we don't want to make those
    # changes on the caller.  See original issue on #211 and PRs #212
    # and #217 (most discussion happens on #212).
    devices = copy.deepcopy(devices)
 
    root_logger = logging.getLogger()
 
    log_handler = RotatingFileHandler("__MAIN__.log")
    log_handler.setFormatter(_create_log_formatter("device-server"))
    root_logger.addHandler(log_handler)
 
    # An event to trigger clean termination of subprocesses. This is the
    # only way to ensure devices are shut down properly when processes
    # exit, as __del__ is not necessarily called when the interpreter exits.
    if exit_event is None:
        exit_event = multiprocessing.Event()
 
    servers = (
        []
    )  # DeviceServers instances that we need to wait for when exiting
 
    # Child processes inherit signal handling from the parent so we
    # need to make sure that only the parent process sets the exit
    # event and waits for the DeviceServers to exit.  See issue #9.
    # This won't work behind a Windows service wrapper, so we deal with
    # clean shutdown on win32 elsewhere.
    parent = multiprocessing.current_process()
 
    def term_func(sig, frame):
        """Terminate subprocesses cleanly."""
        if parent == multiprocessing.current_process():
            _logger.debug("Shutting down all servers.")
            exit_event.set()
            # Join keep_alive_thread so that it can't modify the list
            # of servers.
            keep_alive_thread.join()
            for this_server in servers:
                this_server.join()
            sys.exit()
 
    if sys.platform != "win32":
        signal.signal(signal.SIGTERM, term_func)
        signal.signal(signal.SIGINT, term_func)
 
    # Group devices by class.
    by_class = {}
    for dev in devices:
        by_class[dev["cls"]] = by_class.get(dev["cls"], []) + [dev]
 
    if not by_class:
        _logger.warning("No valid devices specified. Maybe an empty list?")
 
    for cls, devs in by_class.items():
        # Floating devices are devices that can only be identified
        # after having been initialized, so the constructor will
        # return any device that it supports.  To work around this we
        # map all device uid to host/port first.  After the
        # DeviceServer constructs the device, it can check on the map
        # where to serve it.  For non floating devices that
        # information is part of the device definition, no map is
        # needed.
        uid_to_host = {}
        uid_to_port = {}
        if isinstance(cls, type) and issubclass(cls, FloatingDeviceMixin):
            # In addition to the maps of uid to host/port, floating
            # devices SDKs need the number of devices to index them.
            count = 0
            for dev in devs:
                uid = dev["uid"]
                uid_to_host[uid] = dev["host"]
                uid_to_port[uid] = dev["port"]
 
                dev["conf"]["index"] = count
                count += 1
 
        for dev in devs:
            servers.append(
                DeviceServer(
                    dev,
                    options,
                    uid_to_host,
                    uid_to_port,
                    exit_event=exit_event,
                )
            )
            servers[-1].start()
 
    # Main thread must be idle to process signals correctly, so use another
    # thread to check DeviceServers, restarting them where necessary. Define
    # the thread target here so that it can access variables in __main__ scope.
    def keep_alive():
        """Keep DeviceServers alive."""
        while not exit_event.is_set():
            for s in servers:
                if s.is_alive():
                    continue
                else:
                    _logger.info(
                        "DeviceServer Failure. Process %s is dead with"
                        " exitcode %s. Restarting...",
                        s.pid,
                        s.exitcode,
                    )
                    servers.remove(s)
                    servers.append(s.clone())
 
                    try:
                        s.join(30)
                    except:
                        _logger.error("... could not join PID %s.", s.pid)
                    else:
                        old_pid = s.pid
                        del s
                        servers[-1].start()
                        _logger.info(
                            "... DeviceServer with PID %s restarted"
                            " as PID %s.",
                            old_pid,
                            servers[-1].pid,
                        )
            if not servers:
                # Log and exit if no servers running. May want to change this
                # if we add some interface to interactively restart servers.
                _logger.info("No servers running. Exiting.")
                exit_event.set()
            else:
                try:
                    time.sleep(5)
                except (KeyboardInterrupt, IOError):
                    pass
 
    keep_alive_thread = Thread(target=keep_alive)
    keep_alive_thread.start()
 
    _logger.info("Device Server started. Press Ctrl+C to exit.")
    while not exit_event.is_set():
        try:
            time.sleep(5)
        except (KeyboardInterrupt, IOError):
            _logger.debug("KeyboardInterrupt or IOError")
            exit_event.set()
 
    _logger.debug("Shutting down servers ...")
    while servers:
        for s in servers:
            if not s.is_alive():
                servers.remove(s)
                del s
        time.sleep(1)
    _logger.info(" ... No more servers running.")
    _logger.debug("Joining threads ...")
    keep_alive_thread.join()
    _logger.debug("... Threads joined. Exiting.")
    return
 
 

validate_devices()

microscope.device_server.validate_devices

(

configfile

)

Definition at line 583 of file device_server.py.

def validate_devices(configfile):
    config = _load_source(configfile)
    try:
        devices = getattr(config, "DEVICES")
    except AttributeError:
        raise Exception("No 'DEVICES=...' in config file.")
    if not isinstance(devices, Iterable):
        raise Exception("Error in config: DEVICES should be an iterable.")
    return devices
 
 

Variable Documentation

_logger

microscope.device_server._logger = logging.getLogger(__name__)

protected

Definition at line 59 of file device_server.py.

multiprocessing

microscope.device_server.multiprocessing = multiprocessing.get_context("spawn")

Definition at line 66 of file device_server.py.

REQUIRE_EXPOSE

microscope.device_server.REQUIRE_EXPOSE

Definition at line 78 of file device_server.py.

SERIALIZER

microscope.device_server.SERIALIZER

Definition at line 71 of file device_server.py.