sysrepo-python-plugind 1.0.0__tar.gz

sysrepo_python_plugind-1.0.0/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/PKG-INFO

@@ -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/README.rst

@@ -0,0 +1,186 @@
+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/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sysrepo-python-plugind"
+version = "1.0.0"
+description = "Python plugin daemon for sysrepo (replacement for sysrepo-plugind)"
+readme = "README.rst"
+license = "BSD-3-Clause"
+requires-python = ">=3.10"
+dependencies = ["sysrepo~=2.0"]
+
+[project.scripts]
+sysrepo-python-plugind = "sysrepo_python_plugind:main"
+sysrepo-python-plugind-setup = "sysrepo_python_plugind.install_yang:main"
+
+[project.urls]
+Repository = "https://github.com/entrypoint-communications/sysrepo-python-plugind"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+sysrepo_python_plugind = ["yang/*.yang"]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

sysrepo_python_plugind-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sysrepo_python_plugind-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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)