PyroLab 0.5.0rc2__tar.gz → 0.5.0rc3__tar.gz

{pyrolab-0.5.0rc2/pyrolab.egg-info → pyrolab-0.5.0rc3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyrolab
-Version: 0.5.0rc2
+Version: 0.5.0rc3
 Summary: A framework for using remote lab instruments as local resources built on Pyro5.
 Author-email: Sequoia Ploeg <sequoiap4@gmail.com>, BYU CamachoLab <camacho@byu.edu>
 Maintainer-email: Sequoia Ploeg <sequoiap4@gmail.com>, BYU CamachoLab <camacho@byu.edu>

{pyrolab-0.5.0rc2 → pyrolab-0.5.0rc3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyrolab"
-version = "0.5.0rc2"
+version = "0.5.0rc3"
 description = "A framework for using remote lab instruments as local resources built on Pyro5."
 readme = "README.md"
 requires-python = ">=3.11"

{pyrolab-0.5.0rc2 → pyrolab-0.5.0rc3}/pyrolab/cli.py

@@ -796,10 +796,8 @@ def ns_list(
     services = ns.list(return_metadata=True)
 
     listing = []
-    for k, v in services.items():
-        name = k
-        uri, description = v
-        listing.append([name, uri, ": ".join(description)])
+    for name, (uri, description) in sorted(services.items()):
+        listing.append([name, uri, ": ".join(sorted(description))])
 
     typer.echo(tabulate(listing, headers=["NAME", "URI", "DESCRIPTION"]))
 

{pyrolab-0.5.0rc2 → pyrolab-0.5.0rc3}/pyrolab/logs.py

@@ -29,6 +29,8 @@ import json
 import logging
 import logging.handlers
 import os
+import signal
+import sys
 import threading
 import warnings
 from datetime import datetime
@@ -117,8 +119,6 @@ def configure_process() -> None:
     (unless ``PYROLAB_HUSH_DEPRECATION`` is set). Never called on import: a
     library must not change these for the application that imports it.
     """
-    import sys
-
     import Pyro5.errors
 
     sys.excepthook = Pyro5.errors.excepthook
@@ -219,6 +219,38 @@ class PipeHandler(logging.Handler):
         return data
 
 
+def line_buffer_output() -> None:
+    """
+    Write this process's stdout and stderr out line by line.
+
+    The daemon and its child processes have their output redirected to
+    ``pyrolabd_output.log``, and Python block-buffers output to a file: a
+    driver's ``print()`` would only appear once 8 KB had built up, and would be
+    lost if the process were killed. Drivers often report problems that way.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)  # None under pythonw
+        if reconfigure is not None:
+            try:
+                reconfigure(line_buffering=True)
+            except (ValueError, OSError):  # e.g. a stream that's already closed
+                pass
+
+
+def on_sigterm(handler: Callable[[int, object], None]) -> None:
+    """
+    Call ``handler`` when this process is asked to stop with SIGTERM.
+
+    Without a handler, Python exits on SIGTERM at once, skipping all cleanup.
+    That's what ``systemctl stop`` sends (to every process of the service), and
+    what ``multiprocessing.Process.terminate()`` sends on POSIX. Signal
+    handlers can only be installed from the main thread; elsewhere (as when a
+    runner's ``run()`` is called in a thread by the tests) this does nothing.
+    """
+    if threading.current_thread() is threading.main_thread():
+        signal.signal(signal.SIGTERM, handler)
+
+
 def log_to_pipe(conn) -> None:
     """
     In a child process: send all logging to the parent over ``conn``.

{pyrolab-0.5.0rc2 → pyrolab-0.5.0rc3}/pyrolab/manager.py

@@ -276,6 +276,8 @@ class NameServerRunner(multiprocessing.Process):
         goes there (see :py:mod:`pyrolab.logs`).
     """
 
+    KIND = "nameserver"
+
     def __init__(
         self,
         *args,
@@ -336,6 +338,11 @@ class NameServerRunner(multiprocessing.Process):
         """
         return not self.KILL_SIGNAL
 
+    def _stop_on_sigterm(self, signum, frame) -> None:
+        """Treat SIGTERM like the stop message: shut down cleanly."""
+        log.info("SIGTERM received; stopping %s '%s'", self.KIND, self.name)
+        self.KILL_SIGNAL = True
+
     def run(self) -> None:
         """
         Creates and runs the child process.
@@ -345,6 +352,8 @@ class NameServerRunner(multiprocessing.Process):
         """
         if self.log_conn is not None:
             logs.log_to_pipe(self.log_conn)
+        logs.line_buffer_output()
+        logs.on_sigterm(self._stop_on_sigterm)
         log.info("Starting nameserver '%s'", self.name)
         try:
             self.nsconfig.update_pyro_config()
@@ -398,6 +407,8 @@ class DaemonRunner(multiprocessing.Process):
         goes there (see :py:mod:`pyrolab.logs`).
     """
 
+    KIND = "daemon"
+
     def __init__(
         self,
         *args,
@@ -497,6 +508,11 @@ class DaemonRunner(multiprocessing.Process):
         """
         return not self.KILL_SIGNAL
 
+    def _stop_on_sigterm(self, signum, frame) -> None:
+        """Treat SIGTERM like the stop message: shut down cleanly."""
+        log.info("SIGTERM received; stopping %s '%s'", self.KIND, self.name)
+        self.KILL_SIGNAL = True
+
     def plan_registrations(self, uris: Dict[str, URI]) -> Registrations:
         """Queue every nameserver registration this daemon should make."""
         config = PyroLabConfiguration.from_file(RUNTIME_CONFIG)
@@ -526,6 +542,8 @@ class DaemonRunner(multiprocessing.Process):
         """
         if self.log_conn is not None:
             logs.log_to_pipe(self.log_conn)
+        logs.line_buffer_output()
+        logs.on_sigterm(self._stop_on_sigterm)
         log.info("Starting daemon '%s'", self.name)
         stop_registering = threading.Event()
         registrar = None

{pyrolab-0.5.0rc2 → pyrolab-0.5.0rc3}/pyrolab/pyrolabd.py

@@ -12,6 +12,7 @@ Submodule defining the background PyroLab daemon.
 import logging
 import os
 import shutil
+import signal
 import sys
 import threading
 from typing import NamedTuple, Optional
@@ -34,7 +35,7 @@ from pyrolab import (
 from pyrolab.configure import GlobalConfiguration, describe_config_error
 from pyrolab.locations import migrate_legacy_files
 from pyrolab.manager import ProcessManager
-from pyrolab.utils import atomic_write_text, pid_is_running
+from pyrolab.utils import atomic_write_text, names_this_machine, pid_is_running
 
 log = logging.getLogger("pyrolab.pyrolabd")
 
@@ -220,8 +221,12 @@ class PyroLabDaemon:
         log.debug("Daemon process listing requested.")
 
         listing = []
-        for ns in self.gconfig.get_config().nameservers.keys():
+        for ns, nsconfig in self.gconfig.get_config().nameservers.items():
             info = self.manager.get_nameserver_process_info(ns)
+            if info["status"] == "Stopped" and not names_this_machine(nsconfig.host):
+                # Configured so services can register with it, but it runs on
+                # another machine; "Stopped" would suggest something's wrong.
+                info["status"] = "Remote"
             listing.append(NameServerInfo(name=ns, **_short_error(info)))
         nsstring = tabulate(
             listing, headers=["NAMESERVER", "CREATED", "STATUS", "URI", "LAST ERROR"]
@@ -401,6 +406,8 @@ def main(port: int = 0) -> int:
         return 1
 
     handler = logs.start_file_logging(PYROLAB_LOGFILE)
+    logs.line_buffer_output()
+    logs.on_sigterm(_exit_on_sigterm)
     try:
         for copied in migrate_legacy_files(
             LEGACY_DATA_DIR,
@@ -414,6 +421,19 @@ def main(port: int = 0) -> int:
         logs.stop_file_logging(handler)
 
 
+def _exit_on_sigterm(signum, frame) -> None:
+    """
+    Shut down cleanly on SIGTERM (``systemctl stop``) instead of dying at once.
+
+    Raising SystemExit unwinds out of the request loop, so ``_serve``'s
+    ``finally`` stops every nameserver and daemon, removes the lockfile and
+    the runtime config, and the process exits with status 0.
+    """
+    log.info("SIGTERM received; shutting down")
+    signal.signal(signal.SIGTERM, signal.SIG_IGN)  # don't interrupt the cleanup
+    raise SystemExit(0)
+
+
 def _serve(port: int) -> int:
     daemon = None
     published = False

{pyrolab-0.5.0rc2 → pyrolab-0.5.0rc3}/pyrolab/utils.py

@@ -9,11 +9,13 @@ Utils
 Convenience functions for working with the pyrolab package.
 """
 
+import ipaddress
 import logging
 import os
 import secrets
 import socket
 import sys
+from typing import Optional
 
 try:
     import importlib.resources as pkg_resources
@@ -74,6 +76,39 @@ def get_ip() -> str:
     return "127.0.0.1"
 
 
+def names_this_machine(host: Optional[str]) -> bool:
+    """
+    Whether a configured ``host`` refers to this machine.
+
+    Decided without DNS, so it never waits on the network: wildcard and
+    loopback addresses, ``public``, this machine's hostname (or its first
+    label, so ``lab.example.edu`` matches a machine called ``lab``), and, for a
+    literal IP address, this machine's address. Anything else is taken to be
+    another machine.
+
+    Parameters
+    ----------
+    host : str, optional
+        A host as written in the configuration.
+
+    Returns
+    -------
+    bool
+        False if ``host`` names another machine.
+    """
+    if not host:
+        return True
+    host = host.strip().lower().strip("[]")
+    if host in ("localhost", "public", "0.0.0.0", "::", "::1"):
+        return True
+    try:
+        address = ipaddress.ip_address(host)
+    except ValueError:
+        hostname = socket.gethostname().lower()
+        return host == hostname or host.split(".")[0] == hostname.split(".")[0]
+    return address.is_loopback or address.is_unspecified or host == get_ip()
+
+
 def generate_random_name(count: int = 3) -> str:
     """
     Concatenates ``count`` random words as a hyphenated string.

{pyrolab-0.5.0rc2 → pyrolab-0.5.0rc3/pyrolab.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyrolab
-Version: 0.5.0rc2
+Version: 0.5.0rc3
 Summary: A framework for using remote lab instruments as local resources built on Pyro5.
 Author-email: Sequoia Ploeg <sequoiap4@gmail.com>, BYU CamachoLab <camacho@byu.edu>
 Maintainer-email: Sequoia Ploeg <sequoiap4@gmail.com>, BYU CamachoLab <camacho@byu.edu>

{pyrolab-0.5.0rc2 → pyrolab-0.5.0rc3}/tests/test_cli.py

@@ -838,3 +838,24 @@ def test_spawned_daemon_output_goes_to_log_file(data_dir, monkeypatch):
     assert seen["stderr"] is cli.subprocess.STDOUT
     assert seen["stdout"].name == str(data_dir.PYROLAB_LOGDIR / cli.DAEMON_OUTPUT_LOG)
     assert seen["start_new_session"] is True
+
+
+def test_nslist_is_sorted(monkeypatch):
+    # Regression: listed in whatever order the nameserver returned (reversed,
+    # in the lab).
+    class FakeNS:
+        def list(self, return_metadata=False):
+            return {
+                "zeta.service": ("PYRO:z@host:1", {"b-tag", "a-tag"}),
+                "alpha.service": ("PYRO:a@host:1", set()),
+                "Pyro.NameServer": ("PYRO:Pyro.NameServer@host:9090", set()),
+            }
+
+    import pyrolab.api
+
+    monkeypatch.setattr(pyrolab.api, "locate_ns", lambda host, port: FakeNS())
+    result = runner.invoke(cli.app, ["nslist", "--host", "lab", "--port", "9090"])
+    assert result.exit_code == 0, result.output
+    names = [line.split()[0] for line in result.output.splitlines()[2:] if line.strip()]
+    assert names == ["Pyro.NameServer", "alpha.service", "zeta.service"]
+    assert "a-tag: b-tag" in result.output

{pyrolab-0.5.0rc2 → pyrolab-0.5.0rc3}/tests/test_logs.py

@@ -9,6 +9,10 @@ import json
 import logging
 import multiprocessing as mp
 import pickle
+import signal
+import subprocess
+import sys
+import threading
 import time
 
 import pytest
@@ -331,3 +335,54 @@ def test_cli_logging_only_when_requested(monkeypatch):
 def test_log_level_from_environment(monkeypatch, value, level):
     monkeypatch.setenv(logs.LOGLEVEL_ENV_VAR, value)
     assert logs.log_level() == level
+
+
+###############################################################################
+# Output buffering and SIGTERM
+###############################################################################
+
+
+@pytest.mark.parametrize("line_buffered", [False, True])
+def test_output_survives_a_hard_exit_only_when_line_buffered(tmp_path, line_buffered):
+    # Regression: driver print()s went to pyrolabd_output.log block-buffered,
+    # so they showed up late and were lost when the process was killed.
+    # os._exit skips flushing, like a kill does.
+    script = (
+        "import os\n"
+        "from pyrolab import logs\n"
+        + ("logs.line_buffer_output()\n" if line_buffered else "")
+        + "print('Arduino Failed: no such port')\n"
+        "os._exit(1)\n"
+    )
+    out = tmp_path / "pyrolabd_output.log"
+    with open(out, "w") as f:
+        subprocess.run([sys.executable, "-c", script], stdout=f, check=False)
+    printed = "Arduino Failed" in out.read_text()
+    assert printed == line_buffered
+
+
+def test_line_buffer_output_tolerates_missing_streams(monkeypatch):
+    monkeypatch.setattr(sys, "stdout", None)  # as under pythonw
+    monkeypatch.setattr(sys, "stderr", object())
+    logs.line_buffer_output()
+
+
+def test_on_sigterm_installs_the_handler_in_the_main_thread(monkeypatch):
+    installed = {}
+    monkeypatch.setattr(signal, "signal", lambda sig, h: installed.update({sig: h}))
+
+    def handler(signum, frame):
+        pass
+
+    logs.on_sigterm(handler)
+    assert installed == {signal.SIGTERM: handler}
+
+
+def test_on_sigterm_does_nothing_outside_the_main_thread(monkeypatch):
+    # The tests run runners' run() in threads, where signal() would raise.
+    installed = {}
+    monkeypatch.setattr(signal, "signal", lambda sig, h: installed.update({sig: h}))
+    worker = threading.Thread(target=logs.on_sigterm, args=(print,))
+    worker.start()
+    worker.join()
+    assert installed == {}

{pyrolab-0.5.0rc2 → pyrolab-0.5.0rc3}/tests/test_pyrolabd.py

@@ -345,3 +345,38 @@ def test_main_copies_legacy_files(run_main, data_dir, wait_for):
         proxy.shutdown()
     thread.join(timeout=10)
     assert data_dir.USER_CONFIG_FILE.read_text() == "daemons: {old: {}}\n"
+
+
+def test_ps_shows_a_nameserver_on_another_machine_as_remote(
+    data_dir, global_config, fake_manager, monkeypatch
+):
+    # Regression: a nameserver configured only so services can register with
+    # it (it runs elsewhere) was listed as "Stopped".
+    data_dir.USER_CONFIG_FILE.write_text(
+        "version: '1.0'\n"
+        "nameservers:\n"
+        "  here: {host: localhost, ns_port: 9090}\n"
+        "  elsewhere: {host: lab-nameserver.example.edu, ns_port: 9090}\n"
+    )
+    monkeypatch.setattr(
+        fake_manager,
+        "get_nameserver_process_info",
+        lambda name: {"created": "", "status": "Stopped", "uri": "", "error": ""},
+    )
+    rows = {line.split()[0]: line for line in PyroLabDaemon().ps().splitlines() if line}
+    assert "Remote" in rows["elsewhere"]
+    assert "Stopped" in rows["here"]
+
+
+def test_sigterm_exits_cleanly(monkeypatch):
+    # Regression: under systemd, SIGTERM killed the daemon at once, skipping
+    # the cleanup in _serve's finally (stopping children, the lockfile).
+    ignored = []
+    monkeypatch.setattr(
+        pyrolabd.signal, "signal", lambda sig, handler: ignored.append((sig, handler))
+    )
+    with pytest.raises(SystemExit) as exit_:
+        pyrolabd._exit_on_sigterm(15, None)
+    assert exit_.value.code == 0
+    # Further SIGTERMs are ignored so they can't interrupt the cleanup.
+    assert ignored == [(pyrolabd.signal.SIGTERM, pyrolabd.signal.SIG_IGN)]

{pyrolab-0.5.0rc2 → pyrolab-0.5.0rc3}/tests/test_registration.py

@@ -12,10 +12,13 @@ be observed directly.
 
 import gc
 import logging
+import multiprocessing
 import queue
 import socket
+import sys
 import threading
 import time
+from types import SimpleNamespace
 
 import Pyro5
 import pytest
@@ -355,3 +358,37 @@ def test_daemon_runner_closes_its_instruments_when_stopping(
         assert len(closed) == 1
     finally:
         gc.enable()
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="terminate() is not SIGTERM")
+def test_runner_in_a_real_process_stops_cleanly_on_sigterm(wait_for):
+    # Regression: SIGTERM (what systemctl stop and Process.terminate() send)
+    # killed a runner at once, skipping its cleanup; it now stops the same
+    # way the stop message does.
+    with multiprocessing.Manager() as shared:
+        state = shared.dict()
+        runner = NameServerRunner(
+            name="ns",
+            nsconfig=NameServerConfiguration(host="127.0.0.1", ns_port=free_port()),
+            msg_queue=multiprocessing.Queue(),
+            msg_polling=0.05,
+            shared_state=state,
+        )
+        runner.start()
+        try:
+            assert wait_for(lambda: state.get("ready"), timeout=20)
+            runner.terminate()
+            runner.join(timeout=10)
+            assert runner.exitcode == 0  # -15 if the signal had killed it
+        finally:
+            if runner.is_alive():
+                runner.kill()
+                runner.join()
+
+
+def test_runners_treat_sigterm_like_the_stop_message():
+    for cls in (NameServerRunner, DaemonRunner):
+        runner = SimpleNamespace(KIND=cls.KIND, name="x", KILL_SIGNAL=False)
+        cls._stop_on_sigterm(runner, 15, None)
+        assert runner.KILL_SIGNAL is True
+        assert cls.stay_alive(runner) is False

{pyrolab-0.5.0rc2 → pyrolab-0.5.0rc3}/tests/test_utils.py

@@ -137,3 +137,27 @@ def test_get_ip_falls_back_to_loopback(no_route, monkeypatch, caplog, resolved):
     monkeypatch.setattr(utils.socket, "gethostbyname", resolve)
     assert utils.get_ip() == "127.0.0.1"
     assert "only clients on this machine can reach" in caplog.text
+
+
+@pytest.mark.parametrize(
+    "host, here",
+    [
+        (None, True),
+        ("", True),
+        ("localhost", True),
+        ("public", True),
+        ("0.0.0.0", True),
+        ("::", True),
+        ("[::1]", True),
+        ("127.0.0.5", True),
+        ("lab", True),
+        ("LAB.example.edu", True),  # this machine's name, fully qualified
+        ("10.0.0.7", True),  # this machine's address
+        ("camacholab.ee.byu.edu", False),
+        ("10.0.0.8", False),
+    ],
+)
+def test_names_this_machine(monkeypatch, host, here):
+    monkeypatch.setattr(utils.socket, "gethostname", lambda: "lab")
+    monkeypatch.setattr(utils, "get_ip", lambda: "10.0.0.7")
+    assert utils.names_this_machine(host) is here