shepherd-core 2023.12.1__py3-none-any.whl → 2024.4.2__py3-none-any.whl

shepherd_core/data_models/experiment/experiment.py

@@ -1,9 +1,13 @@
+"""Config for testbed experiments."""
+
 from datetime import datetime
 from datetime import timedelta
 from typing import List
 from typing import Optional
+from typing import Union
+from uuid import uuid4
 
-from pydantic import EmailStr
+from pydantic import UUID4
 from pydantic import Field
 from pydantic import model_validator
 from typing_extensions import Annotated
@@ -12,7 +16,6 @@ from typing_extensions import Self
 from ..base.content import IdInt
 from ..base.content import NameStr
 from ..base.content import SafeStr
-from ..base.content import id_default
 from ..base.shepherd import ShpModel
 from ..testbed.target import Target
 from ..testbed.testbed import Testbed
@@ -21,16 +24,13 @@ from .target_config import TargetConfig
 
 
 class Experiment(ShpModel, title="Config of an Experiment"):
-    """Configuration for Experiments on the Shepherd-Testbed
-    emulating Energy Environments for Target Nodes
-    """
+    """Config for experiments on the testbed emulating energy environments for target nodes."""
 
     # General Properties
-    id: IdInt = Field(  # noqa: A003
-        description="Unique ID",
-        default_factory=id_default,
-    )
+    # id: UUID4 ... # TODO: db-migration - temp fix for documentation
+    id: Union[UUID4, int] = Field(default_factory=uuid4)
     # ⤷ TODO: automatic ID is problematic for identification by hash
+
     name: NameStr
     description: Annotated[
         Optional[SafeStr], Field(description="Required for public instances")
@@ -38,12 +38,12 @@ class Experiment(ShpModel, title="Config of an Experiment"):
     comment: Optional[SafeStr] = None
     created: datetime = Field(default_factory=datetime.now)
 
-    # Ownership & Access, TODO
-    owner_id: Optional[IdInt] = 5472  # UUID?
+    # Ownership & Access
+    owner_id: Optional[IdInt] = None
 
     # feedback
-    email_results: Optional[EmailStr] = None
-    # ⤷ TODO: can be bool, as its linked to account
+    email_results: bool = False
+
     sys_logging: SystemLogging = SystemLogging(dmesg=True, ptp=True, shepherd=True)
 
     # schedule
@@ -90,7 +90,7 @@ class Experiment(ShpModel, title="Config of an Experiment"):
         obs_ids = [testbed.get_observer(_id).id for _id in target_ids]
         if len(target_ids) > len(set(obs_ids)):
             raise ValueError(
-                "Observer used more than once in Experiment -> only 1 target per observer!"
+                "Observer is used more than once in Experiment -> only 1 target per observer!"
             )
 
     def get_target_ids(self) -> list:
@@ -101,4 +101,5 @@ class Experiment(ShpModel, title="Config of an Experiment"):
             if target_id in _config.target_IDs:
                 return _config
         # gets already caught in target_config - but keep:
-        raise ValueError(f"Target-ID {target_id} was not found in Experiment '{self.name}'")
+        msg = f"Target-ID {target_id} was not found in Experiment '{self.name}'"
+        raise ValueError(msg)

shepherd_core/data_models/experiment/observer_features.py

@@ -1,3 +1,5 @@
+"""Configs for observer features like gpio- & power-tracing."""
+
 from datetime import timedelta
 from enum import Enum
 from typing import List
@@ -15,7 +17,8 @@ from ..testbed.gpio import GPIO
 
 
 class PowerTracing(ShpModel, title="Config for Power-Tracing"):
-    """Configuration for recording the Power-Consumption of the Target Nodes
+    """Configuration for recording the Power-Consumption of the Target Nodes.
+
     TODO: postprocessing not implemented ATM
     """
 
@@ -45,12 +48,13 @@ class PowerTracing(ShpModel, title="Config for Power-Tracing"):
         if not self.calculate_power and discard_all:
             raise ValueError("Error in config -> tracing enabled, but output gets discarded")
         if self.calculate_power:
-            raise ValueError("postprocessing not implemented ATM")
+            raise NotImplementedError("postprocessing not implemented ATM")
         return self
 
 
 class GpioTracing(ShpModel, title="Config for GPIO-Tracing"):
-    """Configuration for recording the GPIO-Output of the Target Nodes
+    """Configuration for recording the GPIO-Output of the Target Nodes.
+
     TODO: postprocessing not implemented ATM
     """
 
@@ -66,7 +70,7 @@ class GpioTracing(ShpModel, title="Config for GPIO-Tracing"):
 
     # post-processing,
     uart_decode: bool = False
-    # todo: quickfix - uart-log currently done online in userspace
+    # TODO: quickfix - uart-log currently done online in userspace
     # NOTE: gpio-tracing currently shows rather big - but rare - "blind" windows (~1-4us)
     uart_pin: GPIO = GPIO(name="GPIO8")
     uart_baudrate: Annotated[int, Field(ge=2_400, le=921_600)] = 115_200
@@ -84,13 +88,15 @@ class GpioTracing(ShpModel, title="Config for GPIO-Tracing"):
 
 
 class GpioLevel(str, Enum):
+    """Options for setting the gpio-level or state."""
+
     low = "L"
     high = "H"
     toggle = "X"  # TODO: not the smartest decision for writing a converter
 
 
 class GpioEvent(ShpModel, title="Config for a GPIO-Event"):
-    """Configuration for a single GPIO-Event (Actuation)"""
+    """Configuration for a single GPIO-Event (Actuation)."""
 
     delay: PositiveFloat
     # ⤷ from start_time
@@ -104,7 +110,8 @@ class GpioEvent(ShpModel, title="Config for a GPIO-Event"):
     @model_validator(mode="after")
     def post_validation(self) -> Self:
         if not self.gpio.user_controllable():
-            raise ValueError(f"GPIO '{self.gpio.name}' in actuation-event not controllable by user")
+            msg = f"GPIO '{self.gpio.name}' in actuation-event not controllable by user"
+            raise ValueError(msg)
         return self
 
     def get_events(self) -> np.ndarray:
@@ -113,11 +120,10 @@ class GpioEvent(ShpModel, title="Config for a GPIO-Event"):
 
 
 class GpioActuation(ShpModel, title="Config for GPIO-Actuation"):
-    """Configuration for a GPIO-Actuation-Sequence
-    TODO: not implemented ATM:
-        - decide if pru control sys-gpio or
-        - reverses pru-gpio (preferred if possible)
-    """
+    """Configuration for a GPIO-Actuation-Sequence."""
+
+    # TODO: not implemented ATM - decide if pru control sys-gpio or
+    # TODO: not implemented ATM - reverses pru-gpio (preferred if possible)
 
     events: Annotated[List[GpioEvent], Field(min_length=1, max_length=1024)]
 
@@ -126,7 +132,7 @@ class GpioActuation(ShpModel, title="Config for GPIO-Actuation"):
 
 
 class SystemLogging(ShpModel, title="Config for System-Logging"):
-    """Configuration for recording Debug-Output of the Observers System-Services"""
+    """Configuration for recording Debug-Output of the Observers System-Services."""
 
     dmesg: bool = True
     ptp: bool = True

shepherd_core/data_models/experiment/target_config.py

@@ -1,3 +1,5 @@
+"""Configuration related to Target Nodes (DuT)."""
+
 from typing import List
 from typing import Optional
 
@@ -19,7 +21,7 @@ from .observer_features import PowerTracing
 
 
 class TargetConfig(ShpModel, title="Target Config"):
-    """Configuration for Target Nodes (DuT)"""
+    """Configuration related to Target Nodes (DuT)."""
 
     target_IDs: Annotated[List[IdInt], Field(min_length=1, max_length=128)]
     custom_IDs: Optional[Annotated[List[IdInt16], Field(min_length=1, max_length=128)]] = None
@@ -44,7 +46,8 @@ class TargetConfig(ShpModel, title="Target Config"):
     @model_validator(mode="after")
     def post_validation(self) -> Self:
         if not self.energy_env.valid:
-            raise ValueError(f"EnergyEnv '{self.energy_env.name}' for target must be 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)
             for mcu_num in [1, 2]:
@@ -56,24 +59,25 @@ class TargetConfig(ShpModel, title="Target Config"):
                     fw_def = Firmware(name=tgt_mcu.fw_name_default)
                     # ⤷ this will raise if default is faulty
                     if tgt_mcu.id != fw_def.mcu.id:
-                        raise ValueError(
+                        msg = (
                             f"Default-Firmware for MCU{mcu_num} of Target-ID '{target.id}' "
                             f"(={fw_def.mcu.name}) "
                             f"is incompatible (={tgt_mcu.name})"
                         )
+                        raise ValueError(msg)
                 if has_fw and has_mcu and val_fw.mcu.id != tgt_mcu.id:
-                    raise ValueError(
+                    msg = (
                         f"Firmware{mcu_num} for MCU of Target-ID '{target.id}' "
                         f"(={val_fw.mcu.name}) "
                         f"is incompatible (={tgt_mcu.name})"
                     )
+                    raise ValueError(msg)
 
         c_ids = self.custom_IDs
         t_ids = self.target_IDs
         if c_ids is not None and (len(set(c_ids)) < len(set(t_ids))):
-            raise ValueError(
-                f"Provided custom IDs {c_ids} not enough to cover target range {t_ids}"
-            )
+            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
         return self
 

shepherd_core/data_models/readme.md

@@ -0,0 +1,88 @@
+## Datastructure
+
+### experiment-structure
+
+- basics
+- scheduling
+- **SystemLogger**
+- ~~AuxPort~~
+- TargetConfigs
+  - Programming
+  - PowerTracer
+  - GpioTracer
+  - GpioActuator
+  - vSrc
+    - vHarvester
+    - [vConverter]
+
+## TODO
+
+- establish internal variables ``_var``
+- descriptions to parameters (docstring on sub-models)
+- @kai
+  - firmwares
+  - programmer-ports determine IC
+    - memory read - family-code, or write factory
+  - when tracing v_intermediate, also this current, or output?
+- ``objcopy -O ihex input.elf output.hex``
+  - ``-S`` will strip useless sections
+  - ``-I ihex -O elf32-littlearm`` for reversal is also possible
+    - TODO: try to find ``objdump -t [elf_file] | grep SHEPHERD_NODE_ID``
+
+- title in class might be rubbish
+
+- Warn about tricky syntax
+  - defining sub-data-models in an experiment in python:
+    - experiments-default: don't mention argument in init
+    - trace-default: init trace with empty argument list
+    - disable: init with "None"
+  - defining experiment in yaml:
+    - experiment-default: don't mention it
+    - trace-default: NOT POSSIBLE, right?
+    - disable: init with "null" OR just mention parameter but keep it empty
+
+### add documentation after creation ⇾ avoid Field()
+
+- these do not work
+
+```Python
+from pydantic import Field
+from shepherd_core.data_models import ShpModel
+
+class Experiment(ShpModel, title="Config of an Experiment"):
+    def __init__(self):  # test to add doc after creation ⇾ to avoid Field()
+        super().__init__()
+        self.Config.fields["output_path"].description = "test description"
+    class Config:
+        fields: dict[str, Field] = {}
+        fields["output_path"] = Field(description="test description")
+```
+
+### simplify init of pydantic-class
+
+What I want: init a fixture-class with Class("name") or Class(ID) instead of Class(name="name")
+
+What does not work:
+
+```Python
+from pathlib import Path
+from typing import Union
+from pydantic import root_validator
+from shepherd_core.data_models import Fixture
+from shepherd_core.data_models import ShpModel
+
+fixtures = Fixture(Path("fix.yaml"), "testbed.target")
+
+
+class Target(ShpModel, title="Target Node (DuT)"):
+  @root_validator(pre=True)
+  def query_database(cls, values: Union[dict, str, int]):
+    values = fixtures.try_completing_model(values)
+    values, chain = fixtures.try_inheritance(values)
+    return values
+```
+
+what might work:
+
+- writing a custom __init__() and putting lookup() there
+- wait for V2

shepherd_core/data_models/task/__init__.py

@@ -1,3 +1,8 @@
+"""Module for task-related data-modules.
+
+These models import externally from all other model-modules!
+"""
+
 from pathlib import Path
 from typing import List
 from typing import Optional
@@ -33,7 +38,9 @@ __all__ = [
 
 
 def prepare_task(config: Union[ShpModel, Path, str], observer: Optional[str] = None) -> Wrapper:
-    """- Opens file (from Path or str of Path)
+    """Open file and extract tasks.
+
+    - Open file (from Path or str of Path)
     - wraps task-model
     - and if it's an TestbedTasks it will extract the correct ObserverTask
     """
@@ -50,7 +57,7 @@ def prepare_task(config: Union[ShpModel, Path, str], observer: Optional[str] = N
             parameters=config.model_dump(),
         )
     else:
-        raise ValueError("had unknown input: %s", type(config))
+        raise TypeError("had unknown input: %s", type(config))
 
     if shp_wrap.datatype == TestbedTasks.__name__:
         if observer is None:
@@ -72,7 +79,7 @@ def prepare_task(config: Union[ShpModel, Path, str], observer: Optional[str] = N
 
 
 def extract_tasks(shp_wrap: Wrapper, *, no_task_sets: bool = True) -> List[ShpModel]:
-    """ """
+    """Make the individual task-sets usable for each observer."""
     if shp_wrap.datatype == ObserverTasks.__name__:
         obt = ObserverTasks(**shp_wrap.parameters)
         content = obt.get_tasks()

shepherd_core/data_models/task/emulation.py

@@ -1,3 +1,5 @@
+"""Configuration for the Observer in Emulation-Mode."""
+
 import copy
 from datetime import datetime
 from datetime import timedelta
@@ -26,10 +28,10 @@ from ..testbed.cape import TargetPort
 
 
 class Compression(str, Enum):
-    lzf = "lzf"  # not native hdf5
-    gzip1 = 1  # higher compr & load
-    gzip = 1
-    default = "lzf"
+    """Options for choosing a dataset-compression."""
+
+    lzf = default = "lzf"  # not native hdf5
+    gzip1 = gzip = 1  # higher compr & load
     null = None
     # NOTE: changed to lzf as BBB needs every straw it can get
 
@@ -39,7 +41,7 @@ c_translate = {"lzf": "lzf", "1": 1, "None": None, None: None}
 
 
 class EmulationTask(ShpModel):
-    """Configuration for the Observer in Emulation-Mode"""
+    """Configuration for the Observer in Emulation-Mode."""
 
     # General config
     input_path: Path
@@ -111,10 +113,11 @@ class EmulationTask(ShpModel):
         has_time = self.time_start is not None
         time_now = datetime.now().astimezone()
         if has_time and self.time_start < time_now:
-            raise ValueError(
+            msg = (
                 "Start-Time for Emulation can't be in the past "
                 f"('{self.time_start}' vs '{time_now}'."
             )
+            raise ValueError(msg)
         if self.duration and self.duration.total_seconds() < 0:
             raise ValueError("Task-Duration can't be negative.")
         if isinstance(self.voltage_aux, str) and self.voltage_aux not in {

shepherd_core/data_models/task/firmware_mod.py

@@ -1,3 +1,5 @@
+"""Config for Task that adds the custom ID to the firmware & stores it into a file."""
+
 import copy
 from pathlib import Path
 from typing import Optional
@@ -24,7 +26,7 @@ from ..testbed.target import MCUPort
 
 
 class FirmwareModTask(ShpModel):
-    """Config for Task that adds the custom ID to the firmware & stores it into a file"""
+    """Config for Task that adds the custom ID to the firmware & stores it into a file."""
 
     data: Union[FirmwareStr, Path]
     data_type: FirmwareDType
@@ -79,7 +81,7 @@ class FirmwareModTask(ShpModel):
         **kwargs: Unpack[TypedDict],
     ) -> Self:
         if not isinstance(fw, Firmware):
-            raise ValueError("fw-argument must be of type Firmware")
+            raise TypeError("fw-argument must be of type Firmware")
         kwargs["data"] = fw.data
         kwargs["data_type"] = fw.data_type
         fw.compare_hash()

shepherd_core/data_models/task/harvest.py

@@ -1,3 +1,5 @@
+"""Config for the Observer in Harvest-Mode to record IV data from a harvesting-source."""
+
 from datetime import datetime
 from datetime import timedelta
 from pathlib import Path
@@ -17,9 +19,7 @@ from .emulation import Compression
 
 
 class HarvestTask(ShpModel):
-    """Configuration for the Observer in Harvest-Mode
-    Record IV data from a harvest-source
-    """
+    """Config for the Observer in Harvest-Mode to record IV data from a harvesting-source."""
 
     # General config
     output_path: Path
@@ -73,10 +73,11 @@ class HarvestTask(ShpModel):
         has_time = self.time_start is not None
         time_now = datetime.now().astimezone()
         if has_time and self.time_start < time_now:
-            raise ValueError(
+            msg = (
                 "Start-Time for Emulation can't be in the past "
                 f"('{self.time_start}' vs '{time_now}'."
             )
+            raise ValueError(msg)
         if self.duration and self.duration.total_seconds() < 0:
             raise ValueError("Task-Duration can't be negative.")
         return self

shepherd_core/data_models/task/observer_tasks.py

@@ -1,3 +1,5 @@
+"""Collection of tasks for selected observer included in experiment."""
+
 from datetime import datetime
 from datetime import timedelta
 from pathlib import Path
@@ -18,10 +20,10 @@ from .programming import ProgrammingTask
 
 
 class ObserverTasks(ShpModel):
-    """Collection of tasks for selected observer included in experiment"""
+    """Collection of tasks for selected observer included in experiment."""
 
     observer: NameStr
-    owner_id: IdInt
+    owner_id: Optional[IdInt]  # TODO: set to optional for now, shouldn't be
 
     # PRE PROCESS
     time_prep: datetime  # TODO: should be optional

shepherd_core/data_models/task/programming.py

@@ -1,3 +1,5 @@
+"""Config for a Task programming the selected target."""
+
 import copy
 from pathlib import Path
 from typing import Optional
@@ -21,7 +23,7 @@ from ..testbed.testbed import Testbed
 
 
 class ProgrammingTask(ShpModel):
-    """Config for Task programming the target selected"""
+    """Config for a Task programming the selected target."""
 
     firmware_file: Path
     target_port: TargetPort = TargetPort.A

shepherd_core/data_models/task/testbed_tasks.py

@@ -1,12 +1,14 @@
+"""Collection of tasks for all observers included in experiment."""
+
 from typing import List
 from typing import Optional
 
-from pydantic import EmailStr
 from pydantic import Field
 from pydantic import validate_call
 from typing_extensions import Annotated
 from typing_extensions import Self
 
+from ..base.content import IdInt
 from ..base.content import NameStr
 from ..base.shepherd import ShpModel
 from ..experiment.experiment import Experiment
@@ -15,13 +17,16 @@ from .observer_tasks import ObserverTasks
 
 
 class TestbedTasks(ShpModel):
-    """Collection of tasks for all observers included in experiment"""
+    """Collection of tasks for all observers included in experiment."""
 
     name: NameStr
     observer_tasks: Annotated[List[ObserverTasks], Field(min_length=1, max_length=128)]
 
     # POST PROCESS
-    email: Optional[EmailStr] = None
+    email_results: bool = False
+    owner_id: Optional[IdInt]
+    # TODO: had real email previously, does it really need these at all?
+    #  DB stores experiment and knows when to email
 
     @classmethod
     @validate_call
@@ -34,7 +39,8 @@ class TestbedTasks(ShpModel):
         return cls(
             name=xp.name,
             observer_tasks=obs_tasks,
-            email=xp.email_results,
+            email_results=xp.email_results,
+            owner_id=xp.owner_id,
         )
 
     def get_observer_tasks(self, observer: str) -> Optional[ObserverTasks]:

shepherd_core/data_models/testbed/__init__.py

@@ -1,3 +1,8 @@
+"""Module for testbed-related data-models.
+
+These models import externally from: /base
+"""
+
 from .cape import Cape
 from .cape import TargetPort
 from .gpio import GPIO
@@ -10,8 +15,6 @@ from .target import IdInt16
 from .target import Target
 from .testbed import Testbed
 
-# these models import externally from: /base
-
 __all__ = [
     "Testbed",
     "Observer",

shepherd_core/data_models/testbed/cape.py

@@ -1,3 +1,5 @@
+"""meta-data representation of a testbed-component (physical object)."""
+
 from datetime import date
 from datetime import datetime
 from enum import Enum
@@ -15,16 +17,16 @@ from ..base.shepherd import ShpModel
 
 
 class TargetPort(str, Enum):
-    A = "A"
-    B = "B"
-    a = "A"
-    b = "B"
+    """Options for choosing a target-port."""
+
+    A = a = "A"
+    B = b = "B"
 
 
 class Cape(ShpModel, title="Shepherd-Cape"):
-    """meta-data representation of a testbed-component (physical object)"""
+    """meta-data representation of a testbed-component (physical object)."""
 
-    id: IdInt  # noqa: A003
+    id: IdInt
     name: NameStr
     version: NameStr
     description: SafeStr

shepherd_core/data_models/testbed/gpio.py

@@ -1,3 +1,5 @@
+"""meta-data representation of a testbed-component (physical object)."""
+
 from enum import Enum
 from typing import Optional
 
@@ -15,18 +17,17 @@ from ..base.shepherd import ShpModel
 
 
 class Direction(str, Enum):
-    Input = "IN"
-    IN = "IN"
-    Output = "OUT"
-    OUT = "OUT"
-    Bidirectional = "IO"
-    IO = "IO"
+    """Options for pin-direction."""
+
+    Input = IN = "IN"
+    Output = OUT = "OUT"
+    Bidirectional = IO = "IO"
 
 
 class GPIO(ShpModel, title="GPIO of Observer Node"):
-    """meta-data representation of a testbed-component"""
+    """meta-data representation of a testbed-component."""
 
-    id: IdInt  # noqa: A003
+    id: IdInt
     name: NameStr
     description: Optional[SafeStr] = None
     comment: Optional[SafeStr] = None
@@ -54,10 +55,11 @@ class GPIO(ShpModel, title="GPIO of Observer Node"):
         no_pru = (self.reg_pru is None) or (self.pin_pru is None)
         no_sys = (self.reg_sys is None) or (self.pin_sys is None)
         if no_pru and no_sys:
-            raise ValueError(
+            msg = (
                 "GPIO-Instance is faulty -> "
                 f"it needs to use pru or sys, content: {self.model_dump()}"
             )
+            raise ValueError(msg)
         return self
 
     def user_controllable(self) -> bool:

shepherd_core/data_models/testbed/mcu.py

@@ -1,3 +1,5 @@
+"""meta-data representation of a testbed-component (physical object)."""
+
 from enum import Enum
 from typing import Optional
 
@@ -13,20 +15,18 @@ from ..base.shepherd import ShpModel
 
 
 class ProgrammerProtocol(str, Enum):
-    SWD = "SWD"
-    swd = "SWD"
-    SBW = "SBW"
-    sbw = "SBW"
-    JTAG = "JTAG"
-    jtag = "JTAG"
-    UART = "UART"
-    uart = "UART"
+    """Options regarding the programming-protocol."""
+
+    SWD = swd = "SWD"
+    SBW = sbw = "SBW"
+    JTAG = jtag = "JTAG"
+    UART = uart = "UART"
 
 
 class MCU(ShpModel, title="Microcontroller of the Target Node"):
-    """meta-data representation of a testbed-component (physical object)"""
+    """meta-data representation of a testbed-component (physical object)."""
 
-    id: IdInt  # noqa: A003
+    id: IdInt
     name: NameStr
     description: SafeStr
     comment: Optional[SafeStr] = None