shepherd-core 2025.10.1__tar.gz → 2026.2.1__tar.gz

shepherd_core-2026.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2025, Networked Embedded Systems Lab, TU Dresden, Ingmar Splitt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{shepherd_core-2025.10.1 → shepherd_core-2026.2.1}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
-Name: shepherd_core
-Version: 2025.10.1
+Name: shepherd-core
+Version: 2026.2.1
 Summary: Programming- and CLI-Interface for the h5-dataformat of the Shepherd-Testbed
 Author-email: Ingmar Splitt <ingmar.splitt@tu-dresden.de>
 Maintainer-email: Ingmar Splitt <ingmar.splitt@tu-dresden.de>
+License-Expression: MIT
 Project-URL: Documentation, https://github.com/nes-lab/shepherd-tools/blob/main/README.md
 Project-URL: Issues, https://github.com/nes-lab/shepherd-tools/issues
 Project-URL: Source, https://pypi.org/project/shepherd-core/
@@ -23,11 +24,11 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Natural Language :: English
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Requires-Dist: h5py
 Requires-Dist: numpy
 Requires-Dist: pyYAML
@@ -50,6 +51,7 @@ Requires-Dist: pytest; extra == "test"
 Requires-Dist: coverage; extra == "test"
 Provides-Extra: all
 Requires-Dist: shepherd-core[dev,elf,inventory,test]; extra == "all"
+Dynamic: license-file
 
 # Core Library
 

{shepherd_core-2025.10.1 → shepherd_core-2026.2.1}/examples/eenv_generator.py

@@ -1,4 +1,4 @@
-"""Create a set of static artificial energy environments."""
+"""Create a set of static synthetic energy environments."""
 
 from itertools import product
 from pathlib import Path
@@ -29,7 +29,7 @@ for _v, _c in product(voltages_V, currents_A):
         log.info("File exists, will skip: %s", file_path.name)
     else:
         with ShpWriter(file_path) as file:
-            file.store_hostname("artificial")
+            file.store_hostname("synthetic")
             # values in SI units
             timestamp_vector = np.arange(0.0, duration_s, file.sample_interval_ns / 1e9)
             voltage_vector = np.linspace(_v, _v, int(file.samplerate_sps * duration_s))

{shepherd_core-2025.10.1 → shepherd_core-2026.2.1}/examples/experiment_generic_var1.py

@@ -30,20 +30,20 @@ do_connect = False
 if do_connect:
     WebClient()
 
-xp = sm.Experiment(
+exp = sm.Experiment(
     name="meaningful_TestName",
     # time_start could be "2033-03-13 14:15:16" or "datetime.now() + timedelta(minutes=30)"
-    duration=30,
+    duration=30,  # ty: ignore[invalid-argument-type]
     target_configs=[
         sm.TargetConfig(
             target_IDs=range(7, 12),
             custom_IDs=range(1, 100),  # note: longer list is OK
-            energy_env=sm.EnergyEnvironment(name="eenv_static_3000mV_50mA_3600s"),
+            energy_env=sm.EnergyEnvironment(name="synthetic_static_3000mV_50mA"),
             firmware1=sm.Firmware(
                 name="FW_TestXYZ",
                 data=Path("/var/shepherd/content/fw/nes_lab/nrf52_demo_rf/build.elf"),
                 data_type=sm.FirmwareDType.path_elf,
-                data_local=False,
+                data_2_copy=False,
                 mcu=MCU(name="nRF52"),
             ),
             power_tracing=None,
@@ -52,10 +52,10 @@ xp = sm.Experiment(
         ),
     ],
 )
-xp.to_file("experiment_generic_var1.yaml")
+exp.to_file("experiment_generic_var1.yaml")
 
 # Create a tasks-list for the testbed
-tb_tasks = TestbedTasks.from_xp(xp)
+tb_tasks = TestbedTasks.from_xp(exp)
 tb_tasks.to_file("experiment_generic_var1_tbt.yaml")
 
 # next steps:

{shepherd_core-2025.10.1 → shepherd_core-2026.2.1}/examples/experiment_generic_var2.py

@@ -28,7 +28,7 @@ do_connect = False
 if do_connect:
     WebClient()
 
-xp = sm.Experiment(
+exp = sm.Experiment(
     name="meaningful_TestName",
     # time_start could be "2033-03-13 14:15:16" or "datetime.now() + timedelta(minutes=30)"
     duration=30,
@@ -36,7 +36,7 @@ xp = sm.Experiment(
         sm.TargetConfig(
             target_IDs=range(7, 12),
             custom_IDs=range(1, 100),  # note: longer list is OK
-            energy_env=sm.EnergyEnvironment(name="eenv_static_3000mV_50mA_3600s"),
+            energy_env=sm.EnergyEnvironment(name="synthetic_static_3000mV_50mA"),
             firmware1=sm.Firmware.from_firmware(
                 file=Path("./firmware_nrf.elf").absolute(),
             ),
@@ -45,10 +45,10 @@ xp = sm.Experiment(
         ),
     ],
 )
-xp.to_file("experiment_generic_var2.yaml")
+exp.to_file("experiment_generic_var2.yaml")
 
 # Create a tasks-list for the testbed
-tb_tasks = TestbedTasks.from_xp(xp)
+tb_tasks = TestbedTasks.from_xp(exp)
 tb_tasks.to_file("experiment_generic_var2_tbt.yaml")
 
 # next steps:

{shepherd_core-2025.10.1 → shepherd_core-2026.2.1}/examples/simulations/vharvester.py

@@ -15,6 +15,8 @@ E_out = 17.811 mWs -> mppt_opt
 
 """
 
+import os
+import sys
 from pathlib import Path
 
 from shepherd_core.data_models import VirtualHarvesterConfig
@@ -23,8 +25,12 @@ from shepherd_core.vsource import simulate_harvester
 from shepherd_core import Reader
 from shepherd_data import ivonne
 
+DURATION_MAX = 1 if "PYTEST_CURRENT_TEST" in os.environ else sys.float_info.max
+# ⤷ limits runtime for pytest
+
 # config simulation
-sim_duration = 32
+sim_duration = min(32, DURATION_MAX)
+# ⤷ limits runtime for pytest
 file_ivonne = Path(__file__).parents[3] / "shepherd_data/examples/jogging_10m.iv"
 file_ivcurve = Path(__file__).parent / "jogging_ivcurve.h5"
 

{shepherd_core-2025.10.1 → shepherd_core-2026.2.1}/examples/simulations/vstorage.py

@@ -30,7 +30,7 @@ from shepherd_core import log
 
 path_here = Path(__file__).parent
 
-duration_max = 20 if "PYTEST_CURRENT_TEST" in os.environ else sys.float_info.max
+DURATION_MAX = 1 if "PYTEST_CURRENT_TEST" in os.environ else sys.float_info.max
 # ⤷ limits runtime for pytest
 
 
@@ -98,7 +98,7 @@ def experiment_current_ramp_pos(config: VirtualStorageConfig) -> None:
     """Charge virtual storage with a positive current ramp (increasing power)."""
     dt_s = 0.1
     SoC_start = 0.5
-    duration_s = min(200, duration_max)
+    duration_s = min(200, DURATION_MAX)
     sim = StorageSimulator(
         models=get_models(SoC_start, config, dt_s),
         dt_s=dt_s,
@@ -108,14 +108,14 @@ def experiment_current_ramp_pos(config: VirtualStorageConfig) -> None:
         return 0.1 + 0.15 * t_s / duration_s  # pru-model can handle +- 268 mA
 
     sim.run(fn=current_trace, duration_s=duration_s)
-    sim.plot(path_here, f"XP {config.name}, current charge ramp (positive)")
+    sim.plot(path_here, f"Experiment {config.name}, current charge ramp (positive)")
 
 
 def experiment_current_ramp_neg(config: VirtualStorageConfig) -> None:
     """Discharge virtual storage with a negative current ramp (increasing power)."""
     dt_s = 0.1
     SoC_start = 0.5
-    duration_s = min(200, duration_max)
+    duration_s = min(200, DURATION_MAX)
     sim = StorageSimulator(
         models=get_models(SoC_start, config, dt_s),
         dt_s=dt_s,
@@ -125,7 +125,7 @@ def experiment_current_ramp_neg(config: VirtualStorageConfig) -> None:
         return -(0.1 + 0.14 * t_s / duration_s)  # pru-model can handle +- 268 mA
 
     sim.run(fn=current_trace, duration_s=duration_s)
-    sim.plot(path_here, f"XP {config.name}, current discharge ramp (negative)")
+    sim.plot(path_here, f"Experiment {config.name}, current discharge ramp (negative)")
 
 
 def experiment_pulsed_discharge(config: VirtualStorageConfig) -> None:
@@ -140,8 +140,8 @@ def experiment_pulsed_discharge(config: VirtualStorageConfig) -> None:
         models=get_models(SoC_start, config, dt_s),
         dt_s=dt_s,
     )
-    sim.run(fn=i_pulse.step, duration_s=min(1_000, duration_max))
-    sim.plot(path_here, f"XP {config.name}, pulsed discharge .1A, 1000 s (figure_9a)")
+    sim.run(fn=i_pulse.step, duration_s=min(1_000, DURATION_MAX))
+    sim.plot(path_here, f"Experiment {config.name}, pulsed discharge .1A, 1000 s (figure_9a)")
 
 
 def experiment_pulsed_charge(config: VirtualStorageConfig) -> None:
@@ -156,8 +156,8 @@ def experiment_pulsed_charge(config: VirtualStorageConfig) -> None:
         models=get_models(SoC_start, config, dt_s),
         dt_s=dt_s,
     )
-    sim.run(fn=i_pulse.step, duration_s=min(1_000, duration_max))
-    sim.plot(path_here, f"XP {config.name}, pulsed charge .1A, 1000 s (figure_9b)")
+    sim.run(fn=i_pulse.step, duration_s=min(1_000, DURATION_MAX))
+    sim.plot(path_here, f"Experiment {config.name}, pulsed charge .1A, 1000 s (figure_9b)")
 
 
 def experiment_pulsed_resistive_charge(config: VirtualStorageConfig) -> None:
@@ -169,8 +169,10 @@ def experiment_pulsed_resistive_charge(config: VirtualStorageConfig) -> None:
         models=get_models(SoC_start, config, dt_s),
         dt_s=dt_s,
     )
-    sim.run(fn=i_pulse.step, duration_s=min(3_000, duration_max))
-    sim.plot(path_here, f"XP {config.name}, pulsed resistive charge 20 Ohm to 4.2 V, 3000 s")
+    sim.run(fn=i_pulse.step, duration_s=min(3_000, DURATION_MAX))
+    sim.plot(
+        path_here, f"Experiment {config.name}, pulsed resistive charge 20 Ohm to 4.2 V, 3000 s"
+    )
 
 
 def experiment_resistive_load(config: VirtualStorageConfig) -> None:
@@ -185,8 +187,8 @@ def experiment_resistive_load(config: VirtualStorageConfig) -> None:
         models=get_models(SoC_start, config, dt_s),
         dt_s=dt_s,
     )
-    sim.run(fn=i_charge, duration_s=min(1_000, duration_max))
-    sim.plot(path_here, f"XP {config.name}, resistive load 20 Ohm from 4.2 V, 1000 s")
+    sim.run(fn=i_charge, duration_s=min(1_000, DURATION_MAX))
+    sim.plot(path_here, f"Experiment {config.name}, resistive load 20 Ohm from 4.2 V, 1000 s")
 
 
 def experiment_self_discharge() -> None:
@@ -207,10 +209,10 @@ def experiment_self_discharge() -> None:
     def step(_t: float, _s: float, _v: float) -> float:
         return 0
 
-    sim.run(fn=step, duration_s=min(duration.total_seconds(), duration_max))
+    sim.run(fn=step, duration_s=min(duration.total_seconds(), DURATION_MAX))
     sim.plot(
         path_here,
-        f"XP {config.name}, self-discharge, "
+        f"Experiment {config.name}, self-discharge, "
         f"SoC {SoC_start} to {SoC_target} in {duration.total_seconds()} s",
     )
 

{shepherd_core-2025.10.1 → shepherd_core-2026.2.1}/examples/vsource_debug_sim.py

@@ -10,6 +10,7 @@
 
 """
 
+import os
 from itertools import product
 
 import matplotlib.pyplot as plt
@@ -38,6 +39,10 @@ src_list = [
 I_mcu_sleep_A = 200e-9
 I_mcu_active_A = 1e-3
 
+# limit runtime for pytest
+if "PYTEST_CURRENT_TEST" in os.environ:
+    sample_dur_list = [10_000]
+
 # For online-queries the lib can be connected to the testbed-server.
 # NOTE: there are 3 states:
 # - unconnected -> demo-fixtures are queried (locally)

{shepherd_core-2025.10.1 → shepherd_core-2026.2.1}/pyproject.toml

@@ -1,12 +1,13 @@
 [project]
-name = "shepherd_core"
+name = "shepherd-core"
 description = "Programming- and CLI-Interface for the h5-dataformat of the Shepherd-Testbed"
 keywords = ["testbed", "beaglebone", "pru", "batteryless", "energyharvesting", "solar"]
 
 authors = [{name = "Ingmar Splitt", email = "ingmar.splitt@tu-dresden.de"},]
 maintainers = [{name = "Ingmar Splitt", email = "ingmar.splitt@tu-dresden.de"},]
 
-license = {file = "LICENSE"}
+license = "MIT"
+license-files = ["LICENSE"] # can't be in parent dir
 dynamic = ["version"]
 
 classifiers = [
@@ -19,7 +20,6 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
-    "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Natural Language :: English",
 ]
@@ -104,12 +104,3 @@ addopts = "-vvv --stepwise" # opts: verbose result for each tests
 [tool.coverage.run]
 source = ["shepherd_core"]
 omit = ["*/shepherd_data/*"]
-
-[tool.mypy]
-python_version = 3.10
-ignore_missing_imports = true
-disable_error_code = ["call-arg", ]
-exclude = [
-    "build/",
-    ".egg-info/",
-]

{shepherd_core-2025.10.1 → shepherd_core-2026.2.1}/shepherd_core/config.py

@@ -27,7 +27,7 @@ class ConfigDefault(BaseModel):
     UID_SIZE: int = 2
     """Variable size in Byte"""
 
-    TESTBED_SERVER: HttpUrl = "https://shepherd.cfaed.tu-dresden.de:8000/"
+    TESTBED_SERVER: HttpUrl = HttpUrl("https://shepherd.cfaed.tu-dresden.de:8000/")
     """Server that holds up to date testbed fixtures"""
 
 

{shepherd_core-2025.10.1 → shepherd_core-2026.2.1}/shepherd_core/data_models/__init__.py

@@ -18,10 +18,11 @@ from .base.calibration import CapeData
 from .base.content import ContentModel
 from .base.shepherd import ShpModel
 from .base.wrapper import Wrapper
-from .content.energy_environment import EnergyDType
 from .content.energy_environment import EnergyEnvironment
+from .content.energy_environment import EnergyProfile
+from .content.enum_datatypes import EnergyDType
+from .content.enum_datatypes import FirmwareDType
 from .content.firmware import Firmware
-from .content.firmware import FirmwareDType
 from .content.virtual_harvester_config import VirtualHarvesterConfig
 from .content.virtual_source_config import VirtualSourceConfig
 from .content.virtual_storage_config import VirtualStorageConfig
@@ -45,6 +46,7 @@ __all__ = [
     "ContentModel",
     "EnergyDType",
     "EnergyEnvironment",
+    "EnergyProfile",
     "Experiment",
     "Firmware",
     "FirmwareDType",

{shepherd_core-2025.10.1 → shepherd_core-2026.2.1}/shepherd_core/data_models/base/cal_measurement.py

@@ -1,6 +1,7 @@
 """Models for the process of calibration a device by measurements."""
 
 from typing import Annotated
+from typing import final
 
 import numpy as np
 from pydantic import Field
@@ -15,6 +16,7 @@ from .calibration import CapeData
 from .shepherd import ShpModel
 
 
+@final
 class CalMeasurementPair(ShpModel):
     """Value-container for a calibration-measurement."""
 
@@ -39,8 +41,8 @@ def meas_to_cal(data: CalMeasPairs, component: str) -> CalibrationPair:
     gain: float = float(model[0])
 
     # r-squared, Pearson correlation coefficient
-    _p = np.poly1d(model)
-    yhat = _p(x)
+    pcoef = np.poly1d(model)
+    yhat = pcoef(x)
     ybar: float = np.sum(y) / len(y)
     ssreg: float = np.sum((yhat - ybar) ** 2)
     sstot: float = np.sum((y - ybar) ** 2)
@@ -55,6 +57,7 @@ def meas_to_cal(data: CalMeasPairs, component: str) -> CalibrationPair:
     return CalibrationPair(offset=offset, gain=gain)
 
 
+@final
 class CalMeasurementHarvester(ShpModel):
     """Container for the values of the calibration-measurement."""
 
@@ -71,6 +74,7 @@ class CalMeasurementHarvester(ShpModel):
         return CalibrationHarvester(**dcal)
 
 
+@final
 class CalMeasurementEmulator(ShpModel):
     """Container for the values of the calibration-measurement."""
 
@@ -87,6 +91,7 @@ class CalMeasurementEmulator(ShpModel):
         return CalibrationEmulator(**dcal)
 
 
+@final
 class CalMeasurementCape(ShpModel):
     """Container for the values of the calibration-measurement."""
 

{shepherd_core-2025.10.1 → shepherd_core-2026.2.1}/shepherd_core/data_models/base/calibration.py

@@ -5,14 +5,16 @@ from collections.abc import Callable
 from collections.abc import Generator
 from collections.abc import Mapping
 from collections.abc import Sequence
+from typing import Annotated
 from typing import TypeVar
+from typing import final
 
 import numpy as np
 from numpy.typing import NDArray
 from pydantic import Field
 from pydantic import PositiveFloat
+from pydantic import StringConstraints
 from pydantic import conbytes
-from pydantic import constr
 from pydantic import validate_call
 from typing_extensions import Self
 
@@ -47,6 +49,7 @@ def dict_generator(
         yield [*pre, in_dict]
 
 
+@final
 class CalibrationPair(ShpModel):
     """SI-value [SI-Unit] = raw-value * gain + offset."""
 
@@ -56,11 +59,11 @@ class CalibrationPair(ShpModel):
 
     def raw_to_si(self, values_raw: Calc_t, *, allow_negative: bool = True) -> Calc_t:
         """Convert between physical units and raw unsigned integers."""
-        values_si = values_raw * self.gain + self.offset
+        values_si = self.gain * values_raw + self.offset
         if not allow_negative:
             if isinstance(values_si, np.ndarray):
                 values_si[values_si < 0.0] = 0.0
-                # if pyright still complains, cast with .astype(float)
+                # if type-checker still complains, cast with .astype(float)
             else:
                 values_si = float(max(values_si, 0.0))
         elif not isinstance(values_si, np.ndarray):
@@ -99,6 +102,7 @@ cal_pair_adc_V = CalibrationPair.from_fn(adc_voltage_to_raw, unit="V")
 cal_pair_adc_C = CalibrationPair.from_fn(adc_current_to_raw, unit="A")
 
 
+@final
 class CalibrationHarvester(ShpModel):
     """Container for all calibration-pairs for that device."""
 
@@ -140,6 +144,7 @@ cal_emu_legacy = {  # legacy translator
 }
 
 
+@final
 class CalibrationEmulator(ShpModel):
     """Container for all calibration-pairs for that device.
 
@@ -177,6 +182,7 @@ class CalibrationEmulator(ShpModel):
         return cal_set
 
 
+@final
 class CapeData(ShpModel):
     """Representation of Beaglebone Cape information.
 
@@ -190,15 +196,17 @@ class CapeData(ShpModel):
     """
 
     header: conbytes(max_length=4) = b"\xaa\x55\x33\xee"
-    eeprom_revision: constr(max_length=2) = "A2"
-    board_name: constr(max_length=32) = "BeagleBone SHEPHERD2 Cape"
-    version: constr(max_length=4) = "24B0"
-    manufacturer: constr(max_length=16) = "NES TU DRESDEN"
-    part_number: constr(max_length=16) = "BB-SHPRD"
+    eeprom_revision: Annotated[str, StringConstraints(max_length=2)] = "A2"
+    board_name: Annotated[str, StringConstraints(max_length=32)] = "BeagleBone SHEPHERD2 Cape"
+    version: Annotated[str, StringConstraints(max_length=4)] = "24B0"
+    manufacturer: Annotated[str, StringConstraints(max_length=16)] = "NES TU DRESDEN"
+    part_number: Annotated[str, StringConstraints(max_length=16)] = "BB-SHPRD"
 
-    serial_number: constr(max_length=12)
+    serial_number: Annotated[str, StringConstraints(max_length=12)]
 
-    cal_date: constr(max_length=12) = Field(default_factory=local_iso_date)
+    cal_date: Annotated[str, StringConstraints(max_length=12)] = Field(
+        default_factory=local_iso_date
+    )
     # ⤷ produces something like '2023-01-01'
 
     def __repr__(self) -> str:  # TODO: override useful?
@@ -206,6 +214,7 @@ class CapeData(ShpModel):
         return str(self.model_dump())
 
 
+@final
 class CalibrationCape(ShpModel):
     """Represents calibration data of shepherd cape.
 
@@ -231,6 +240,7 @@ class CalibrationCape(ShpModel):
         ----
             data: Byte string containing calibration data.
             cape: data can be supplied
+
         Returns:
             CalibrationCape object with extracted calibration data.
 
@@ -240,9 +250,9 @@ class CalibrationCape(ShpModel):
         lw2 = [elem for elem in lw1 if isinstance(elem[-1], float)]
         values = struct.unpack(">" + len(lw2) * "d", data)
         # ⤷ X => double float, big endian
-        for _i, walk in enumerate(lw2):
+        for i_, walk in enumerate(lw2):
             # hardcoded fixed depth ... bad but easy
-            dv[walk[0]][walk[1]][walk[2]] = float(values[_i])
+            dv[walk[0]][walk[1]][walk[2]] = float(values[i_])
         dv["cape"] = cape
         return cls(**dv)
 
@@ -260,6 +270,7 @@ class CalibrationCape(ShpModel):
         return struct.pack(">" + len(values) * "d", *values)
 
 
+@final
 class CalibrationSeries(ShpModel):
     """Cal-Data for a typical recording of a testbed experiment."""
 

{shepherd_core-2025.10.1 → shepherd_core-2026.2.1}/shepherd_core/data_models/base/content.py

@@ -9,12 +9,15 @@ from pydantic import StringConstraints
 from pydantic import model_validator
 from typing_extensions import Self
 
+from shepherd_core.logger import log
+from shepherd_core.version import version as core_ver
+
 from .shepherd import ShpModel
 
 # constr -> to_lower=True, max_length=16, regex=r"^[\w]+$"
 # ⤷ Regex = AlphaNum
 IdInt = Annotated[int, Field(ge=0, lt=2**128)]
-NameStr = Annotated[str, StringConstraints(max_length=32, pattern=r"^[^<>:;,?\"\*|\/\\]+$")]
+NameStr = Annotated[str, StringConstraints(max_length=50, pattern=r"^[^<>:;,?\"\*|\/\\]+$")]
 # ⤷ Regex = FileSystem-Compatible ASCII
 SafeStr = Annotated[str, StringConstraints(pattern=r"^[ -~]+$")]
 # ⤷ Regex = All Printable ASCII-Characters with Space
@@ -41,6 +44,8 @@ class ContentModel(ShpModel):
     comment: SafeStr | None = None
     created: datetime = Field(default_factory=datetime.now)
     updated_last: datetime = Field(default_factory=datetime.now)
+    deprecated: str | None = None
+    """ ⤷ deprecation-comments provoke a warning during validation of model."""
     # TODO: add dedicated 'inherit_from' field?
 
     # Ownership & Access
@@ -50,7 +55,8 @@ class ContentModel(ShpModel):
     visible2group: bool = False
     visible2all: bool = False
 
-    # TODO: we probably need to remember the lib-version for content &| experiment
+    sw_ver: Annotated[str, Field(default=core_ver)]
+    """ ⤷ store core-version with content for compatibility management."""
 
     def __str__(self) -> str:
         return self.name
@@ -62,4 +68,6 @@ class ContentModel(ShpModel):
             raise ValueError(
                 "Public instances require a description (check visible2*- and description-field)"
             )
+        if isinstance(self.deprecated, str) and len(self.deprecated) > 0:
+            log.warning(f"Content {self.name} is deprecated: {self.deprecated}")
         return self

{shepherd_core-2025.10.1 → shepherd_core-2026.2.1}/shepherd_core/data_models/base/shepherd.py

@@ -8,6 +8,7 @@ from datetime import timedelta
 from ipaddress import IPv4Address
 from pathlib import Path
 from typing import Any
+from typing import final
 from uuid import UUID
 
 import yaml
@@ -38,6 +39,7 @@ def generic2str(dumper: SafeDumper, data: Any) -> Node:
     return dumper.represent_scalar("tag:yaml.org,2002:str", str(data))
 
 
+# TODO: put in helper-file (similar to models/task/helper_paths.py) and make it callable
 yaml.add_representer(pathlib.PosixPath, path2str, SafeDumper)
 yaml.add_representer(pathlib.WindowsPath, path2str, SafeDumper)
 yaml.add_representer(pathlib.Path, path2str, SafeDumper)
@@ -108,12 +110,15 @@ class ShpModel(BaseModel):
         )
         return str(content)
 
-    def __getitem__(self, key: str) -> Any:
+    def __getitem__(self, key: Any) -> Any:
         """Allow dict access like model["key"].
 
         in addition to model.key.
         """
-        return self.__getattribute__(key)
+        if isinstance(key, str):
+            return self.__getattribute__(key)
+        msg = f"Unknown key '{key}' used when selecting from Model."
+        raise IndexError(msg)
 
     def __contains__(self, item: str) -> bool:
         """Allow checks like 'x in YClass'."""
@@ -127,8 +132,9 @@ class ShpModel(BaseModel):
     def items(self) -> Generator[tuple, None, None]:
         """Fn of dict."""
         for key in self.keys():
-            yield key, self[key]
+            yield key, self.__getattribute__(key)
 
+    @final
     @classmethod
     def schema_to_file(cls, path: str | Path) -> None:
         """Store schema to yaml (for frontend-generators)."""
@@ -137,6 +143,7 @@ class ShpModel(BaseModel):
         with Path(path).resolve().with_suffix(".yaml").open("w") as f:
             f.write(model_yaml)
 
+    @final
     def to_file(
         self,
         path: str | Path,
@@ -178,6 +185,7 @@ class ShpModel(BaseModel):
             f.write(model_serial)
         return model_path
 
+    @final
     @classmethod
     def from_file(cls, path: str | Path) -> Self:
         """Load from YAML or pickle file."""
@@ -188,12 +196,13 @@ class ShpModel(BaseModel):
             with Path(path).open("rb") as shp_file:
                 shp_dict = pickle.load(shp_file)  # noqa: S301
         else:
-            with Path(path).open() as shp_file:
+            with Path(path).open(encoding="utf-8-sig") as shp_file:
                 shp_dict = yaml.safe_load(shp_file)
         shp_wrap = Wrapper(**shp_dict)
         if shp_wrap.datatype != cls.__name__:
             raise ValueError("Model in file does not match the actual Class")
         return cls(**shp_wrap.parameters)
 
+    @final
     def get_hash(self) -> str:
         return hashlib.sha3_224(str(self.model_dump()).encode("utf-8")).hexdigest()

{shepherd_core-2025.10.1 → shepherd_core-2026.2.1}/shepherd_core/data_models/base/wrapper.py

@@ -2,6 +2,7 @@
 
 from datetime import datetime
 from typing import Annotated
+from typing import final
 
 from pydantic import BaseModel
 from pydantic import StringConstraints
@@ -12,6 +13,7 @@ SafeStrClone = Annotated[str, StringConstraints(pattern=r"^[ -~]+$")]
 # ⤷ copy avoids circular import
 
 
+@final
 class Wrapper(BaseModel):
     """Generalized web- & file-interface for all models with dynamic typecasting."""