shepherd-core 2025.10.1__py3-none-any.whl → 2026.2.3__py3-none-any.whl

shepherd_core/data_models/experiment/target_config.py

@@ -1,6 +1,8 @@
 """Configuration related to Target Nodes (DuT)."""
 
+from pathlib import Path
 from typing import Annotated
+from typing import final
 
 from pydantic import Field
 from pydantic import model_validator
@@ -13,6 +15,7 @@ from shepherd_core.data_models.content.firmware import Firmware
 from shepherd_core.data_models.content.virtual_source_config import VirtualSourceConfig
 from shepherd_core.data_models.testbed.target import IdInt16
 from shepherd_core.data_models.testbed.target import Target
+from shepherd_core.logger import log
 
 from .observer_features import GpioActuation
 from .observer_features import GpioTracing
@@ -23,7 +26,8 @@ from .observer_features import UartLogging
 vsrc_neutral = VirtualSourceConfig(name="neutral")
 
 
-class TargetConfig(ShpModel, title="Target Config"):
+@final
+class TargetConfig(ShpModel):
     """Configuration related to Target Nodes (DuT)."""
 
     target_IDs: Annotated[list[IdInt], Field(min_length=1, max_length=128)]
@@ -55,13 +59,40 @@ class TargetConfig(ShpModel, title="Target Config"):
     gpio_actuation: GpioActuation | None = None
     uart_logging: UartLogging | None = None
 
+    @model_validator(mode="after")
+    def validate_eenv_mapping(self) -> Self:
+        """Validate that a mapping between targets and EEnvs can be found."""
+        if self.energy_env.repetitions_ok:
+            return self
+        n_env = len(self.energy_env)
+        n_tgt = len(self.target_IDs)
+        if n_env == n_tgt:
+            return self
+        if n_env > n_tgt:
+            log.debug(
+                f"TargetConfig for {self.target_IDs} has remaining "
+                f"{n_env - n_tgt} EEnv-profiles -> will not be used there"
+            )
+            return self
+        msg = (
+            f"Energy-Environment of TargetConfig for tgt{self.target_IDs} was too small "
+            f"({n_tgt - n_env} missing). Please use a larger environment."
+        )
+        raise ValueError(msg)
+
     @model_validator(mode="after")
     def post_validation(self) -> Self:
-        if not self.energy_env.valid:
-            msg = f"EnergyEnv '{self.energy_env.name}' for target must be valid"
-            raise ValueError(msg)
-        for _id in self.target_IDs:
-            target = Target(id=_id)
+        # trigger a reuse warning if needed
+        self.get_critical_paths(warn_reuse=True)
+        try:
+            self.energy_env.enforce_validity()
+        except ValueError as xpt:
+            msg = f"EnergyEnv '{self.energy_env.name}' for TargetConfig must be valid.\n{xpt}"
+            # note: added xpt in text because pydantic refuses to show "from xpt" part below
+            raise ValueError(msg) from xpt
+        # check IDs
+        for id_ in self.target_IDs:
+            target = Target(id=id_)
             for mcu_num in [1, 2]:
                 val_fw = getattr(self, f"firmware{mcu_num}")
                 has_fw = val_fw is not None
@@ -91,11 +122,28 @@ class TargetConfig(ShpModel, title="Target Config"):
             msg = f"Provided custom IDs {c_ids} not enough to cover target range {t_ids}"
             raise ValueError(msg)
         # TODO: if custom ids present, firmware must be ELF
+        if self.target_delays is not None:
+            log.warning("Feature TargetDelays is reserved for future use (not implemented).")
         if self.gpio_actuation is not None:
-            raise NotImplementedError("Feature GpioActuation reserved for future use.")
+            log.warning("Feature GpioActuation is reserved for future use (not implemented).")
         return self
 
     def get_custom_id(self, target_id: int) -> int | None:
         if self.custom_IDs is not None and target_id in self.target_IDs:
             return self.custom_IDs[self.target_IDs.index(target_id)]
         return None
+
+    def get_critical_paths(self, *, warn_reuse: bool = True) -> set[Path]:
+        """Return all paths of non-repeatable energy profiles to warn about re-usage."""
+        paths: list[Path] = [
+            profile.data_path
+            for profile in self.energy_env.energy_profiles
+            if not profile.repetitions_ok
+        ]
+        path_set = set(paths)
+        if warn_reuse and len(paths) != len(path_set):
+            log.warning(
+                f"Detected re-usage of non-repeatable EnergyProfiles "
+                f"in EnergyEnv '{self.energy_env.name}' (TargetConfig-Level)"
+            )
+        return path_set

shepherd_core/data_models/task/__init__.py

@@ -3,7 +3,9 @@
 These models import externally from all other model-modules!
 """
 
+import pathlib
 import pickle
+import sys
 from pathlib import Path
 
 import yaml
@@ -44,8 +46,17 @@ def prepare_task(config: ShpModel | Path | str, observer: str | None = None) ->
         config = Path(config)
 
     if isinstance(config, Path) and config.exists() and config.suffix.lower() == ".pickle":
-        with config.resolve().open("rb") as shp_file:
-            shp_dict = pickle.load(shp_file)  # noqa: S301
+        try:
+            with config.resolve().open("rb") as shp_file:
+                shp_dict = pickle.load(shp_file)  # noqa: S301
+        except ModuleNotFoundError as e:
+            # NOTE: workaround for interop-problem
+            # "No module named 'pathlib._local'; 'pathlib' is not a package"
+            log.warning("Had trouble loading pickled task -> activate pathlib-workaround")
+            log.warning(" -> Caught Exception: %s", e.msg)
+            sys.modules["pathlib._local"] = pathlib
+            with config.resolve().open("rb") as shp_file:
+                shp_dict = pickle.load(shp_file)  # noqa: S301
         shp_wrap = Wrapper(**shp_dict)
     elif isinstance(config, Path) and config.exists() and config.suffix.lower() == ".yaml":
         with config.resolve().open() as shp_file:

shepherd_core/data_models/task/emulation.py

@@ -8,6 +8,7 @@ from enum import Enum
 from pathlib import Path
 from pathlib import PurePosixPath
 from typing import Annotated
+from typing import final
 
 from pydantic import Field
 from pydantic import model_validator
@@ -46,6 +47,7 @@ compressions_allowed: list = [None, "lzf", 1]
 c_translate = {"lzf": "lzf", "1": 1, "None": None, None: None}
 
 
+@final
 class EmulationTask(ShpModel):
     """Configuration for the Observer in Emulation-Mode."""
 
@@ -145,7 +147,7 @@ class EmulationTask(ShpModel):
             raise ValueError("GPIO Actuation not yet implemented!")
 
         io_requested = any(
-            _io is not None for _io in (self.gpio_actuation, self.gpio_tracing, self.uart_logging)
+            io_ is not None for io_ in (self.gpio_actuation, self.gpio_tracing, self.uart_logging)
         )
         if self.enable_io and not io_requested:
             log.warning("Target IO enabled, but no feature requested IO")
@@ -158,13 +160,14 @@ class EmulationTask(ShpModel):
     def from_xp(cls, xp: Experiment, tb: Testbed, tgt_id: IdInt, root_path: Path) -> Self:
         obs = tb.get_observer(tgt_id)
         tgt_cfg = xp.get_target_config(tgt_id)
+        tgt_idx = tgt_cfg.target_IDs.index(tgt_id)
         io_requested = any(
-            _io is not None
-            for _io in (tgt_cfg.gpio_actuation, tgt_cfg.gpio_tracing, tgt_cfg.uart_logging)
+            io_ is not None
+            for io_ in (tgt_cfg.gpio_actuation, tgt_cfg.gpio_tracing, tgt_cfg.uart_logging)
         )
 
         return cls(
-            input_path=path_posix(tgt_cfg.energy_env.data_path),
+            input_path=path_posix(tgt_cfg.energy_env[tgt_idx].data_path),
             output_path=path_posix(root_path / f"emu_{obs.name}.h5"),
             time_start=copy.copy(xp.time_start),
             duration=xp.duration,
@@ -185,7 +188,8 @@ class EmulationTask(ShpModel):
         TODO: could be added to validator (with a switch)
         """
         all_ok = any(self.input_path.is_relative_to(path) for path in paths)
-        all_ok &= any(self.output_path.is_relative_to(path) for path in paths)
+        if self.output_path is not None:
+            all_ok &= any(self.output_path.is_relative_to(path) for path in paths)
         return all_ok
 
 

shepherd_core/data_models/task/firmware_mod.py

@@ -5,6 +5,7 @@ from pathlib import Path
 from pathlib import PurePosixPath
 from typing import Annotated
 from typing import TypedDict
+from typing import final
 
 from pydantic import Field
 from pydantic import model_validator
@@ -14,8 +15,8 @@ from typing_extensions import Unpack
 
 from shepherd_core.data_models.base.content import IdInt
 from shepherd_core.data_models.base.shepherd import ShpModel
+from shepherd_core.data_models.content.enum_datatypes import FirmwareDType
 from shepherd_core.data_models.content.firmware import Firmware
-from shepherd_core.data_models.content.firmware import FirmwareDType
 from shepherd_core.data_models.content.firmware import FirmwareStr
 from shepherd_core.data_models.experiment.experiment import Experiment
 from shepherd_core.data_models.testbed import Testbed
@@ -26,6 +27,7 @@ from shepherd_core.logger import log
 from .helper_paths import path_posix
 
 
+@final
 class FirmwareModTask(ShpModel):
     """Config for Task that adds the custom ID to the firmware & stores it into a file."""
 

shepherd_core/data_models/task/harvest.py

@@ -6,6 +6,7 @@ from datetime import timedelta
 from pathlib import Path
 from pathlib import PurePosixPath
 from typing import Annotated
+from typing import final
 
 from pydantic import Field
 from pydantic import model_validator
@@ -20,6 +21,7 @@ from shepherd_core.data_models.experiment.observer_features import SystemLogging
 from .emulation import Compression
 
 
+@final
 class HarvestTask(ShpModel):
     """Config for the Observer in Harvest-Mode to record IV data from a harvesting-source."""
 

shepherd_core/data_models/task/helper_paths.py

@@ -1,6 +1,6 @@
 r"""Helper FN to avoid unwanted behavior.
 
-On windows Path("\xyz") gets transformed to "/xyz", but not on linux.
+On WinOS Path("\xyz") gets transformed to "/xyz", but not on linux.
 When sending an experiment via fastapi, this bug gets triggered.
 """
 
@@ -10,6 +10,6 @@ from pathlib import Path
 def path_posix(path: Path) -> Path:
     r"""Help Linux to get from "\xyz" to "/xyz".
 
-    This isn't a problem on windows and gets triggered when sending XP via fastapi.
+    This isn't a problem on WinOS and gets triggered when sending experiments via fastapi.
     """
     return Path(path.as_posix().replace("\\", "/"))

shepherd_core/data_models/task/observer_tasks.py

@@ -5,6 +5,7 @@ from datetime import datetime
 from pathlib import Path
 from pathlib import PurePosixPath
 from typing import Annotated
+from typing import final
 
 from pydantic import validate_call
 from typing_extensions import Self
@@ -22,6 +23,7 @@ from .helper_paths import path_posix
 from .programming import ProgrammingTask
 
 
+@final
 class ObserverTasks(ShpModel):
     """Collection of tasks for selected observer included in experiment."""
 
@@ -60,7 +62,7 @@ class ObserverTasks(ShpModel):
         if xp_folder is None:
             xp_folder = xp.folder_name()  # moved a layer up for consistent naming
         root_path = tb.data_on_observer / "experiments" / xp_folder
-        fw_paths = [root_path / f"fw{_i}_{obs.name}.hex" for _i in [1, 2]]
+        fw_paths = [root_path / f"fw{i_}_{obs.name}.hex" for i_ in [1, 2]]
 
         return cls(
             observer=obs.name,
@@ -97,9 +99,9 @@ class ObserverTasks(ShpModel):
     def is_contained(self, paths: AbstractSet[PurePosixPath]) -> bool:
         """Limit paths to allowed directories."""
         all_ok = any(self.root_path.is_relative_to(path) for path in paths)
-        all_ok &= self.fw1_mod.is_contained(paths)
-        all_ok &= self.fw2_mod.is_contained(paths)
-        all_ok &= self.fw1_prog.is_contained(paths)
-        all_ok &= self.fw2_prog.is_contained(paths)
-        all_ok &= self.emulation.is_contained(paths)
+        all_ok &= self.fw1_mod is None or self.fw1_mod.is_contained(paths)
+        all_ok &= self.fw2_mod is None or self.fw2_mod.is_contained(paths)
+        all_ok &= self.fw1_prog is None or self.fw1_prog.is_contained(paths)
+        all_ok &= self.fw2_prog is None or self.fw2_prog.is_contained(paths)
+        all_ok &= self.emulation is None or self.emulation.is_contained(paths)
         return all_ok

shepherd_core/data_models/task/programming.py

@@ -4,6 +4,7 @@ from collections.abc import Set as AbstractSet
 from pathlib import Path
 from pathlib import PurePosixPath
 from typing import Annotated
+from typing import final
 
 from pydantic import Field
 from pydantic import model_validator
@@ -13,8 +14,8 @@ from typing_extensions import Self
 from shepherd_core.data_models.base.content import IdInt
 from shepherd_core.data_models.base.content import SafeStr
 from shepherd_core.data_models.base.shepherd import ShpModel
+from shepherd_core.data_models.content.enum_datatypes import FirmwareDType
 from shepherd_core.data_models.content.firmware import suffix_to_DType
-from shepherd_core.data_models.content.firmware_datatype import FirmwareDType
 from shepherd_core.data_models.experiment.experiment import Experiment
 from shepherd_core.data_models.testbed.cape import TargetPort
 from shepherd_core.data_models.testbed.mcu import ProgrammerProtocol
@@ -24,6 +25,7 @@ from shepherd_core.data_models.testbed.testbed import Testbed
 from .helper_paths import path_posix
 
 
+@final
 class ProgrammingTask(ShpModel):
     """Config for a Task programming the selected target."""
 
@@ -31,7 +33,7 @@ class ProgrammingTask(ShpModel):
     target_port: TargetPort = TargetPort.A
     mcu_port: MCUPort = 1
     mcu_type: SafeStr
-    """ ⤷ must be either "nrf52" or "msp430" ATM, TODO: clean xp to tasks"""
+    """ ⤷ must be either "nrf52" or "msp430" ATM, TODO: clean Experiment to tasks"""
     voltage: Annotated[float, Field(ge=1, lt=5)] = 3
     datarate: Annotated[int, Field(gt=0, le=1_000_000)] = 200_000
     protocol: ProgrammerProtocol

shepherd_core/data_models/task/testbed_tasks.py

@@ -4,6 +4,7 @@ from pathlib import Path
 from pathlib import PurePosixPath
 from typing import TYPE_CHECKING
 from typing import Annotated
+from typing import final
 
 from pydantic import Field
 from pydantic import validate_call
@@ -20,6 +21,7 @@ if TYPE_CHECKING:
     from collections.abc import Set as AbstractSet
 
 
+@final
 class TestbedTasks(ShpModel):
     """Collection of tasks for all observers included in experiment."""
 
@@ -35,7 +37,7 @@ class TestbedTasks(ShpModel):
 
         tgt_ids = xp.get_target_ids()
         xp_folder = xp.folder_name()
-        obs_tasks = [ObserverTasks.from_xp(xp, xp_folder, tb, _id) for _id in tgt_ids]
+        obs_tasks = [ObserverTasks.from_xp(xp, xp_folder, tb, id_) for id_ in tgt_ids]
         return cls(
             name=xp.name,
             observer_tasks=obs_tasks,
@@ -60,7 +62,11 @@ class TestbedTasks(ShpModel):
         return values
 
     def is_contained(self) -> bool:
-        """Limit paths to allowed directories."""
+        """Limit paths to allowed directories.
+
+        This is the central checking point for the webserver.
+        """
+        # TODO: load paths from config
         paths_allowed: AbstractSet[PurePosixPath] = {
             PurePosixPath("/var/shepherd/"),
             PurePosixPath("/tmp/"),  # noqa: S108

shepherd_core/data_models/testbed/cape.py

@@ -4,6 +4,7 @@ from datetime import date
 from datetime import datetime
 from enum import Enum
 from typing import Any
+from typing import final
 
 from pydantic import Field
 from pydantic import model_validator
@@ -22,6 +23,7 @@ class TargetPort(str, Enum):
     B = b = "B"
 
 
+@final
 class Cape(ShpModel, title="Shepherd-Cape"):
     """meta-data representation of a testbed-component (physical object)."""
 

shepherd_core/data_models/testbed/gpio.py

@@ -3,6 +3,7 @@
 from enum import Enum
 from typing import Annotated
 from typing import Any
+from typing import final
 
 from pydantic import Field
 from pydantic import StringConstraints
@@ -24,6 +25,7 @@ class Direction(str, Enum):
     Bidirectional = IO = "IO"
 
 
+@final
 class GPIO(ShpModel, title="GPIO of Observer Node"):
     """meta-data representation of a testbed-component."""
 

shepherd_core/data_models/testbed/mcu.py

@@ -3,6 +3,7 @@
 from enum import Enum
 from typing import Annotated
 from typing import Any
+from typing import final
 
 from pydantic import Field
 from pydantic import model_validator
@@ -23,6 +24,7 @@ class ProgrammerProtocol(str, Enum):
     UART = uart = "UART"
 
 
+@final
 class MCU(ShpModel, title="Microcontroller of the Target Node"):
     """meta-data representation of a testbed-component (physical object)."""
 

shepherd_core/data_models/testbed/observer.py

@@ -3,6 +3,7 @@
 from datetime import datetime
 from typing import Annotated
 from typing import Any
+from typing import final
 
 from pydantic import Field
 from pydantic import IPvAnyAddress
@@ -26,6 +27,7 @@ MACStr = Annotated[
 ]
 
 
+@final
 class Observer(ShpModel, title="Shepherd-Sheep"):
     """meta-data representation of a testbed-component (physical object)."""
 

shepherd_core/data_models/testbed/target.py

@@ -3,6 +3,7 @@
 from datetime import datetime
 from typing import Annotated
 from typing import Any
+from typing import final
 
 from pydantic import Field
 from pydantic import model_validator
@@ -20,6 +21,7 @@ IdInt16 = Annotated[int, Field(ge=0, lt=2**16)]
 MCUPort = Annotated[int, Field(ge=1, le=2)]
 
 
+@final
 class Target(ShpModel, title="Target Node (DuT)"):
     """meta-data representation of a testbed-component (physical object)."""
 
@@ -49,12 +51,12 @@ class Target(ShpModel, title="Target Node (DuT)"):
         values, _ = tb_client.try_completing_model(cls.__name__, values)
 
         # post correction
-        for _mcu in ["mcu1", "mcu2"]:
-            if isinstance(values.get(_mcu), str):
-                values[_mcu] = MCU(name=values[_mcu])
+        for mcu in ["mcu1", "mcu2"]:
+            if isinstance(values.get(mcu), str):
+                values[mcu] = MCU(name=values[mcu])
                 # ⤷ this will raise if default is faulty
-            elif isinstance(values.get(_mcu), dict):
-                values[_mcu] = MCU(**values[_mcu])
+            elif isinstance(values.get(mcu), dict):
+                values[mcu] = MCU(**values[mcu])
         if values.get("testbed_id") is None:
             values["testbed_id"] = values.get("id") % 2**16
 

shepherd_core/data_models/testbed/target_fixture.old1

@@ -3,7 +3,7 @@
 # https://github.com/orgua/shepherd-v2-planning/blob/main/doc_testbed/Target_pre-deployment-tests.xlsx
 - datatype: target
   parameters:
-    id: 6  # Outer ID - selected by user for XP - can be rearranged
+    id: 6  # Outer ID - selected by user for Experiment - can be rearranged
     name: nRF52_FRAM_001  # inner ID - used to link all parts together
     version: v1.0
     description: nRF52 as MCU + Radio, MSP430FR as SPI-FRAM or additional MCU

shepherd_core/data_models/testbed/target_fixture.yaml

@@ -3,7 +3,7 @@
 # https://github.com/orgua/shepherd-v2-planning/blob/main/doc_testbed/Target_pre-deployment-tests.xlsx
 - datatype: target
   parameters:
-    id: 2  # Outer ID - selected by user for XP - can be rearranged
+    id: 2  # Outer ID - selected by user for experiment - can be rearranged
     name: nRF52_FRAM_1392_377  # inner ID - used to link all parts together
     version: v1.3
     description: nRF52 as MCU + Radio, MSP430FR as SPI-FRAM or additional MCU

shepherd_core/data_models/testbed/testbed.py

@@ -4,6 +4,7 @@ from datetime import timedelta
 from pathlib import Path
 from typing import Annotated
 from typing import Any
+from typing import final
 
 from pydantic import Field
 from pydantic import HttpUrl
@@ -22,6 +23,7 @@ from .observer import Observer
 duration_5min = timedelta(minutes=5)
 
 
+@final
 class Testbed(ShpModel):
     """meta-data representation of a testbed-component (physical object)."""
 
@@ -61,17 +63,17 @@ class Testbed(ShpModel):
         capes = []
         targets = []
         eth_ports = []
-        for _obs in self.observers:
-            observers.append(_obs.id)
-            ips.append(_obs.ip)
-            macs.append(_obs.mac)
-            if _obs.cape is not None:
-                capes.append(_obs.cape)
-            if _obs.target_a is not None:
-                targets.append(_obs.target_a)
-            if _obs.target_b is not None:
-                targets.append(_obs.target_b)
-            eth_ports.append(_obs.eth_port)
+        for obs in self.observers:
+            observers.append(obs.id)
+            ips.append(obs.ip)
+            macs.append(obs.mac)
+            if obs.cape is not None:
+                capes.append(obs.cape)
+            if obs.target_a is not None:
+                targets.append(obs.target_a)
+            if obs.target_b is not None:
+                targets.append(obs.target_b)
+            eth_ports.append(obs.eth_port)
         if len(observers) > len(set(observers)):
             raise ValueError("Observers used more than once in Testbed")
         if len(ips) > len(set(ips)):
@@ -91,11 +93,11 @@ class Testbed(ShpModel):
         return self
 
     def get_observer(self, target_id: int) -> Observer:
-        for _observer in self.observers:
-            if not _observer.active or not _observer.cape.active:
+        for obs in self.observers:
+            if not obs.active or not obs.cape.active:
                 # skip decommissioned setups
                 continue
-            if _observer.has_target(target_id):
-                return _observer
+            if obs.has_target(target_id):
+                return obs
         msg = f"Target-ID {target_id} was not found in Testbed '{self.name}'"
         raise ValueError(msg)

shepherd_core/exit_handler.py

@@ -0,0 +1,22 @@
+"""Generalized exit handler for Shepherd."""
+
+import signal
+import sys
+from collections.abc import Callable
+from types import FrameType
+
+from .logger import log
+
+
+def exit_gracefully(_signum: int, _frame: FrameType | None) -> None:
+    """Usual exit handler for single-processing applications."""
+    log.warning("Exiting!")
+    sys.exit(0)
+
+
+def activate_exit_handler(custom: Callable = exit_gracefully) -> None:
+    """Register the provided exit handler or use the default one."""
+    signal.signal(signal.SIGTERM, custom)
+    signal.signal(signal.SIGINT, custom)
+    if hasattr(signal, "SIGALRM"):
+        signal.signal(signal.SIGALRM, custom)

shepherd_core/fw_tools/converter.py

@@ -8,7 +8,7 @@ from pathlib import Path
 import zstandard as zstd
 from pydantic import validate_call
 
-from shepherd_core.data_models.content.firmware_datatype import FirmwareDType
+from shepherd_core.data_models.content.enum_datatypes import FirmwareDType
 
 from .converter_elf import elf_to_hex
 from .validation import is_elf
@@ -98,7 +98,7 @@ def extract_firmware(data: str | Path, data_type: FirmwareDType, file_path: Path
         elif data_type == FirmwareDType.path_hex:
             file = file_path.with_suffix(".hex")
         else:
-            msg = "FW-Extraction failed due to unknown datatype '{data_type}'"
+            msg = f"FW-Extraction failed due to unknown datatype '{data_type}'"
             raise ValueError(msg)
         if not file.parent.exists():
             file.parent.mkdir(parents=True)

shepherd_core/fw_tools/validation.py

@@ -13,7 +13,7 @@ from intelhex import IntelHex
 from intelhex import IntelHexError
 from pydantic import validate_call
 
-from shepherd_core.data_models.content.firmware_datatype import FirmwareDType
+from shepherd_core.data_models.content.enum_datatypes import FirmwareDType
 from shepherd_core.logger import log
 
 from .converter_elf import elf_to_hex