Add function to retrieve example datasets

[kandersolar]

It would be nice to have a clean way for gallery examples to get access to the test data files. See #860 (comment)

For a function like load_dataset('greensboro-tmy'):

Pros:

• No need to monkey around with filepaths, especially ones that aren't really meant to be public
• Associating files with keys means we can move and rename test data files without it being a breaking change
• Simplifies example code

Cons:

• The data files are in several formats (csv, json, nc, h5 etc), so this function would either have to know the appropriate reading method for each file (complicated) or just return a file handle and let the user parse the contents (less useful).

[cwhanse]

+1 to having the function. I think a useful scope is to return the full path to the file. Reading file content and providing output in various formats seems like a large bite to chew.

[kandersolar]

Any ideas for what the function should be named if it returns the file path? I'm having trouble coming up with a verb that doesn't seem misleading. Maybe just dataset()?

df = pd.read_csv(dataset('greensboro-tmy'))

with open(dataset('greensboro-tmy')) as f:

[mikofski]

Con: The data files are in several formats (csv, json, nc, h5 etc)

To me this a "Pro" for having a dedicated data reader, to make it easier for users, if it's a PITA for us, it will be a blocker for them I think

[wholmgren]

I would be happy if this

pvlib-python/docs/examples/plot_greensboro_kimber_soiling.py

Lines 39 to 43 in c9929e8

	# get full path to the data directory
	DATA_DIR = pathlib.Path(pvlib.__file__).parent / 'data'
	# get TMY3 data with rain
	greensboro, _ = read_tmy3(DATA_DIR / '723170TYA.CSV', coerce_year=1990)

looked like

# get full path to the data file
file_path = dataset('greensboro-tmy')

# parse TMY3 data
greensboro, _ = read_tmy3(file_path, coerce_year=1990)

I don't think the broader scope is feasible. To be clear, this is just something for the tests/examples - not for anything else.

metpy has a get_test_data function with the same idea, but a different implementation because it uses a caching back end that I think we should avoid.

example: https://unidata.github.io/MetPy/latest/examples/XArray_Projections.html#sphx-glr-examples-xarray-projections-py

[kandersolar]

I just stumbled across some functions in pkg_resources that might be relevant to this issue: https://setuptools.readthedocs.io/en/latest/pkg_resources.html#resource-extraction

[echedey-ls]

I just stumbled upon this issue looking for ideas for GSoC.
@kanderso-nrel , just a quick note on that might-be-relevant package:
From my experience both with PVLIB and SciencePlots, sticking to __path__[0] (which is already in use in PVLIB) is more than enough, and I believe (or want to) it is exempt from errors. At least, in SciencePlots we haven't recorded any issues regarding that after the breaking changes in the v2.0.0 release.
About pkg_resources, it's use is deprecated in favor of other packages. See this attention directive at pkg_resources.