Inconsistencies in iotools

There exists a number of inconsistencies between the functions in pvlib.iotools that I would like to address.

First, the naming of start/stop date differs between functions for unknown reasons. E.g., get_ecmw_macc uses startdate/stopdate, read_midc_raw_data_from_nrel uses start/end and #1175 currently uses start_date/end_date. It would be great with a common consensus of which of the three to use. I’d be willing to change the functions to comply with the decision (of course with deprecation warnings to start with)

Another inconsistency is that meta data is called different things by different functions. Here’s a list:

• Meta: pvigs, epw (code), tmy (in code)
• Metadata: epw (in documentation), surfrad, tmy (in documentation) and then there’s psm3 which calls it “headers”.

Again if we can agree on a consensus I’d like to offer to implement the changes.

Lastly, the naming of the two data retrieval functions: read_midc_raw_data_from_nrel and read_srml_month_from_solardat, which ideally should be called get_midc and get_srml to match their read_ counterparts.

[kanderso-nrel]

For PVGIS map_variables can we do a typical deprecation cycle using a strategy like this?

def get_pvgis_tmy(..., map_variables=None):
    if map_variables is None:
        warnings.warn(
            'PVGIS variable names will be renamed to pvlib conventions by '
            'default starting in pvlib 0.10.0. Specify map_variables=True to '
            'enable that behavior now, or specify map_variables=False to '
            'hide this warning.', pvlib._deprecation.pvlibDeprecationWarning
        )
        map_variables = False
    ...

And then in pvlib 0.10.0 we change map_variables to default to True instead of None and remove the warning. Thoughts?

[wholmgren]

I like start, end, and metadata.

While our long and detailed review of #1175 suggests otherwise (sorry), I really have wanted to keep iotools relatively easy to contribute to. Part of that means accepting some inconsistencies, but there’s also no reason we can’t come through and clean up the API from time to time.

We don’t maintain standards for names within actual code other than readability - it’s only the API names that matter. And no need to deprecate positional argument names - just function names and keyword arguments.