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

shepherd_core/testbed_client/fixtures.py

@@ -1,3 +1,5 @@
+"""Current implementation of a file-based database."""
+
 import copy
 import os
 import pickle
@@ -18,6 +20,7 @@ from ..data_models.base.timezone import local_now
 from ..data_models.base.timezone import local_tz
 from ..data_models.base.wrapper import Wrapper
 from ..logger import logger
+from .cache_path import cache_user_path
 
 # Proposed field-name:
 # - inheritance
@@ -28,7 +31,7 @@ from ..logger import logger
 
 
 class Fixture:
-    """Current implementation of a file-based database"""
+    """Current implementation of a file-based database."""
 
     def __init__(self, model_type: str) -> None:
         self.model_type: str = model_type.lower()
@@ -62,7 +65,8 @@ class Fixture:
             key = int(key) if key.isdigit() else None
         if key in self.elements_by_id:
             return self.elements_by_id[int(key)]
-        raise ValueError(f"{self.model_type} '{key}' not found!")
+        msg = f"{self.model_type} '{key}' not found!"
+        raise ValueError(msg)
 
     def __iter__(self) -> Self:
         self._iter_index = 0
@@ -94,12 +98,14 @@ class Fixture:
             if "name" in values and len(chain) < 1:
                 base_name = values.get("name")
                 if base_name in chain:
+                    msg = f"Inheritance-Circle detected ({base_name} already in {chain})"
                     raise ValueError(
-                        f"Inheritance-Circle detected ({base_name} already in {chain})",
+                        msg,
                     )
                 if base_name == fixture_name:
+                    msg = f"Inheritance-Circle detected ({base_name} == {fixture_name})"
                     raise ValueError(
-                        f"Inheritance-Circle detected ({base_name} == {fixture_name})",
+                        msg,
                     )
                 chain.append(base_name)
             fixture_base = copy.copy(self[fixture_name])
@@ -148,15 +154,18 @@ class Fixture:
     def query_id(self, _id: int) -> dict:
         if isinstance(_id, int) and _id in self.elements_by_id:
             return self.elements_by_id[_id]
-        raise ValueError(f"Initialization of {self.model_type} by ID failed - {_id} is unknown!")
+        msg = f"Initialization of {self.model_type} by ID failed - {_id} is unknown!"
+        raise ValueError(msg)
 
     def query_name(self, name: str) -> dict:
         if isinstance(name, str) and name.lower() in self.elements_by_name:
             return self.elements_by_name[name.lower()]
-        raise ValueError(f"Initialization of {self.model_type} by name failed - {name} is unknown!")
+        msg = f"Initialization of {self.model_type} by name failed - {name} is unknown!"
+        raise ValueError(msg)
 
 
 def file_older_than(file: Path, delta: timedelta) -> bool:
+    """Decide if file is older than a specific duration of time."""
     cutoff = local_now() - delta
     mtime = datetime.fromtimestamp(file.stat().st_mtime, tz=local_tz())
     if mtime < cutoff:
@@ -165,6 +174,8 @@ def file_older_than(file: Path, delta: timedelta) -> bool:
 
 
 class Fixtures:
+    """A collection of individual fixture-elements."""
+
     suffix = ".yaml"
 
     @validate_call
@@ -174,10 +185,11 @@ class Fixtures:
         else:
             self.file_path = file_path
         self.components: Dict[str, Fixture] = {}
-        save_path = self.file_path / "fixtures.pickle"
+        save_path = cache_user_path / "fixtures.pickle"
 
         if save_path.exists() and not file_older_than(save_path, timedelta(hours=24)) and not reset:
             # speedup
+            # TODO: also add version as criterion
             with save_path.open("rb", buffering=-1) as fd:
                 self.components = pickle.load(fd)  # noqa: S301
             logger.debug(" -> found & used pickled fixtures")
@@ -192,8 +204,12 @@ class Fixtures:
             for file in files:
                 self.insert_file(file)
 
-            with save_path.open("wb", buffering=-1) as fd:
-                pickle.dump(self.components, fd)
+            if len(self.components) < 1:
+                logger.error(f"No fixture-components found at {self.file_path.as_posix()}")
+            else:
+                save_path.parent.mkdir(parents=True, exist_ok=True)
+                with save_path.open("wb", buffering=-1) as fd:
+                    pickle.dump(self.components, fd)
 
     @validate_call
     def insert_file(self, file: Path) -> None:
@@ -215,17 +231,20 @@ class Fixtures:
         key = key.lower()
         if key in self.components:
             return self.components[key]
-        raise ValueError(f"Component '{key}' not found!")
+        msg = f"Component '{key}' not found!"
+        raise ValueError(msg)
 
     def keys(self):  # noqa: ANN201
         return self.components.keys()
 
     @staticmethod
     def to_file(file: Path) -> None:
-        raise RuntimeError(f"Not Implemented, TODO (val={file})")
+        msg = f"TODO (val={file})"
+        raise NotImplementedError(msg)
 
 
 def get_files(start_path: Path, suffix: str, recursion_depth: int = 0) -> List[Path]:
+    """Generate a recursive list of all files in a directory."""
     if recursion_depth == 0:
         suffix = suffix.lower().split(".")[-1]
     dir_items = os.scandir(start_path)

shepherd_core/testbed_client/user_model.py

@@ -1,7 +1,12 @@
+"""Model for user-management."""
+
 import secrets
 from hashlib import pbkdf2_hmac
 from typing import Optional
+from typing import Union
+from uuid import uuid4
 
+from pydantic import UUID4
 from pydantic import EmailStr
 from pydantic import Field
 from pydantic import SecretBytes
@@ -11,17 +16,18 @@ from pydantic import model_validator
 from pydantic import validate_call
 from typing_extensions import Annotated
 
-from ..data_models.base.content import IdInt
 from ..data_models.base.content import NameStr
 from ..data_models.base.content import SafeStr
-from ..data_models.base.content import id_default
 from ..data_models.base.shepherd import ShpModel
 
 
 @validate_call
 def hash_password(pw: Annotated[str, StringConstraints(min_length=20, max_length=100)]) -> bytes:
-    # TODO: add salt of testbed -> this fn should be part of Testbed-Object
+    """Generate a hash of a string.
+
     # NOTE: 1M Iterations need 25s on beaglebone
+    # TODO: add salt of testbed -> this fn should be part of Testbed-Object
+    """
     return pbkdf2_hmac(
         "sha512",
         password=pw.encode("utf-8"),
@@ -32,11 +38,12 @@ def hash_password(pw: Annotated[str, StringConstraints(min_length=20, max_length
 
 
 class User(ShpModel):
-    """meta-data representation of a testbed-component (physical object)"""
+    """meta-data representation of a testbed-component (physical object)."""
 
-    id: IdInt = Field(  # noqa: A003
+    # id: UUID4 = Field(  # TODO: db-migration - temp fix for documentation
+    id: Union[UUID4, int] = Field(
         description="Unique ID",
-        default_factory=id_default,
+        default_factory=uuid4,
     )
     name: NameStr
     description: Optional[SafeStr] = None

shepherd_core/vsource/__init__.py

@@ -1,3 +1,5 @@
+"""Simulation model of the virtual source."""
+
 from .virtual_converter_model import PruCalibration
 from .virtual_converter_model import VirtualConverterModel
 from .virtual_harvester_model import VirtualHarvesterModel

shepherd_core/vsource/virtual_converter_model.py

@@ -1,4 +1,7 @@
-"""this is ported py-version of the pru-code, goals:
+"""This is ported py-version of the pru-code.
+
+Goals:
+
 - stay close to original code-base
 - offer a comparison for the tests
 - step 1 to a virtualization of emulation
@@ -6,7 +9,8 @@
 NOTE: DO NOT OPTIMIZE -> stay close to original code-base
 
 Compromises:
-- bitshifted values (ie. _n28) are converted to float without shift
+
+- bitshifted values (i.e. _n28) are converted to float without shift
 
 """
 
@@ -19,7 +23,7 @@ from ..data_models.content.virtual_source import ConverterPRUConfig
 
 
 class PruCalibration:
-    """part of calibration.h"""
+    """part of calibration.h."""
 
     def __init__(self, cal_emu: Optional[CalibrationEmulator] = None) -> None:
         self.cal = cal_emu if cal_emu else CalibrationEmulator()
@@ -30,7 +34,8 @@ class PruCalibration:
 
     @staticmethod
     def conv_adc_raw_to_uV(voltage_raw: int) -> float:
-        raise RuntimeError(f"This Fn should not been used (val={voltage_raw})")
+        msg = f"This Fn should not been used (val={voltage_raw})"
+        raise RuntimeError(msg)
 
     def conv_uV_to_dac_raw(self, voltage_uV: float) -> int:
         dac_raw = self.cal.dac_V_A.si_to_raw(float(voltage_uV) / (10**6))
@@ -40,6 +45,8 @@ class PruCalibration:
 
 
 class VirtualConverterModel:
+    """Ported python version of the pru vCnv."""
+
     def __init__(self, cfg: ConverterPRUConfig, cal: PruCalibration) -> None:
         self._cal: PruCalibration = cal
         self._cfg: ConverterPRUConfig = cfg

shepherd_core/vsource/virtual_harvester_model.py

@@ -1,4 +1,7 @@
-"""this is ported py-version of the pru-code, goals:
+"""this is ported py-version of the pru-code.
+
+Goals:
+
 - stay close to original code-base
 - offer a comparison for the tests
 - step 1 to a virtualization of emulation
@@ -7,16 +10,20 @@ NOTE1: DO NOT OPTIMIZE -> stay close to original c-code-base
 NOTE2: adc-harvest-routines are not part of this model (virtual_harvester lines 66:289)
 
 Compromises:
+
 - Py has to map the settings-list to internal vars -> is kernel-task
 - Python has no static vars -> FName_reset is handling the class-vars
 
 """
+
 from typing import Tuple
 
 from ..data_models.content.virtual_harvester import HarvesterPRUConfig
 
 
 class VirtualHarvesterModel:
+    """Ported python version of the pru vHrv."""
+
     HRV_IVCURVE: int = 2**4
     HRV_CV: int = 2**8
     HRV_MPPT_VOC: int = 2**12

shepherd_core/vsource/virtual_source_model.py

@@ -1,11 +1,15 @@
-"""this is ported py-version of the pru-code, goals:
+"""This is ported py-version of the pru-code.
+
+Goals:
+
 - stay close to original code-base
 - offer a comparison for the tests
-- step 1 to a virtualization of emulation
+- step 1 to a virtualization of emulation.
 
 NOTE: DO NOT OPTIMIZE -> stay close to original code-base
 
 """
+
 from typing import Optional
 
 from ..data_models import CalibrationEmulator
@@ -19,7 +23,7 @@ from .virtual_harvester_model import VirtualHarvesterModel
 
 
 class VirtualSourceModel:
-    """part of sampling.c"""
+    """part of sampling.c."""
 
     def __init__(
         self,
@@ -52,8 +56,9 @@ class VirtualSourceModel:
         self.W_out_fWs: float = 0.0
 
     def iterate_sampling(self, V_inp_uV: int = 0, I_inp_nA: int = 0, I_out_nA: int = 0) -> int:
-        """TEST-SIMPLIFICATION - code below is not part of pru-code,
-        but in part sample_emulator() in sampling.c
+        """TEST-SIMPLIFICATION - code below is not part of pru-code.
+
+        It originates from sample_emulator() in sampling.c.
 
         :param V_inp_uV:
         :param I_inp_nA:

shepherd_core/writer.py

@@ -1,5 +1,5 @@
-"""Writer that inherits from Reader-Baseclass
-"""
+"""Writer that inherits from Reader-Baseclass."""
+
 import logging
 import math
 import pathlib
@@ -35,10 +35,12 @@ from .reader import Reader
 def path2str(
     dumper: Dumper, data: Union[pathlib.Path, pathlib.WindowsPath, pathlib.PosixPath]
 ) -> ScalarNode:
+    """Add a yaml-representation for a specific datatype."""
     return dumper.represent_scalar("tag:yaml.org,2002:str", str(data.as_posix()))
 
 
 def time2int(dumper: Dumper, data: timedelta) -> ScalarNode:
+    """Add a yaml-representation for a specific datatype."""
     return dumper.represent_scalar("tag:yaml.org,2002:int", str(int(data.total_seconds())))
 
 
@@ -49,7 +51,7 @@ yaml.add_representer(timedelta, time2int, SafeDumper)
 
 
 def unique_path(base_path: Union[str, Path], suffix: str) -> Path:
-    """Finds an unused filename in case it already exists
+    """Find an unused filename in case it already exists.
 
     :param base_path: file-path to test
     :param suffix: file-suffix
@@ -64,7 +66,7 @@ def unique_path(base_path: Union[str, Path], suffix: str) -> Path:
 
 
 class Writer(Reader):
-    """Stores data for Shepherd in HDF5 format
+    """Stores data for Shepherd in HDF5 format.
 
     Choose lossless compression filter
      - lzf:  low to moderate compression, VERY fast, no options
@@ -87,6 +89,7 @@ class Writer(Reader):
             otherwise a unique name will be found
         compression: (str) use either None, lzf or "1" (gzips compression level)
         verbose: (bool) provides more debug-info
+
     """
 
     comp_default: int = 1
@@ -123,7 +126,8 @@ class Writer(Reader):
             self.file_path: Path = file_path.resolve()
             self._logger.info("Storing data to   '%s'", self.file_path)
         elif file_path.exists() and not file_path.is_file():
-            raise TypeError(f"Path is not a file ({file_path})")
+            msg = f"Path is not a file ({file_path})"
+            raise TypeError(msg)
         else:
             base_dir = file_path.resolve().parents[0]
             self.file_path = unique_path(base_dir / file_path.stem, file_path.suffix)
@@ -134,15 +138,15 @@ class Writer(Reader):
             )
 
         if isinstance(mode, str) and mode not in self.mode_dtype_dict:
-            raise ValueError(f"Can't handle mode '{mode}' (choose one of {self.mode_dtype_dict})")
+            msg = f"Can't handle mode '{mode}' (choose one of {self.mode_dtype_dict})"
+            raise ValueError(msg)
 
-        _dtypes = self.mode_dtype_dict[mode if mode else self.mode_default]
+        _dtypes = self.mode_dtype_dict[mode or self.mode_default]
         if isinstance(datatype, str):
             datatype = EnergyDType[datatype]
         if isinstance(datatype, EnergyDType) and datatype not in _dtypes:
-            raise ValueError(
-                f"Can't handle value '{datatype}' of datatype (choose one of {_dtypes})"
-            )
+            msg = f"Can't handle value '{datatype}' of datatype (choose one of {_dtypes})"
+            raise ValueError(msg)
 
         if self._modify:
             self._mode = mode
@@ -222,7 +226,7 @@ class Writer(Reader):
         self.h5file.close()
 
     def _create_skeleton(self) -> None:
-        """Initializes the structure of the HDF5 file
+        """Initialize the structure of the HDF5 file.
 
         HDF5 is hierarchically structured and before writing data, we have to
         setup this structure, i.e. creating the right groups with corresponding
@@ -278,13 +282,14 @@ class Writer(Reader):
         voltage: np.ndarray,
         current: np.ndarray,
     ) -> None:
-        """Writes raw data to database
+        """Write raw data to database.
 
         Args:
         ----
             timestamp: just start of buffer or whole ndarray
             voltage: ndarray as raw unsigned integers
             current: ndarray as raw unsigned integers
+
         """
         len_new = min(voltage.size, current.size)
 
@@ -296,7 +301,7 @@ class Writer(Reader):
         if isinstance(timestamp, np.ndarray):
             len_new = min(len_new, timestamp.size)
         else:
-            raise ValueError("timestamp-data was not usable")
+            raise TypeError("timestamp-data was not usable")
 
         len_old = self.ds_voltage.shape[0]
 
@@ -316,7 +321,9 @@ class Writer(Reader):
         voltage: np.ndarray,
         current: np.ndarray,
     ) -> None:
-        """Writes data (in SI / physical unit) to file, but converts it to raw-data first
+        """Write data (provided in SI / physical unit) to file.
+
+        This will convert it to raw-data first.
 
            SI-value [SI-Unit] = raw-value * gain + offset,
 
@@ -326,6 +333,7 @@ class Writer(Reader):
                        -> provide start of buffer or whole ndarray
             voltage: ndarray in physical-unit V
             current: ndarray in physical-unit A
+
         """
         timestamp = self._cal.time.si_to_raw(timestamp)
         voltage = self._cal.voltage.si_to_raw(voltage)
@@ -333,7 +341,7 @@ class Writer(Reader):
         self.append_iv_data_raw(timestamp, voltage, current)
 
     def _align(self) -> None:
-        """Align datasets with buffer-size of shepherd"""
+        """Align datasets with buffer-size of shepherd."""
         self._refresh_file_stats()
         n_buff = self.ds_voltage.size / self.samples_per_buffer
         size_new = int(math.floor(n_buff) * self.samples_per_buffer)
@@ -350,21 +358,21 @@ class Writer(Reader):
             self.ds_current.resize((size_new,))
 
     def __setitem__(self, key: str, item: Any) -> None:
-        """A convenient interface to store relevant key-value data (attribute) if H5-structure"""
+        """Conveniently store relevant key-value data (attribute) in H5-structure."""
         self.h5file.attrs.__setitem__(key, item)
 
     def store_config(self, data: dict) -> None:
-        """Important Step to get a self-describing Output-File
+        """Get a better self-describing Output-File.
+
         TODO: use data-model?
-        :param data: from virtual harvester or converter / source
+        :param data: from virtual harvester or converter / source.
         """
         self.h5file["data"].attrs["config"] = yaml.safe_dump(
             data, default_flow_style=False, sort_keys=False
         )
 
     def store_hostname(self, name: str) -> None:
-        """Option to distinguish the host, target or data-source in the testbed
-            -> perfect for plotting later
+        """Option to distinguish the host, target or data-source -> perfect for plotting later.
 
         :param name: something unique, or "artificial" in case of generated content
         """

{shepherd_core-2023.12.1.dist-info → shepherd_core-2024.4.2.dist-info}/METADATA

@@ -1,14 +1,12 @@
 Metadata-Version: 2.1
-Name: shepherd-core
-Version: 2023.12.1
+Name: shepherd_core
+Version: 2024.4.2
 Summary: Programming- and CLI-Interface for the h5-dataformat of the Shepherd-Testbed
-Home-page: https://pypi.org/project/shepherd-core/
-Author: Ingmar Splitt, Kai Geissdoerfer
-Author-email: ingmar.splitt@tu-dresden.de
-Maintainer-email: ingmar.splitt@tu-dresden.de
-License: MIT
-Project-URL: Tracker, https://github.com/orgua/shepherd-datalib/issues
-Project-URL: Source, https://github.com/orgua/shepherd-datalib
+Author-email: Ingmar Splitt <ingmar.splitt@tu-dresden.de>
+Maintainer-email: Ingmar Splitt <ingmar.splitt@tu-dresden.de>
+Project-URL: Documentation, https://github.com/orgua/shepherd-datalib/blob/main/README.md
+Project-URL: Issues, https://github.com/orgua/shepherd-datalib/issues
+Project-URL: Source, https://pypi.org/project/shepherd-core/
 Keywords: testbed,beaglebone,pru,batteryless,energyharvesting,solar
 Platform: unix
 Platform: linux
@@ -35,12 +33,13 @@ Requires-Dist: numpy
 Requires-Dist: pyYAML
 Requires-Dist: chromalog
 Requires-Dist: pydantic[email] >2.0.0
-Requires-Dist: tqdm
 Requires-Dist: scipy
+Requires-Dist: tqdm
 Requires-Dist: intelhex
 Requires-Dist: requests
 Requires-Dist: pyelftools
 Requires-Dist: zstandard
+Requires-Dist: typing-extensions
 Provides-Extra: dev
 Requires-Dist: twine ; extra == 'dev'
 Requires-Dist: pre-commit ; extra == 'dev'
@@ -63,7 +62,7 @@ Requires-Dist: coverage ; extra == 'test'
 [![Pytest](https://github.com/orgua/shepherd-datalib/actions/workflows/py_unittest.yml/badge.svg)](https://github.com/orgua/shepherd-datalib/actions/workflows/py_unittest.yml)
 [![CodeStyle](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 
-**Documentation**: <https://orgua.github.io/shepherd/external/shepherd_core.html>
+**Main Documentation**: <https://orgua.github.io/shepherd>
 
 **Source Code**: <https://github.com/orgua/shepherd-datalib>
 
@@ -71,53 +70,42 @@ Requires-Dist: coverage ; extra == 'test'
 
 ---
 
-This Python Module is designed as a library and bundles data-models and file-access-routines for the shepherd-testbed, that are used by several codebases.
+`shepherd-core` is designed as a library and bundles data-models and file-access-routines for the shepherd-testbed, that are used by several codebases.
 
-For postprocessing shepherds .h5-files users want to use [shepherd_data](https://pypi.org/project/shepherd_data).
+For postprocessing shepherds .h5-files usage of [shepherd_data](https://pypi.org/project/shepherd_data) is recommended.
 
 ## Features
 
 - read and write shepherds hdf5-files
-- create, read, write and convert experiments for the testbed (all data-models included)
+- create, read, write and convert experiments for the testbed
+  - all required data-models are included
 - simulate the virtual source, including virtual harvesters (and virtual converter as a whole)
-- connect and query the testbed via a webclient (TestbedClient)
+- connect and query the testbed via a webclient (TestbedClient in alpha-stage)
   - offline usage defaults to static demo-fixtures loaded from yaml-files in the model-directories
 - work with target-firmwares
   - embed, modify, verify, convert
   - **Note**: working with ELF-files requires external dependencies, see ``Installation``-Chapter
 - decode waveforms (gpio-state & timestamp) to UART
-- create an inventory (used versions of software, hardware)
+- create an inventory (for deployed versions of software, hardware)
 
-See [examples](https://github.com/orgua/shepherd-datalib/tree/main/shepherd_core/examples) for more details and usage. Most functionality is showcased there. The [extra](https://github.com/orgua/shepherd-datalib/tree/main/shepherd_core/extra)-directory holds data-generators relevant for the testbed. Notably is a trafficbench-experiment that's used to derive the link-matrix.
+See [official documentation](https://orgua.github.io/shepherd) or [example scripts](https://github.com/orgua/shepherd-datalib/tree/main/shepherd_core/examples) for more details and usage. Most functionality is showcased in both. The [extra](https://github.com/orgua/shepherd-datalib/tree/main/shepherd_core/extra)-directory holds data-generators relevant for the testbed. Notably is a [trafficbench](https://github.com/orgua/TrafficBench)-experiment that's used to derive the link-matrix of the testbed-nodes.
 
-### Compatibility
+## Config-Models in Detail
 
-| OS      |   PyVersion  | Comment                                    |
-|---------|--------------|--------------------------------------------|
-| Ubuntu  | 3.8 - 3.12   |                                            |
-| Windows | 3.8 - 3.12   | no support for elf and hex-conversions yet |
-| MacOS   | 3.8 - 3.12   | hex-conversion missing                     |
+These pydantic data-models are used throughout all shepherd interfaces. Users can create an experiment, include their own content and feed it to the testbed.
 
-Notes:
-- hex-conversion needs a working and accessible objcopy
-- elf-supports needs
-  - ``shepherd-core[elf]`` installs ``pwntools-elf-only``
-  - most elf-features also still utilize hex-conversion
-
-### Data-Models in Detail
-
-- new orchestration ``/data-models`` with focus on remote shepherd-testbed
+- orchestration ``/data-models`` with focus on remote shepherd-testbed
 - classes of sub-models
   - ``/base``: base-classes, configuration and -functionality for all models
   - ``/testbed``: meta-data representation of all testbed-components
-  - ``/content``: reusable meta-data for fw, h5 and vsrc-definitions
+  - ``/content``: reusable user-defined meta-data for fw, h5 and vsrc-definitions
   - ``/experiment``: configuration-models including sub-systems
   - ``/task``: digestible configs for shepherd-herd or -sheep
   - behavior controlled by ``ShpModel`` and ``content``-model
 - a basic database is available as fixtures through a ``tb_client``
   - fixtures selectable by name & ID
   - fixtures support inheritance
-- models support
+- the models support
   - auto-completion with neutral / sensible values
   - complex and custom datatypes (i.e. PositiveInt, lists-checks on length)
   - checking of inputs and type-casting
@@ -130,6 +118,20 @@ Notes:
   - exposes no internal paths
 - experiments can be transformed to task-sets (``TestbedTasks.from_xp()``)
 
+## Compatibility
+
+| OS      |   PyVersion  | Comment                                    |
+|---------|--------------|--------------------------------------------|
+| Ubuntu  | 3.8 - 3.12   |                                            |
+| Windows | 3.8 - 3.12   | no support for elf and hex-conversions yet |
+| MacOS   | 3.8 - 3.12   | hex-conversion missing                     |
+
+Notes:
+- hex-conversion needs a working and accessible objcopy
+- elf-supports needs
+  - ``shepherd-core[elf]`` installs ``pwntools-elf-only``
+  - most elf-features also still utilize hex-conversion
+
 ## Installation
 
 The Library is available via PyPI and can be installed with
@@ -166,3 +168,17 @@ For creating an inventory of the host-system you should install
 ```shell
   pip install shepherd-core[inventory]
 ```
+
+## Unittests
+
+To run the testbench, follow these steps:
+
+1. Navigate your host-shell into the package-folder and
+2. install dependencies
+3. run the testbench (~ 320 tests):
+
+```Shell
+cd shepherd-datalib/shepherd_core
+pip3 install ./[tests]
+pytest
+```