make iotools package (#272)

* make iotools package and move tmy readers into it

* fix api, add deprecations

* whitespace at end of file

* update whatsnew

* define api in init instead of api.py

* fix a few style errors

* more style fixes

Author: wholmgren

docs/sphinx/source/api.rst

@@ -294,9 +294,37 @@ Functions
    tracking.singleaxis
 
 
+.. _iotools:
+
+IO Tools
+========
+
+Functions for reading and writing data from a variety of file formats
+relevant to solar energy modeling.
+
+.. autosummary::
+   :toctree: generated/
+
+   iotools.read_tmy2
+   iotools.read_tmy3
+
+A :py:class:`~pvlib.location.Location` object may be created from metadata
+in some files.
+
+.. autosummary::
+   :toctree: generated/
+
+   location.Location.from_tmy
+
+
 TMY
 ===
 
+.. warning::
+
+    The :py:mod:`pvlib.tmy` module is deprecated; it will be removed
+    in pvlib 0.7. Please see the :ref:`pvlib.iotools <iotools>` package.
+
 Methods and functions for reading data from TMY files.
 
 .. autosummary::

docs/sphinx/source/clearsky.rst

@@ -40,10 +40,12 @@ We'll need these imports for the examples below.
 
     In [1]: import pvlib
 
-    In [1]: from pvlib import clearsky, atmosphere, tmy, solarposition
+    In [1]: from pvlib import clearsky, atmosphere, solarposition
 
     In [1]: from pvlib.location import Location
 
+    In [1]: from pvlib.iotools import read_tmy3
+
 
 .. _location:
 
@@ -214,7 +216,7 @@ wavelengths [Bir80]_, and is implemented in
 
     In [1]: tmy_file = os.path.join(pvlib_data, '703165TY.csv')  # TMY file
 
-    In [1]: tmy_data, tmy_header = tmy.readtmy3(tmy_file, coerce_year=1999)  # read TMY data
+    In [1]: tmy_data, tmy_header = read_tmy3(tmy_file, coerce_year=1999)  # read TMY data
 
     In [1]: tl_historic = clearsky.lookup_linke_turbidity(time=tmy_data.index,
        ...:     latitude=tmy_header['latitude'], longitude=tmy_header['longitude'])

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

@@ -12,6 +12,10 @@ date will require Python 3. (:issue:`501`)
 
 API Changes
 ~~~~~~~~~~~
+* Created the ``pvlib.iotools`` subpackage. (:issue:`29`, :issue:`261`)
+* Deprecated ``tmy``, ``tmy.readtmy2`` and ``tmy.readtmy3``;
+  they will be removed in v0.7. Use the new :py:func:`pvlib.iotools.read_tmy2`
+  and :py:func:`pvlib.iotools.read_tmy3` instead. (:issue:`261`)
 
 
 Enhancements

pvlib/__init__.py

@@ -6,9 +6,12 @@
 from pvlib import irradiance
 from pvlib import location
 from pvlib import solarposition
-from pvlib import tmy
+from pvlib import iotools
 from pvlib import tracking
 from pvlib import pvsystem
 from pvlib import spa
 from pvlib import modelchain
 from pvlib import singlediode
+
+# for backwards compatibility for pvlib.tmy module
+from pvlib import tmy

pvlib/iotools/__init__.py

@@ -0,0 +1,2 @@
+from pvlib.iotools.tmy import read_tmy2  # noqa: F401
+from pvlib.iotools.tmy import read_tmy3  # noqa: F401

pvlib/iotools/tmy.py

@@ -232,8 +232,8 @@ def test_get_clearsky_valueerror():
 
 def test_from_tmy_3():
     from test_tmy import tmy3_testfile
-    from pvlib.tmy import readtmy3
-    data, meta = readtmy3(tmy3_testfile)
+    from pvlib.iotools import read_tmy3
+    data, meta = read_tmy3(tmy3_testfile)
     loc = Location.from_tmy(meta, data)
     assert loc.name is not None
     assert loc.altitude != 0
@@ -243,8 +243,8 @@ def test_from_tmy_3():
 
 def test_from_tmy_2():
     from test_tmy import tmy2_testfile
-    from pvlib.tmy import readtmy2
-    data, meta = readtmy2(tmy2_testfile)
+    from pvlib.iotools import read_tmy2
+    data, meta = read_tmy2(tmy2_testfile)
     loc = Location.from_tmy(meta, data)
     assert loc.name is not None
     assert loc.altitude != 0

pvlib/test/test_location.py

@@ -11,7 +11,6 @@
 from pandas.util.testing import assert_series_equal, assert_frame_equal
 from numpy.testing import assert_allclose
 
-from pvlib import tmy
 from pvlib import pvsystem
 from pvlib import clearsky
 from pvlib import irradiance
@@ -23,9 +22,10 @@
 
 
 def test_systemdef_tmy3():
-    pvlib_abspath = os.path.dirname(os.path.abspath(inspect.getfile(tmy)))
+    from pvlib.iotools import tmy
+    pvlib_abspath = os.path.dirname(os.path.abspath(inspect.getfile(pvsystem)))
     tmy3_testfile = os.path.join(pvlib_abspath, 'data', '703165TY.csv')
-    tmy3_data, tmy3_metadata = tmy.readtmy3(tmy3_testfile)
+    tmy3_data, tmy3_metadata = tmy.read_tmy3(tmy3_testfile)
     expected = {'tz': -9.0,
                 'albedo': 0.1,
                 'altitude': 7.0,
@@ -40,9 +40,10 @@ def test_systemdef_tmy3():
 
 
 def test_systemdef_tmy2():
-    pvlib_abspath = os.path.dirname(os.path.abspath(inspect.getfile(tmy)))
+    from pvlib.iotools import tmy
+    pvlib_abspath = os.path.dirname(os.path.abspath(inspect.getfile(pvsystem)))
     tmy2_testfile = os.path.join(pvlib_abspath, 'data', '12839.tm2')
-    tmy2_data, tmy2_metadata = tmy.readtmy2(tmy2_testfile)
+    tmy2_data, tmy2_metadata = tmy.read_tmy2(tmy2_testfile)
 
     expected = {'tz': -5,
                 'albedo': 0.1,

pvlib/test/test_pvsystem.py

@@ -2,40 +2,60 @@
 import os
 
 from pandas.util.testing import network
+import pytest
+
+from pvlib._deprecation import pvlibDeprecationWarning
+from pvlib.iotools import tmy
+
+from conftest import fail_on_pvlib_version
+
 
 test_dir = os.path.dirname(os.path.abspath(inspect.getfile(inspect.currentframe())))
 tmy3_testfile = os.path.join(test_dir, '../data/703165TY.csv')
 tmy2_testfile = os.path.join(test_dir, '../data/12839.tm2')
 
-from pvlib import tmy
+
+@fail_on_pvlib_version('0.7')
+def test_deprecated_07():
+    with pytest.warns(pvlibDeprecationWarning):
+        from pvlib.tmy import readtmy2
+        readtmy2(tmy2_testfile)
+    with pytest.warns(pvlibDeprecationWarning):
+        from pvlib.tmy import readtmy3
+        readtmy3(tmy3_testfile)
 
 
-def test_readtmy3():
-    tmy.readtmy3(tmy3_testfile)
+def test_read_tmy3():
+    tmy.read_tmy3(tmy3_testfile)
+
 
 @network
-def test_readtmy3_remote():
+def test_read_tmy3_remote():
     url = 'http://rredc.nrel.gov/solar/old_data/nsrdb/1991-2005/data/tmy3/703165TYA.CSV'
-    tmy.readtmy3(url)
-    
-def test_readtmy3_recolumn():
-    data, meta = tmy.readtmy3(tmy3_testfile)
+    tmy.read_tmy3(url)
+
+
+def test_read_tmy3_recolumn():
+    data, meta = tmy.read_tmy3(tmy3_testfile)
     assert 'GHISource' in data.columns
-    
-def test_readtmy3_norecolumn():
-    data, meta = tmy.readtmy3(tmy3_testfile, recolumn=False)
+
+
+def test_read_tmy3_norecolumn():
+    data, meta = tmy.read_tmy3(tmy3_testfile, recolumn=False)
     assert 'GHI source' in data.columns
-    
-def test_readtmy3_coerce_year():
+
+
+def test_read_tmy3_coerce_year():
     coerce_year = 1987
-    data, meta = tmy.readtmy3(tmy3_testfile, coerce_year=coerce_year)
+    data, meta = tmy.read_tmy3(tmy3_testfile, coerce_year=coerce_year)
     assert (data.index.year == 1987).all()
-    
-def test_readtmy3_no_coerce_year():
+
+
+def test_read_tmy3_no_coerce_year():
     coerce_year = None
-    data, meta = tmy.readtmy3(tmy3_testfile, coerce_year=coerce_year)
+    data, meta = tmy.read_tmy3(tmy3_testfile, coerce_year=coerce_year)
     assert 1997 and 1999 in data.index.year
-    
-def test_readtmy2():
-    tmy.readtmy2(tmy2_testfile)
-    
+
+
+def test_read_tmy2():
+    tmy.read_tmy2(tmy2_testfile)