Implements all available webhooks in IEX API 1.0

rgkimball · bashtage · commit f3a6fb2c28ef · 2018-01-18T09:58:52.000Z
diff --git a/pandas_datareader/data.py b/pandas_datareader/data.py
@@ -13,6 +13,14 @@
 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 IEXMonthlySummary
+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
 from pandas_datareader.nasdaq_trader import get_nasdaq_symbols
 from pandas_datareader.oecd import OECDReader
@@ -71,10 +79,40 @@ 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()
+
+
+def get_last_iex(*args, **kwargs):
+    return IEXLasts(*args, **kwargs).read()
+
+
+def get_markets_iex(*args, **kwargs):
+    return IEXMarkets(*args, **kwargs).read()
+
+
+def get_data_iex(*args, **kwargs):
+    return IEXHistorical(*args, **kwargs).read()
+
+
+def get_summary_iex(*args, **kwargs):
+    return IEXMonthlySummary(*args, **kwargs).read()
+
+
+def get_records_iex(*args, **kwargs):
+    return IEXRecords(*args, **kwargs).read()
+
+
+def get_recent_iex(*args, **kwargs):
+    return IEXRecents(*args, **kwargs).read()
+
+
+def get_iex_symbols(*args, **kwargs):
+    return IEXSymbols(*args, **kwargs).read()
+
 
 def DataReader(name, data_source=None, start=None, end=None,
                retry_count=3, pause=0.001, session=None, access_key=None):
@@ -151,6 +189,15 @@ def DataReader(name, data_source=None, start=None, end=None,
                                  chunksize=25,
                                  retry_count=retry_count, pause=pause,
                                  session=session).read()
+    elif data_source == "iex-tops":
+        return IEXTops(symbols=name, start=start, end=end,
+                       retry_count=retry_count, pause=pause,
+                       session=session).read()
+
+    elif data_source == "iex-last":
+        return IEXLasts(symbols=name, start=start, end=end,
+                        retry_count=retry_count, pause=pause,
+                        session=session).read()
 
     elif data_source == "bankofcanada":
         return BankOfCanadaReader(symbols=name, start=start, end=end,
diff --git a/pandas_datareader/iex/__init__.py b/pandas_datareader/iex/__init__.py
@@ -0,0 +1,73 @@
+import json
+import pandas as pd
+from pandas.io.common import urlencode
+from pandas_datareader.base import _BaseReader
+
+# Data provided for free by IEX
+# Data is furnished in compliance with the guidelines promulgated in the IEX API terms of service and manual
+# See https://iextrading.com/api-exhibit-a/ for additional information and conditions of use
+
+
+class IEX(_BaseReader):
+
+    """
+    Serves as the base class for all IEX API services.
+    """
+
+    _format = 'json'
+
+    def __init__(self, symbols=None, start=None, end=None, retry_count=3,
+                 pause=0.001, session=None):
+        super(IEX, self).__init__(symbols=symbols,
+                                      start=start, end=end,
+                                      retry_count=retry_count,
+                                      pause=pause, session=session)
+
+    @property
+    def service(self):
+        # This property will be overridden by the subclass
+        raise NotImplementedError("IEX API service not specified.")
+
+    @property
+    def url(self):
+        qstring = urlencode(self._get_params(self.symbols))
+        return "https://api.iextrading.com/1.0/{}?{}".format(self.service, qstring)
+
+    def read(self):
+        df = super(IEX, self).read()
+        return df
+
+    def _get_params(self, symbols):
+        p = {}
+        if isinstance(symbols, list):
+            p['symbols'] = ','.join(symbols)
+        elif isinstance(symbols, str):
+            p['symbols'] = symbols
+        return p
+
+    def _output_error(self, out):
+        """If IEX returns a non-200 status code, we need to notify the user of the error returned.
+        
+        :param out: Raw HTTP Output
+        """
+        try:
+            content = json.loads(out.text)
+        except:
+            raise TypeError("Failed to interpret response as JSON.")
+
+        for key, string in content.items():
+            e = "IEX Output error encountered: {}".format(string)
+            if key == 'error':
+                raise Exception(e)
+
+    def _read_lines(self, out):
+        """IEX's output does not need anything complex, so we're overriding to use Pandas' default interpreter
+        
+        :param out: Raw HTTP Output
+        :return: DataFrame
+        """
+
+        # IEX will return a blank line for invalid tickers:
+        if isinstance(out, list):
+            out = [x for x in out if x is not None]
+        return pd.DataFrame(out) if len(out) > 0 else pd.DataFrame()
diff --git a/pandas_datareader/iex/market.py b/pandas_datareader/iex/market.py
@@ -0,0 +1,22 @@
+from pandas_datareader.iex import IEX
+
+# Data provided for free by IEX
+# Data is furnished in compliance with the guidelines promulgated in the IEX API terms of service and manual
+# See https://iextrading.com/api-exhibit-a/ for additional information and conditions of use
+
+
+class MarketReader(IEX):
+    def __init__(self, symbols=None, start=None, end=None, retry_count=3,
+                 pause=0.001, session=None):
+        super(MarketReader, self).__init__(symbols=symbols,
+                                          start=start, end=end,
+                                          retry_count=retry_count,
+                                          pause=pause, session=session)
+
+    @property
+    def service(self):
+        return "market"
+
+    def _get_params(self, symbols):
+        # Market API does not take any parameters, returning empty dict
+        return {}
diff --git a/pandas_datareader/iex/ref.py b/pandas_datareader/iex/ref.py
@@ -0,0 +1,22 @@
+from pandas_datareader.iex import IEX
+
+# Data provided for free by IEX
+# Data is furnished in compliance with the guidelines promulgated in the IEX API terms of service and manual
+# See https://iextrading.com/api-exhibit-a/ for additional information and conditions of use
+
+
+class SymbolsReader(IEX):
+    def __init__(self, symbols=None, start=None, end=None, retry_count=3,
+                 pause=0.001, session=None):
+        super(SymbolsReader, self).__init__(symbols=symbols,
+                                          start=start, end=end,
+                                          retry_count=retry_count,
+                                          pause=pause, session=session)
+
+    @property
+    def service(self):
+        return "ref-data/symbols"
+
+    def _get_params(self, symbols):
+        # Ref Data API does not take any parameters, returning empty dict
+        return {}
diff --git a/pandas_datareader/iex/stats.py b/pandas_datareader/iex/stats.py
@@ -0,0 +1,131 @@
+import pandas as pd
+from datetime import datetime, timedelta
+from pandas_datareader.iex import IEX
+
+# Data provided for free by IEX
+# Data is furnished in compliance with the guidelines promulgated in the IEX API terms of service and manual
+# See https://iextrading.com/api-exhibit-a/ for additional information and conditions of use
+
+
+class DailySummaryReader(IEX):
+    def __init__(self, symbols=None, start=None, end=None, retry_count=3,
+                 pause=0.001, session=None):
+        self.curr_date = start
+        super(DailySummaryReader, self).__init__(symbols=symbols,
+                                          start=start, end=end,
+                                          retry_count=retry_count,
+                                          pause=pause, session=session)
+
+    @property
+    def service(self):
+        return "stats/historical/daily"
+
+    def _get_params(self, symbols):
+        p = {}
+
+        if self.curr_date is not None:
+            p['date'] = self.curr_date.strftime('%Y%m%d')
+
+        return p
+
+    def read(self):
+        """Unfortunately, IEX's API can only retrieve data one day or one month at a time. Rather than specifying a date
+        range, we will have to run the read function for each date provided.
+        
+        :return: DataFrame
+        """
+        tlen = self.end - self.start
+        dfs = []
+        for date in (self.start + timedelta(n) for n in range(tlen.days)):
+            self.curr_date = date
+            tdf = super(IEX, self).read()
+            dfs.append(tdf)
+        return pd.concat(dfs)
+
+
+class MonthlySummaryReader(IEX):
+    def __init__(self, symbols=None, start=None, end=None, retry_count=3,
+                 pause=0.001, session=None):
+        self.curr_date = start
+        self.date_format = '%Y%m'
+
+        super(MonthlySummaryReader, self).__init__(symbols=symbols,
+                                          start=start, end=end,
+                                          retry_count=retry_count,
+                                          pause=pause, session=session)
+
+    @property
+    def service(self):
+        return "stats/historical"
+
+    def _get_params(self, symbols):
+        p = {}
+
+        if self.curr_date is not None:
+            p['date'] = self.curr_date.strftime(self.date_format)
+
+        return p
+
+    def read(self):
+        """Unfortunately, IEX's API can only retrieve data one day or one month at a time. Rather than specifying a date
+        range, we will have to run the read function for each date provided.
+        
+        :return: DataFrame
+        """
+        tlen = self.end - self.start
+        dfs = []
+
+        # Build list of all dates within the given range
+        lrange = [x for x in (self.start + timedelta(n) for n in range(tlen.days))]
+
+        mrange = []
+        for dt in lrange:
+            if datetime(dt.year, dt.month, 1) not in mrange:
+                mrange.append(datetime(dt.year, dt.month, 1))
+        lrange = mrange
+
+        for date in lrange:
+            self.curr_date = date
+            tdf = super(IEX, self).read()
+
+            # We may not return data if this was a weekend/holiday:
+            if not tdf.empty:
+                tdf['date'] = date.strftime(self.date_format)
+                dfs.append(tdf)
+
+        # We may not return any data if we failed to specify useful parameters:
+        return pd.concat(dfs) if len(dfs) > 0 else pd.DataFrame()
+
+
+class RecordsReader(IEX):
+    def __init__(self, symbols=None, start=None, end=None, retry_count=3,
+                 pause=0.001, session=None):
+        super(RecordsReader, self).__init__(symbols=symbols,
+                                          start=start, end=end,
+                                          retry_count=retry_count,
+                                          pause=pause, session=session)
+
+    @property
+    def service(self):
+        return "stats/records"
+
+    def _get_params(self, symbols):
+        # Record Stats API does not take any parameters, returning empty dict
+        return {}
+
+
+class RecentReader(IEX):
+    def __init__(self, symbols=None, start=None, end=None, retry_count=3,
+                 pause=0.001, session=None):
+        super(RecentReader, self).__init__(symbols=symbols,
+                                          start=start, end=end,
+                                          retry_count=retry_count,
+                                          pause=pause, session=session)
+
+    @property
+    def service(self):
+        return "stats/recent"
+
+    def _get_params(self, symbols):
+        # Record Stats API does not take any parameters, returning empty dict
+        return {}
diff --git a/pandas_datareader/iex/tops.py b/pandas_datareader/iex/tops.py
@@ -0,0 +1,33 @@
+from pandas_datareader.iex import IEX
+
+# Data provided for free by IEX
+# Data is furnished in compliance with the guidelines promulgated in the IEX API terms of service and manual
+# See https://iextrading.com/api-exhibit-a/ for additional information and conditions of use
+
+
+class TopsReader(IEX):
+
+    def __init__(self, symbols=None, start=None, end=None, retry_count=3,
+                 pause=0.001, session=None):
+        super(TopsReader, self).__init__(symbols=symbols,
+                                          start=start, end=end,
+                                          retry_count=retry_count,
+                                          pause=pause, session=session)
+
+    @property
+    def service(self):
+        return "tops"
+
+
+class LastReader(IEX):
+    # todo: Eventually we'll want to implement the WebSockets version as an option.
+    def __init__(self, symbols=None, start=None, end=None, retry_count=3,
+                 pause=0.001, session=None):
+        super(LastReader, self).__init__(symbols=symbols,
+                                          start=start, end=end,
+                                          retry_count=retry_count,
+                                          pause=pause, session=session)
+
+    @property
+    def service(self):
+        return "tops/last"
