deprecate parse_cams

Author: kandersolar

pvlib/iotools/sodapro.py

@@ -7,7 +7,9 @@
 import requests
 import io
 import warnings
+from pvlib import tools
 
+from pvlib._deprecation import deprecated
 
 URL = 'api.soda-solardata.com'
 
@@ -145,7 +147,7 @@ def get_cams(latitude, longitude, start, end, email, identifier='mcclear',
 
     See Also
     --------
-    pvlib.iotools.read_cams, pvlib.iotools.parse_cams
+    pvlib.iotools.read_cams
 
     Raises
     ------
@@ -231,20 +233,22 @@ def get_cams(latitude, longitude, start, end, email, identifier='mcclear',
     # Successful requests returns a csv data file
     else:
         fbuf = io.StringIO(res.content.decode('utf-8'))
-        data, metadata = parse_cams(fbuf, integrated=integrated, label=label,
-                                    map_variables=map_variables)
+        data, metadata = read_cams(fbuf, integrated=integrated, label=label,
+                                   map_variables=map_variables)
         return data, metadata
 
 
-def parse_cams(fbuf, integrated=False, label=None, map_variables=True):
+def read_cams(filename, integrated=False, label=None, map_variables=True):
     """
-    Parse a file-like buffer with data in the format of a CAMS Radiation or
-    McClear file. The CAMS solar radiation services are described in [1]_.
+    Read a file or file-like buffer with data in the format of a CAMS
+    Radiation or McClear file.
+    
+    The CAMS solar radiation services are described in [1]_.
 
     Parameters
     ----------
-    fbuf: file-like object
-        File-like object containing data to read.
+    filename: str, path-like, or buffer
+        Filename or in-memory buffer of a file containing data to read.
     integrated: boolean, default False
         Whether to return radiation parameters as integrated values (Wh/m^2)
         or as average irradiance values (W/m^2) (pvlib preferred units)
@@ -264,23 +268,31 @@ def parse_cams(fbuf, integrated=False, label=None, map_variables=True):
 
     See Also
     --------
-    pvlib.iotools.read_cams, pvlib.iotools.get_cams
+    pvlib.iotools.get_cams
 
     References
     ----------
     .. [1] `CAMS solar radiation documentation
        <https://atmosphere.copernicus.eu/solar-radiation>`_
     """
     metadata = {}
-    # Initial lines starting with # contain metadata
-    while True:
-        line = fbuf.readline().rstrip('\n')
-        if line.startswith('# Observation period'):
-            # The last line of the metadata section contains the column names
-            names = line.lstrip('# ').split(';')
-            break  # End of metadata section has been reached
-        elif ': ' in line:
-            metadata[line.split(': ')[0].lstrip('# ')] = line.split(': ')[1]
+
+    with tools._file_context_manager(filename) as fbuf:
+
+        # Initial lines starting with # contain metadata
+        while True:
+            line = fbuf.readline().rstrip('\n')
+            if line.startswith('# Observation period'):
+                # The last line of the metadata section contains the column names
+                names = line.lstrip('# ').split(';')
+                break  # End of metadata section has been reached
+            elif ': ' in line:
+                key = line.split(': ')[0].lstrip('# ')
+                value = line.split(': ')[1]
+                metadata[key] = value
+
+        data = pd.read_csv(fbuf, sep=';', comment='#', header=None,
+                           names=names)
 
     # Convert latitude, longitude, and altitude values from strings to floats
     for k_old in list(metadata.keys()):
@@ -296,8 +308,6 @@ def parse_cams(fbuf, integrated=False, label=None, map_variables=True):
         metadata['Summarization (integration) period']]
     metadata['time_step'] = time_step
 
-    data = pd.read_csv(fbuf, sep=';', comment='#', header=None, names=names)
-
     obs_period = data['Observation period'].str.split('/')
 
     # Set index as the start observation time (left) and localize to UTC
@@ -336,43 +346,5 @@ def parse_cams(fbuf, integrated=False, label=None, map_variables=True):
     return data, metadata
 
 
-def read_cams(filename, integrated=False, label=None, map_variables=True):
-    """
-    Read a CAMS Radiation or McClear file into a pandas DataFrame.
-
-    CAMS Radiation and McClear are described in [1]_.
-
-    Parameters
-    ----------
-    filename: str
-        Filename of a file containing data to read.
-    integrated: boolean, default False
-        Whether to return radiation parameters as integrated values (Wh/m^2)
-        or as average irradiance values (W/m^2) (pvlib preferred units)
-    label : {'right', 'left}, optional
-        Which bin edge label to label time-step with. The default is 'left' for
-        all time steps except for '1M' which has a default of 'right'.
-    map_variables: bool, default: True
-        When true, renames columns of the Dataframe to pvlib variable names
-        where applicable. See variable :const:`VARIABLE_MAP`.
-
-    Returns
-    -------
-    data: pandas.DataFrame
-        Timeseries data from CAMS Radiation or McClear.
-        See :func:`pvlib.iotools.get_cams` for fields.
-    metadata: dict
-        Metadata available in the file.
-
-    See Also
-    --------
-    pvlib.iotools.parse_cams, pvlib.iotools.get_cams
-
-    References
-    ----------
-    .. [1] `CAMS solar radiation documentation
-       <https://atmosphere.copernicus.eu/solar-radiation>`_
-    """
-    with open(str(filename), 'r') as fbuf:
-        content = parse_cams(fbuf, integrated, label, map_variables)
-    return content
+parse_cams = deprecated(since="0.12.1", name="parse_cams",
+                        alternative="read_cams")(read_cams)

tests/iotools/test_sodapro.py

@@ -11,6 +11,8 @@
 from tests.conftest import TESTS_DATA_DIR, assert_frame_equal
 
 
+from pvlib._deprecation import pvlibDeprecationWarning
+
 testfile_mcclear_verbose = TESTS_DATA_DIR / 'cams_mcclear_1min_verbose.csv'
 testfile_mcclear_monthly = TESTS_DATA_DIR / 'cams_mcclear_monthly.csv'
 testfile_radiation_verbose = TESTS_DATA_DIR / 'cams_radiation_1min_verbose.csv'
@@ -144,7 +146,6 @@
      0.9897]])
 
 
-# @pytest.fixture
 def generate_expected_dataframe(values, columns, index, dtypes):
     """Create dataframe from arrays of values, columns and index, in order to
     use this dataframe to compare to.
@@ -185,6 +186,12 @@ def test_read_cams_integrated_unmapped_label():
     assert_frame_equal(out, expected, check_less_precise=True)
 
 
+def test_parse_cams_deprecated():
+    with pytest.warns(pvlibDeprecationWarning, match='Use read_cams instead'):
+        with open(testfile_radiation_verbose, mode="r") as fbuf:
+            _ = sodapro.parse_cams(fbuf)
+
+
 def test_read_cams_metadata():
     _, metadata = sodapro.read_cams(testfile_mcclear_monthly, integrated=False)
     assert metadata['Time reference'] == 'Universal time (UT)'
@@ -203,7 +210,7 @@ def test_read_cams_metadata():
      values_radiation_monthly, dtypes_radiation, 'cams_radiation')])
 def test_get_cams(requests_mock, testfile, index, columns, values, dtypes,
                   identifier):
-    """Test that get_cams generates the correct URI request and that parse_cams
+    """Test that get_cams generates the correct URI request and that read_cams
     is being called correctly"""
     # Open local test file containing McClear mothly data
     with open(testfile, 'r') as test_file: