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

shepherd_core/__init__.py

@@ -1,5 +1,5 @@
-"""shepherd.core
-~~~~~
+"""Bundled core features used by several systems.
+
 Provides classes for storing and retrieving sampled IV data to/from
 HDF5 files.
 
@@ -23,7 +23,7 @@ from .testbed_client.client import TestbedClient
 from .testbed_client.client import tb_client
 from .writer import Writer
 
-__version__ = "2024.04.1"
+__version__ = "2024.5.1"
 
 __all__ = [
     "Reader",

shepherd_core/calibration_hw_def.py

@@ -1,4 +1,6 @@
-"""Contains some info about the hardware configuration on the shepherd
+"""parametrized math models for converting between raw- and si-values.
+
+Contains some info about the hardware configuration on the shepherd
 cape. Based on these values, one can derive the expected adc readings given
 an input voltage/current or, for emulation, the expected voltage and current
 given the digital code in the DAC.
@@ -31,6 +33,7 @@ RAW_MAX_DAC = 2**M_DAC - 1
 
 
 def adc_current_to_raw(current: float) -> int:
+    """Convert back a current [A] to raw ADC value."""
     # voltage on input of adc
     val_adc = G_INST_AMP * R_SHT * current
     # digital value according to ADC gain
@@ -39,6 +42,7 @@ def adc_current_to_raw(current: float) -> int:
 
 
 def adc_raw_to_current(value: int) -> float:
+    """Convert a raw ADC value to a current [A]."""
     value = min(max(value, 0), 2**M_ADC - 1)
     # voltage on input of adc
     val_adc = float(value) * (G_ADC_I * V_REF_ADC) / (2**M_ADC)
@@ -47,22 +51,26 @@ def adc_raw_to_current(value: int) -> float:
 
 
 def adc_voltage_to_raw(voltage: float) -> int:
+    """Convert back a voltage [V] to raw ADC value."""
     # digital value according to ADC gain
     val_raw = int(voltage * (2**M_ADC) / (G_ADC_V * V_REF_ADC))
     return min(max(val_raw, 0), 2**M_ADC - 1)
 
 
 def adc_raw_to_voltage(value: int) -> float:
+    """Convert a raw ADC value to a voltage [V]."""
     value = min(max(value, 0), 2**M_ADC - 1)
     # voltage according to ADC value
     return float(value) * (G_ADC_V * V_REF_ADC) / (2**M_ADC)
 
 
 def dac_raw_to_voltage(value: int) -> float:
+    """Convert back a raw DAC value to a voltage [V]."""
     value = min(max(value, 0), 2**M_DAC - 1)
     return float(value) * (V_REF_DAC * G_DAC) / (2**M_DAC)
 
 
 def dac_voltage_to_raw(voltage: float) -> int:
+    """Convert a voltage [V] to raw DAC value."""
     val_raw = int(voltage * (2**M_DAC) / (V_REF_DAC * G_DAC))
     return min(max(val_raw, 0), 2**M_DAC - 1)

shepherd_core/commons.py

@@ -1,3 +1,5 @@
+"""Container for commonly shared constants."""
+
 samplerate_sps_default: int = 100_000
 
 uid_str_default: str = "SHEPHERD_NODE_ID"

shepherd_core/data_models/__init__.py

@@ -1,3 +1,14 @@
+"""Container for shepherds data-models.
+
+Public models are directly referenced here and are usable like:
+
+'''python
+from shepherd-core import data_models
+
+cdata = data_models.CapeData(serial_number="A123")
+'''
+"""
+
 from .base.calibration import CalibrationCape
 from .base.calibration import CalibrationEmulator
 from .base.calibration import CalibrationHarvester

shepherd_core/data_models/base/__init__.py

@@ -1 +1,4 @@
-# these models import externally from: None
+"""Module for lowest hierarchy of data-models.
+
+these models import externally from: None
+"""

shepherd_core/data_models/base/cal_measurement.py

@@ -1,3 +1,5 @@
+"""Models for the process of calibration a device by measurements."""
+
 from typing import List
 from typing import Optional
 
@@ -7,10 +9,10 @@ from pydantic import PositiveFloat
 from pydantic import validate_call
 from typing_extensions import Annotated
 
-from .. import CalibrationCape
-from .. import CalibrationEmulator
-from .. import CalibrationHarvester
-from .. import CalibrationPair
+from .calibration import CalibrationCape
+from .calibration import CalibrationEmulator
+from .calibration import CalibrationHarvester
+from .calibration import CalibrationPair
 from .calibration import CapeData
 from .shepherd import ShpModel
 
@@ -18,6 +20,8 @@ from .shepherd import ShpModel
 
 
 class CalMeasurementPair(ShpModel):
+    """Value-container for a calibration-measurement."""
+
     shepherd_raw: PositiveFloat
     reference_si: float = 0
 
@@ -27,7 +31,8 @@ CalMeasPairs = Annotated[List[CalMeasurementPair], Field(min_length=2)]
 
 @validate_call
 def meas_to_cal(data: CalMeasPairs, component: str) -> CalibrationPair:
-    from scipy import stats  # here due to massive delay
+    """Convert values from calibration-measurement to the calibration itself."""
+    from scipy import stats  # placed here due to massive delay
 
     x = np.empty(len(data))
     y = np.empty(len(data))
@@ -40,14 +45,17 @@ def meas_to_cal(data: CalMeasPairs, component: str) -> CalibrationPair:
     rval = result.rvalue  # test quality of regression
 
     if rval < 0.999:
-        raise ValueError(
+        msg = (
             "Calibration faulty -> Correlation coefficient "
             f"(rvalue) = {rval}:.6f is too low for '{component}'"
         )
+        raise ValueError(msg)
     return CalibrationPair(offset=offset, gain=gain)
 
 
 class CalMeasurementHarvester(ShpModel):
+    """Container for the values of the calibration-measurement."""
+
     dac_V_Hrv: CalMeasPairs
     dac_V_Sim: CalMeasPairs
     adc_V_Sense: CalMeasPairs
@@ -62,6 +70,8 @@ class CalMeasurementHarvester(ShpModel):
 
 
 class CalMeasurementEmulator(ShpModel):
+    """Container for the values of the calibration-measurement."""
+
     dac_V_A: CalMeasPairs  # TODO: why not V_dac_A or V_dac_a
     dac_V_B: CalMeasPairs
     adc_C_A: CalMeasPairs
@@ -76,6 +86,8 @@ class CalMeasurementEmulator(ShpModel):
 
 
 class CalMeasurementCape(ShpModel):
+    """Container for the values of the calibration-measurement."""
+
     cape: Optional[CapeData] = None
     host: Optional[str] = None
 

shepherd_core/data_models/base/calibration.py

@@ -1,3 +1,5 @@
+"""Models for the calibration-data to convert between raw & SI-Values."""
+
 import struct
 from typing import Callable
 from typing import Generator
@@ -26,6 +28,10 @@ Calc_t = TypeVar("Calc_t", NDArray[np.float64], float)
 def dict_generator(
     in_dict: Union[dict, list], pre: Optional[list] = None
 ) -> Generator[list, None, None]:
+    """Recursive helper-function to generate a 1D-List(or not?).
+
+    TODO: isn't that a 1D-List generator?
+    """
     pre = pre[:] if pre else []
     if isinstance(in_dict, dict):
         for key, value in in_dict.items():
@@ -41,13 +47,13 @@ def dict_generator(
 
 
 class CalibrationPair(ShpModel):
-    """SI-value [SI-Unit] = raw-value * gain + offset"""
+    """SI-value [SI-Unit] = raw-value * gain + offset."""
 
     gain: PositiveFloat
     offset: float = 0
 
     def raw_to_si(self, values_raw: Calc_t, *, allow_negative: bool = True) -> Calc_t:
-        """Convert between physical units and raw unsigned integers"""
+        """Convert between physical units and raw unsigned integers."""
         values_si = values_raw * self.gain + self.offset
         if not allow_negative:
             if isinstance(values_si, np.ndarray):
@@ -60,17 +66,19 @@ class CalibrationPair(ShpModel):
         return values_si
 
     def si_to_raw(self, values_si: Calc_t) -> Calc_t:
-        """Convert between physical units and raw unsigned integers"""
+        """Convert between physical units and raw unsigned integers."""
         values_raw = (values_si - self.offset) / self.gain
         if isinstance(values_raw, np.ndarray):
             values_raw[values_raw < 0.0] = 0.0
             values_raw = np.around(values_raw)
+            # TODO: overflow should also be prevented (add bit-width) -> fail or warn at both?
         else:
             values_raw = round(max(values_raw, 0.0))
         return values_raw
 
     @classmethod
     def from_fn(cls, fn: Callable) -> Self:
+        """Probe linear function to determine scaling values."""
         offset = fn(0)
         gain_inv = fn(1.0) - offset
         return cls(
@@ -88,13 +96,17 @@ cal_hrv_legacy = {  # legacy translator
 
 
 class CalibrationHarvester(ShpModel):
+    """Container for all calibration-pairs for that device."""
+
     dac_V_Hrv: CalibrationPair = CalibrationPair.from_fn(dac_voltage_to_raw)
     dac_V_Sim: CalibrationPair = CalibrationPair.from_fn(dac_voltage_to_raw)
     adc_V_Sense: CalibrationPair = CalibrationPair.from_fn(adc_voltage_to_raw)
     adc_C_Hrv: CalibrationPair = CalibrationPair.from_fn(adc_current_to_raw)
 
     def export_for_sysfs(self) -> dict:
-        """[scaling according to commons.h]
+        """Convert and write the essential data.
+
+        [scaling according to commons.h]
         # ADC-C is handled in nA (nano-ampere), gain is shifted by 8 bit
         # ADC-V is handled in uV (micro-volt), gain is shifted by 8 bit
         # DAC-V is handled in uV (micro-volt), gain is shifted by 20 bit
@@ -111,7 +123,8 @@ class CalibrationHarvester(ShpModel):
             if (("gain" in key) and not (0 <= value < 2**32)) or (
                 ("offset" in key) and not (-(2**31) <= value < 2**31)
             ):
-                raise ValueError(f"Value ({key}={value}) exceeds uint32-container")
+                msg = f"Value ({key}={value}) exceeds uint32-container"
+                raise ValueError(msg)
         return cal_set
 
 
@@ -124,7 +137,10 @@ cal_emu_legacy = {  # legacy translator
 
 
 class CalibrationEmulator(ShpModel):
-    """Cal-Data for both Target-Ports A/B"""
+    """Container for all calibration-pairs for that device.
+
+    Differentiates between both target-ports A/B.
+    """
 
     dac_V_A: CalibrationPair = CalibrationPair.from_fn(dac_voltage_to_raw)
     dac_V_B: CalibrationPair = CalibrationPair.from_fn(dac_voltage_to_raw)
@@ -132,7 +148,9 @@ class CalibrationEmulator(ShpModel):
     adc_C_B: CalibrationPair = CalibrationPair.from_fn(adc_current_to_raw)
 
     def export_for_sysfs(self) -> dict:
-        """[scaling according to commons.h]
+        """Convert and write the essential data.
+
+        [scaling according to commons.h]
         # ADC-C is handled in nA (nano-ampere), gain is shifted by 8 bit
         # ADC-V -> unused by vsrc / emu
         # DAC-V is handled in uV (micro-volt), gain is shifted by 20 bit
@@ -150,13 +168,15 @@ class CalibrationEmulator(ShpModel):
             if (("gain" in key) and not (0 <= value < 2**32)) or (
                 ("offset" in key) and not (-(2**31) <= value < 2**31)
             ):
-                raise ValueError(f"Value ({key}={value}) exceeds uint32-container")
+                msg = f"Value ({key}={value}) exceeds uint32-container"
+                raise ValueError(msg)
         return cal_set
 
 
 class CapeData(ShpModel):
-    """Representation of Beaglebone Cape information
-        -> just provide serial-number on creation
+    """Representation of Beaglebone Cape information.
+
+    User must at least provide serial-number on creation.
 
     According to BeagleBone specifications, each cape should host an EEPROM
     that contains some standardized information about the type of cape,
@@ -178,12 +198,13 @@ class CapeData(ShpModel):
     # ⤷ produces something like '2023-01-01'
 
     def __repr__(self) -> str:  # TODO: override useful?
-        """string-representation allows print(model)"""
+        """string-representation allows print(model)."""
         return str(self.model_dump())
 
 
 class CalibrationCape(ShpModel):
     """Represents calibration data of shepherd cape.
+
     Defines the format of calibration data and provides convenient functions
     to read and write calibration data.
 
@@ -198,7 +219,8 @@ class CalibrationCape(ShpModel):
 
     @classmethod
     def from_bytestr(cls, data: bytes, cape: Optional[CapeData] = None) -> Self:
-        """Instantiates calibration data based on byte string.
+        """Instantiate calibration data based on byte string.
+
         This is mainly used to deserialize data read from an EEPROM memory.
 
         Args:
@@ -220,11 +242,11 @@ class CalibrationCape(ShpModel):
         return cls(**dv)
 
     def to_bytestr(self) -> bytes:
-        """Serializes calibration data to byte string.
+        """Serialize calibration data to byte string.
+
         Used to prepare data for writing it to EEPROM.
 
-        Returns
-        -------
+        Returns:
             Byte string representation of calibration values.
 
         """
@@ -234,6 +256,8 @@ class CalibrationCape(ShpModel):
 
 
 class CalibrationSeries(ShpModel):
+    """Cal-Data for a typical recording of a testbed experiment."""
+
     voltage: CalibrationPair = CalibrationPair(gain=3 * 1e-9)
     # ⤷ default allows 0 - 12 V in 3 nV-Steps
     current: CalibrationPair = CalibrationPair(gain=250 * 1e-12)

shepherd_core/data_models/base/content.py

@@ -1,3 +1,5 @@
+"""Base-Model for all content."""
+
 import hashlib
 from datetime import datetime
 from typing import Optional
@@ -10,6 +12,7 @@ from pydantic import StringConstraints
 from pydantic import model_validator
 from typing_extensions import Annotated
 from typing_extensions import Self
+from typing_extensions import deprecated
 
 from .shepherd import ShpModel
 from .timezone import local_now
@@ -23,15 +26,20 @@ SafeStr = Annotated[str, StringConstraints(pattern=r"^[ -~]+$")]
 # ⤷ Regex = All Printable ASCII-Characters with Space
 
 
+@deprecated("use UUID4 instead")
 def id_default() -> int:
-    # note: IdInt has space for 128 bit, so 128/4 = 32 hex-chars
+    """Generate a unique ID - usable as default value.
+
+    Note: IdInt has space for 128 bit, so 128/4 = 32 hex-chars
+    """
     time_stamp = str(local_now()).encode("utf-8")
     time_hash = hashlib.sha3_224(time_stamp).hexdigest()[-32:]
     return int(time_hash, 16)
 
 
 class ContentModel(ShpModel):
-    # General Properties
+    """Base-Model for content with generalized properties."""
+
     # id: UUID4 = Field(  # TODO: db-migration - temp fix for documentation
     id: Union[UUID4, int] = Field(
         description="Unique ID",

shepherd_core/data_models/base/shepherd.py

@@ -1,3 +1,5 @@
+"""Shepherds base-model that brings a lot of default functionality."""
+
 import hashlib
 import pathlib
 from datetime import timedelta
@@ -24,14 +26,17 @@ from .wrapper import Wrapper
 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())))
 
 
 def generic2str(dumper: Dumper, data: Any) -> ScalarNode:
+    """Add a yaml-representation for a specific datatype."""
     return dumper.represent_scalar("tag:yaml.org,2002:str", str(data))
 
 
@@ -44,7 +49,7 @@ yaml.add_representer(UUID, generic2str, SafeDumper)
 
 
 class ShpModel(BaseModel):
-    """Pre-configured Pydantic Base-Model (specifically for shepherd)
+    """Pre-configured Pydantic Base-Model (specifically for shepherd).
 
     Inheritable Features:
     - constant / frozen, hashable .get_hash()
@@ -69,17 +74,17 @@ class ShpModel(BaseModel):
         str_strip_whitespace=True,  # strip leading & trailing whitespaces
         use_enum_values=True,  # cleaner export of enum-parameters
         allow_inf_nan=False,  # float without +-inf or NaN
-        # defer_build, possible speedup -> but it triggers a bug
+        # defer_build=True, possible speedup -> but it triggers a bug
     )
 
     def __repr__(self) -> str:
-        """string-representation allows print(model)"""
+        """string-representation allows print(model)."""
         name = type(self).__name__
         content = self.model_dump(exclude_unset=True, exclude_defaults=True)
         return f"{name}({content})"
 
     def __str__(self) -> str:
-        """string-representation allows str(model)"""
+        """string-representation allows str(model)."""
         content = yaml.safe_dump(
             self.model_dump(exclude_unset=True, exclude_defaults=True),
             default_flow_style=False,
@@ -88,26 +93,29 @@ class ShpModel(BaseModel):
         return str(content)
 
     def __getitem__(self, key: str) -> Any:
-        """Allows dict access -> model["key"], in addition to model.key"""
+        """Allow dict access like model["key"].
+
+        in addition to model.key.
+        """
         return self.__getattribute__(key)
 
     def __contains__(self, item: str) -> bool:
-        """Allows checks like 'x in YClass'"""
+        """Allow checks like 'x in YClass'."""
         return item in self.model_dump().keys()  # noqa: SIM118
         # more correct, but probably slower than hasattr
 
     def keys(self):  # noqa: ANN201
-        """Fn of dict"""
+        """Fn of dict."""
         return self.model_dump().keys()
 
     def items(self) -> Generator[tuple, None, None]:
-        """Fn of dict"""
+        """Fn of dict."""
         for key in self.keys():
             yield key, self[key]
 
     @classmethod
     def schema_to_file(cls, path: Union[str, Path]) -> None:
-        """Store schema to yaml (for frontend-generators)"""
+        """Store schema to yaml (for frontend-generators)."""
         model_dict = cls.model_json_schema()
         model_yaml = yaml.safe_dump(model_dict, default_flow_style=False, sort_keys=False)
         with Path(path).resolve().with_suffix(".yaml").open("w") as f:
@@ -120,9 +128,10 @@ class ShpModel(BaseModel):
         *,
         minimal: bool = True,
     ) -> Path:
-        """Store data to yaml in a wrapper
+        """Store data to yaml in a wrapper.
+
         minimal: stores minimal set (filters out unset & default parameters)
-        comment: documentation
+        comment: documentation.
         """
         model_dict = self.model_dump(exclude_unset=minimal)
         model_wrap = Wrapper(
@@ -146,7 +155,7 @@ class ShpModel(BaseModel):
 
     @classmethod
     def from_file(cls, path: Union[str, Path]) -> Self:
-        """Load from yaml"""
+        """Load from yaml."""
         with Path(path).open() as shp_file:
             shp_dict = yaml.safe_load(shp_file)
         shp_wrap = Wrapper(**shp_dict)

shepherd_core/data_models/base/timezone.py

@@ -1,3 +1,5 @@
+"""Helper-functions for better support of timezones."""
+
 import time
 from datetime import datetime
 from datetime import timedelta
@@ -5,14 +7,17 @@ from datetime import timezone
 
 
 def local_tz() -> timezone:
+    """Query the local timezone of the user."""
     if time.daylight:
         return timezone(timedelta(seconds=-time.altzone), time.tzname[1])
     return timezone(timedelta(seconds=-time.timezone), time.tzname[0])
 
 
 def local_now() -> datetime:
+    """Query the local date-time of the user."""
     return datetime.now(tz=local_tz())
 
 
 def local_iso_date() -> str:
+    """Query the local date-time of the user as a ISO 8601 date."""
     return local_now().date().isoformat()

shepherd_core/data_models/base/wrapper.py

@@ -1,3 +1,5 @@
+"""Wrapper-related ecosystem for transferring models."""
+
 from datetime import datetime
 from typing import Optional
 
@@ -10,9 +12,7 @@ SafeStrClone = Annotated[str, StringConstraints(pattern=r"^[ -~]+$")]
 
 
 class Wrapper(BaseModel):
-    """Prototype for enabling one web- & file-interface for
-    all models with dynamic typecasting
-    """
+    """Generalized web- & file-interface for all models with dynamic typecasting."""
 
     datatype: str
     # ⤷ model-name

shepherd_core/data_models/content/__init__.py

@@ -1,3 +1,8 @@
+"""Module for content-type data-models.
+
+These models import externally from: /base, /testbed.
+"""
+
 from .energy_environment import EnergyDType
 from .energy_environment import EnergyEnvironment
 from .firmware import Firmware
@@ -5,8 +10,6 @@ from .firmware_datatype import FirmwareDType
 from .virtual_harvester import VirtualHarvesterConfig
 from .virtual_source import VirtualSourceConfig
 
-# these models import externally from: /base, /testbed
-
 __all__ = [
     "EnergyEnvironment",
     "VirtualSourceConfig",
@@ -16,5 +19,3 @@ __all__ = [
     "EnergyDType",
     "FirmwareDType",
 ]
-
-# TODO: include models for end-users on root-level