climarraykit 0.2.0__tar.gz

climarraykit-0.2.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# climarraykit Changelog
+
+All notable changes to this project will be documented in this file.
+
+---
+
+## [0.2.0] - 2026-03-31
+
+### Changed (0.2.0)
+
+#### **Package Dependencies** (changing; 0.2.0)
+
+- **NumPy / Pandas:** require **`numpy>=2.2.3`** and **`pandas>=2.2.3`** in **`pyproject.toml`**, **`requirements.txt`**, and **`recipe/meta.yaml`**.
+
+---
+
+## [0.1.0] - 2026-03-30
+
+### Added (0.1.0)
+
+- Bootstrap dedicated package metadata:
+  - `pyproject.toml`
+  - `LICENSE`
+  - `MANIFEST.in`
+  - `requirements.txt`
+  - `requirements-dev.txt`
+  - `README.md`
+  - package `climarraykit/`
+
+- Introduce initial xarray-focused module surface:
+  - `climarraykit.file_utils`
+  - `climarraykit.patterns`
+  - `climarraykit.conversions`
+  - `climarraykit.data_manipulation`
+  - `climarraykit.xarray_obj_handler`
+
+- Provide a non-breaking migration path by preserving the legacy logic and API shape while
+  enabling import migration towards `climarraykit`.
+
+- Add `rename_xarray_dimension` to `climarraykit.patterns` for robust xarray dimension
+  renaming (shared by downstream packages such as `statflow` climatology helpers).

climarraykit-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 climarraykit
+
+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.

climarraykit-0.2.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include requirements.txt
+include requirements-dev.txt
+recursive-include climarraykit *.py

climarraykit-0.2.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: climarraykit
+Version: 0.2.0
+Summary: Climate-focused xarray toolkit for NetCDF/GRIB handling, coordinate discovery, and dataset serialisation
+Author-email: Jon Ander Gabantxo <jagabantxo@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 climarraykit
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/EusDancerDev/climarraykit
+Project-URL: Documentation, https://github.com/EusDancerDev/climarraykit#readme
+Project-URL: Repository, https://github.com/EusDancerDev/climarraykit.git
+Project-URL: Bug Reports, https://github.com/EusDancerDev/climarraykit/issues
+Keywords: xarray,climate,netcdf,grib,meteorology,climatology
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.2.3
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: xarray>=2024.2.0
+Requires-Dist: filewise>=3.13.0
+Requires-Dist: pygenutils>=16.4.0
+Requires-Dist: paramlib>=3.4.10
+Provides-Extra: grib
+Requires-Dist: cfgrib>=0.9.10; extra == "grib"
+Provides-Extra: regrid
+Requires-Dist: xesmf>=0.8.0; extra == "regrid"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Dynamic: license-file
+
+# climarraykit
+
+`climarraykit` is a dedicated xarray-centric toolkit for climate and weather data workflows.
+
+It is introduced to decouple heavy xarray/netCDF functionality from broader utility packages
+where those dependencies are not always needed.
+
+## Scope
+
+- netCDF file scanning and integrity checks
+- coordinate and dimension discovery utilities
+- GRIB-to-netCDF conversion helpers
+- xarray Dataset/DataArray creation and serialisation helpers
+- climate-oriented xarray data manipulation helpers
+
+## Transitional compatibility
+
+This initial release preserves behaviour by exposing the same module-level APIs as the
+legacy `filewise.xarray_utils` package while enabling downstream projects to migrate imports
+to `climarraykit`.
+
+---
+
+Current version: **0.2.0** (see [CHANGELOG.md](CHANGELOG.md)).

climarraykit-0.2.0/README.md

@@ -0,0 +1,24 @@
+# climarraykit
+
+`climarraykit` is a dedicated xarray-centric toolkit for climate and weather data workflows.
+
+It is introduced to decouple heavy xarray/netCDF functionality from broader utility packages
+where those dependencies are not always needed.
+
+## Scope
+
+- netCDF file scanning and integrity checks
+- coordinate and dimension discovery utilities
+- GRIB-to-netCDF conversion helpers
+- xarray Dataset/DataArray creation and serialisation helpers
+- climate-oriented xarray data manipulation helpers
+
+## Transitional compatibility
+
+This initial release preserves behaviour by exposing the same module-level APIs as the
+legacy `filewise.xarray_utils` package while enabling downstream projects to migrate imports
+to `climarraykit`.
+
+---
+
+Current version: **0.2.0** (see [CHANGELOG.md](CHANGELOG.md)).

climarraykit-0.2.0/climarraykit/__init__.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "conversions",
+    "data_manipulation",
+    "file_utils",
+    "patterns",
+    "xarray_obj_handler",
+]

climarraykit-0.2.0/climarraykit/conversions.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+#----------------#
+# Import modules #
+#----------------#
+
+import xarray as xr
+from pathlib import Path
+
+#------------------------#
+# Import project modules #
+#------------------------#
+
+from climarraykit.xarray_obj_handler import _save_ds_as_nc
+from paramlib.global_parameters import CLIMATE_FILE_EXTENSIONS
+from pygenutils.arrays_and_lists.conversions import flatten_to_string
+from pygenutils.arrays_and_lists.data_manipulation import flatten_list
+from pygenutils.operative_systems.os_operations import exit_info, run_system_command
+from pygenutils.strings.string_handler import (
+    find_substring_index,
+    get_obj_specs,
+    modify_obj_specs
+)
+
+#------------------#
+# Define functions #
+#------------------#
+
+# Xarray objects #
+#----------------#
+
+def grib2nc(
+        grib_file_list: str | list[str], 
+        on_shell: bool = False, 
+        option_str: str | None = None,
+        capture_output: bool = False,
+        return_output_name: bool = False,
+        encoding: str = "utf-8",
+        shell: bool = True) -> None:
+    """
+    Converts a GRIB file or list of GRIB files to netCDF format. The conversion
+    can be executed either via shell commands or programmatically using xarray.
+    
+    Parameters
+    ----------
+    grib_file_list : str | list[str]
+        The file path(s) of the GRIB file(s) to be converted.
+    on_shell : bool, optional
+        If True, the conversion will be handled through shell commands using 
+        the 'grib_to_netcdf' tool. If False, the conversion will be done 
+        programmatically using xarray.
+    option_str : str, optional
+        Additional options to pass to the shell command for 'grib_to_netcdf'. 
+        This parameter is only used if 'on_shell' is set to True.
+    capture_output : bool, optional
+        Whether to capture the command output. Default is False.
+    return_output_name : bool, optional
+        Whether to return file descriptor names. Default is False.
+    encoding : str, optional
+        Encoding to use when decoding command output. Default is "utf-8".
+    shell : bool, optional
+        Whether to execute the command through the shell. Default is True.
+        
+    Returns
+    -------
+    None
+        Converts the GRIB file(s) to netCDF format and saves the output 
+        netCDF file(s) in the same directory as the GRIB files.
+
+    Raises
+    ------
+    TypeError
+        If grib_file_list is not str or list of str.
+    ValueError
+        If any GRIB file path is invalid or empty.
+    FileNotFoundError
+        If any GRIB file doesn't exist.
+
+    Notes
+    -----
+    - When 'on_shell' is True, the function builds and runs a shell command 
+      that calls the 'grib_to_netcdf' tool, with optional flags.
+    - When 'on_shell' is False, xarray is used to directly open the GRIB file 
+      and convert it to netCDF format.
+    - The function will prompt for input in the case of multiple GRIB files if 
+      'on_shell' is True.
+    """
+    
+    # Parameter validation
+    if not isinstance(grib_file_list, (str, list)):
+        raise TypeError("grib_file_list must be a string or list of strings")
+    
+    # Flatten nested lists for defensive programming
+    if isinstance(grib_file_list, list):
+        grib_file_list = flatten_list(grib_file_list)
+        
+        # Validate all items are strings
+        if not all(isinstance(item, str) for item in grib_file_list):
+            raise TypeError("All items in grib_file_list must be strings")
+        
+        # Check for empty strings
+        if not all(item.strip() for item in grib_file_list):
+            raise ValueError("All GRIB file paths must be non-empty strings")
+    else:
+        # Single string validation
+        if not isinstance(grib_file_list, str) or not grib_file_list.strip():
+            raise ValueError("GRIB file path must be a non-empty string")
+    
+    # Check file existence
+    files_to_check = [grib_file_list] if isinstance(grib_file_list, str) else grib_file_list
+    for grib_file in files_to_check:
+        if not Path(grib_file).exists():
+            raise FileNotFoundError(f"GRIB file not found: {grib_file}")
+        
+        # Check if file has expected GRIB extension
+        if not any(grib_file.lower().endswith(ext.lower()) for ext in ['.grib', '.grb', '.grib2', '.grb2']):
+            print(f"Warning: File {grib_file} may not be a GRIB file based on extension")
+
+    # Shell-based conversion #
+    #-#-#-#-#-#-#-#-#-#-#-#-#
+    
+    if on_shell:
+        # Handle single GRIB file
+        if isinstance(grib_file_list, str):
+            nc_file_new = modify_obj_specs(grib_file_list, "ext", EXTENSIONS[0])
+        
+        # Handle list of GRIB files
+        else:
+            grib_allfile_info_str = flatten_to_string(grib_file_list)
+            
+            # Prompt user for the netCDF file name without extension
+            nc_file_new_noext = input("Please introduce a name "
+                                      "for the netCDF file, "
+                                      "WITHOUT THE EXTENSION: ")
+            
+            # Validate the file name using RegEx
+            allowed_minimum_char_idx = find_substring_index(nc_file_new_noext,
+                                                            REGEX_GRIB2NC,
+                                                            advanced_search=True)
+            
+            while allowed_minimum_char_idx == -1:
+                print("Invalid file name.\nIt can contain alphanumeric characters, "
+                      "as well as the following non-word characters: {. _ -}")
+                nc_file_new_noext = input("Please introduce a valid name: ")
+                allowed_minimum_char_idx = find_substring_index(nc_file_new_noext,
+                                                                REGEX_GRIB2NC,
+                                                                advanced_search=True)
+            
+            # Modify the file name to have the .nc extension
+            nc_file_new = modify_obj_specs(nc_file_new_noext,
+                                                 obj2modify="ext",
+                                                 new_obj=EXTENSIONS[0])
+        
+        # Construct the shell command for conversion
+        grib2nc_template = "grib_to_netcdf "
+        if option_str:
+            grib2nc_template += f"{option_str} "
+        grib2nc_template += f"-o {nc_file_new} {grib_allfile_info_str}"
+        
+        # Execute the shell command
+        try:
+            process_exit_info = run_system_command(
+                grib2nc_template,
+                capture_output=capture_output,
+                return_output_name=return_output_name,
+                encoding=encoding,
+                shell=shell
+            )
+            # Call exit_info with parameters based on capture_output
+            exit_info(
+                process_exit_info,
+                check_stdout=True,
+                check_stderr=True,
+                check_return_code=True
+            )
+        except Exception as e:
+            raise RuntimeError(f"Shell command execution failed: {e}")
+
+    # Programmatic conversion #
+    #-#-#-#-#-#-#-#-#-#-#-#-#-#
+    
+    else:
+        # Ensure grib_file_list is a list
+        if isinstance(grib_file_list, str):
+            grib_file_list = [grib_file_list]
+
+        # Convert each GRIB file in the list to netCDF
+        for grib_file in grib_file_list:
+            try:
+                grib_file_noext = get_obj_specs(grib_file, "name_noext", EXTENSIONS[0])
+                ds = xr.open_dataset(grib_file, engine="cfgrib")
+                _save_ds_as_nc(ds, grib_file_noext)
+                print(f"Successfully converted {grib_file} to netCDF format")
+            except Exception as e:
+                print(f"Error converting {grib_file}: {e}")
+                raise
+
+            
+#--------------------------#
+# Parameters and constants #
+#--------------------------#
+
+# Valid file extensions #
+EXTENSIONS = CLIMATE_FILE_EXTENSIONS[::3]
+  
+# RegEx control for GRIB-to-netCDF single file name #
+REGEX_GRIB2NC = r"^[a-zA-Z\d\._-]$"