From 5652a048c73c10db4ff9fac619fc5b005e01c7ae Mon Sep 17 00:00:00 2001 From: prasad-sawantdesai Date: Tue, 18 Mar 2025 11:35:02 +0100 Subject: [PATCH 1/8] added workflow for sphinx doc generation and fixed docstrings --- .github/workflows/verify_sphinx_doc.yml | 56 +++++++++++++++++++++++++ docs/source/changelog.rst | 4 +- imas/backends/imas_core/al_context.py | 12 ++++++ imas/backends/netcdf/ids_tensorizer.py | 11 +++++ imas/backends/netcdf/nc2ids.py | 38 +++++++++++++++++ 5 files changed, 119 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/verify_sphinx_doc.yml diff --git a/.github/workflows/verify_sphinx_doc.yml b/.github/workflows/verify_sphinx_doc.yml new file mode 100644 index 0000000..706fa1b --- /dev/null +++ b/.github/workflows/verify_sphinx_doc.yml @@ -0,0 +1,56 @@ +name: verify-sphinx-doc-generation + +on: + push: + pull_request: + types: [opened, synchronize, reopened] + +jobs: + build-and-test: + runs-on: ubuntu-22.04 + + steps: + - name: Checkout IMAS-Python sources + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + with: + # until saxonche is available in 3.13 + # https://saxonica.plan.io/issues/6561 + python-version: "<3.13" + + - name: Display Python version + run: python -c "import sys; print(sys.version)" + + + - name: Set up Python virtual environment + run: | + python -m venv venv + source venv/bin/activate + + - name: Install build dependencies + run: | + pip install --upgrade pip setuptools wheel build + + - name: Build package + run: | + rm -rf dist + python -m build . + + - name: Install package and dependencies + run: | + pip install "$(readlink -f dist/*.whl)[docs,netcdf]" + + - name: Debug dependencies + run: | + pip freeze + + - name: Build Sphinx documentation + run: | + export SPHINXOPTS='-W -n --keep-going' + make -C docs clean html + + - name: Deactivate virtual environment + run: deactivate \ No newline at end of file diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst index b764f73..92d8b04 100644 --- a/docs/source/changelog.rst +++ b/docs/source/changelog.rst @@ -4,12 +4,12 @@ Changelog ========= What's new in IMAS-Python 1.2.0 --------------------------- +------------------------------- New features and improvements ''''''''''''''''''''''''''''' -- Add :py:func:`imaspy.DBEntry.get_sample` (requires imas_core >= 5.4.0) +- Add :py:func:`imas.DBEntry.get_sample` previously imaspy.DBEntry.get_sample (requires imas_core >= 5.4.0) - Improved validation of netCDF files - Improve compatibility with the UDA backend in imas_core - Extend the support of netCDF to >= 1.4.1 (without complex numbers) diff --git a/imas/backends/imas_core/al_context.py b/imas/backends/imas_core/al_context.py index 19b34d8..7fafd77 100644 --- a/imas/backends/imas_core/al_context.py +++ b/imas/backends/imas_core/al_context.py @@ -282,6 +282,18 @@ def __init__( """Potential weak reference to opened context.""" def get_child(self, child): + """ + Retrieve a child entry from the field. + + Args: + child (str): The name or identifier of the child entry to retrieve. + + Returns: + The child entry retrieved from the database. + + Raises: + Exception: If the child entry cannot be found or an error occurs during retrieval. + """ imas.backends.imas_core.db_entry_helpers._get_child(child, self) def get_context(self) -> ALContext: diff --git a/imas/backends/netcdf/ids_tensorizer.py b/imas/backends/netcdf/ids_tensorizer.py index 95bfba4..3e9f77d 100644 --- a/imas/backends/netcdf/ids_tensorizer.py +++ b/imas/backends/netcdf/ids_tensorizer.py @@ -169,6 +169,17 @@ def filter_coordinates(self, path: str) -> str: ) def tensorize(self, path, fillvalue): + """ + Tensorizes the data at the given path with the specified fill value. + + Args: + path (str): The path to the data in the NetCDF file. + fillvalue (any): The value to fill the tensor with. Can be of any type, + including strings. + + Returns: + numpy.ndarray: A tensor filled with the data from the specified path. + """ dimensions = self.ncmeta.get_dimensions(path, self.homogeneous_time) shape = tuple(self.dimension_size[dim] for dim in dimensions) diff --git a/imas/backends/netcdf/nc2ids.py b/imas/backends/netcdf/nc2ids.py index e9b524f..a4da2b6 100644 --- a/imas/backends/netcdf/nc2ids.py +++ b/imas/backends/netcdf/nc2ids.py @@ -317,6 +317,13 @@ def __init__(self, nc2ids, index=()): self.index = index def get_child(self, child): + """ + Retrieves and sets the appropriate context or value for a given child node based on its metadata. + + Args: + child: The child node for which the context or value is to be set. The child node should have metadata attributes. + + """ metadata = child.metadata path = metadata.path_string data_type = metadata.data_type @@ -366,12 +373,43 @@ def get_child(self, child): class LazyArrayStructContext(LazyContext): + """ + LazyArrayStructContext is a subclass of LazyContext that provides a context for + handling structured arrays in a lazy manner. It is initialized with a NetCDF to + IDS mapping object, an index, and a size. + """ def __init__(self, nc2ids, index, size): + """ + Initialize the instance with nc2ids, index, and size. + + Args: + nc2ids: The NetCDF to IDS mapping object. + index: The index within the NetCDF file. + size: The size of the data to be processed. + """ super().__init__(nc2ids, index) self.size = size def get_context(self): + """ + Returns the current context. + + This method returns the current instance of the class, which is expected + to have a 'size' attribute as required by IDSStructArray. + + Returns: + self: The current instance of the class. + """ return self # IDSStructArray expects to get something with a size attribute def iterate_to_index(self, index: int) -> LazyContext: + """ + Iterates to a specified index and returns a LazyContext object. + + Args: + index (int): The index to iterate to. + + Returns: + LazyContext: A LazyContext object initialized with the updated index. + """ return LazyContext(self.nc2ids, self.index + (index,)) From c74009bcee597c6a163d72b8c3510085101a377c Mon Sep 17 00:00:00 2001 From: prasad-sawantdesai Date: Tue, 18 Mar 2025 13:13:48 +0100 Subject: [PATCH 2/8] fix sphinx docstring issue --- docs/source/changelog.rst | 2 +- imas/backends/netcdf/ids_tensorizer.py | 6 +++--- imas/backends/netcdf/nc2ids.py | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst index 92d8b04..d04aea0 100644 --- a/docs/source/changelog.rst +++ b/docs/source/changelog.rst @@ -9,7 +9,7 @@ What's new in IMAS-Python 1.2.0 New features and improvements ''''''''''''''''''''''''''''' -- Add :py:func:`imas.DBEntry.get_sample` previously imaspy.DBEntry.get_sample (requires imas_core >= 5.4.0) +- Add :py:func:`imas.DBEntry.get_sample ` (requires imas_core >= 5.4.0) - Improved validation of netCDF files - Improve compatibility with the UDA backend in imas_core - Extend the support of netCDF to >= 1.4.1 (without complex numbers) diff --git a/imas/backends/netcdf/ids_tensorizer.py b/imas/backends/netcdf/ids_tensorizer.py index 3e9f77d..38e934e 100644 --- a/imas/backends/netcdf/ids_tensorizer.py +++ b/imas/backends/netcdf/ids_tensorizer.py @@ -173,12 +173,12 @@ def tensorize(self, path, fillvalue): Tensorizes the data at the given path with the specified fill value. Args: - path (str): The path to the data in the NetCDF file. - fillvalue (any): The value to fill the tensor with. Can be of any type, + path: The path to the data in the NetCDF file. + fillvalue: The value to fill the tensor with. Can be of any type, including strings. Returns: - numpy.ndarray: A tensor filled with the data from the specified path. + A tensor filled with the data from the specified path. """ dimensions = self.ncmeta.get_dimensions(path, self.homogeneous_time) shape = tuple(self.dimension_size[dim] for dim in dimensions) diff --git a/imas/backends/netcdf/nc2ids.py b/imas/backends/netcdf/nc2ids.py index a4da2b6..0af27d9 100644 --- a/imas/backends/netcdf/nc2ids.py +++ b/imas/backends/netcdf/nc2ids.py @@ -398,7 +398,7 @@ def get_context(self): to have a 'size' attribute as required by IDSStructArray. Returns: - self: The current instance of the class. + The current instance of the class. """ return self # IDSStructArray expects to get something with a size attribute From 9bad55f34bbae385e53a69ec401bbaeddfff4110 Mon Sep 17 00:00:00 2001 From: prasad-sawantdesai Date: Tue, 18 Mar 2025 13:31:41 +0100 Subject: [PATCH 3/8] fixed formatting --- imas/backends/imas_core/al_context.py | 3 ++- imas/backends/netcdf/nc2ids.py | 13 ++++++++----- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/imas/backends/imas_core/al_context.py b/imas/backends/imas_core/al_context.py index 7fafd77..2b6117e 100644 --- a/imas/backends/imas_core/al_context.py +++ b/imas/backends/imas_core/al_context.py @@ -292,7 +292,8 @@ def get_child(self, child): The child entry retrieved from the database. Raises: - Exception: If the child entry cannot be found or an error occurs during retrieval. + Exception: If the child entry cannot be found or an error occurs + during retrieval. """ imas.backends.imas_core.db_entry_helpers._get_child(child, self) diff --git a/imas/backends/netcdf/nc2ids.py b/imas/backends/netcdf/nc2ids.py index 0af27d9..509b754 100644 --- a/imas/backends/netcdf/nc2ids.py +++ b/imas/backends/netcdf/nc2ids.py @@ -318,10 +318,12 @@ def __init__(self, nc2ids, index=()): def get_child(self, child): """ - Retrieves and sets the appropriate context or value for a given child node based on its metadata. + Retrieves and sets the appropriate context or value for a given + child node based on its metadata. Args: - child: The child node for which the context or value is to be set. The child node should have metadata attributes. + child: The child node for which the context or value is to be + set. The child node should have metadata attributes. """ metadata = child.metadata @@ -374,10 +376,11 @@ def get_child(self, child): class LazyArrayStructContext(LazyContext): """ - LazyArrayStructContext is a subclass of LazyContext that provides a context for - handling structured arrays in a lazy manner. It is initialized with a NetCDF to + LazyArrayStructContext is a subclass of LazyContext that provides a context for + handling structured arrays in a lazy manner. It is initialized with a NetCDF to IDS mapping object, an index, and a size. """ + def __init__(self, nc2ids, index, size): """ Initialize the instance with nc2ids, index, and size. @@ -394,7 +397,7 @@ def get_context(self): """ Returns the current context. - This method returns the current instance of the class, which is expected + This method returns the current instance of the class, which is expected to have a 'size' attribute as required by IDSStructArray. Returns: From c5b9b753b87d8a55e91db0ce4d60a371be124cab Mon Sep 17 00:00:00 2001 From: prasad-sawantdesai Date: Tue, 18 Mar 2025 13:57:35 +0100 Subject: [PATCH 4/8] fixed sphinx doc issue --- imas/backends/imas_core/al_context.py | 4 ---- imas/backends/netcdf/nc2ids.py | 2 +- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/imas/backends/imas_core/al_context.py b/imas/backends/imas_core/al_context.py index 2b6117e..3341121 100644 --- a/imas/backends/imas_core/al_context.py +++ b/imas/backends/imas_core/al_context.py @@ -290,10 +290,6 @@ def get_child(self, child): Returns: The child entry retrieved from the database. - - Raises: - Exception: If the child entry cannot be found or an error occurs - during retrieval. """ imas.backends.imas_core.db_entry_helpers._get_child(child, self) diff --git a/imas/backends/netcdf/nc2ids.py b/imas/backends/netcdf/nc2ids.py index 509b754..f62c438 100644 --- a/imas/backends/netcdf/nc2ids.py +++ b/imas/backends/netcdf/nc2ids.py @@ -323,7 +323,7 @@ def get_child(self, child): Args: child: The child node for which the context or value is to be - set. The child node should have metadata attributes. + set. The child node should have metadata attributes. """ metadata = child.metadata From 3784b718dba76ec340b84d2d3b5486de7993fbaa Mon Sep 17 00:00:00 2001 From: prasad-sawantdesai Date: Tue, 18 Mar 2025 14:06:01 +0100 Subject: [PATCH 5/8] removed deactivate command from workflow --- .github/workflows/verify_sphinx_doc.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/.github/workflows/verify_sphinx_doc.yml b/.github/workflows/verify_sphinx_doc.yml index 706fa1b..6a12690 100644 --- a/.github/workflows/verify_sphinx_doc.yml +++ b/.github/workflows/verify_sphinx_doc.yml @@ -51,6 +51,3 @@ jobs: run: | export SPHINXOPTS='-W -n --keep-going' make -C docs clean html - - - name: Deactivate virtual environment - run: deactivate \ No newline at end of file From d142583d0f2732cf13863a375d4daa57d5cb1011 Mon Sep 17 00:00:00 2001 From: Prasad Date: Tue, 18 Mar 2025 16:59:34 +0100 Subject: [PATCH 6/8] Update imas/backends/netcdf/ids_tensorizer.py Co-authored-by: Maarten Sebregts <110895564+maarten-ic@users.noreply.github.com> --- imas/backends/netcdf/ids_tensorizer.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/imas/backends/netcdf/ids_tensorizer.py b/imas/backends/netcdf/ids_tensorizer.py index 38e934e..7e9e33e 100644 --- a/imas/backends/netcdf/ids_tensorizer.py +++ b/imas/backends/netcdf/ids_tensorizer.py @@ -173,7 +173,7 @@ def tensorize(self, path, fillvalue): Tensorizes the data at the given path with the specified fill value. Args: - path: The path to the data in the NetCDF file. + path: The path to the data in the IDS. fillvalue: The value to fill the tensor with. Can be of any type, including strings. From e318116f111d4c6f7518357f1b3e03bc595d4e7e Mon Sep 17 00:00:00 2001 From: Prasad Date: Tue, 18 Mar 2025 16:59:45 +0100 Subject: [PATCH 7/8] Update imas/backends/netcdf/nc2ids.py Co-authored-by: Maarten Sebregts <110895564+maarten-ic@users.noreply.github.com> --- imas/backends/netcdf/nc2ids.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/imas/backends/netcdf/nc2ids.py b/imas/backends/netcdf/nc2ids.py index f62c438..306c128 100644 --- a/imas/backends/netcdf/nc2ids.py +++ b/imas/backends/netcdf/nc2ids.py @@ -322,8 +322,7 @@ def get_child(self, child): child node based on its metadata. Args: - child: The child node for which the context or value is to be - set. The child node should have metadata attributes. + child: The child IDS node which should be lazy loaded. """ metadata = child.metadata From f39bb2045aa101f6087dd9ac005da0acb5877657 Mon Sep 17 00:00:00 2001 From: prasad-sawantdesai Date: Tue, 18 Mar 2025 17:06:12 +0100 Subject: [PATCH 8/8] imas to imaspy for old version --- docs/source/changelog.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst index d04aea0..ee83128 100644 --- a/docs/source/changelog.rst +++ b/docs/source/changelog.rst @@ -9,7 +9,7 @@ What's new in IMAS-Python 1.2.0 New features and improvements ''''''''''''''''''''''''''''' -- Add :py:func:`imas.DBEntry.get_sample ` (requires imas_core >= 5.4.0) +- Add :py:func:`imaspy.DBEntry.get_sample ` (requires imas_core >= 5.4.0) - Improved validation of netCDF files - Improve compatibility with the UDA backend in imas_core - Extend the support of netCDF to >= 1.4.1 (without complex numbers)