Reduces import footprint of IEX, adds docstrings, fixes DEEP API test after market hours

Author: rgkimball

pandas_datareader/__init__.py

@@ -3,18 +3,17 @@
 from .data import (get_components_yahoo, get_data_famafrench, get_data_google,
                    get_data_yahoo, get_data_enigma, get_data_yahoo_actions,
                    get_quote_google, get_quote_yahoo, get_tops_iex,
-                   get_last_iex, get_markets_iex, get_data_iex,
-                   get_summary_iex, get_records_iex, get_recent_iex,
-                   get_iex_symbols, get_iex_book,
-                   DataReader, Options)
+                   get_last_iex, get_markets_iex, get_summary_iex,
+                   get_records_iex, get_recent_iex, get_iex_symbols,
+                   get_iex_book, DataReader, Options)
 
 __version__ = get_versions()['version']
 del get_versions
 
 __all__ = ['__version__', 'get_components_yahoo', 'get_data_enigma',
            'get_data_famafrench', 'get_data_google', 'get_data_yahoo',
            'get_data_yahoo_actions', 'get_quote_google', 'get_quote_yahoo',
-           'get_data_iex', 'get_iex_book', 'get_iex_symbols', 'get_last_iex',
+           'get_iex_book', 'get_iex_symbols', 'get_last_iex',
            'get_markets_iex', 'get_recent_iex', 'get_records_iex',
            'get_summary_iex', 'get_tops_iex',
            'DataReader', 'Options']

pandas_datareader/data.py

@@ -13,13 +13,7 @@
 from pandas_datareader.google.daily import GoogleDailyReader
 from pandas_datareader.google.options import Options as GoogleOptions
 from pandas_datareader.google.quotes import GoogleQuotesReader
-from pandas_datareader.iex.market import MarketReader as IEXMarkets
-from pandas_datareader.iex.ref import SymbolsReader as IEXSymbols
-from pandas_datareader.iex.stats import DailySummaryReader as IEXHistorical
-from pandas_datareader.iex.stats import MonthlySummaryReader as IEXMonthSummary
 from pandas_datareader.iex.deep import Deep as IEXDeep
-from pandas_datareader.iex.stats import RecentReader as IEXRecents
-from pandas_datareader.iex.stats import RecordsReader as IEXRecords
 from pandas_datareader.iex.tops import LastReader as IEXLasts
 from pandas_datareader.iex.tops import TopsReader as IEXTops
 from pandas_datareader.moex import MoexReader
@@ -38,6 +32,9 @@
            'get_data_fred', 'get_data_google', 'get_data_moex',
            'get_data_quandl', 'get_data_yahoo', 'get_data_yahoo_actions',
            'get_nasdaq_symbols', 'get_quote_google', 'get_quote_yahoo',
+           'get_tops_iex', 'get_summary_iex', 'get_records_iex',
+           'get_recent_iex', 'get_markets_iex', 'get_last_iex',
+           'get_iex_symbols', 'get_iex_book', 'get_dailysummary_iex',
            'get_data_stooq', 'DataReader']
 
 
@@ -80,9 +77,11 @@ def get_data_quandl(*args, **kwargs):
 def get_data_moex(*args, **kwargs):
     return MoexReader(*args, **kwargs).read()
 
+
 def get_data_stooq(*args, **kwargs):
     return StooqDailyReader(*args, **kwargs).read()
 
+
 def get_tops_iex(*args, **kwargs):
     return IEXTops(*args, **kwargs).read()
 
@@ -92,31 +91,118 @@ def get_last_iex(*args, **kwargs):
 
 
 def get_markets_iex(*args, **kwargs):
-    return IEXMarkets(*args, **kwargs).read()
+    """
+    Returns near-real time volume data across markets segregated by tape
+    and including a percentage of overall volume during the session
+    
+    This endpoint does not accept any parameters.
+    
+    Reference: https://www.iextrading.com/developer/docs/#markets
+    
+    :return: DataFrame
+    """
+    from pandas_datareader.iex.market import MarketReader
+    return MarketReader(*args, **kwargs).read()
 
 
-def get_data_iex(*args, **kwargs):
-    return IEXHistorical(*args, **kwargs).read()
+def get_dailysummary_iex(*args, **kwargs):
+    """
+    Returns a summary of daily market volume statistics. Without parameters,
+    this will return the most recent trading session by default.
+    
+    :param start: 
+        A datetime object - the beginning of the date range.
+    :param end:
+        A datetime object - the end of the date range.
+        
+    Reference: https://www.iextrading.com/developer/docs/#historical-daily
+        
+    :return: DataFrame
+    """
+    from pandas_datareader.iex.stats import DailySummaryReader
+    return DailySummaryReader(*args, **kwargs).read()
 
 
 def get_summary_iex(*args, **kwargs):
-    return IEXMonthSummary(*args, **kwargs).read()
+    """
+    Returns an aggregated monthly summary of market volume and a variety of 
+    related metrics for trades by lot size, security market cap, and venue.
+    In the absence of parameters, this will return month-to-date statistics.
+    For ranges spanning multiple months, this will return one row per month.
+        
+    :param start: 
+        A datetime object - the beginning of the date range.
+    :param end:
+        A datetime object - the end of the date range.
+        
+    :return: DataFrame
+    """
+    from pandas_datareader.iex.stats import MonthlySummaryReader
+    return MonthlySummaryReader(*args, **kwargs).read()
 
 
 def get_records_iex(*args, **kwargs):
-    return IEXRecords(*args, **kwargs).read()
+    """
+    Returns the record value, record date, recent value, and 30-day average for
+    market volume, # of symbols traded, # of routed trades and notional value.
+    This function accepts no additional parameters.
+    
+    Reference: https://www.iextrading.com/developer/docs/#records
+    
+    :return: DataFrame
+    """
+    from pandas_datareader.iex.stats import RecordsReader
+    return RecordsReader(*args, **kwargs).read()
 
 
 def get_recent_iex(*args, **kwargs):
-    return IEXRecents(*args, **kwargs).read()
+    """
+    Returns market volume and trade routing statistics for recent sessions.
+    Also reports IEX's relative market share, lit share volume and a boolean
+    halfday indicator.
+    
+    Reference: https://www.iextrading.com/developer/docs/#recent
+    
+    :return: DataFrame
+    """
+    from pandas_datareader.iex.stats import RecentReader
+    return RecentReader(*args, **kwargs).read()
 
 
 def get_iex_symbols(*args, **kwargs):
-    return IEXSymbols(*args, **kwargs).read()
+    """
+    Returns a list of all equity symbols available for trading on IEX. Accepts
+    no additional parameters.
+    
+    Reference: https://www.iextrading.com/developer/docs/#symbols
+    
+    :return: DataFrame
+    """
+    from pandas_datareader.iex.ref import SymbolsReader
+    return SymbolsReader(*args, **kwargs).read()
 
 
 def get_iex_book(*args, **kwargs):
-    return IEXDeep(*args, **kwargs).read()
+    """
+    Returns an array of dictionaries with depth of book data from IEX for up to
+    10 securities at a time. Returns a dictionary of the bid and ask books.
+    
+    :param symbols:
+        A string or list of strings of valid tickers
+    :param service:
+        'book': Live depth of book data
+        'op-halt-status': Checks to see if the exchange has instituted a halt
+        'security-event': Denotes individual security related event
+        'ssr-status': Short Sale Price Test restrictions, per reg 201 of SHO
+        'system-event': Relays current feed status (i.e. market open)
+        'trades': Retrieves recent executions, trade size/price and flags
+        'trade-breaks': Lists execution breaks for the current trading session
+        'trading-status': Returns status and cause codes for securities
+     
+    :return: Object
+    """
+    from pandas_datareader.iex.deep import Deep
+    return Deep(*args, **kwargs).read()
 
 
 def DataReader(name, data_source=None, start=None, end=None,
@@ -146,7 +232,9 @@ def DataReader(name, data_source=None, start=None, end=None,
         single value given for symbol, represents the pause between retries.
     session : Session, default None
             requests.sessions.Session instance to be used
-
+    access_key : (str, None)
+        Optional parameter to specify an API key for certain data sources.
+    
     Examples
     ----------
 
@@ -159,7 +247,14 @@ def DataReader(name, data_source=None, start=None, end=None,
 
     # Data from Google Finance
     aapl = DataReader("AAPL", "google")
-
+    
+    # Price and volume data from IEX
+    tops = DataReader(["GS", "AAPL"], "iex-tops")
+    # Top of book executions from IEX
+    gs = DataReader("GS", "iex-last")
+    # Real-time depth of book data from IEX
+    gs = DataReader("GS", "iex-book")
+    
     # Data from FRED
     vix = DataReader("VIXCLS", "fred")
 
@@ -183,6 +278,7 @@ def DataReader(name, data_source=None, start=None, end=None,
         return YahooActionReader(symbols=name, start=start, end=end,
                                  retry_count=retry_count, pause=pause,
                                  session=session).read()
+
     elif data_source == "yahoo-dividends":
         return YahooDivReader(symbols=name, start=start, end=end,
                               adjust_price=False, chunksize=25,

pandas_datareader/tests/test_iex.py

@@ -3,9 +3,10 @@
 import pandas.util.testing as tm
 
 from pandas import DataFrame
-from datetime import datetime
+from datetime import datetime, timedelta
 from pandas_datareader.data import (DataReader, get_summary_iex, get_last_iex,
-                                    get_data_iex, get_iex_symbols)
+                                    get_dailysummary_iex, get_iex_symbols,
+                                    get_iex_book)
 
 
 class TestIEX(object):
@@ -27,7 +28,7 @@ def test_false_ticker(self):
         tm.assert_frame_equal(df, DataFrame())
 
     def test_daily(self):
-        df = get_data_iex(start=datetime(2017, 5, 5), end=datetime(2017, 5, 6))
+        df = get_dailysummary_iex(start=datetime(2017, 5, 5), end=datetime(2017, 5, 6))  #noqa
         assert df['routedVolume'].iloc[0] == 39974788
 
     def test_symbols(self):
@@ -41,7 +42,6 @@ def test_live_prices(self):
         assert df["price"].mean() > 0
 
     def test_deep(self):
-        dob = DataReader('GS', 'iex-book')
-        assert 'GS' in dob
-        assert 'asks' in dob['GS']
-        assert dob['GS']['bids'][0]['price'] > 0
+        dob = get_iex_book('GS', service='system-event')
+        assert len(dob['eventResponse']) > 0
+        assert dob['timestamp'] > datetime.now() - timedelta(days=1)