Merge sedsprintf_rs upstream main

Author: Rylan-Meilutis

sedsprintf_rs/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sedsprintf_rs_2026"
-version = "1.0.6"
+version = "1.0.8"
 edition = "2024"
 build = "build.rs"
 authors = ["Rylan Meilutis <[email protected]>"]

sedsprintf_rs/header_templates/sedsprintf_rs.pyi.txt

@@ -96,6 +96,26 @@ class Router:
                     serialized_handler: Optional[Callable[[bytes], None]])
     """
 
+    @staticmethod
+    def new_singleton(tx: Optional[TxCallback] = ...,
+            now_ms: Optional[NowMsCallback] = ...,
+            handlers: Optional[
+                Sequence[Tuple[int, Optional[PacketHandler], Optional[SerializedHandler]]]
+            ] = ...,
+        ) -> "Router":
+        """
+        Create or retrieve a per-process singleton Router.
+
+        The first call creates the singleton with the given `tx` callback
+        (no clock and no endpoint handlers). Subsequent calls return another
+        Router object wrapping the same underlying singleton instance.
+
+        Passing a non-None `tx` after the singleton has already been created
+        will raise a RuntimeError.
+        """
+        ...
+
+
     def __init__(
         self,
         tx: Optional[TxCallback] = ...,

sedsprintf_rs/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "sedsprintf_rs_2026"
-version = "1.0.6"
+version = "1.0.8"
 description = "Rust telemetry and serialization library"
 authors = [{ name = "Rylan Meilutis", email = "[email protected]" }]
 readme = "README.md"

sedsprintf_rs/src/python_api.rs

@@ -26,7 +26,7 @@ use alloc::{boxed::Box, string::String, sync::Arc as AArc, vec::Vec};
 use pyo3::exceptions::{PyRuntimeError, PyValueError};
 use pyo3::prelude::*;
 use pyo3::types::{PyBytes, PyDict, PyList, PyModule, PyTuple};
-use std::sync::{Arc as SArc, Mutex};
+use std::sync::{Arc as SArc, Mutex, OnceLock};
 
 use crate::{
     config::DataEndpoint, get_needed_message_size, message_meta, router::{BoardConfig, Clock, EndpointHandler, LeBytes, Router},
@@ -39,6 +39,8 @@ use crate::{
     MAX_VALUE_DATA_TYPE,
 };
 
+static GLOBAL_ROUTER_SINGLETON: OnceLock<SArc<Mutex<Router>>> = OnceLock::new();
+
 // ============================================================================
 //  Shared helpers / constants
 // ============================================================================
@@ -218,6 +220,170 @@ pub struct PyRouter {
 
 #[pymethods]
 impl PyRouter {
+    // ------------------------------------------------------------------------
+    //  Singleton construction
+    // ------------------------------------------------------------------------
+
+    /// Create or retrieve a per-process singleton Router.
+    ///
+    /// This creates a Router with:
+    ///   - no clock (timestamp=0 unless you pass explicit timestamps),
+    ///   - no endpoint handlers,
+    ///   - an optional TX callback.
+    ///
+    /// The first call initializes the singleton. Subsequent calls return
+    /// another `PyRouter` object wrapping the same underlying Router.
+    ///
+    /// If you pass a non-None `tx` after the singleton is already created,
+    /// an error is raised (the TX callback cannot be changed once set).
+    #[staticmethod]
+    #[pyo3(signature = (tx=None, now_ms=None, handlers=None))]
+    fn new_singleton(
+        py: Python<'_>,
+        tx: Option<Py<PyAny>>,
+        now_ms: Option<Py<PyAny>>,
+        handlers: Option<&Bound<'_, PyAny>>,
+    ) -> PyResult<Self> {
+        // ----------------------------------------------------------
+        // 1. If the singleton already exists, return a new wrapper
+        // ----------------------------------------------------------
+        if let Some(existing) = GLOBAL_ROUTER_SINGLETON.get() {
+            // Prevent changing TX / clock / handlers after initialized
+            if tx.is_some() || now_ms.is_some() || handlers.is_some() {
+                return Err(PyRuntimeError::new_err(
+                    "Router singleton already exists; cannot modify tx/now_ms/handlers",
+                ));
+            }
+
+            return Ok(PyRouter {
+                inner: existing.clone(),
+                _tx_cb: None,
+                _pkt_cbs: Vec::new(),
+                _ser_cbs: Vec::new(),
+            });
+        }
+
+        // ----------------------------------------------------------
+        // 2. FIRST CALL — build the whole router (same as __init__)
+        // ----------------------------------------------------------
+
+        // Copy callbacks to keep them alive
+        let tx_keep = tx.as_ref().map(|p| p.clone_ref(py));
+        let now_keep = now_ms.as_ref().map(|p| p.clone_ref(py));
+
+        // Build transmit callback
+        let tx_for_closure = tx_keep.as_ref().map(|p| p.clone_ref(py));
+        let transmit = if let Some(cb) = tx_for_closure {
+            Some(move |bytes: &[u8]| -> TelemetryResult<()> {
+                Python::attach(|py| {
+                    let arg = PyBytes::new(py, bytes);
+                    match cb.call1(py, (&arg,)) {
+                        Ok(_) => Ok(()),
+                        Err(err) => {
+                            err.restore(py);
+                            Err(TelemetryError::Io("tx error"))
+                        }
+                    }
+                })
+            })
+        } else {
+            None
+        };
+
+        // Build endpoint handlers (same as __init__)
+        let mut handlers_vec = Vec::new();
+        let mut keep_pkt = Vec::new();
+        let mut keep_ser = Vec::new();
+
+        if let Some(hs) = handlers {
+            let list = hs.cast::<PyList>().map_err(|_| {
+                PyValueError::new_err("handlers must be list of (endpoint, pkt_cb, ser_cb) tuples")
+            })?;
+
+            for item in list.iter() {
+                let tup = item
+                    .cast::<PyTuple>()
+                    .map_err(|_| PyValueError::new_err("handler must be a 3-tuple"))?;
+                if tup.len() != 3 {
+                    return Err(PyValueError::new_err("tuple arity must be 3"));
+                }
+
+                let ep_u32: u32 = tup.get_item(0)?.extract()?;
+                let endpoint = endpoint_from_u32(ep_u32).map_err(py_err_from)?;
+
+                // Packet handler
+                if !tup.get_item(1)?.is_none() {
+                    let cb: Py<PyAny> = tup.get_item(1)?.extract()?;
+                    let cb_for_closure = cb.clone_ref(py);
+                    keep_pkt.push(cb);
+
+                    let eh = EndpointHandler::new_packet_handler(endpoint, move |pkt| {
+                        Python::attach(|py| {
+                            let py_pkt = PyPacket { inner: pkt.clone() };
+                            let any = Py::new(py, py_pkt)
+                                .map_err(|_| TelemetryError::Io("packet wrapper"))?;
+                            match cb_for_closure.call1(py, (&any,)) {
+                                Ok(_) => Ok(()),
+                                Err(err) => {
+                                    err.restore(py);
+                                    Err(TelemetryError::Io("packet handler error"))
+                                }
+                            }
+                        })
+                    });
+
+                    handlers_vec.push(eh);
+                }
+
+                // Serialized handler
+                if !tup.get_item(2)?.is_none() {
+                    let cb: Py<PyAny> = tup.get_item(2)?.extract()?;
+                    let cb_for_closure = cb.clone_ref(py);
+                    keep_ser.push(cb);
+
+                    let eh = EndpointHandler::new_serialized_handler(endpoint, move |bytes| {
+                        Python::attach(|py| {
+                            let arg = PyBytes::new(py, bytes);
+                            match cb_for_closure.call1(py, (&arg,)) {
+                                Ok(_) => Ok(()),
+                                Err(err) => {
+                                    err.restore(py);
+                                    Err(TelemetryError::Io("serialized handler error"))
+                                }
+                            }
+                        })
+                    });
+
+                    handlers_vec.push(eh);
+                }
+            }
+        }
+
+        // Build clock callback
+        let clock = PyClock {
+            cb: now_keep.as_ref().map(|p| p.clone_ref(py)),
+        };
+
+        // Build router
+        let cfg = BoardConfig::new(handlers_vec);
+        let router = Router::new(transmit, cfg, Box::new(clock));
+
+        let arc = SArc::new(Mutex::new(router));
+
+        // Store it into OnceLock
+        GLOBAL_ROUTER_SINGLETON
+            .set(arc.clone())
+            .map_err(|_existing| PyRuntimeError::new_err("Router singleton already exists"))?;
+
+        // Return wrapper
+        Ok(PyRouter {
+            inner: arc,
+            _tx_cb: tx_keep,
+            _pkt_cbs: keep_pkt,
+            _ser_cbs: keep_ser,
+        })
+    }
+
     /// Create a new router.
     ///
     /// Parameters