Add function to retrieve example dataset paths

docs/examples/soiling/plot_greensboro_kimber_soiling.py

@@ -30,17 +30,16 @@
 # step.
 
 from datetime import datetime
-import pathlib
 from matplotlib import pyplot as plt
 from pvlib.iotools import read_tmy3
 from pvlib.soiling import kimber
-import pvlib
+from pvlib.tools import dataset
 
 # get full path to the data directory
-DATA_DIR = pathlib.Path(pvlib.__file__).parent / 'data'
+DATASET_DIR = dataset('723170TYA.CSV')
 
 # get TMY3 data with rain
-greensboro, _ = read_tmy3(DATA_DIR / '723170TYA.CSV', coerce_year=1990,
+greensboro, _ = read_tmy3(DATASET_DIR, coerce_year=1990,
                           map_variables=True)
 # get the rain data
 greensboro_rain = greensboro['Lprecip depth (mm)']

pvlib/tests/test_tools.py

@@ -2,6 +2,7 @@
 
 from pvlib import tools
 import numpy as np
+import pathlib
 
 
 @pytest.mark.parametrize('keys, input_dict, expected', [
@@ -95,3 +96,17 @@ def test_degrees_to_index_1():
     'latitude' or 'longitude' is passed."""
     with pytest.raises(IndexError):  # invalid value for coordinate argument
         tools._degrees_to_index(degrees=22.0, coordinate='width')
+
+
+def test_dataset_passes():
+    expected_dataset = '723170TYA.CSV'
+    assert tools.dataset(expected_dataset).endswith(expected_dataset)
+    assert tools.dataset(pathlib.Path(expected_dataset)) \
+        .endswith(expected_dataset)
+
+
+def test_dataset_fails_on_not_found():
+    error_prompt = "Dataset has not been found in pvlib. " \
+                   "Please check dataset name."
+    with pytest.raises(IOError, match=error_prompt):
+        tools.dataset("_Texto_cualquiera.-formato-")

pvlib/tools.py

@@ -2,11 +2,14 @@
 Collection of functions used in pvlib_python
 """
 
+import pvlib
+
 import datetime as dt
 import numpy as np
 import pandas as pd
 import pytz
 import warnings
+import os.path
 
 
 def cosd(angle):
@@ -469,3 +472,15 @@ def _first_order_centered_difference(f, x0, dx=DX, args=()):
     # removal in scipy 1.12.0
     df = f(x0+dx, *args) - f(x0-dx, *args)
     return df / 2 / dx
+
+
+def dataset(dataset):
+    """
+    Return a filepath to a dataset bundled with PVLIB with name `dataset`.
+    This utility is intended to be used in tests and examples.
+    """
+    dataset = os.path.join(pvlib.__path__[0], 'data', dataset)
+    if not os.path.exists(dataset):
+        raise IOError("Dataset has not been found in pvlib. "
+                      "Please check dataset name.")
+    return dataset