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

shepherd_core/testbed_client/client.py

@@ -41,8 +41,7 @@ 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"
+        """server: either "local" to use demo-fixtures or something like "https://HOST:PORT"
         token: your account validation
         """
         if isinstance(token, Path):
@@ -120,7 +119,7 @@ class TestbedClient:
         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 (

shepherd_core/testbed_client/fixtures.py

@@ -18,6 +18,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
@@ -174,10 +175,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,6 +194,7 @@ class Fixtures:
             for file in files:
                 self.insert_file(file)
 
+            save_path.parent.mkdir(parents=True, exist_ok=True)
             with save_path.open("wb", buffering=-1) as fd:
                 pickle.dump(self.components, fd)
 

shepherd_core/testbed_client/user_model.py

@@ -1,7 +1,10 @@
 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,10 +14,8 @@ 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
 
 
@@ -34,9 +35,10 @@ def hash_password(pw: Annotated[str, StringConstraints(min_length=20, max_length
 class User(ShpModel):
     """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/virtual_converter_model.py

@@ -6,7 +6,7 @@
 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
 
 """
 

shepherd_core/vsource/virtual_harvester_model.py

@@ -11,6 +11,7 @@ Compromises:
 - Python has no static vars -> FName_reset is handling the class-vars
 
 """
+
 from typing import Tuple
 
 from ..data_models.content.virtual_harvester import HarvesterPRUConfig

shepherd_core/vsource/virtual_source_model.py

@@ -6,6 +6,7 @@
 NOTE: DO NOT OPTIMIZE -> stay close to original code-base
 
 """
+
 from typing import Optional
 
 from ..data_models import CalibrationEmulator

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
@@ -87,6 +87,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
@@ -285,6 +286,7 @@ class Writer(Reader):
             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)
 
@@ -326,6 +328,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)

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

@@ -1,14 +1,12 @@
 Metadata-Version: 2.1
-Name: shepherd-core
-Version: 2023.12.1
+Name: shepherd_core
+Version: 2024.4.1
 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,8 +33,8 @@ 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
@@ -63,7 +61,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 +69,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 +117,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 +167,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
+```

shepherd_core-2024.4.1.dist-info/RECORD

@@ -0,0 +1,64 @@
+shepherd_core/__init__.py,sha256=UPDbfToRQ7BvvtGOE2ogINDK22SdlYdS3Z4TQp9JLUI,1358
+shepherd_core/calibration_hw_def.py,sha256=VBPgekKtoA6xc5pLOADGdAIuJUNz5kdDf3pm3A13F0U,2158
+shepherd_core/commons.py,sha256=8HLrOq30Zrgh0AcrtakJYyu3hwMgQks7mF7JyaBMcdw,170
+shepherd_core/logger.py,sha256=mIJQ5eCpamsCnc_R7qoceYVXe8JM4-YZriqfzvTt9Yk,1656
+shepherd_core/reader.py,sha256=NPpyMa0aArTyfz1vPHNbIzOGZQxkii96JUMX3jZ6_dY,26082
+shepherd_core/writer.py,sha256=VeBqJZYw6M5CeswPaYWWeAjtQ2xH9ROqA6ziEBK-Npg,14355
+shepherd_core/data_models/__init__.py,sha256=mem0m4nZY3EgG1ctBdGGGt128lhmglF9a4e5w9OGJu0,1651
+shepherd_core/data_models/doc_virtual_source.py,sha256=KizMcfGKj7BnHIbaJHT7KeTF01SV__UXv01qV_DGHSs,6057
+shepherd_core/data_models/base/__init__.py,sha256=ugVEWXfYRCmK4o94RG4N_GKR7AbBQLfn5PCbEKVpZMU,44
+shepherd_core/data_models/base/cal_measurement.py,sha256=ZlSnHXOiY--AzQ1-g0BnU7I4g9sMDqF3g52jsl5IHDY,2873
+shepherd_core/data_models/base/calibration.py,sha256=QTUGpW_YZ4slvfzUwkImp67u13gX90r5ua_qgbVPRXw,9711
+shepherd_core/data_models/base/content.py,sha256=oCefaykxq9HnuRe-6ruk_hC96WECZldriBFeX-PBb8M,2254
+shepherd_core/data_models/base/shepherd.py,sha256=kasSaMZ2baq160WNJMwEhdko2x13fsWYtE5VfHhg8Fs,5822
+shepherd_core/data_models/base/timezone.py,sha256=OBzPPfrD__z1aTO7qlVWD1uD8eZFJ6CoDLac_mTrYCg,443
+shepherd_core/data_models/base/wrapper.py,sha256=mzAMdX9-BeSAeTzlWKFnjj3v2wV6NJgaSHULFHEiWes,600
+shepherd_core/data_models/content/__init__.py,sha256=JLj2zzjDeyqLrz9KiWDMW1shCeJjj676zjcXj8ly10Y,545
+shepherd_core/data_models/content/energy_environment.py,sha256=bH6jB93e_XAAZ_NixNPlF2syEKzRtpMbImA7aD3lyTo,1342
+shepherd_core/data_models/content/firmware.py,sha256=cuh8tURI39ZzTF-wuh4ofsNfRC1TK8lHrGKYm-o9SC0,5533
+shepherd_core/data_models/content/firmware_datatype.py,sha256=WHVJu-LIP_snjeITIKkuZo7aIapoTIZeFXkUNqyEqy8,154
+shepherd_core/data_models/content/virtual_harvester.py,sha256=M23YRfmXPkW145GNFoMHJvsVvJE8wUc_sNOU3OBXZtc,9268
+shepherd_core/data_models/content/virtual_source.py,sha256=rBjfX1a22x_JF4MiQiEpaaWz2LVoHplMSrkHQnqHjDQ,13958
+shepherd_core/data_models/experiment/__init__.py,sha256=DX9kylCe8zFm4PpVT8YS4csip7-MDoSrdah3nhBdiJE,651
+shepherd_core/data_models/experiment/experiment.py,sha256=-qsmogEgHbijxrSfV0mLWj8biOMmDU1sEssZHo97HNI,3912
+shepherd_core/data_models/experiment/observer_features.py,sha256=80z_U3fVFagROtMlWy2vZdbLn1-G8fZm9k8rZlyo4Lo,4997
+shepherd_core/data_models/experiment/target_config.py,sha256=IBWxf3yVF5dUBi7mS5mJXfN1rL2S7QYhu_4IL6u6Yig,3532
+shepherd_core/data_models/task/__init__.py,sha256=g0l4dtIgTPKhfFvnClJrCm3zLFiZpBVbbQ2f4gzdwK0,3180
+shepherd_core/data_models/task/emulation.py,sha256=HE7L3GWKdsAkUPgvdDHxYJG92GNodP9CUEtKgQJghjA,6221
+shepherd_core/data_models/task/firmware_mod.py,sha256=8uXMFVk3Z96gUW0gVY95VeUx-YtZnMc2yw3paC5S5Mw,2730
+shepherd_core/data_models/task/harvest.py,sha256=QcNJjgixiq70NogdcYXwpj91_6Jl7s7CaAnEw_xEWck,3254
+shepherd_core/data_models/task/observer_tasks.py,sha256=_fgG_xqPHQN34jdWxXVvtgJuY_05YiLGPftTGtglTfk,3437
+shepherd_core/data_models/task/programming.py,sha256=uO6IZR8wb0N3791QgAZE7AF0CB7XoyOkFBiDH395IvE,2244
+shepherd_core/data_models/task/testbed_tasks.py,sha256=5T_aTUE6Fby-TG5ZZAcqXVolzs4oCQ_ttNXoinREE4U,1966
+shepherd_core/data_models/testbed/__init__.py,sha256=kQG0EUqJ5ylGRuwYZTbppWue9zDcSytpsHtUnohbGgA,566
+shepherd_core/data_models/testbed/cape.py,sha256=_u38jvy_7yv_J3HSjGblwZXX3iOm0JF7IpTEkF9zhyg,1140
+shepherd_core/data_models/testbed/gpio.py,sha256=9LlaxsWzEnjwaCobO-YcCWi1HZ67OsPKg5ExvtnVglQ,2086
+shepherd_core/data_models/testbed/mcu.py,sha256=enaKdwgmasJuyHlru3UqMIA-mUq1xAoafqAgzVITxoU,1287
+shepherd_core/data_models/testbed/observer.py,sha256=OjdvVa6uxreqIV9VM8jK1OM-RPsH4FGbKklY25_oTqg,3096
+shepherd_core/data_models/testbed/target.py,sha256=bKrPpVcdUNYcpEudbySQ6mPFibedeNsPy9kzUMu-Um0,1762
+shepherd_core/data_models/testbed/testbed.py,sha256=dR4yEwQKSMSXSGyPsuQ7zG2cp2LqCAQZjAzmuFOWvJo,3260
+shepherd_core/decoder_waveform/__init__.py,sha256=HEdjRcm3m4ySEXpJ_D3lZqnxiuobJqC8axZAaAHBwDk,43
+shepherd_core/decoder_waveform/uart.py,sha256=M4k5ymWeGP28i-_tl2FMG0YivY_WGpiZN2JOwSzlSBQ,10672
+shepherd_core/fw_tools/__init__.py,sha256=9W-MXU5j3iJ8AgRzoGUaljD0bN29jh8LtY-pyj5HWbY,2071
+shepherd_core/fw_tools/converter.py,sha256=2g0CZBZLn-CfUTpJljghf8AEpjIt4X7Q1FoCTsmx3A0,3273
+shepherd_core/fw_tools/converter_elf.py,sha256=SEkrPuYUsr1VICDlZiZzr0B1njWcl9mW3J_oZk32Sb4,1008
+shepherd_core/fw_tools/patcher.py,sha256=nXgYKGQjcEE4IYd8yNl4-t5kjlB43iFdp24oYlEaras,3774
+shepherd_core/fw_tools/validation.py,sha256=pdZ4Q7_GyMUarELBt3OOTPIqZIGtDF3MBqOhlF75n4E,4261
+shepherd_core/inventory/__init__.py,sha256=vTeAXOHk3paE3McpWQNBlsll40wY-IQT8alPh3n_1dE,3690
+shepherd_core/inventory/python.py,sha256=Ar_M4cmmQgViY4caU5XH9Iye5X3jNFDnJiWGaZwNpo4,1168
+shepherd_core/inventory/system.py,sha256=lD70oYMF0dPDvYDglhYIXIfjEFtxVoY9Zhoiwvj-oo0,2181
+shepherd_core/inventory/target.py,sha256=XywiKmDpYKIBQt1Jo_k3bJeCOKxnzy5ob_9PYdFrjGE,421
+shepherd_core/testbed_client/__init__.py,sha256=V38uxXOhwB8tlAjR0jH1MPSWB1LltwC0g8ipwaIyC9o,103
+shepherd_core/testbed_client/cache_path.py,sha256=ZAoYi0je5Bg6fcP_OJa32zL6rXNPL5Ef-8vSungW9_M,401
+shepherd_core/testbed_client/client.py,sha256=83RynaL7MiezZky-Iw-K6m8QWqRV4hAHW8awKNcTUFk,5776
+shepherd_core/testbed_client/fixtures.py,sha256=vhSYWd3OgMP4fL5I_n1Y6flR68aSJlJnR6yFwX-D38Y,9233
+shepherd_core/testbed_client/user_model.py,sha256=6HfDSRs4WgttEA1znVLdNwV8Pv7R_0YKxK0b30hr6mQ,2026
+shepherd_core/vsource/__init__.py,sha256=x84_0M8Dg8R7DLKE5zyNAAGFiuOHPehDOWPt2KeBhKw,344
+shepherd_core/vsource/virtual_converter_model.py,sha256=DCNf-O3gFmU1DIbZkESNvveCJ5sN-5dZoqAxBUogzO4,10332
+shepherd_core/vsource/virtual_harvester_model.py,sha256=MoMa2S0VKfK1Q8fZ9CEx7sNnr3b3ae8M4YhsyY5DSgY,7764
+shepherd_core/vsource/virtual_source_model.py,sha256=5AcNG7s_GqGn4hTzCWKTz0CNIBjF8g3YsZtc8HF0D5Q,2724
+shepherd_core-2024.4.1.dist-info/METADATA,sha256=G0Lc2ETRLVsNDAKlpq3Od7xYsClqjbwjJiYyeEwFiv0,7618
+shepherd_core-2024.4.1.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
+shepherd_core-2024.4.1.dist-info/top_level.txt,sha256=wy-t7HRBrKARZxa-Y8_j8d49oVHnulh-95K9ikxVhew,14
+shepherd_core-2024.4.1.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+shepherd_core-2024.4.1.dist-info/RECORD,,

{shepherd_core-2023.12.1.dist-info → shepherd_core-2024.4.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.42.0)
+Generator: bdist_wheel (0.43.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

{shepherd_core-2023.12.1.dist-info → shepherd_core-2024.4.1.dist-info}/top_level.txt

@@ -1,2 +1 @@
 shepherd_core
-tests