shepherd-data 2023.2.1__py3-none-any.whl → 2023.3.1__py3-none-any.whl

shepherd_data/writer.py

@@ -5,7 +5,6 @@ import logging
 import math
 from itertools import product
 from pathlib import Path
-from typing import NoReturn
 from typing import Optional
 from typing import Union
 
@@ -27,7 +26,7 @@ def unique_path(base_path: Union[str, Path], suffix: str) -> Path:
     """
     counter = 0
     while True:
-        path = base_path.with_suffix(f".{counter}{suffix}")
+        path = Path(base_path).with_suffix(f".{counter}{suffix}")
         if not path.exists():
             return path
         counter += 1
@@ -57,35 +56,32 @@ class Writer(Reader):
     #         -> lower levels seem fine
     #         -> _algo=number instead of "gzip" is read as compression level for gzip
     # -> comparison / benchmarks https://www.h5py.org/lzf/
-    comp_default = 1
+    comp_default: int = 1
     mode_default: str = "harvester"
     datatype_default: str = "ivsample"
 
     _chunk_shape: tuple = (Reader.samples_per_buffer,)
 
-    _logger: logging.Logger = logging.getLogger("SHPData.Writer")
-
     def __init__(
         self,
         file_path: Path,
-        mode: str = None,
-        datatype: str = None,
-        window_samples: int = None,
-        cal_data: dict = None,
+        mode: Optional[str] = None,
+        datatype: Optional[str] = None,
+        window_samples: Optional[int] = None,
+        cal_data: Optional[dict] = None,
         modify_existing: bool = False,
         compression: Union[None, str, int] = "default",
         verbose: Optional[bool] = True,
     ):
-        super().__init__(file_path=None, verbose=verbose)
-
         file_path = Path(file_path)
         self._modify = modify_existing
 
-        if verbose is not None:
-            self._logger.setLevel(logging.INFO if verbose else logging.WARNING)
+        if not hasattr(self, "_logger"):
+            self._logger: logging.Logger = logging.getLogger("SHPData.Writer")
+        # -> logger gets configured in reader()
 
         if self._modify or not file_path.exists():
-            self._file_path = file_path
+            self._file_path: Path = file_path
             self._logger.info("Storing data to   '%s'", self._file_path)
         else:
             base_dir = file_path.resolve().parents[0]
@@ -97,94 +93,60 @@ class Writer(Reader):
             )
 
         if not isinstance(mode, (str, type(None))):
-            raise TypeError(f"can not handle type '{type(mode)}' for mode")
+            raise TypeError(f"Can't handle type '{type(mode)}' for mode [str, None]")
         if isinstance(mode, str) and mode not in self.mode_dtype_dict:
-            raise ValueError(f"can not handle mode '{mode}'")
+            raise ValueError(
+                f"Can't handle mode '{mode}' " f"(choose one of {self.mode_dtype_dict})"
+            )
+        if not isinstance(window_samples, (int, type(None))):
+            raise TypeError(
+                f"Can't handle type '{type(window_samples)}' for window_samples [int, None]"
+            )
+        if not isinstance(cal_data, (dict, type(None))):
+            raise TypeError(
+                f"Can't handle type '{type(cal_data)}' for cal_data [dict, None]"
+            )
 
         if not isinstance(datatype, (str, type(None))):
-            raise TypeError(f"can not handle type '{type(datatype)}' for datatype")
-        if (
-            isinstance(datatype, str)
-            and datatype
-            not in self.mode_dtype_dict[self.mode_default if (mode is None) else mode]
-        ):
-            raise ValueError(f"can not handle datatype '{datatype}'")
+            raise TypeError(
+                f"Can't handle type '{type(datatype)}' for datatype [str, None]"
+            )
+
+        _dtypes = self.mode_dtype_dict[self.mode_default if (mode is None) else mode]
+        if isinstance(datatype, str) and datatype not in _dtypes:
+            raise ValueError(
+                f"Can't handle value '{datatype}' of datatype "
+                f"(choose one of {_dtypes})"
+            )
 
         if self._modify:
             self._mode = mode
-            self._cal = cal_data
+            self._cal = (
+                cal_data if isinstance(cal_data, dict) else cal_default
+            )  # TODO: switch to pydantic
             self._datatype = datatype
             self._window_samples = window_samples
         else:
-            self._mode = self.mode_default if (mode is None) else mode
-            self._cal = cal_default if (cal_data is None) else cal_data
-            self._datatype = self.datatype_default if (datatype is None) else datatype
-            self._window_samples = 0 if (window_samples is None) else window_samples
+            self._mode = mode if isinstance(mode, str) else self.mode_default
+            self._cal = cal_data if isinstance(cal_data, dict) else cal_default
+            self._datatype = (
+                datatype if isinstance(datatype, str) else self.datatype_default
+            )
+            self._window_samples = (
+                window_samples if isinstance(window_samples, int) else 0
+            )
 
         if compression in [None, "lzf", 1]:  # order of recommendation
             self._compression_algo = compression
         else:
             self._compression_algo = self.comp_default
 
-    def __enter__(self):
-        """Initializes 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
-        data types. We will store 3 types of data in a database: The
-        actual IV samples recorded either from the harvester (during recording)
-        or the target (during emulation). Any log messages, that can be used to
-        store relevant events or tag some parts of the recorded data.
-
-        """
+        # open file
         if self._modify:
-            self.h5file = h5py.File(self._file_path, "r+")
+            self.h5file = h5py.File(self._file_path, "r+")  # = rw
         else:
-            self.h5file = h5py.File(self._file_path, "w")
-
-            # Store voltage and current samples in the data group,
-            # both are stored as 4 Byte unsigned int
-            gp_data = self.h5file.create_group("data")
-            # the size of window_samples-attribute in harvest-data indicates ivcurves as input
-            # -> emulator uses virtual-harvester, field will be adjusted by .embed_config()
-            gp_data.attrs["window_samples"] = 0
-
-            gp_data.create_dataset(
-                "time",
-                (0,),
-                dtype="u8",
-                maxshape=(None,),
-                chunks=self._chunk_shape,
-                compression=self._compression_algo,
-            )
-            gp_data["time"].attrs["unit"] = "ns"
-            gp_data["time"].attrs["description"] = "system time [ns]"
-
-            gp_data.create_dataset(
-                "current",
-                (0,),
-                dtype="u4",
-                maxshape=(None,),
-                chunks=self._chunk_shape,
-                compression=self._compression_algo,
-            )
-            gp_data["current"].attrs["unit"] = "A"
-            gp_data["current"].attrs[
-                "description"
-            ] = "current [A] = value * gain + offset"
-
-            gp_data.create_dataset(
-                "voltage",
-                (0,),
-                dtype="u4",
-                maxshape=(None,),
-                chunks=self._chunk_shape,
-                compression=self._compression_algo,
-            )
-            gp_data["voltage"].attrs["unit"] = "V"
-            gp_data["voltage"].attrs[
-                "description"
-            ] = "voltage [V] = value * gain + offset"
+            self.h5file = h5py.File(self._file_path, "w")  # write, truncate if exist
+            self._create_skeleton()
 
         # Store the mode in order to allow user to differentiate harvesting vs emulation data
         if isinstance(self._mode, str) and self._mode in self.mode_dtype_dict:
@@ -208,11 +170,13 @@ class Writer(Reader):
                 self.h5file["data"][channel].attrs[parameter] = self._cal[channel][
                     parameter
                 ]
+        super().__init__(file_path=None, verbose=verbose)
 
+    def __enter__(self):
         super().__enter__()
         return self
 
-    def __exit__(self, *exc):
+    def __exit__(self, *exc):  # type: ignore
         self._align()
         self._refresh_file_stats()
         self._logger.info(
@@ -224,12 +188,63 @@ class Writer(Reader):
         self.is_valid()
         self.h5file.close()
 
+    def _create_skeleton(self) -> None:
+        """Initializes 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
+        data types. We will store 3 types of data in a database: The
+        actual IV samples recorded either from the harvester (during recording)
+        or the target (during emulation). Any log messages, that can be used to
+        store relevant events or tag some parts of the recorded data.
+
+        """
+        # Store voltage and current samples in the data group,
+        # both are stored as 4 Byte unsigned int
+        gp_data = self.h5file.create_group("data")
+        # the size of window_samples-attribute in harvest-data indicates ivcurves as input
+        # -> emulator uses virtual-harvester, field will be adjusted by .embed_config()
+        gp_data.attrs["window_samples"] = 0
+
+        gp_data.create_dataset(
+            "time",
+            (0,),
+            dtype="u8",
+            maxshape=(None,),
+            chunks=self._chunk_shape,
+            compression=self._compression_algo,
+        )
+        gp_data["time"].attrs["unit"] = "ns"
+        gp_data["time"].attrs["description"] = "system time [ns]"
+
+        gp_data.create_dataset(
+            "current",
+            (0,),
+            dtype="u4",
+            maxshape=(None,),
+            chunks=self._chunk_shape,
+            compression=self._compression_algo,
+        )
+        gp_data["current"].attrs["unit"] = "A"
+        gp_data["current"].attrs["description"] = "current [A] = value * gain + offset"
+
+        gp_data.create_dataset(
+            "voltage",
+            (0,),
+            dtype="u4",
+            maxshape=(None,),
+            chunks=self._chunk_shape,
+            compression=self._compression_algo,
+        )
+        gp_data["voltage"].attrs["unit"] = "V"
+        gp_data["voltage"].attrs["description"] = "voltage [V] = value * gain + offset"
+
     def append_iv_data_raw(
         self,
         timestamp_ns: Union[np.ndarray, float, int],
         voltage: np.ndarray,
         current: np.ndarray,
-    ) -> NoReturn:
+    ) -> None:
         """Writes raw data to database
 
         Args:
@@ -266,23 +281,24 @@ class Writer(Reader):
         self,
         timestamp: Union[np.ndarray, float],
         voltage: np.ndarray,
-        current: np.array,
-    ) -> NoReturn:
+        current: np.ndarray,
+    ) -> None:
         """Writes data (in SI / physical unit) to file, but converts it to raw-data first
 
+           SI-value [SI-Unit] = raw-value * gain + offset,
+
         Args:
             timestamp: python timestamp (time.time()) in seconds (si-unit)
                        -> provide start of buffer or whole ndarray
             voltage: ndarray in physical-unit V
             current: ndarray in physical-unit A
         """
-        # SI-value [SI-Unit] = raw-value * gain + offset,
         timestamp = timestamp * 10**9
         voltage = si_to_raw(voltage, self._cal["voltage"])
         current = si_to_raw(current, self._cal["current"])
         self.append_iv_data_raw(timestamp, voltage, current)
 
-    def _align(self) -> NoReturn:
+    def _align(self) -> None:
         """Align datasets with buffer-size of shepherd"""
         self._refresh_file_stats()
         n_buff = self.ds_time.size / self.samples_per_buffer
@@ -299,11 +315,11 @@ class Writer(Reader):
             self.ds_voltage.resize((size_new,))
             self.ds_current.resize((size_new,))
 
-    def __setitem__(self, key, item):
+    def __setitem__(self, key: str, item):  # type: ignore
         """A convenient interface to store relevant key-value data (attribute) if H5-structure"""
         return self.h5file.attrs.__setitem__(key, item)
 
-    def set_config(self, data: dict) -> NoReturn:
+    def set_config(self, data: dict) -> None:
         """Important Step to get a self-describing Output-File
 
         :param data: from virtual harvester or converter / source
@@ -314,14 +330,14 @@ class Writer(Reader):
         if "window_samples" in data:
             self.set_window_samples(data["window_samples"])
 
-    def set_window_samples(self, samples: int = 0) -> NoReturn:
+    def set_window_samples(self, samples: int = 0) -> None:
         """parameter essential for ivcurves
 
         :param samples: length of window / voltage sweep
         """
         self.h5file["data"].attrs["window_samples"] = samples
 
-    def set_hostname(self, name: str) -> NoReturn:
+    def set_hostname(self, name: str) -> None:
         """option to distinguish the host, target or data-source in the testbed
             -> perfect for plotting later
 

{shepherd_data-2023.2.1.dist-info → shepherd_data-2023.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: shepherd-data
-Version: 2023.2.1
+Version: 2023.3.1
 Summary: Programming- and CLI-Interface for the h5-dataformat of the Shepherd-Testbed
 Home-page: https://pypi.org/project/shepherd-data/
 Author: Ingmar Splitt, Kai Geissdoerfer
@@ -45,43 +45,53 @@ Requires-Dist: pylint ; extra == 'dev'
 Requires-Dist: flake8 ; extra == 'dev'
 Requires-Dist: twine ; extra == 'dev'
 Requires-Dist: pre-commit ; extra == 'dev'
+Requires-Dist: pyright ; extra == 'dev'
+Requires-Dist: pandas-stubs ; extra == 'dev'
 Provides-Extra: test
 Requires-Dist: pytest ; extra == 'test'
 Requires-Dist: pytest-click ; extra == 'test'
 Requires-Dist: coverage ; extra == 'test'
 
+# Shepherd - Data
+
 [![PyPiVersion](https://img.shields.io/pypi/v/shepherd_data.svg)](https://pypi.org/project/shepherd_data)
 [![Pytest](https://github.com/orgua/shepherd-datalib/actions/workflows/python-app.yml/badge.svg)](https://github.com/orgua/shepherd-datalib/actions/workflows/python-app.yml)
 [![CodeStyle](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
-## Shepherd - Data
-
 This Python Module eases the handling of hdf5-recordings used by the [shepherd](https://github.com/orgua/shepherd)-testbed. Users can read, validate and create files and also extract, down-sample and plot information.
 
-### Installation
+---
 
-#### PIP - Online
+**Main Project**: [https://github.com/orgua/shepherd](https://github.com/orgua/shepherd)
 
-```Shell
+**Source Code**: [https://github.com/orgua/shepherd-datalib](https://github.com/orgua/shepherd-datalib)
+
+---
+
+## Installation
+
+### PIP - Online
+
+```shell
 pip3 install shepherd-data
 ```
 
-#### PIP - Offline
+### PIP - Offline
 
 - clone repository
 - navigate shell into directory
 - install local module
 
-```Shell
+```shell
 git clone https://github.com/orgua/shepherd-datalib
 cd .\shepherd-datalib
 
 pip3 install ./
 ```
 
-### Development
+## Development
 
-#### PipEnv
+### PipEnv
 
 - clone repository
 - navigate shell into directory
@@ -103,20 +113,20 @@ pipenv update
 pipenv install --dev pytest
 ```
 
-#### running Testbench
+### running Testbench
 
 - run pytest
 
-```Shell
+```shell
 pytest
 ```
 
-#### code coverage (with pytest)
+### code coverage (with pytest)
 
 - run coverage
 - check results (in browser `./htmlcov/index.html`)
 
-```Shell
+```shell
 coverage run -m pytest
 
 coverage html
@@ -124,11 +134,11 @@ coverage html
 coverage report
 ```
 
-### Programming Interface
+## Programming Interface
 
-#### Basic Usage (recommendation)
+### Basic Usage (recommendation)
 
-```Python
+```python
 import shepherd_data as shpd
 
 with shpd.Reader("./hrv_sawtooth_1h.h5") as db:
@@ -137,7 +147,7 @@ with shpd.Reader("./hrv_sawtooth_1h.h5") as db:
     print(f"Config: {db.get_config()}")
 ```
 
-#### Available Functionality
+### Available Functionality
 
 - `Reader()`
   - file can be checked for plausibility and validity (`is_valid()`)
@@ -172,7 +182,7 @@ with shpd.Reader("./hrv_sawtooth_1h.h5") as db:
       - 50 Hz measurement with Short-Circuit-Current and two other parameters
       - recorded with "IVonne"
 
-### CLI-Interface
+## CLI-Interface
 
 After installing the module the datalib offers some often needed functionality on the command line:
 
@@ -180,7 +190,7 @@ After installing the module the datalib offers some often needed functionality o
 
 - takes a file or directory as an argument
 
-```Shell
+```shell
 shepherd-data validate dir_or_file
 
 # examples:
@@ -193,7 +203,7 @@ shepherd-data validate hrv_saw_1h.h5
 - takes a file or directory as an argument
 - can take down-sample-factor as an argument
 
-```Shell
+```shell
 shepherd-data extract [-f ds-factor] [-s separator_symbol] dir_or_file
 
 # examples:
@@ -205,7 +215,7 @@ shepherd-data extract -f 1000 -s ; hrv_saw_1h.h5
 
 - takes a file or directory as an argument
 
-```Shell
+```shell
 shepherd-data extract-meta dir_or_file
 
 # examples:
@@ -219,7 +229,7 @@ shepherd-data extract-meta hrv_saw_1h.h5
 - can take start- and end-time as an argument
 - can take image-width and -height as an argument
 
-```Shell
+```shell
 shepherd-data plot [-s start_time] [-e end_time] [-w plot_width] [-h plot_height] [--multiplot] dir_or_file
 
 # examples:
@@ -233,7 +243,7 @@ shepherd-data plot -s10 -e20 hrv_saw_1h.h5
 - takes a file or directory as an argument
 - can take down-sample-factor as an argument
 
-```Shell
+```shell
 shepherd-data downsample [-f ds-factor] [-r sample-rate] dir_or_file
 
 # examples:
@@ -242,7 +252,7 @@ shepherd-data downsample -f 1000 hrv_saw_1h.h5
 shepherd-data downsample -r 100 hrv_saw_1h.h5
 ```
 
-### Data-Layout and Design choices
+## Data-Layout and Design choices
 
 Details about the file-structure can be found in the [main-project](https://github.com/orgua/shepherd/blob/main/docs/user/data_format.rst).
 
@@ -250,7 +260,7 @@ TODO:
 - update design of file
 - data dtype, mode, ...
 
-#### Modes and Datatypes
+### Modes and Datatypes
 
 - Mode `harvester` recorded a harvesting-source like solar with one of various algorithms
   - Datatype `ivsample` is directly usable by shepherd, input for virtual source / converter
@@ -259,7 +269,7 @@ TODO:
 - Mode `emulator` replayed a harvester-recording through a virtual converter and supplied a target while recording the power-consumption
   - Datatype `ivsample` is the only output of this mode
 
-#### Compression & Beaglebone
+### Compression & Beaglebone
 
 - supported are uncompressed, lzf and gzip with level 1 (order of recommendation)
   - lzf seems better-suited due to lower load, or if space isn't a constraint: uncompressed (None as argument)
@@ -284,7 +294,7 @@ TODO:
   emu_120s_unc_to_unc.h5 	-> emulator, cpu_util [%] = 51.69, data-rate = 1564.0 KiB/s
 ```
 
-### Release-Procedure
+## Release-Procedure
 
 - increase version number in __init__.py
 - install and run pre-commit, for QA-Checks, see steps below
@@ -292,13 +302,13 @@ TODO:
 - put together a release on Github - the tag should match current version-number
 - Github automatically pushes release to pypi
 
-```Shell
+```shell
 pip3 install pre-commit
 
 pre-commit run --all-files
 ```
 
-### Open Tasks
+## Open Tasks
 
 - [click progressbar](https://click.palletsprojects.com/en/8.1.x/api/#click.progressbar) -> could replace tqdm
 - implementations for this lib

shepherd_data-2023.3.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+shepherd_data/__init__.py,sha256=PcRoZstviwMJ9lX_yD3x7M2xwyuSNgDh-Iz7zc7rfeI,338
+shepherd_data/calibration.py,sha256=QJBioq1VTKEQRxH-kfILZtZj8eQIsg3fuv3Iwo2rDp8,1702
+shepherd_data/cli.py,sha256=nVtSRTdBkCQQSLti2OWF-LhvK1EEh5k_Z7rf4HeRgyY,10785
+shepherd_data/ivonne.py,sha256=eYKa3rxRFbD8b_Svt7vuOEVHQc6V9Facs5DDeK2IgGA,11683
+shepherd_data/mppt.py,sha256=t-GkSmcB8bUaLsqjWsD--voUdFxnNBHIy8D8LcaIXt8,3598
+shepherd_data/reader.py,sha256=CNOdxBallUHoRl9CiIBNi9m9yhYvptQ_tqBsgStMSLY,36078
+shepherd_data/writer.py,sha256=nn5T8pLHbz2FSOfD8yEPvGJLkzrmCcbwitCO0BK9kKc,13261
+shepherd_data-2023.3.1.dist-info/LICENSE,sha256=_d1BhE98zOhkxahuCifG6l34LjhJanVunxp5-QMQHpE,1069
+shepherd_data-2023.3.1.dist-info/METADATA,sha256=AgWVKXvxQU9PPKERT62HsAR_uVWaDgHBj8kFIJQMQq8,12217
+shepherd_data-2023.3.1.dist-info/WHEEL,sha256=pkctZYzUS4AYVn6dJ-7367OJZivF2e8RA9b_ZBjif18,92
+shepherd_data-2023.3.1.dist-info/entry_points.txt,sha256=6PBfY36A1xNOdzLiz-Qoukya_UzFZAwOapwmRNnPeZ8,56
+shepherd_data-2023.3.1.dist-info/top_level.txt,sha256=7-SCTY-TG1mLY72OVKCaqte1hy-X8woxknIUAD3OIxs,14
+shepherd_data-2023.3.1.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+shepherd_data-2023.3.1.dist-info/RECORD,,

{shepherd_data-2023.2.1.dist-info → shepherd_data-2023.3.1.dist-info}/WHEEL

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

shepherd_data-2023.2.1.dist-info/RECORD

@@ -1,14 +0,0 @@
-shepherd_data/__init__.py,sha256=vOcsbuxOTwP1PrLgvd33c_dt8Cu5sXvJvrUNJV0SARA,337
-shepherd_data/calibration.py,sha256=j9iEm9XNSI4Z8O3hrCuFqupoOBczdNOhnDIzywWtnrQ,1387
-shepherd_data/cli.py,sha256=lmFJi_qMRQu9oArBnOwbFmazqvpD4Z-urYojZWfeqYc,10435
-shepherd_data/ivonne.py,sha256=q8kscQCerJ81f10_wXPsN1GdM6jnemfY7vra28e_2FM,11111
-shepherd_data/mppt.py,sha256=X8kKB4x8J8xwn3peIUG12fEtGybyGABf5CA9a6poJhc,3487
-shepherd_data/reader.py,sha256=6I_A_agALqi7DwTYgNpHjPjLuJjmAdDAsZK-DnY46aY,34366
-shepherd_data/writer.py,sha256=51fsSsTkJl8-1KIYgclp6Jwtqjj6V0njVb26lSCqqZU,12536
-shepherd_data-2023.2.1.dist-info/LICENSE,sha256=_d1BhE98zOhkxahuCifG6l34LjhJanVunxp5-QMQHpE,1069
-shepherd_data-2023.2.1.dist-info/METADATA,sha256=-wz_vWdMDABNDXajtswFiCqO2lVBcpYYk12wGrA2HwY,11944
-shepherd_data-2023.2.1.dist-info/WHEEL,sha256=2wepM1nk4DS4eFpYrW1TTqPcoGNfHhhO_i5m4cOimbo,92
-shepherd_data-2023.2.1.dist-info/entry_points.txt,sha256=6PBfY36A1xNOdzLiz-Qoukya_UzFZAwOapwmRNnPeZ8,56
-shepherd_data-2023.2.1.dist-info/top_level.txt,sha256=7-SCTY-TG1mLY72OVKCaqte1hy-X8woxknIUAD3OIxs,14
-shepherd_data-2023.2.1.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-shepherd_data-2023.2.1.dist-info/RECORD,,