sds-library 0.6.0__py3-none-any.whl

sds/__init__.py

@@ -0,0 +1,159 @@
+"""
+SDS (Synchronized Data Structures) Python Library
+
+A Pythonic interface for IoT state synchronization over MQTT.
+This is a wrapper around the SDS C library using CFFI.
+
+Example usage:
+    >>> from sds import SdsNode, Role, Field, FieldType
+    >>> from dataclasses import dataclass
+    >>>
+    >>> @dataclass
+    ... class SensorState:
+    ...     temperature: float = Field(float32=True)
+    ...     humidity: float = Field(float32=True)
+    >>>
+    >>> with SdsNode("sensor_01", "localhost") as node:
+    ...     table = node.register_table(
+    ...         "SensorData", Role.DEVICE,
+    ...         state_schema=SensorState,
+    ...     )
+    ...
+    ...     # C-like attribute access
+    ...     table.state.temperature = 23.5
+    ...     table.state.humidity = 65.0
+    ...
+    ...     while True:
+    ...         node.poll(timeout_ms=1000)
+"""
+
+import logging as _logging_std
+
+__version__ = "0.6.0"
+__author__ = "SDS Team"
+
+# Core classes
+# Logging configuration
+from sds._logging import configure_logging
+
+# Enums
+# Exceptions
+from sds._types import (
+    ErrorCode,
+    LogLevel,
+    Role,
+    SdsAlreadyInitializedError,
+    SdsCapacityError,
+    SdsConfigError,
+    SdsError,
+    SdsMqttError,
+    SdsNotInitializedError,
+    SdsPlatformError,
+    SdsTableError,
+    SdsValidationError,
+    check_error,
+)
+from sds.node import SdsNode
+from sds.table import DeviceView, SdsTable, SectionProxy
+
+# Table helpers
+from sds.tables import Field, FieldType
+
+# Public API
+__all__ = [
+    # Version
+    "__version__",
+
+    # Core classes
+    "SdsNode",
+    "SdsTable",
+    "SectionProxy",
+    "DeviceView",
+
+    # Enums
+    "Role",
+    "ErrorCode",
+    "LogLevel",
+
+    # Exceptions
+    "SdsError",
+    "SdsNotInitializedError",
+    "SdsAlreadyInitializedError",
+    "SdsConfigError",
+    "SdsMqttError",
+    "SdsTableError",
+    "SdsCapacityError",
+    "SdsPlatformError",
+    "SdsValidationError",
+    "check_error",
+
+    # Table helpers
+    "Field",
+    "FieldType",
+
+    # Utility functions
+    "get_version",
+    "get_c_library_version",
+    "set_log_level",
+    "get_log_level",
+    "configure_logging",
+]
+
+
+def get_version() -> str:
+    """Get the SDS Python library version."""
+    return __version__
+
+
+def get_c_library_version() -> str:
+    """
+    Get the SDS C library version.
+
+    The pure-Python backend does not link the C library; this reports the
+    optional CFFI extension when present.
+    """
+    try:
+        from sds._bindings import lib  # noqa: F401
+        return "1.0.0"
+    except Exception:
+        return "unknown (extension not built)"
+
+
+# Runtime log level for the pure-Python backend. Mapped onto the "sds" logger
+# so it composes with standard logging configuration.
+_LOGLEVEL_TO_PY = {
+    LogLevel.NONE: _logging_std.CRITICAL + 10,
+    LogLevel.ERROR: _logging_std.ERROR,
+    LogLevel.WARN: _logging_std.WARNING,
+    LogLevel.INFO: _logging_std.INFO,
+    LogLevel.DEBUG: _logging_std.DEBUG,
+}
+_current_log_level: LogLevel = LogLevel.WARN
+
+
+def set_log_level(level: LogLevel) -> None:
+    """
+    Set the runtime log level.
+
+    Controls which SDS log messages are output. Can be called at any time,
+    even before creating an SdsNode.
+
+    Example:
+        >>> from sds import set_log_level, LogLevel
+        >>> set_log_level(LogLevel.DEBUG)  # Enable all logs
+        >>> set_log_level(LogLevel.NONE)   # Disable all logs
+    """
+    global _current_log_level
+    level = LogLevel(level)
+    _current_log_level = level
+    _logging_std.getLogger("sds").setLevel(_LOGLEVEL_TO_PY[level])
+
+
+def get_log_level() -> LogLevel:
+    """
+    Get the current runtime log level.
+
+    Returns:
+        The current log level
+    """
+    return _current_log_level

sds/_bindings.py

@@ -0,0 +1,96 @@
+"""
+Low-level CFFI bindings for the SDS library.
+
+This module provides direct access to the C library functions.
+Most users should use the higher-level sds.SdsNode class instead.
+"""
+from __future__ import annotations
+
+# Try to import the compiled CFFI extension
+try:
+    from sds._sds_cffi import ffi, lib
+except ImportError as e:
+    # Provide helpful error message
+    raise ImportError(
+        "SDS CFFI extension not found. Please build the extension first:\n"
+        "  cd python && pip install -e .\n"
+        "or:\n"
+        "  cd python && python sds/_build_ffi.py\n"
+        f"Original error: {e}"
+    ) from e
+
+
+# Re-export ffi and lib for direct access
+__all__ = [
+    "ffi",
+    "lib",
+    "SdsErrorCode",
+    "SdsRoleCode",
+    "encode_string",
+    "decode_string",
+]
+
+
+class SdsErrorCode:
+    """Error code constants from the C library."""
+
+    OK = lib.SDS_OK
+    NOT_INITIALIZED = lib.SDS_ERR_NOT_INITIALIZED
+    ALREADY_INITIALIZED = lib.SDS_ERR_ALREADY_INITIALIZED
+    INVALID_CONFIG = lib.SDS_ERR_INVALID_CONFIG
+    MQTT_CONNECT_FAILED = lib.SDS_ERR_MQTT_CONNECT_FAILED
+    MQTT_DISCONNECTED = lib.SDS_ERR_MQTT_DISCONNECTED
+    TABLE_NOT_FOUND = lib.SDS_ERR_TABLE_NOT_FOUND
+    TABLE_ALREADY_REGISTERED = lib.SDS_ERR_TABLE_ALREADY_REGISTERED
+    MAX_TABLES_REACHED = lib.SDS_ERR_MAX_TABLES_REACHED
+    INVALID_TABLE = lib.SDS_ERR_INVALID_TABLE
+    INVALID_ROLE = lib.SDS_ERR_INVALID_ROLE
+    OWNER_EXISTS = lib.SDS_ERR_OWNER_EXISTS
+    MAX_NODES_REACHED = lib.SDS_ERR_MAX_NODES_REACHED
+    BUFFER_FULL = lib.SDS_ERR_BUFFER_FULL
+    SECTION_TOO_LARGE = lib.SDS_ERR_SECTION_TOO_LARGE
+    PLATFORM_NOT_SET = lib.SDS_ERR_PLATFORM_NOT_SET
+    PLATFORM_ERROR = lib.SDS_ERR_PLATFORM_ERROR
+
+
+class SdsRoleCode:
+    """Role code constants from the C library."""
+
+    OWNER = lib.SDS_ROLE_OWNER
+    DEVICE = lib.SDS_ROLE_DEVICE
+
+
+def encode_string(s: str | None) -> bytes | ffi.CData:
+    """
+    Encode a Python string to a C string (char*).
+
+    Args:
+        s: Python string or None
+
+    Returns:
+        C string (ffi.new("char[]")) or ffi.NULL if input is None
+    """
+    if s is None:
+        return ffi.NULL
+    return s.encode("utf-8")
+
+
+def decode_string(c_str: ffi.CData) -> str | None:
+    """
+    Decode a C string (char*) to a Python string.
+
+    Args:
+        c_str: C string pointer
+
+    Returns:
+        Python string or None if pointer is NULL
+    """
+    if c_str == ffi.NULL:
+        return None
+    return ffi.string(c_str).decode("utf-8")
+
+
+def get_error_string(error_code: int) -> str:
+    """Get human-readable error message for an error code."""
+    c_str = lib.sds_error_string(error_code)
+    return decode_string(c_str) or f"Unknown error ({error_code})"

sds/_build_ffi.py

@@ -0,0 +1,144 @@
+"""
+CFFI build script for SDS library bindings.
+
+This script is used by setup.py to compile the CFFI extension.
+It can also be run directly to build the extension in-place.
+"""
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from cffi import FFI
+
+# Find the project root (parent of python/)
+# Use resolve() to get absolute paths
+PYTHON_DIR = Path(__file__).resolve().parent.parent
+PROJECT_ROOT = PYTHON_DIR.parent
+
+# Paths to C sources
+INCLUDE_DIR = PROJECT_ROOT / "include"
+SRC_DIR = PROJECT_ROOT / "src"
+PLATFORM_DIR = PROJECT_ROOT / "platform"
+
+print("Building CFFI extension with:")
+print(f"  PROJECT_ROOT: {PROJECT_ROOT}")
+print(f"  INCLUDE_DIR: {INCLUDE_DIR}")
+print(f"  SRC_DIR: {SRC_DIR}")
+
+ffibuilder = FFI()
+
+# Read the C definitions
+cdefs_path = Path(__file__).parent / "_cdefs.h"
+with open(cdefs_path, "r") as f:
+    cdefs = f.read()
+
+ffibuilder.cdef(cdefs)
+
+# Source code to compile - we'll compile the C library directly into the extension
+# Include sds_types.h to get the auto-registered table metadata (SensorData, ActuatorData, etc.)
+# Include sds_platform.h for log level types and functions
+source_code = """
+#include "sds.h"
+#include "sds_json.h"
+#include "sds_error.h"
+#include "sds_platform.h"  /* For SdsLogLevel, sds_set_log_level, sds_get_log_level */
+#include "sds_types.h"  /* Generated types - auto-registers via constructor */
+"""
+
+# Get include directories and source files
+include_dirs = [str(INCLUDE_DIR)]
+library_dirs = []
+sources = []
+
+# For setuptools, we need relative paths from python/ directory
+# But for the compiler, we need include paths to be absolute
+def make_relative_source(path):
+    """Convert absolute path to relative from python/ directory."""
+    return os.path.relpath(str(path), str(PYTHON_DIR))
+
+# Add all C source files
+for src_file in SRC_DIR.glob("*.c"):
+    sources.append(make_relative_source(src_file))
+
+# Add platform implementation (POSIX for macOS/Linux)
+platform_posix_c = PLATFORM_DIR / "posix" / "sds_platform_posix.c"
+if platform_posix_c.exists():
+    sources.append(make_relative_source(platform_posix_c))
+    print(f"Using POSIX platform: {platform_posix_c}")
+else:
+    print(f"Warning: Platform implementation not found at {platform_posix_c}")
+
+# Platform-specific library paths
+# The POSIX platform uses Paho MQTT C library (paho-mqtt3c)
+libraries = ["paho-mqtt3c"]
+
+if sys.platform == "darwin":
+    # macOS: Use Homebrew paths for Paho MQTT
+    homebrew_prefix = None
+
+    # Try to get Homebrew prefix
+    try:
+        result = subprocess.run(
+            ["brew", "--prefix", "libpaho-mqtt"],
+            capture_output=True,
+            text=True
+        )
+        if result.returncode == 0:
+            homebrew_prefix = result.stdout.strip()
+    except FileNotFoundError:
+        pass
+
+    # Fallback to common locations
+    if not homebrew_prefix:
+        for prefix in ["/opt/homebrew/opt/libpaho-mqtt", "/usr/local/opt/libpaho-mqtt"]:
+            if Path(prefix).exists():
+                homebrew_prefix = prefix
+                break
+
+    if homebrew_prefix:
+        include_dirs.append(f"{homebrew_prefix}/include")
+        library_dirs.append(f"{homebrew_prefix}/lib")
+        print(f"Using Homebrew Paho MQTT at: {homebrew_prefix}")
+    else:
+        print("Warning: Could not find Homebrew Paho MQTT installation")
+        print("Install with: brew install libpaho-mqtt")
+
+elif sys.platform == "linux":
+    # Linux: Check for pkg-config
+    try:
+        result = subprocess.run(
+            ["pkg-config", "--cflags", "--libs", "paho-mqtt3c"],
+            capture_output=True,
+            text=True
+        )
+        if result.returncode == 0:
+            # Parse pkg-config output
+            for flag in result.stdout.split():
+                if flag.startswith("-I"):
+                    include_dirs.append(flag[2:])
+                elif flag.startswith("-L"):
+                    library_dirs.append(flag[2:])
+    except FileNotFoundError:
+        pass
+
+# Define the extension module
+ffibuilder.set_source(
+    "sds._sds_cffi",
+    source_code,
+    sources=sources,
+    include_dirs=include_dirs,
+    library_dirs=library_dirs,
+    libraries=libraries,
+    # Extra compile args for safety
+    extra_compile_args=["-Wall", "-Wextra"],
+)
+
+
+def build_inplace():
+    """Build the extension in-place for development."""
+    ffibuilder.compile(verbose=True)
+
+
+if __name__ == "__main__":
+    build_inplace()

sds/_logging.py

@@ -0,0 +1,78 @@
+"""
+SDS Logging Configuration.
+
+This module provides logging setup for the SDS library.
+By default, the library uses a NullHandler to avoid unwanted output.
+Applications can configure logging as needed.
+
+Example:
+    # Enable SDS logging to console
+    import logging
+    from sds import configure_logging
+
+    configure_logging(level=logging.DEBUG)
+
+    # Or configure manually
+    logging.getLogger("sds").setLevel(logging.DEBUG)
+    logging.getLogger("sds").addHandler(logging.StreamHandler())
+"""
+import logging
+from typing import Optional
+
+# Library logger - uses NullHandler by default (library best practice)
+logger = logging.getLogger("sds")
+logger.addHandler(logging.NullHandler())
+
+
+def configure_logging(
+    level: int = logging.INFO,
+    format: Optional[str] = None,
+    handler: Optional[logging.Handler] = None,
+) -> None:
+    """
+    Configure logging for the SDS library.
+
+    This is a convenience function for setting up logging. For more
+    complex setups, configure the "sds" logger directly.
+
+    Args:
+        level: Logging level (default: INFO)
+        format: Log format string (default: "[%(levelname)s] sds: %(message)s")
+        handler: Custom handler (default: StreamHandler to stderr)
+
+    Example:
+        >>> from sds import configure_logging
+        >>> import logging
+        >>> configure_logging(level=logging.DEBUG)
+    """
+    sds_logger = logging.getLogger("sds")
+    sds_logger.setLevel(level)
+
+    # Remove existing handlers to avoid duplicates
+    for h in sds_logger.handlers[:]:
+        if not isinstance(h, logging.NullHandler):
+            sds_logger.removeHandler(h)
+
+    # Add the specified or default handler
+    if handler is None:
+        handler = logging.StreamHandler()
+        if format is None:
+            format = "[%(levelname)s] sds: %(message)s"
+        handler.setFormatter(logging.Formatter(format))
+
+    sds_logger.addHandler(handler)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Get a logger for an SDS submodule.
+
+    Args:
+        name: Module name (will be prefixed with "sds.")
+
+    Returns:
+        Logger instance
+    """
+    if name.startswith("sds."):
+        return logging.getLogger(name)
+    return logging.getLogger(f"sds.{name}")

sds/_mqtt.py

@@ -0,0 +1,129 @@
+"""
+sds._mqtt — thin paho-mqtt transport for the pure-Python SDS engine.
+
+A minimal wrapper that the protocol engine drives: connect (registering the
+node's LWT will), subscribe/unsubscribe, publish (retain/QoS), and a
+``poll()``-compatible network pump. Incoming messages are delivered to a single
+callback as ``(topic, payload_str)``.
+
+This module is intentionally *not* imported by ``sds/__init__`` or the
+conformance harness — the wire/protocol engine is transport-agnostic and is
+validated against the golden vectors without a broker. ``paho-mqtt`` is only
+required when this layer is actually used (live broker, Phase 6+).
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+try:
+    import paho.mqtt.client as mqtt
+except ImportError as exc:  # pragma: no cover - exercised only without paho
+    raise ImportError(
+        "sds._mqtt requires the 'paho-mqtt' package. Install it with "
+        "`pip install paho-mqtt` (it is declared as a runtime dependency of "
+        "sds-library)."
+    ) from exc
+
+from ._protocol import is_reserved_topic
+
+# Callback: (topic, payload) -> None
+MessageCallback = Callable[[str, str], None]
+
+_RESERVED_MSG = "topic '{}' is reserved (sds/ prefix); use the table API instead"
+
+
+class MqttTransport:
+    """A small paho-mqtt client tuned for SDS usage."""
+
+    def __init__(
+        self,
+        node_id: str,
+        host: str = "localhost",
+        port: int = 1883,
+        *,
+        keepalive: int = 60,
+        on_message: Optional[MessageCallback] = None,
+    ) -> None:
+        self.node_id = node_id
+        self.host = host
+        self.port = port
+        self.keepalive = keepalive
+        self._on_message = on_message
+        self._connected = False
+
+        # client_id = node_id keeps broker-side session identity aligned with SDS.
+        self._client = mqtt.Client(client_id=node_id, clean_session=True)
+        self._client.on_connect = self._handle_connect
+        self._client.on_disconnect = self._handle_disconnect
+        self._client.on_message = self._handle_message
+
+    # ---- lifecycle --------------------------------------------------------
+
+    def connect(
+        self,
+        will_topic: Optional[str] = None,
+        will_payload: Optional[str] = None,
+        *,
+        will_retain: bool = True,
+        will_qos: int = 0,
+    ) -> None:
+        """Connect to the broker, registering the LWT will if provided."""
+        if will_topic is not None and will_payload is not None:
+            self._client.will_set(
+                will_topic, payload=will_payload, qos=will_qos, retain=will_retain
+            )
+        self._client.connect(self.host, self.port, self.keepalive)
+
+    def disconnect(self) -> None:
+        self._client.disconnect()
+
+    @property
+    def is_connected(self) -> bool:
+        return self._connected
+
+    # ---- pub/sub ----------------------------------------------------------
+
+    def subscribe(self, topic: str, qos: int = 0) -> None:
+        self._client.subscribe(topic, qos=qos)
+
+    def unsubscribe(self, topic: str) -> None:
+        self._client.unsubscribe(topic)
+
+    def publish(self, topic: str, payload: str, qos: int = 0, retain: bool = False) -> None:
+        self._client.publish(topic, payload=payload, qos=qos, retain=retain)
+
+    # ---- raw pub/sub (reserved-prefix guarded) ----------------------------
+
+    def raw_subscribe(self, topic: str, qos: int = 0) -> None:
+        if is_reserved_topic(topic):
+            raise ValueError(_RESERVED_MSG.format(topic))
+        self.subscribe(topic, qos)
+
+    def raw_publish(self, topic: str, payload: str, qos: int = 0, retain: bool = False) -> None:
+        if is_reserved_topic(topic):
+            raise ValueError(_RESERVED_MSG.format(topic))
+        self.publish(topic, payload, qos, retain)
+
+    # ---- network pump -----------------------------------------------------
+
+    def poll(self, timeout_ms: int = 0) -> None:
+        """Pump the network for up to ``timeout_ms`` (poll()-compatible)."""
+        self._client.loop(timeout=max(timeout_ms, 0) / 1000.0)
+
+    # ---- paho callbacks ---------------------------------------------------
+
+    def _handle_connect(self, client, userdata, flags, rc, *args) -> None:
+        self._connected = rc == 0
+
+    def _handle_disconnect(self, client, userdata, rc, *args) -> None:
+        self._connected = False
+
+    def _handle_message(self, client, userdata, msg) -> None:
+        if self._on_message is None:
+            return
+        try:
+            payload = msg.payload.decode("utf-8")
+        except (UnicodeDecodeError, AttributeError):
+            return
+        self._on_message(msg.topic, payload)