Add argument logic for the arguments into cutout init and prepare (#445)

* Refactor cutout.py and data.py. Improve documentation and argument handling.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* doc: Add release notes.

* code: Fix UnboundLocalError when no bounds are provided

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: euronion <[email protected]>
Co-authored-by: Johannes HAMPP <[email protected]>

Author: 3 people

RELEASE_NOTES.rst

@@ -18,6 +18,8 @@ Release Notes
 ..   ``pip install git+https://github.com/pypsa/atlite``.
 
 * Feature: Add new onshore turbine models: eno 126 3.5 MW, eno 126 4 MW, and eno 126 4.8 MW . (turbines that match more closely the PyPSA/technologydata cost assumptions)
+* Fix `atlite.Cutout()` to be able to handle the `bounds` argument to be a `DataFrame` in accordance to the docstring (https://github.com/PyPSA/atlite/pull/445).
+* Raise a `FileNotFoundError` if the `temp_dir` explicitly specified for cutout preparation does not exist instead of failing with an obfuscated error message (https://github.com/PyPSA/atlite/pull/445).
 
 `v0.4.1 <https://github.com/PyPSA/atlite/releases/tag/v0.4.1>`__ (12th May 2025)
 =======================================================================================

atlite/cutout.py

@@ -98,9 +98,10 @@ def __init__(self, path, **cutoutparams):
             Time range to include in the cutout, e.g. "2011" or
             ("2011-01-05", "2011-01-25")
             This is necessary when building a new cutout.
-        bounds : GeoSeries.bounds | DataFrame, optional
-            The outer bounds of the cutout or as a DataFrame
-            containing (min.long, min.lat, max.long, max.lat).
+        bounds : DataFrame | Tuple, optional
+            The outer bounds of the cutout containing (min.long, min.lat, max.long, max.lat)
+            or a single-row DataFrame with [["minx", "miny", "maxx", "maxy"]] column values.
+            From GeoPandas DataFrames and Series, this is easily accessible through `.geometry.bounds`.
         x : slice, optional
             Outer longitudinal bounds for the cutout (west, east).
         y : slice, optional
@@ -163,7 +164,18 @@ def __init__(self, path, **cutoutparams):
             logger.info(f"Building new cutout {path}")
 
             if "bounds" in cutoutparams:
-                x1, y1, x2, y2 = cutoutparams.pop("bounds")
+                bounds = cutoutparams.pop("bounds")
+                # If its a dataframe, we will extract the values
+                if isinstance(bounds, pd.DataFrame) and bounds.shape[0] == 1:
+                    x1, y1, x2, y2 = bounds.iloc[0][
+                        ["minx", "miny", "maxx", "maxy"]
+                    ].to_list()
+                elif isinstance(bounds, tuple):  # If its a tuple
+                    x1, y1, x2, y2 = bounds
+                else:
+                    raise ValueError(
+                        "`bounds` must be a tuple or a DataFrame with a single row entry."
+                    )
                 cutoutparams.update(x=slice(x1, x2), y=slice(y1, y2))
 
             try:

atlite/data.py

@@ -8,6 +8,7 @@
 import logging
 import os
 from functools import wraps
+from pathlib import Path
 from shutil import rmtree
 from tempfile import mkdtemp, mkstemp
 
@@ -161,7 +162,7 @@ def cutout_prepare(
     tmpdir : str/Path, optional
         Directory in which temporary files (for example retrieved ERA5 netcdf
         files) are stored. If set, the directory will not be deleted and the
-        intermediate files can be examined.
+        intermediate files can be examined. The path must be a valid path.
     data_format : str, optional
         The data format used to retrieve the data. Only relevant for ERA5 data. The default is 'grib'.
     overwrite : bool, optional
@@ -191,6 +192,12 @@ def cutout_prepare(
     cutout : atlite.Cutout
         Cutout with prepared data. The variables are stored in `cutout.data`.
 
+
+    Raises
+    ------
+    NotADirectoryError
+        The argument `tmpdir` is not a valid path.
+
     """
     if dask_kwargs is None:
         dask_kwargs = {}
@@ -199,6 +206,10 @@ def cutout_prepare(
         logger.info("Cutout already prepared.")
         return cutout
 
+    # ensure that the tmpdir actually exists
+    temp_dir_path = Path(tmpdir)
+    if not temp_dir_path.is_dir():
+        raise FileNotFoundError(f"The tmpdir: {temp_dir_path} does not exist.")
     logger.info(f"Storing temporary files in {tmpdir}")
 
     modules = atleast_1d(cutout.module)