Deprecate parse_epw (pvlib#2467)

* deprecate parse_epw

* tests

* whatsnew

* lint

* PR number in whatsnew

---------

Co-authored-by: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com>

Author: kandersolar

docs/sphinx/source/whatsnew/v0.12.1.rst

@@ -17,8 +17,10 @@ Breaking Changes
 Deprecations
 ~~~~~~~~~~~~
 * The following ``parse_`` functions in :py:mod:`pvlib.iotools` are deprecated,
-  with the corresponding ``read_`` functions taking their place: (:issue:`2444`, :pull:`2458`, :pull:`2466`)
+  with the corresponding ``read_`` functions taking their place: (:issue:`2444`, :pull:`2458`,
+  :pull:`2467`, :pull:`2466`)
 
+  - :py:func:`~pvlib.iotools.parse_epw`
   - :py:func:`~pvlib.iotools.parse_psm3`
   - :py:func:`~pvlib.iotools.parse_cams`
   - :py:func:`~pvlib.iotools.parse_bsrn`

pvlib/iotools/epw.py

@@ -6,6 +6,9 @@
 from urllib.request import urlopen, Request
 import pandas as pd
 
+from pvlib.tools import _file_context_manager
+from pvlib._deprecation import deprecated
+
 
 def read_epw(filename, coerce_year=None):
     r'''
@@ -23,7 +26,8 @@ def read_epw(filename, coerce_year=None):
     Parameters
     ----------
     filename : String
-        Can be a relative file path, absolute file path, or url.
+        Can be a relative file path, absolute file path, url, or in-memory
+        file buffer.
 
     coerce_year : int, optional
         If supplied, the year of the data will be set to this value. This can
@@ -43,10 +47,6 @@ def read_epw(filename, coerce_year=None):
     metadata : dict
         The site metadata available in the file.
 
-    See Also
-    --------
-    pvlib.iotools.parse_epw
-
     Notes
     -----
 
@@ -226,18 +226,17 @@ def read_epw(filename, coerce_year=None):
             'Safari/537.36')})
         response = urlopen(request)
         with io.StringIO(response.read().decode(errors='ignore')) as csvdata:
-            data, meta = parse_epw(csvdata, coerce_year)
+            data, meta = _parse_epw(csvdata, coerce_year)
 
     else:
-        # Assume it's accessible via the file system
-        with open(str(filename), 'r') as csvdata:
-            data, meta = parse_epw(csvdata, coerce_year)
-
+        # Assume it's a buffer or accessible via the file system
+        with _file_context_manager(filename, 'r') as csvdata:
+            data, meta = _parse_epw(csvdata, coerce_year)
 
     return data, meta
 
 
-def parse_epw(csvdata, coerce_year=None):
+def _parse_epw(csvdata, coerce_year=None):
     """
     Given a file-like buffer with data in Energy Plus Weather (EPW) format,
     parse the data into a dataframe.
@@ -310,3 +309,7 @@ def parse_epw(csvdata, coerce_year=None):
     data.index = idx
 
     return data, meta
+
+
+parse_epw = deprecated(since="0.13.0", name="parse_epw",
+                       alternative="read_epw")(read_epw)

pvlib/iotools/pvgis.py

@@ -21,7 +21,7 @@
 import numpy as np
 import pandas as pd
 import pytz
-from pvlib.iotools import read_epw, parse_epw
+from pvlib.iotools import read_epw
 
 URL = 'https://re.jrc.ec.europa.eu/api/'
 
@@ -536,7 +536,7 @@ def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
             data, months_selected, inputs, meta = _parse_pvgis_tmy_csv(src)
     elif outputformat == 'epw':
         with io.StringIO(res.content.decode('utf-8')) as src:
-            data, meta = parse_epw(src)
+            data, meta = read_epw(src)
             months_selected, inputs = None, None
     elif outputformat == 'basic':
         err_msg = ("outputformat='basic' is no longer supported by pvlib, "
@@ -661,10 +661,7 @@ def read_pvgis_tmy(filename, pvgis_format=None, map_variables=True):
 
     # EPW: use the EPW parser from the pvlib.iotools epw.py module
     if outputformat == 'epw':
-        try:
-            data, meta = parse_epw(filename)
-        except AttributeError:  # str/path has no .read() attribute
-            data, meta = read_epw(filename)
+        data, meta = read_epw(filename)
         months_selected, inputs = None, None
 
     # NOTE: json and csv output formats have parsers defined as private

tests/iotools/test_epw.py

@@ -3,11 +3,33 @@
 from pvlib.iotools import epw
 from tests.conftest import TESTS_DATA_DIR, RERUNS, RERUNS_DELAY
 
+from pvlib._deprecation import pvlibDeprecationWarning
+
 epw_testfile = TESTS_DATA_DIR / 'NLD_Amsterdam062400_IWEC.epw'
 
 
 def test_read_epw():
-    epw.read_epw(epw_testfile)
+    df, meta = epw.read_epw(epw_testfile)
+    assert len(df) == 8760
+    assert 'ghi' in df.columns
+    assert meta['latitude'] == 52.3
+
+
+def test_read_epw_buffer():
+    with open(epw_testfile, 'r') as f:
+        df, meta = epw.read_epw(f)
+    assert len(df) == 8760
+    assert 'ghi' in df.columns
+    assert meta['latitude'] == 52.3
+
+
+def test_parse_epw_deprecated():
+    with pytest.warns(pvlibDeprecationWarning, match='Use read_epw instead'):
+        with open(epw_testfile, 'r') as f:
+            df, meta = epw.parse_epw(f)
+    assert len(df) == 8760
+    assert 'ghi' in df.columns
+    assert meta['latitude'] == 52.3
 
 
 @pytest.mark.remote_data