sysrepo-python-plugind 1.0.0__py3-none-any.whl

sysrepo_python_plugind/__init__.py

@@ -0,0 +1,15 @@
+# Copyright (c) 2026 EntryPoint Communications, LLC
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""sysrepo-python-plugind — Python plugin daemon for sysrepo.
+
+Public API:
+
+- :class:`SysrepoPlugin`: Abstract base class for Python plugins.
+- :func:`main`: Entry point for the ``sysrepo-python-plugind`` console script.
+"""
+
+from .cli import main
+from .plugin import SysrepoPlugin
+
+__all__ = ["SysrepoPlugin", "main"]

sysrepo_python_plugind/__main__.py

@@ -0,0 +1,8 @@
+# Copyright (c) 2026 EntryPoint Communications, LLC
+# SPDX-License-Identifier: BSD-3-Clause
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

sysrepo_python_plugind/cli.py

@@ -0,0 +1,158 @@
+# Copyright (c) 2026 EntryPoint Communications, LLC
+# SPDX-License-Identifier: BSD-3-Clause
+
+import argparse
+import logging
+import os
+import sys
+from typing import Optional
+
+import sysrepo
+
+from .daemon import PluginDaemon
+from .pid import PidFile
+
+# Map sysrepo-plugind -v levels to Python logging levels, matching the C daemon.
+_LOG_LEVELS = {
+    0: logging.ERROR,
+    1: logging.WARNING,
+    2: logging.INFO,
+    3: logging.DEBUG,
+    4: logging.DEBUG,
+}
+
+
+def main() -> int:
+    """Parse CLI arguments and run the sysrepo Python plugin daemon.
+
+    Parses ``-d``, ``-v``, ``-p``, and ``-f`` flags (mirroring the C
+    sysrepo-plugind), configures logging, creates a PluginDaemon, and
+    either daemonizes or runs in the foreground.
+
+    Returns:
+        int: Exit code; 0 on success, 1 on error.
+    """
+    parser = argparse.ArgumentParser(
+        prog="sysrepo-python-plugind",
+        description="Sysrepo Python plugin daemon",
+    )
+    parser.add_argument(
+        "-d",
+        dest="debug",
+        action="store_true",
+        help="debug mode: stay in foreground, log to stderr",
+    )
+    parser.add_argument(
+        "-v",
+        dest="verbosity",
+        type=int,
+        default=2,
+        metavar="LEVEL",
+        choices=range(5),
+        help="log verbosity 0-4 (default: 2 = INFO)",
+    )
+    parser.add_argument(
+        "-p",
+        dest="pid_file",
+        metavar="PATH",
+        help="write PID file at PATH",
+    )
+    parser.add_argument(
+        "-f",
+        dest="fatal_fail",
+        action="store_true",
+        help="exit if any plugin fails to initialise",
+    )
+    args = parser.parse_args()
+
+    log_level = _LOG_LEVELS.get(args.verbosity, logging.DEBUG)
+    _configure_logging(debug=args.debug, level=log_level)
+
+    daemon = PluginDaemon(fatal_fail=args.fatal_fail)
+
+    if args.pid_file:
+        return _run_with_pid(daemon, args.pid_file, debug=args.debug)
+
+    if not args.debug:
+        _daemonize()
+    return daemon.run()
+
+
+# ------------------------------------------------------------------------------
+def _run_with_pid(daemon: PluginDaemon, pid_path: str, debug: bool) -> int:
+    """Run the daemon with a PID file, handling lock failure gracefully.
+
+    Opens the PID file lock before daemonizing so that a second invocation
+    fails immediately with a clear error message.
+
+    Args:
+        daemon (PluginDaemon): Configured daemon instance to run.
+        pid_path (str): Filesystem path for the PID file.
+        debug (bool): If True, skip daemonization and stay in foreground.
+
+    Returns:
+        int: Exit code from daemon.run(), or 1 if the PID file is already
+            locked by another instance.
+    """
+    try:
+        with PidFile(pid_path) as pid_file:
+            if not debug:
+                _daemonize()
+            return daemon.run(pid_file)
+    except RuntimeError as exc:
+        # PID file lock failure — another instance is running.
+        logging.getLogger(__name__).error("%s", exc)
+        return 1
+
+
+def _configure_logging(debug: bool, level: int) -> None:
+    """Configure Python and sysrepo logging.
+
+    In debug mode logs to stderr; otherwise routes to syslog under the
+    application name ``'sysrepo-python-plugind'``.
+
+    Args:
+        debug (bool): If True, log to stderr; otherwise log to syslog.
+        level (int): Python logging level (e.g. ``logging.INFO``).
+    """
+    handler = logging.StreamHandler()
+    handler.setLevel(level)
+    logging.getLogger().addHandler(handler)
+    logging.getLogger().setLevel(level)
+
+    if debug:
+        sysrepo.configure_logging(stderr_level=level, py_logging=True)
+    else:
+        sysrepo.configure_logging(
+            syslog_level=level,
+            syslog_app_name="sysrepo-python-plugind",
+            py_logging=True,
+        )
+
+
+def _daemonize() -> None:
+    """Daemonize the current process using the standard double-fork technique.
+
+    After the second fork the process is in its own session, has no
+    controlling terminal, and has stdin/stdout/stderr redirected to
+    /dev/null.  File descriptors beyond stderr are left open so that a
+    PidFile lock opened before this call survives in the child process.
+    """
+    # First fork: become session leader's child.
+    pid = os.fork()
+    if pid > 0:
+        sys.exit(0)
+
+    os.setsid()
+
+    # Second fork: ensure we can never re-acquire a controlling terminal.
+    pid = os.fork()
+    if pid > 0:
+        sys.exit(0)
+
+    os.chdir("/")
+
+    devnull = os.open(os.devnull, os.O_RDWR)
+    for fd in (sys.stdin.fileno(), sys.stdout.fileno(), sys.stderr.fileno()):
+        os.dup2(devnull, fd)
+    os.close(devnull)

sysrepo_python_plugind/daemon.py

@@ -0,0 +1,306 @@
+# Copyright (c) 2026 EntryPoint Communications, LLC
+# SPDX-License-Identifier: BSD-3-Clause
+
+import asyncio
+import contextlib
+import logging
+import os
+import signal
+import socket
+import sys
+import threading
+from importlib.metadata import entry_points
+from typing import Optional
+
+import sysrepo
+
+from .pid import PidFile
+from .plugin import SysrepoPlugin
+from .sort import PluginList, sort_plugins
+
+LOG = logging.getLogger(__name__)
+
+_LOADED_XPATH = (
+    "/sysrepo-plugind:sysrepo-plugind"
+    "/sysrepo-python-plugind:python-loaded-plugins/plugin"
+)
+_LOADED_CONTAINER = (
+    "/sysrepo-plugind:sysrepo-plugind"
+    "/sysrepo-python-plugind:python-loaded-plugins"
+)
+
+
+class PluginDaemon:
+    """Python equivalent of sysrepo-plugind.
+
+    Loads Python plugins via entry points, manages their lifecycle (init,
+    run, cleanup), and publishes loaded-plugin state to the sysrepo
+    operational datastore.
+
+    Args:
+        fatal_fail (bool): If True, a plugin init() failure aborts the
+            entire daemon.  If False (default), the failing plugin is
+            skipped and the remaining plugins are attempted.
+
+    Example::
+
+        daemon = PluginDaemon(fatal_fail=False)
+        with PidFile("/run/srpy-plugind.pid") as pid_file:
+            _daemonize()
+            rc = daemon.run(pid_file)
+        sys.exit(rc)
+    """
+
+    def __init__(self, fatal_fail: bool = False) -> None:
+        self.fatal_fail = fatal_fail
+        self._stop = threading.Event()
+        self._plugins: PluginList = []
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._loop_thread: Optional[threading.Thread] = None
+
+    # ------------------------------------------------------------------
+    # Public entry point
+
+    def run(self, pid_file: Optional[PidFile] = None) -> int:
+        """Run the daemon; block until a termination signal is received.
+
+        Opens a sysrepo connection, initialises all discovered plugins,
+        publishes the loaded-plugins list to the operational datastore,
+        notifies systemd, and then waits for a stop signal before cleaning
+        up.
+
+        Args:
+            pid_file (PidFile, optional): If provided, write() is called
+                after all plugins are initialised so the file contains the
+                daemonized child's PID.
+
+        Returns:
+            int: 0 on clean shutdown, 1 if a fatal error occurred.
+        """
+        self._setup_signals()
+        self._start_event_loop()
+
+        rc = 0
+        try:
+            with sysrepo.SysrepoConnection() as conn:
+                with conn.start_session("running") as sess:
+                    self._init_plugins(sess)
+                    self._publish_loaded(sess)
+                    if pid_file is not None:
+                        pid_file.write()
+                    _sd_notify("READY=1")
+                    LOG.info(
+                        "daemon ready, %d plugin(s) loaded", len(self._plugins)
+                    )
+                    self._stop.wait()
+                    LOG.info("shutting down")
+                    _sd_notify("STOPPING=1")
+                    self._cleanup_plugins(sess)
+        except Exception:
+            LOG.exception("daemon error")
+            rc = 1
+        finally:
+            self._stop_event_loop()
+
+        return rc
+
+    # ------------------------------------------------------------------
+    # Signal handling
+
+    def _setup_signals(self) -> None:
+        """Register signal handlers matching the C sysrepo-plugind behaviour.
+
+        SIGINT, SIGTERM, SIGQUIT, SIGABRT, and SIGHUP trigger a graceful
+        shutdown.  A second signal while shutdown is already in progress
+        calls sys.exit(1).  SIGPIPE, SIGTSTP, SIGTTIN, and SIGTTOU are
+        ignored.
+        """
+        def _handler(sig: int, _frame) -> None:
+            if self._stop.is_set():
+                # Second signal while already shutting down → hard exit.
+                sys.exit(1)
+            LOG.info("received %s, initiating shutdown", signal.Signals(sig).name)
+            self._stop.set()
+
+        for sig in (
+            signal.SIGINT,
+            signal.SIGTERM,
+            signal.SIGQUIT,
+            signal.SIGABRT,
+            signal.SIGHUP,
+        ):
+            signal.signal(sig, _handler)
+
+        for sig in (signal.SIGPIPE, signal.SIGTSTP, signal.SIGTTIN, signal.SIGTTOU):
+            signal.signal(sig, signal.SIG_IGN)
+
+    # ------------------------------------------------------------------
+    # asyncio event loop
+
+    def _start_event_loop(self) -> None:
+        """Create and start an asyncio event loop in a background daemon thread.
+
+        The loop is set as the thread-local event loop via
+        asyncio.set_event_loop() before any plugin init() calls, so plugins
+        that use asyncio_register=True subscriptions can rely on
+        asyncio.get_event_loop() returning a running loop without managing
+        one themselves.
+        """
+        self._loop = asyncio.new_event_loop()
+        # Make the loop visible to asyncio.get_event_loop() in plugin init().
+        asyncio.set_event_loop(self._loop)
+        self._loop_thread = threading.Thread(
+            target=self._loop.run_forever,
+            name="sysrepo-asyncio",
+            daemon=True,
+        )
+        self._loop_thread.start()
+        LOG.debug("asyncio event loop started")
+
+    def _stop_event_loop(self) -> None:
+        """Signal the asyncio event loop to stop and join its thread.
+
+        Safe to call if the loop was never started.  Waits up to 5 seconds
+        for the loop thread to exit before returning.
+        """
+        if self._loop and not self._loop.is_closed():
+            self._loop.call_soon_threadsafe(self._loop.stop)
+        if self._loop_thread:
+            self._loop_thread.join(timeout=5.0)
+        LOG.debug("asyncio event loop stopped")
+
+    # ------------------------------------------------------------------
+    # Plugin lifecycle
+
+    def _discover_plugins(self) -> PluginList:
+        """Discover all installed plugins via the sysrepo_python.plugins entry point group.
+
+        Loads each entry point, verifies it is a SysrepoPlugin subclass,
+        and instantiates it.
+
+        Returns:
+            PluginList: (entry-point-name, instance) pairs in discovery order.
+
+        Raises:
+            Exception: Re-raised from ep.load() or instantiation when
+                fatal_fail is True; otherwise logged and skipped.
+        """
+        discovered: PluginList = []
+        for ep in entry_points(group="sysrepo_python.plugins"):
+            try:
+                cls = ep.load()
+                if not (isinstance(cls, type) and issubclass(cls, SysrepoPlugin)):
+                    raise TypeError(
+                        f"{ep.value!r} must be a SysrepoPlugin subclass, got {cls!r}"
+                    )
+                discovered.append((ep.name, cls()))
+                LOG.debug("discovered plugin %r (%s)", ep.name, ep.value)
+            except Exception:
+                LOG.exception("failed to load entry point %r", ep.name)
+                if self.fatal_fail:
+                    raise
+        return discovered
+
+    def _init_plugins(self, sess: sysrepo.session.SysrepoSession) -> None:
+        """Discover, sort, and initialise all plugins.
+
+        Calls _discover_plugins(), reorders the result via sort_plugins(),
+        then calls init() on each plugin.  Successfully initialised plugins
+        are appended to self._plugins.
+
+        Args:
+            sess (sysrepo.session.SysrepoSession): Active running-datastore session
+                passed to each plugin's init().
+
+        Raises:
+            Exception: Re-raised from plugin init() when fatal_fail is True;
+                otherwise logged and the plugin is skipped.
+        """
+        plugins = self._discover_plugins()
+        plugins = sort_plugins(sess, plugins)
+
+        for ep_name, inst in plugins:
+            try:
+                inst.init(sess)
+                self._plugins.append((ep_name, inst))
+                LOG.info("initialized plugin %r", ep_name)
+            except Exception:
+                LOG.exception("plugin %r init() failed", ep_name)
+                if self.fatal_fail:
+                    raise
+
+    def _cleanup_plugins(self, sess: sysrepo.session.SysrepoSession) -> None:
+        """Call cleanup() on all initialised plugins in reverse init order.
+
+        Exceptions from individual cleanup() calls are logged but do not
+        prevent the remaining plugins from being cleaned up.
+
+        Args:
+            sess (sysrepo.session.SysrepoSession): Active running-datastore session
+                passed to each plugin's cleanup().
+        """
+        for ep_name, inst in reversed(self._plugins):
+            try:
+                inst.cleanup(sess)
+                LOG.info("cleaned up plugin %r", ep_name)
+            except Exception:
+                LOG.exception("plugin %r cleanup() raised", ep_name)
+
+    # ------------------------------------------------------------------
+    # Operational datastore
+
+    def _publish_loaded(self, sess: sysrepo.session.SysrepoSession) -> None:
+        """Publish initialised plugin names to the sysrepo operational datastore.
+
+        Switches to the operational datastore, clears any stale entries
+        under the python-loaded-plugins container, writes one leaf-list
+        entry per successfully initialised plugin, applies changes, then
+        switches back to the running datastore.
+
+        Args:
+            sess (sysrepo.session.SysrepoSession): Active sysrepo session;
+                temporarily switched to operational and back to running.
+
+        Raises:
+            sysrepo.SysrepoNotFoundError: Caught internally when clearing
+                stale entries on first run; not propagated.
+        """
+        sess.switch_datastore("operational")
+        try:
+            sess.discard_items(_LOADED_CONTAINER)
+        except sysrepo.SysrepoNotFoundError:
+            pass
+
+        for ep_name, _ in self._plugins:
+            sess.set_item(_LOADED_XPATH, ep_name)
+            LOG.info("add plugin %r to operational datastore", ep_name)
+
+        sess.apply_changes()
+        LOG.info("operational store update complete")
+        sess.switch_datastore("running")
+        LOG.debug(
+            "published %d plugin name(s) to operational datastore",
+            len(self._plugins),
+        )
+
+
+# ------------------------------------------------------------------------------
+def _sd_notify(state: str) -> None:
+    """Send a state notification to systemd via the NOTIFY_SOCKET.
+
+    Does nothing if the NOTIFY_SOCKET environment variable is not set.
+    Suppresses OSError (e.g. if the socket path is stale or invalid).
+
+    Args:
+        state (str): Notification string, e.g. ``'READY=1'`` or
+            ``'STOPPING=1'``.
+    """
+    sock_path = os.environ.get("NOTIFY_SOCKET", "")
+    if not sock_path:
+        return
+    # systemd may use an abstract socket (leading '@' means NUL byte).
+    addr = "\0" + sock_path[1:] if sock_path.startswith("@") else sock_path
+    with contextlib.suppress(OSError):
+        with socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM) as s:
+            s.connect(addr)
+            s.sendall(state.encode())

sysrepo_python_plugind/install_yang.py

@@ -0,0 +1,82 @@
+# Copyright (c) 2026 EntryPoint Communications, LLC
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Install or upgrade the sysrepo-python-plugind YANG module into sysrepo."""
+
+import argparse
+import subprocess
+import sys
+from importlib.resources import as_file, files
+
+
+_MODULE_NAME = "sysrepo-python-plugind"
+
+
+def main() -> int:
+    """Install or upgrade the sysrepo-python-plugind YANG augmentation module.
+
+    Checks whether the module is already installed via ``sysrepoctl --list``
+    and either skips (already installed, no ``--force``), installs (first
+    run), or upgrades (``--force``) using ``sysrepoctl``.
+
+    Returns:
+        int: 0 on success or when already installed, non-zero if
+            ``sysrepoctl`` exits with an error.
+    """
+    parser = argparse.ArgumentParser(
+        prog="sysrepo-python-plugind-setup",
+        description="Install the sysrepo-python-plugind YANG augmentation module.",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="upgrade the module even if it is already installed",
+    )
+    args = parser.parse_args()
+
+    already_installed = _is_installed()
+
+    if not args.force and already_installed:
+        print(f"{_MODULE_NAME}: already installed, nothing to do")
+        print("  (use --force to upgrade)")
+        return 0
+
+    flag = "--update" if already_installed else "--install"
+    verb = "Upgrading" if already_installed else "Installing"
+
+    yang_ref = files("sysrepo_python_plugind").joinpath(
+        "yang/sysrepo-python-plugind.yang"
+    )
+    with as_file(yang_ref) as yang_path:
+        print(f"{verb} {yang_path} ...")
+        result = subprocess.run(
+            ["sysrepoctl", flag, str(yang_path)],
+            check=False,
+        )
+        if result.returncode != 0:
+            print(
+                f"sysrepoctl {flag} failed (exit {result.returncode})",
+                file=sys.stderr,
+            )
+            return result.returncode
+
+    print(f"{_MODULE_NAME}: module installed successfully")
+    return 0
+
+
+def _is_installed() -> bool:
+    """Check whether the sysrepo-python-plugind YANG module is installed.
+
+    Runs ``sysrepoctl --list`` and searches the output for the module name.
+
+    Returns:
+        bool: True if the module appears in ``sysrepoctl`` output, False
+            otherwise or if ``sysrepoctl`` itself fails.
+    """
+    result = subprocess.run(
+        ["sysrepoctl", "--list"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return _MODULE_NAME in result.stdout

sysrepo_python_plugind/pid.py

@@ -0,0 +1,92 @@
+# Copyright (c) 2026 EntryPoint Communications, LLC
+# SPDX-License-Identifier: BSD-3-Clause
+
+import fcntl
+import logging
+import os
+
+LOG = logging.getLogger(__name__)
+
+
+class PidFile:
+    """POSIX PID file with exclusive advisory lock.
+
+    Matches the C sysrepo-plugind behaviour:
+
+    - Open and lock **before** daemonizing so a second invocation fails
+      immediately, even before the first instance writes its PID.
+    - :meth:`write` is called **after** plugins have initialised so the
+      file contains the daemonized child's PID, not the parent's.
+    - On exit the file is closed and unlinked.
+
+    Args:
+        path (str): Filesystem path for the PID file.
+
+    Example::
+
+        with PidFile("/run/sysrepo-python-plugind.pid") as pid_file:
+            _daemonize()
+            # ... init plugins ...
+            pid_file.write()
+    """
+
+    __slots__ = ("path", "_fd")
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+        self._fd: int | None = None
+
+    def __enter__(self) -> "PidFile":
+        """Open and exclusively lock the PID file.
+
+        Returns:
+            PidFile: self, for use as a context manager.
+
+        Raises:
+            RuntimeError: If the exclusive lock cannot be acquired because
+                another instance of the daemon already holds it.
+        """
+        self._fd = os.open(self.path, os.O_RDWR | os.O_CREAT, 0o640)
+        try:
+            fcntl.lockf(self._fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError as exc:
+            os.close(self._fd)
+            self._fd = None
+            raise RuntimeError(
+                f"another sysrepo-python-plugind instance is running "
+                f"(cannot lock {self.path})"
+            ) from exc
+        return self
+
+    def write(self) -> None:
+        """Write the current process PID to the file.
+
+        Truncates any existing content before writing so the file always
+        contains exactly one line.  Should be called after daemonizing so
+        the written PID belongs to the final child process, not the
+        pre-fork parent.
+        """
+        if self._fd is None:
+            return
+        pid_bytes = f"{os.getpid()}\n".encode()
+        os.ftruncate(self._fd, 0)
+        os.lseek(self._fd, 0, os.SEEK_SET)
+        os.write(self._fd, pid_bytes)
+        LOG.debug("wrote PID %d to %s", os.getpid(), self.path)
+
+    def __exit__(self, *_) -> None:
+        """Close and unlink the PID file.
+
+        Silently ignores FileNotFoundError in case the file was already
+        removed externally.
+
+        Args:
+            *_: Exception info from the ``with`` block; not used.
+        """
+        if self._fd is not None:
+            os.close(self._fd)
+            self._fd = None
+        try:
+            os.unlink(self.path)
+        except FileNotFoundError:
+            pass

sysrepo_python_plugind/plugin.py

@@ -0,0 +1,56 @@
+# Copyright (c) 2026 EntryPoint Communications, LLC
+# SPDX-License-Identifier: BSD-3-Clause
+
+from abc import ABC, abstractmethod
+
+import sysrepo
+
+
+class SysrepoPlugin(ABC):
+    """Abstract base class for sysrepo Python plugins.
+
+    Plugins are discovered by sysrepo-python-plugind via the
+    ``sysrepo_python.plugins`` entry point group.  Declare a plugin in
+    your package's ``pyproject.toml``::
+
+        [project.entry-points."sysrepo_python.plugins"]
+        my-plugin = "my_package.plugin:MyPlugin"
+
+    The daemon instantiates the class with no arguments, calls
+    :meth:`init` at startup (after plugin ordering), and :meth:`cleanup`
+    at shutdown in reverse init order.  State that the C daemon stored in
+    ``void *private_data`` should be stored as instance attributes.
+    """
+
+    @abstractmethod
+    def init(self, session: sysrepo.session.SysrepoSession) -> None:
+        """Initialise the plugin at daemon startup.
+
+        Called once after plugin ordering and before ``sd_notify("READY=1")``.
+        Register sysrepo subscriptions and allocate resources here.  The
+        session is on ``SR_DS_RUNNING`` and is shared with all other plugins.
+
+        Args:
+            session (sysrepo.session.SysrepoSession): Active running-datastore
+                session shared across all plugins.
+
+        Raises:
+            Exception: Signals rejection of this plugin.  With
+                ``--fatal-plugin-fail`` the daemon exits; otherwise this
+                plugin is skipped and the next one is attempted.
+        """
+
+    def cleanup(self, session: sysrepo.session.SysrepoSession) -> None:
+        """Clean up plugin resources at daemon shutdown.
+
+        Called once in reverse init order after a stop signal is received.
+        Sysrepo subscriptions created on the session are automatically
+        released when the session closes, so this method only needs to
+        release external resources (file handles, network connections, etc.).
+
+        The default implementation does nothing.
+
+        Args:
+            session (sysrepo.session.SysrepoSession): Active running-datastore
+                session shared across all plugins.
+        """

sysrepo_python_plugind/sort.py

@@ -0,0 +1,91 @@
+# Copyright (c) 2026 EntryPoint Communications, LLC
+# SPDX-License-Identifier: BSD-3-Clause
+
+import logging
+from typing import TYPE_CHECKING
+
+import sysrepo
+
+if TYPE_CHECKING:
+    from .plugin import SysrepoPlugin
+
+LOG = logging.getLogger(__name__)
+
+_ORDER_XPATH = (
+    "/sysrepo-plugind:sysrepo-plugind"
+    "/sysrepo-python-plugind:python-plugin-order/plugin"
+)
+
+# Type alias for the (entry-point-name, instance) pairs the daemon works with.
+PluginList = list[tuple[str, "SysrepoPlugin"]]
+
+
+def sort_plugins(session: sysrepo.session.SysrepoSession, plugins: PluginList) -> PluginList:
+    """Reorder plugins according to the operator-configured plugin order.
+
+    Reads the ``python-plugin-order`` leaf-list from the sysrepo running
+    datastore and performs a stable partition: configured plugins are moved
+    to the front in YANG list order; unconfigured plugins retain their
+    original discovery order at the end.
+
+    Mirrors ``srpd_sort_plugins()`` from
+    ``sysrepo/src/executables/srpd_common.c``.
+
+    Args:
+        session (sysrepo.session.SysrepoSession): Active running-datastore session
+            used to read the python-plugin-order configuration.
+        plugins (PluginList): Discovered (entry-point-name, instance) pairs
+            in discovery order.  The input list is not modified.
+
+    Returns:
+        PluginList: Reordered (entry-point-name, instance) pairs.
+            Configured plugins appear first in YANG list order; remaining
+            plugins follow in their original discovery order.
+
+    Raises:
+        sysrepo.SysrepoNotFoundError: Caught internally when no
+            plugin-order is configured; treated as an empty list and the
+            original order is returned unchanged.
+    """
+    try:
+        # String(Value, str) — each item IS a Python str already.
+        configured = [_strip_ext(v) for v in session.get_items(_ORDER_XPATH)]
+    except sysrepo.SysrepoNotFoundError:
+        LOG.debug("no plugin-order configured, using discovery order")
+        return plugins
+
+    if not configured:
+        return plugins
+
+    LOG.debug("plugin-order from sysrepo: %s", configured)
+
+    ordered: PluginList = []
+    remaining = list(plugins)
+
+    for cfg_name in configured:
+        for i, (ep_name, inst) in enumerate(remaining):
+            if _strip_ext(ep_name) == cfg_name:
+                ordered.append(remaining.pop(i))
+                LOG.debug("placed plugin %r at position %d", ep_name, len(ordered))
+                break
+        # cfg_name not found among loaded plugins — ignore, per C implementation.
+
+    return ordered + remaining
+
+
+def _strip_ext(name: str) -> str:
+    """Strip the last file extension from a plugin name, if any.
+
+    Used to normalise operator-configured names (e.g. ``'my_plugin.so'``)
+    to match Python entry-point names (e.g. ``'my_plugin'``), preserving
+    compatibility with operator configs written for the C daemon.
+
+    Args:
+        name (str): Plugin name, optionally including a file extension.
+
+    Returns:
+        str: Name with the last dot-suffix removed, or the original name
+            if no dot is present.
+    """
+    dot = name.rfind(".")
+    return name[:dot] if dot >= 0 else name

sysrepo_python_plugind/yang/sysrepo-python-plugind.yang

@@ -0,0 +1,54 @@
+module sysrepo-python-plugind {
+  yang-version 1.1;
+  namespace "urn:sysrepo:python-plugind";
+  prefix srpdpy;
+
+  import sysrepo-plugind {
+    prefix srpd;
+    revision-date 2022-08-26;
+  }
+
+  organization "sysrepo-python-plugind contributors";
+  description
+    "Augments sysrepo-plugind with Python-daemon-specific configuration
+     and state nodes.  This allows the Python daemon and the C daemon to
+     coexist: each manages only its own subtree and neither overwrites the
+     other's operational data.";
+
+  revision 2026-05-13 {
+    description "Initial revision.";
+    reference "https://github.com/...";
+  }
+
+  augment "/srpd:sysrepo-plugind" {
+    description "Python-daemon plugin ordering and loaded-plugin state.";
+
+    container python-plugin-order {
+      description
+        "Ordered list of Python plugin entry-point names.  Mirrors
+         plugin-order from the base module but applies only to the
+         Python daemon.";
+      leaf-list plugin {
+        type string;
+        ordered-by user;
+        description
+          "Entry-point name of a Python plugin.  A trailing file
+           extension (e.g. '.so') is stripped before comparison,
+           preserving compatibility with operator configs written for
+           the C daemon.";
+      }
+    }
+
+    container python-loaded-plugins {
+      config false;
+      description
+        "Names of Python plugins successfully initialised by the running
+         Python daemon.  Written to the operational datastore after all
+         plugins have been initialised.";
+      leaf-list plugin {
+        type string;
+        description "Entry-point name of a loaded Python plugin.";
+      }
+    }
+  }
+}

sysrepo_python_plugind-1.0.0.dist-info/METADATA

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: sysrepo-python-plugind
+Version: 1.0.0
+Summary: Python plugin daemon for sysrepo (replacement for sysrepo-plugind)
+License-Expression: BSD-3-Clause
+Project-URL: Repository, https://github.com/entrypoint-communications/sysrepo-python-plugind
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: sysrepo~=2.0
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+sysrepo-python-plugind
+======================
+
+A Python reimplementation of ``sysrepo-plugind`` — the sysrepo plugin daemon.
+
+The C daemon loads compiled ``.so`` plugins via ``dlopen``.  This daemon loads
+**Python plugins** discovered via entry points (``importlib.metadata``), giving
+plugin authors a pure-Python development experience against the existing
+`sysrepo-python`_ CFFI bindings.
+
+The two daemons can run **simultaneously**: the Python daemon manages its own
+YANG subtree (``python-plugin-order``, ``python-loaded-plugins``) and never
+touches the C daemon's nodes.
+
+.. _sysrepo-python: https://github.com/sysrepo/sysrepo-python
+
+
+Requirements
+------------
+
+- Python ≥ 3.10
+- sysrepo-python_ (and the underlying ``libsysrepo.so``)
+- sysrepo core 4.2.10 (ships ``sysrepo-plugind@2022-08-26.yang``)
+
+
+Installation
+------------
+
+.. code-block:: console
+
+   pip install sysrepo-python-plugind
+
+Then register the YANG augmentation module with sysrepo (requires write
+access to the sysrepo repository, typically run as root):
+
+.. code-block:: console
+
+   sysrepo-python-plugind-setup
+
+This is idempotent — safe to run on every deployment or system boot.  Pass
+``--force`` to upgrade the module after a package update.
+
+
+Writing a plugin
+----------------
+
+Subclass ``SysrepoPlugin`` and implement ``init()``.  Register the class via
+an entry point in your package's ``pyproject.toml``:
+
+.. code-block:: toml
+
+   [project.entry-points."sysrepo_python.plugins"]
+   my-plugin = "my_package.plugin:MyPlugin"
+
+Installing your package makes the plugin visible to the daemon immediately —
+no copying of files or environment variables required.
+
+Minimal example:
+
+.. code-block:: python
+
+   import logging
+   import sysrepo
+   from sysrepo_python_plugind import SysrepoPlugin
+
+   LOG = logging.getLogger(__name__)
+
+   class MyPlugin(SysrepoPlugin):
+
+       def init(self, session: sysrepo.SysrepoSession) -> None:
+           self._counter = 0
+           session.subscribe_module_change(
+               "my-module", None, self._on_change, done_only=True
+           )
+           session.subscribe_oper_data_request(
+               "my-module", "/my-module:stats", self._on_oper
+           )
+           LOG.info("MyPlugin ready")
+
+       def cleanup(self, session: sysrepo.SysrepoSession) -> None:
+           LOG.info("MyPlugin stopping (counter=%d)", self._counter)
+
+       def _on_change(self, event, req_id, changes, priv):
+           self._counter += 1
+
+       def _on_oper(self, xpath, priv):
+           return {"my-module": {"stats": {"change-count": self._counter}}}
+
+State that the C daemon stored in ``void *private_data`` is stored as instance
+attributes (``self._counter`` above).
+
+Async callbacks
+~~~~~~~~~~~~~~~
+
+The daemon starts an asyncio event loop in a background thread before calling
+any ``init()``, so plugins can use ``asyncio_register=True`` subscriptions
+without managing a loop themselves:
+
+.. code-block:: python
+
+   class AsyncMyPlugin(SysrepoPlugin):
+
+       def init(self, session: sysrepo.SysrepoSession) -> None:
+           session.subscribe_module_change(
+               "my-module", None, self._on_change,
+               done_only=True, asyncio_register=True,
+           )
+
+       async def _on_change(self, event, req_id, changes, priv):
+           ...
+
+
+Running the daemon
+------------------
+
+.. code-block:: console
+
+   # Foreground, INFO-level logging to stderr:
+   sysrepo-python-plugind -d -v 2
+
+   # Background (daemonize), write PID file:
+   sysrepo-python-plugind -p /run/sysrepo-python-plugind.pid
+
+CLI flags mirror those of the C ``sysrepo-plugind``:
+
+============  ===================================================================
+``-d``        Stay in foreground; log to stderr instead of syslog
+``-v LEVEL``  Verbosity: 0=ERROR 1=WARNING 2=INFO 3=DEBUG (default: 2)
+``-p PATH``   Write PID file at PATH
+``-f``        Exit if any plugin fails to initialise (default: skip and continue)
+============  ===================================================================
+
+
+Plugin ordering
+---------------
+
+By default plugins are initialised in entry-point discovery order.  To
+override this, set the ``python-plugin-order`` leaf-list in sysrepo's running
+datastore:
+
+.. code-block:: console
+
+   sysrepocfg -d running --edit
+
+Add under ``/sysrepo-plugind:sysrepo-plugind``:
+
+.. code-block:: xml
+
+   <python-plugin-order xmlns="urn:sysrepo:python-plugind">
+     <plugin>my-plugin</plugin>
+     <plugin>other-plugin</plugin>
+   </python-plugin-order>
+
+Plugins absent from the list are appended after the ordered set, preserving
+their discovery order.  A trailing file extension in a configured name (e.g.
+``my-plugin.so``) is stripped before comparison, so operator configs written
+for the C daemon can be reused unchanged.
+
+The list of successfully initialised plugins is published to the operational
+datastore at ``/sysrepo-plugind:sysrepo-plugind/sysrepo-python-plugind:python-loaded-plugins/plugin``.
+
+
+Systemd deployment
+------------------
+
+A service file is provided in the ``systemd/`` directory of the source
+distribution:
+
+.. code-block:: console
+
+   cp systemd/sysrepo-python-plugind.service /etc/systemd/system/
+   systemctl daemon-reload
+   systemctl enable --now sysrepo-python-plugind
+
+The service runs ``sysrepo-python-plugind-setup`` as ``ExecStartPre=``,
+ensuring the YANG module is present before the daemon starts.
+
+If the daemon binary is not at ``/usr/bin/sysrepo-python-plugind`` (e.g. when
+installed into a virtual environment), update the ``ExecStartPre=`` and
+``ExecStart=`` paths in the service file accordingly.
+
+
+License
+-------
+
+BSD-3-Clause — same as sysrepo-python.

sysrepo_python_plugind-1.0.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+sysrepo_python_plugind/__init__.py,sha256=Lo3hxrcCQPfchf5mEglwlR9hrNdGsSDB68wkujX3nIo,414
+sysrepo_python_plugind/__main__.py,sha256=nW9n-CT29lx3_sAo84sNy9AiAejptM5XvSvkLmZJisU,145
+sysrepo_python_plugind/cli.py,sha256=_uqqNqscJH2jrsFE5EmBPFicU_Ea1OFv6JUxJSxu_M8,4625
+sysrepo_python_plugind/daemon.py,sha256=akOafUkE2XugFQ1xkzRymDwAdaG0sTtnbfTJdBm5x8w,11217
+sysrepo_python_plugind/install_yang.py,sha256=hT7i0qfBvL9DzeRrwElWWfPSL_66X7tW6NtxxZGUDaI,2543
+sysrepo_python_plugind/pid.py,sha256=lpgatUUZUZcFm_ik8EJsZ0MqnPwvd_O4euPOrASGEa8,2826
+sysrepo_python_plugind/plugin.py,sha256=SL8D5LX-MBObvARYTcAiO4L6GJsiAmKzvSNt-HwFVEc,2175
+sysrepo_python_plugind/sort.py,sha256=W-uTeqHwHCnVjWYg-mm23QuX7ZLKffo3TOfm29stVd4,3198
+sysrepo_python_plugind/yang/sysrepo-python-plugind.yang,sha256=R122VcgpoZ4jlcaS384ts06Pfr6M70ATGpadk8nrpjg,1673
+sysrepo_python_plugind-1.0.0.dist-info/licenses/LICENSE,sha256=Ci_I22dLniZTPKK9Q_l2vbAzwhnKXjFltyD-AE_T9wI,1516
+sysrepo_python_plugind-1.0.0.dist-info/METADATA,sha256=C2TLhu6KOyb9uyYfOViRvc3W4L2sTPKyTSsYfU2hQZs,6106
+sysrepo_python_plugind-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sysrepo_python_plugind-1.0.0.dist-info/entry_points.txt,sha256=VuJTp-tPelbpAFCeyasniST9I-jgn6zrdc89Vb43ONY,143
+sysrepo_python_plugind-1.0.0.dist-info/top_level.txt,sha256=k8eY3OJSeYlfOuhzyjr2dSOSGBVp5GgnAHqec-IOtAE,23
+sysrepo_python_plugind-1.0.0.dist-info/RECORD,,

sysrepo_python_plugind-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sysrepo_python_plugind-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+sysrepo-python-plugind = sysrepo_python_plugind:main
+sysrepo-python-plugind-setup = sysrepo_python_plugind.install_yang:main

sysrepo_python_plugind-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026 EntryPoint Communications, LLC
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

sysrepo_python_plugind-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sysrepo_python_plugind