shepherd-core 2024.4.1__py3-none-any.whl → 2024.5.1__py3-none-any.whl

shepherd_core/fw_tools/converter.py

@@ -1,3 +1,5 @@
+"""Content-Converters for firmwares."""
+
 import base64
 import hashlib
 import shutil
@@ -15,21 +17,25 @@ from .validation import is_hex
 
 @validate_call
 def firmware_to_hex(file_path: Path) -> Path:
-    """Generic converter that handles ELF & HEX"""
+    """Convert ELF-Files to HEX.
+
+    Generic converter that handles ELF & HEX.
+    """
     if not file_path.is_file():
-        raise ValueError("Fn needs an existing file as input")
+        raise FileNotFoundError("Fn needs an existing file as input")
     if is_elf(file_path):
         return elf_to_hex(file_path)
     if is_hex(file_path):
         return file_path
-    raise ValueError("FW2Hex: unknown file '%s', it should be ELF or HEX", file_path.name)
+    raise FileNotFoundError("FW2Hex: unknown file '%s', it should be ELF or HEX", file_path.name)
 
 
 @validate_call
 def file_to_base64(file_path: Path) -> str:
-    """Compress and encode content of file
+    """Compress and encode content of file.
+
     - base64 adds ~33 % overhead
-    - zstd compression ~ 1:3
+    - zstd compression reduces to ~ 1:3
     """
     if not file_path.is_file():
         raise ValueError("Fn needs an existing file as input")
@@ -41,9 +47,10 @@ def file_to_base64(file_path: Path) -> str:
 
 @validate_call
 def base64_to_file(content: str, file_path: Path) -> None:
-    """DeCompress and decode Content of file
+    """DeCompress and decode Content of file.
+
     - base64 adds ~33 % overhead
-    - zstd compression ~ 1:3
+    - zstd compression reduces to ~ 1:3
     """
     file_cmpress = base64.b64decode(content)
     file_content = zstd.ZstdDecompressor().decompress(file_cmpress)
@@ -55,6 +62,7 @@ def base64_to_file(content: str, file_path: Path) -> None:
 
 @validate_call
 def file_to_hash(file_path: Path) -> str:
+    """Convert file-content to hash-value."""
     if not file_path.is_file():
         raise ValueError("Fn needs an existing file as input")
     with file_path.resolve().open("rb") as file:
@@ -64,6 +72,7 @@ def file_to_hash(file_path: Path) -> str:
 
 @validate_call
 def base64_to_hash(content: str) -> str:
+    """Convert base64-content to hash-value."""
     file_cmpress = base64.b64decode(content)
     file_content = zstd.ZstdDecompressor().decompress(file_cmpress)
     return hashlib.sha3_224(file_content).hexdigest()
@@ -71,8 +80,10 @@ def base64_to_hash(content: str) -> str:
 
 @validate_call
 def extract_firmware(data: Union[str, Path], data_type: FirmwareDType, file_path: Path) -> Path:
-    """- base64-string will be transformed into file
-    - if data is a path the file will be copied to the destination
+    """Make embedded firmware-data usable in filesystem.
+
+    - base64-string will be transformed to file
+    - if data is a path the file will be copied to the destination.
     """
     if data_type == FirmwareDType.base64_elf:
         file = file_path.with_suffix(".elf")

shepherd_core/fw_tools/converter_elf.py

@@ -1,3 +1,5 @@
+"""Converter for ELF-files."""
+
 import subprocess
 from pathlib import Path
 from typing import Optional
@@ -9,6 +11,7 @@ from pydantic import validate_call
 
 @validate_call
 def elf_to_hex(file_elf: Path, file_hex: Optional[Path] = None) -> Path:
+    """Convert ELF to hex file using objcopy."""
     if not file_elf.is_file():
         raise ValueError("Fn needs an existing file as input")
     if not file_hex:

shepherd_core/fw_tools/patcher.py

@@ -1,3 +1,5 @@
+"""Read and modify symbols in ELF-files."""
+
 from pathlib import Path
 from typing import Optional
 
@@ -15,13 +17,14 @@ try:
 except ImportError as e:
     ELF = None
     elf_error_text = (
-        "Please install functionality with 'pip install shepherd_core[elf] -U' first, "
+        "Please install functionality with 'pip install shepherd-core[elf] -U' first, "
         f"underlying exception: {e.msg}"
     )
 
 
 @validate_call
 def find_symbol(file_elf: Path, symbol: str) -> bool:
+    """Find a symbol in the ELF file."""
     if symbol is None or not is_elf(file_elf):
         return False
     if ELF is None:
@@ -47,7 +50,10 @@ def find_symbol(file_elf: Path, symbol: str) -> bool:
 
 @validate_call
 def read_symbol(file_elf: Path, symbol: str, length: int = uid_len_default) -> Optional[int]:
-    """Interpreted as int"""
+    """Read value of symbol in ELF-File.
+
+    Will be interpreted as int.
+    """
     if not find_symbol(file_elf, symbol):
         return None
     if ELF is None:
@@ -60,10 +66,12 @@ def read_symbol(file_elf: Path, symbol: str, length: int = uid_len_default) -> O
 
 
 def read_uid(file_elf: Path) -> Optional[int]:
+    """Read value of UID-symbol for shepherd testbed."""
     return read_symbol(file_elf, symbol=uid_str_default, length=uid_len_default)
 
 
 def read_arch(file_elf: Path) -> Optional[str]:
+    """Determine chip-architecture from elf-metadata."""
     if not is_elf(file_elf):
         return None
     if ELF is None:
@@ -83,9 +91,12 @@ def modify_symbol_value(
     *,
     overwrite: bool = False,
 ) -> Optional[Path]:
-    """Replaces value of symbol in ELF-File, hardcoded for uint16_t (2 byte)
-    testbed uses FN to patch firmware with custom target-ID
-    NOTE: can overwrite provided file
+    """Replace value of uint16-symbol in ELF-File.
+
+    Hardcoded for uint16_t (2 byte).
+    The testbed uses this to patch firmware with custom target-ID.
+
+    NOTE: can overwrite provided file.
 
     """
     if not find_symbol(file_elf, symbol):
@@ -121,4 +132,5 @@ def modify_symbol_value(
 
 
 def modify_uid(file_elf: Path, value: int) -> Optional[Path]:
+    """Replace value of UID-symbol for shepherd testbed."""
     return modify_symbol_value(file_elf, symbol=uid_str_default, value=value, overwrite=True)

shepherd_core/fw_tools/validation.py

@@ -1,4 +1,9 @@
-"""TODO: Work in Progress"""
+"""Helper-functions for firmware-validation.
+
+TODO: Work in Progress.
+    - Each arch should have its own file and
+    - detection-functions that register in main validator.
+"""
 
 import tempfile
 from pathlib import Path
@@ -18,13 +23,14 @@ except ImportError as e:
     ELF = None
     ELFError = None
     elf_error_text = (
-        "Please install functionality with 'pip install shepherd_core[elf] -U' first, "
+        "Please install functionality with 'pip install shepherd-core[elf] -U' first, "
         f"underlying exception: {e.msg}"
     )
 
 
 @validate_call
 def is_hex(file: Path) -> bool:
+    """Check if file is containing intel-hex data."""
     try:
         _ = IntelHex(file.as_posix())
     except ValueError:  # parsing
@@ -35,7 +41,9 @@ def is_hex(file: Path) -> bool:
 
 
 def is_hex_msp430(file: Path) -> bool:
-    """Observations:
+    """Try to detect specifics for that MCU.
+
+    Observations:
     - addresses begin at 0x4000
     - value @0xFFFE (IVT) is start_address (of pgm-code)
     """
@@ -56,7 +64,9 @@ def is_hex_msp430(file: Path) -> bool:
 
 
 def is_hex_nrf52(file: Path) -> bool:
-    """Observations:
+    """Try to detect specifics for that MCU.
+
+    Observations:
     - addresses begin at 0x0
     - only one segment (.get_segments), todo
     """
@@ -79,6 +89,7 @@ def is_hex_nrf52(file: Path) -> bool:
 
 @validate_call
 def is_elf(file: Path) -> bool:
+    """Check if file is an ELF file."""
     if ELF is None:
         raise RuntimeError(elf_error_text)
     if not file.is_file():
@@ -91,7 +102,11 @@ def is_elf(file: Path) -> bool:
     return True
 
 
-def is_elf_msp430(file: Path) -> bool:  # TODO: allow detection without conversion
+def is_elf_msp430(file: Path) -> bool:
+    """Check if file is an ELF for that MCU.
+
+    TODO: allow detection without conversion
+    """
     if is_elf(file):
         with tempfile.TemporaryDirectory() as path:
             file_hex = Path(path) / "file.hex"
@@ -102,7 +117,11 @@ def is_elf_msp430(file: Path) -> bool:  # TODO: allow detection without conversi
     return False
 
 
-def is_elf_nrf52(file: Path) -> bool:  # TODO: allow detection without conversion
+def is_elf_nrf52(file: Path) -> bool:
+    """Check if file is an ELF for that MCU.
+
+    TODO: allow detection without conversion
+    """
     if is_elf(file):
         with tempfile.TemporaryDirectory() as path:
             file_hex = Path(path) / "file.hex"
@@ -114,6 +133,7 @@ def is_elf_nrf52(file: Path) -> bool:  # TODO: allow detection without conversio
 
 
 def determine_type(file: Path) -> FirmwareDType:
+    """Figure out file-type (hex or elf)."""
     if not file.is_file():
         raise ValueError("Fn needs an existing file as input")
     if is_hex(file):
@@ -124,6 +144,7 @@ def determine_type(file: Path) -> FirmwareDType:
 
 
 def determine_arch(file: Path) -> str:
+    """Figure out arch (msp430 or nrf52)."""
     file_t = determine_type(file)
     if file_t == FirmwareDType.path_elf:
         if is_elf_nrf52(file):

shepherd_core/inventory/__init__.py

@@ -1,7 +1,9 @@
-"""Creates an overview for shepherd-host-machines with:
+"""Creates an overview for shepherd-host-machines.
+
+This will collect:
 - relevant software-versions
 - system-parameters
-- hardware-config
+- hardware-config.
 """
 
 from datetime import datetime
@@ -28,7 +30,11 @@ __all__ = [
 
 
 class Inventory(PythonInventory, SystemInventory, TargetInventory):
-    # has all child-parameters
+    """Complete inventory for one device.
+
+    Has all child-parameters.
+    """
+
     hostname: str
     created: datetime
 
@@ -47,12 +53,16 @@ class Inventory(PythonInventory, SystemInventory, TargetInventory):
 
 
 class InventoryList(ShpModel):
+    """Collection of inventories for several devices."""
+
     elements: Annotated[List[Inventory], Field(min_length=1)]
 
     def to_csv(self, path: Path) -> None:
-        """TODO: pretty messed up (raw lists and dicts for sub-elements)
+        """Generate a CSV.
+
+        TODO: pretty messed up (raw lists and dicts for sub-elements)
         numpy.savetxt -> too basic
-        np.concatenate(content).reshape((len(content), len(content[0])))
+        np.concatenate(content).reshape((len(content), len(content[0]))).
         """
         if path.is_dir():
             path = path / "inventory.yaml"

shepherd_core/inventory/python.py

@@ -1,3 +1,5 @@
+"""Python related inventory model."""
+
 import platform
 from contextlib import suppress
 from importlib import import_module
@@ -10,6 +12,8 @@ from ..data_models import ShpModel
 
 
 class PythonInventory(ShpModel):
+    """Python related inventory model."""
+
     # program versions
     h5py: Optional[str] = None
     numpy: Optional[str] = None

shepherd_core/inventory/system.py

@@ -1,3 +1,5 @@
+"""System / OS related inventory model."""
+
 import platform
 import subprocess
 import time
@@ -7,8 +9,8 @@ from typing import Optional
 
 from typing_extensions import Self
 
-from .. import local_now
-from .. import logger
+from ..data_models.base.timezone import local_now
+from ..logger import logger
 
 try:
     import psutil
@@ -22,6 +24,8 @@ from ..data_models import ShpModel
 
 
 class SystemInventory(ShpModel):
+    """System / OS related inventory model."""
+
     uptime: PositiveInt
     # ⤷ seconds
     timestamp: datetime

shepherd_core/inventory/target.py

@@ -1,3 +1,5 @@
+"""Hardware related inventory model."""
+
 from typing import List
 from typing import Optional
 
@@ -8,6 +10,8 @@ from ..data_models import ShpModel
 
 
 class TargetInventory(ShpModel):
+    """Hardware related inventory model."""
+
     cape: Optional[str] = None
     targets: List[str] = []  # noqa: RUF012
 

shepherd_core/logger.py

@@ -1,3 +1,5 @@
+"""Log handler of shepherd."""
+
 import logging
 import logging.handlers
 from typing import Union
@@ -12,10 +14,12 @@ verbose_level: int = 2
 
 
 def get_verbose_level() -> int:
+    """Get log level of shepherd."""
     return verbose_level
 
 
 def set_log_verbose_level(log_: Union[logging.Logger, logging.Handler], verbose: int) -> None:
+    """Set log level of shepherd."""
     if verbose == 0:
         log_.setLevel(logging.ERROR)
         logging.basicConfig(level=logging.ERROR)
@@ -39,6 +43,7 @@ def set_log_verbose_level(log_: Union[logging.Logger, logging.Handler], verbose:
 
 
 def increase_verbose_level(verbose: int) -> None:
+    """Increase log level of shepherd."""
     global verbose_level  # noqa: PLW0603
     if verbose >= verbose_level:
         verbose_level = min(max(verbose, 0), 3)

shepherd_core/reader.py

@@ -1,4 +1,6 @@
-"""Reader-Baseclass"""
+"""Reader-Baseclass."""
+
+from __future__ import annotations
 
 import contextlib
 import errno
@@ -7,7 +9,7 @@ import math
 import os
 from itertools import product
 from pathlib import Path
-from types import TracebackType
+from typing import TYPE_CHECKING
 from typing import Any
 from typing import ClassVar
 from typing import Dict
@@ -30,6 +32,9 @@ from .data_models.base.calibration import CalibrationSeries
 from .data_models.content.energy_environment import EnergyDType
 from .decoder_waveform import Uart
 
+if TYPE_CHECKING:
+    from types import TracebackType
+
 
 class Reader:
     """Sequentially Reads shepherd-data from HDF5 file.
@@ -96,7 +101,8 @@ class Reader:
                 self.h5file = h5py.File(self.file_path, "r")  # = readonly
                 self._reader_opened = True
             except OSError as _xcp:
-                raise TypeError(f"Unable to open HDF5-File '{self.file_path.name}'") from _xcp
+                msg = f"Unable to open HDF5-File '{self.file_path.name}'"
+                raise TypeError(msg) from _xcp
 
             if self.is_valid():
                 self._logger.debug("File is available now")
@@ -159,7 +165,7 @@ class Reader:
         )
 
     def _refresh_file_stats(self) -> None:
-        """Update internal states, helpful after resampling or other changes in data-group"""
+        """Update internal states, helpful after resampling or other changes in data-group."""
         self.h5file.flush()
         if (self.ds_time.shape[0] > 1) and (self.ds_time[1] != self.ds_time[0]):
             # this assumes isochronal sampling
@@ -181,10 +187,11 @@ class Reader:
         is_raw: bool = False,
         omit_ts: bool = False,
     ) -> Generator[tuple, None, None]:
-        """Generator that reads the specified range of buffers from the hdf5 file.
-        can be configured on first call
+        """Read the specified range of buffers from the hdf5 file.
+
+        Generator - can be configured on first call
         TODO: reconstruct - start/end mark samples &
-         each call can request a certain number of samples
+         each call can request a certain number of samples.
 
         Args:
         ----
@@ -218,7 +225,7 @@ class Reader:
                 )
 
     def get_calibration_data(self) -> CalibrationSeries:
-        """Reads calibration-data from hdf5 file.
+        """Read calibration-data from hdf5 file.
 
         :return: Calibration data as CalibrationSeries object
         """
@@ -248,12 +255,14 @@ class Reader:
         try:
             if "datatype" in self.h5file["data"].attrs:
                 return EnergyDType[self.h5file["data"].attrs["datatype"]]
-            return None
         except KeyError:
             return None
+        else:
+            return None
 
     def get_hrv_config(self) -> dict:
-        """Essential info for harvester
+        """Essential info for harvester.
+
         :return: config-dict directly for vHarvester to be used during emulation
         """
         return {
@@ -262,7 +271,7 @@ class Reader:
         }
 
     def is_valid(self) -> bool:
-        """Checks file for plausibility
+        """Check file for plausibility, validity / correctness.
 
         :return: state of validity
         """
@@ -390,7 +399,7 @@ class Reader:
         return True
 
     def __getitem__(self, key: str) -> Any:
-        """Returns attribute or (if none found) a handle for a group or dataset (if found)
+        """Query attribute or (if none found) a handle for a group or dataset (if found).
 
         :param key: attribute, group, dataset
         :return: value of that key, or handle of object
@@ -402,9 +411,10 @@ class Reader:
         raise KeyError
 
     def energy(self) -> float:
-        """Determine the recorded energy of the trace
+        """Determine the recorded energy of the trace.
+
         # multiprocessing: https://stackoverflow.com/a/71898911
-        # -> failed with multiprocessing.pool and pathos.multiprocessing.ProcessPool
+        # -> failed with multiprocessing.pool and pathos.multiprocessing.ProcessPool.
 
         :return: sampled energy in Ws (watt-seconds)
         """
@@ -430,7 +440,8 @@ class Reader:
     def _dset_statistics(
         self, dset: h5py.Dataset, cal: Optional[CalibrationPair] = None
     ) -> Dict[str, float]:
-        """Some basic stats for a provided dataset
+        """Create basic stats for a provided dataset.
+
         :param dset: dataset to evaluate
         :param cal: calibration (if wanted)
         :return: dict with entries for mean, min, max, std
@@ -472,8 +483,9 @@ class Reader:
         return stats
 
     def _data_timediffs(self) -> List[float]:
-        """Calculate list of (unique) time-deltas between buffers [s]
-            -> optimized version that only looks at the start of each buffer
+        """Calculate list of unique time-deltas [s] between buffers.
+
+        Optimized version that only looks at the start of each buffer.
 
         :return: list of (unique) time-deltas between buffers [s]
         """
@@ -503,8 +515,9 @@ class Reader:
         return list(diffs)
 
     def check_timediffs(self) -> bool:
-        """Validate equal time-deltas
-        -> unexpected time-jumps hint at a corrupted file or faulty measurement
+        """Validate equal time-deltas.
+
+        Unexpected time-jumps hint at a corrupted file or faulty measurement.
 
         :return: True if OK
         """
@@ -532,7 +545,8 @@ class Reader:
         *,
         minimal: bool = False,
     ) -> Dict[str, dict]:
-        """Recursive FN to capture the structure of the file
+        """Recursive FN to capture the structure of the file.
+
         :param node: starting node, leave free to go through whole file
         :param minimal: just provide a bare tree (much faster)
         :return: structure of that node with everything inside it
@@ -583,7 +597,7 @@ class Reader:
         return metadata
 
     def save_metadata(self, node: Union[h5py.Dataset, h5py.Group, None] = None) -> dict:
-        """Get structure of file and dump content to yaml-file with same name as original
+        """Get structure of file and dump content to yaml-file with same name as original.
 
         :param node: starting node, leave free to go through whole file
         :return: structure of that node with everything inside it
@@ -612,8 +626,9 @@ class Reader:
 
     @staticmethod
     def get_filter_for_redundant_states(data: np.ndarray) -> np.ndarray:
-        """Input is 1D state-vector, kep only first from identical & sequential states
-        algo: create an offset-by-one vector and compare against original
+        """Input is 1D state-vector, kep only first from identical & sequential states.
+
+        Algo: create an offset-by-one vector and compare against original.
         """
         if len(data.shape) > 1:
             ValueError("Array must be 1D")

shepherd_core/testbed_client/__init__.py

@@ -1,3 +1,5 @@
+"""Client to access a testbed-instance for controlling experiments."""
+
 from .client import tb_client
 from .user_model import User
 

shepherd_core/testbed_client/cache_path.py

@@ -1,3 +1,5 @@
+"""Generalized path for the file-cache."""
+
 import os
 from pathlib import Path
 

shepherd_core/testbed_client/client.py

@@ -1,3 +1,5 @@
+"""Client-Class to access a testbed instance."""
+
 from importlib import import_module
 from pathlib import Path
 from typing import Optional
@@ -16,6 +18,8 @@ from .user_model import User
 
 
 class TestbedClient:
+    """Client-Class to access a testbed instance."""
+
     _instance: Optional[Self] = None
 
     def __init__(self, server: Optional[str] = None, token: Union[str, Path, None] = None) -> None:
@@ -41,8 +45,10 @@ class TestbedClient:
 
     @validate_call
     def connect(self, server: Optional[str] = None, token: Union[str, Path, None] = None) -> bool:
-        """server: either "local" to use demo-fixtures or something like "https://HOST:PORT"
-        token: your account validation
+        """Establish connection to testbed-server.
+
+        server: either "local" to use demo-fixtures or something like "https://HOST:PORT"
+        token: your account validation.
         """
         if isinstance(token, Path):
             with token.resolve().open() as file:
@@ -77,19 +83,19 @@ class TestbedClient:
 
     def query_ids(self, model_type: str) -> list:
         if self._connected:
-            raise RuntimeError("Not Implemented, TODO")
+            raise NotImplementedError("TODO")
         return list(self._fixtures[model_type].elements_by_id.keys())
 
     def query_names(self, model_type: str) -> list:
         if self._connected:
-            raise RuntimeError("Not Implemented, TODO")
+            raise NotImplementedError("TODO")
         return list(self._fixtures[model_type].elements_by_name.keys())
 
     def query_item(
         self, model_type: str, uid: Optional[int] = None, name: Optional[str] = None
     ) -> dict:
         if self._connected:
-            raise RuntimeError("Not Implemented, TODO")
+            raise NotImplementedError("TODO")
         if uid is not None:
             return self._fixtures[model_type].query_id(uid)
         if name is not None:
@@ -115,11 +121,11 @@ class TestbedClient:
 
     def try_inheritance(self, model_type: str, values: dict) -> (dict, list):
         if self._connected:
-            raise RuntimeError("Not Implemented, TODO")
+            raise NotImplementedError("TODO")
         return self._fixtures[model_type].inheritance(values)
 
     def try_completing_model(self, model_type: str, values: dict) -> (dict, list):
-        """Init by name/id, for none existing instances raise Exception"""
+        """Init by name/id, for none existing instances raise Exception."""
         if len(values) == 1 and next(iter(values.keys())) in {"id", "name"}:
             value = next(iter(values.values()))
             if (
@@ -131,7 +137,8 @@ class TestbedClient:
                 # TODO: still depending on _fixture
                 values = self.query_item(model_type, uid=value)
             else:
-                raise ValueError(f"Query {model_type} by name / ID failed - {values} is unknown!")
+                msg = f"Query {model_type} by name / ID failed - {values} is unknown!"
+                raise ValueError(msg)
         return self.try_inheritance(model_type, values)
 
     def fill_in_user_data(self, values: dict) -> dict: