Merge pull request #466 from bashtage/doc-cleanup

bashtage · web-flow · commit 1953452b39b8 · 2018-01-22T11:34:28.000Z
DOC: Clean up docs
diff --git a/README.rst b/README.rst
@@ -25,6 +25,11 @@ Up to date remote data access for pandas, works for multiple versions of pandas.
   been immediately deprecated due to large changes in their API and
   no stable replacement.
 
+.. note::
+
+  As of v0.6.0 Google finance is still functioning for historical price data,
+  although there are frequent reports of failures.  Failure is frequently
+  encountered when bulk downloading historical price data.
 
 Installation
 ------------
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -42,6 +42,7 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.extlinks',
+    'sphinx.ext.napoleon',
     'IPython.sphinxext.ipython_directive',
     'IPython.sphinxext.ipython_console_highlighting'
 ]
diff --git a/docs/source/readers/iex.rst b/docs/source/readers/iex.rst
@@ -1,6 +1,12 @@
 The Investors Exchange (IEX)
 ----------------------------
 
+.. py:module:: pandas_datareader.iex.daily
+
+.. autoclass:: IEXDailyReader
+   :members:
+   :inherited-members:
+
 .. py:module:: pandas_datareader.iex.market
 
 .. autoclass:: MarketReader
diff --git a/docs/source/remote_data.rst b/docs/source/remote_data.rst
@@ -39,7 +39,6 @@ Currently the following sources are supported:
     - :ref:`Eurostat<remote_data.eurostat>`
     - :ref:`Thrift Savings Plan<remote_data.tsp>`
     - :ref:`Nasdaq Trader symbol definitions<remote_data.nasdaq_symbols>`
-    - :ref:`IEX<remote_data.iex>`
     - :ref:`Stooq<remote_data.stooq>`
     - :ref:`MOEX<remote_data.moex>`
 
@@ -70,7 +69,9 @@ Google Finance
 IEX
 ===
 
-Historical stock prices from `IEX <https://iextrading.com/developer/>`__, 
+The Investors Exchange (IEX) provides a wide range of data through an
+`API <https://iextrading.com/developer/docs/>`__.  Historical stock
+prices are available for up to 5 years:
 
 .. ipython:: python
 
@@ -81,8 +82,16 @@ Historical stock prices from `IEX <https://iextrading.com/developer/>`__,
     f = web.DataReader('F', 'iex', start, end)
     f.loc['2015-02-09']
 
+There are additional interfaces to this API that are
+directly exposed: tops (`'iex-tops'`) and last (`'iex-lasts'`).
+A third interface to the deep API is exposed through
+`Deep` class or the `get_iex_book` function.
 
-Prices are available up for the past 5 years.
+.. ipython:: python
+
+    import pandas_datareader.data as web
+    f = web.DataReader('gs', 'iex-tops')
+    f[:10]
 
 .. _remote_data.enigma:
 
@@ -422,20 +431,6 @@ available. More information on the `field <http://www.nasdaqtrader.com/trader.as
         Name: IBM, dtype: object
 
 
-.. _remote_data.iex:
-
-The Investors Exchange (IEX) provides a wide range of data through an
-`API <https://iextrading.com/developer/docs/>`__. There are two interfaces
-to this API that are directly exposed: tops (`'iex-tops'`) and last
-(`'iex-lasts'`).  A third interface to the deep API is exposed through
-`IEXDeep` class or the `get_iex_book` function.
-
-.. ipython:: python
-
-    import pandas_datareader.data as web
-    f = web.DataReader('gs', 'iex-tops')
-    f[:10]
-
 .. _remote_data.stooq:
 
 Stooq Index Data
diff --git a/docs/source/whatsnew/v0.6.0.txt b/docs/source/whatsnew/v0.6.0.txt
@@ -1,6 +1,6 @@
 .. _whatsnew_060:
 
-v0.6.0 (January TODO, 2018)
+v0.6.0 (January 23, 2018)
 ---------------------------
 
 This is a major release from 0.5.0. We recommend that all users upgrade.
@@ -10,16 +10,30 @@ This is a major release from 0.5.0. We recommend that all users upgrade.
   Yahoo!, Google Options, Google Quotes and EDGAR have been immediately
   deprecated.
 
+.. note::
+
+  Google finance is still functioning for historical price data,
+  although there are frequent reports of failures.  Failure is frequently
+  encountered when bulk downloading historical price data.
+
 Highlights include:
 
-- A new data connector for stock index data provided by Stooq was
-  introduced. (:issue:`447`)
+- Immediate deprecation of Yahoo!, Google Options and Quotes and EDGAR. The
+  end points behind these APIs have radically changed and the existing readers
+  require complete rewrites. In the case of most Yahoo! data the endpoints
+  have been removed.  PDR would like to restore these features, and pull
+  requests are welcome.
 
-- A new data connector for data provided by the Bank of Canada was
-  introduced. (:issue:`440`)
+- A new connector for IEX daily price data was introduced (:issue:`465`).
+
+- A new connector for IEX the majority of the IEX API was introduced
+  (:issue:`446`).
 
-- Immediate deprecation of Yahoo!, Google Options and Quotes and EDGAR.
+- A new data connector for stock index data provided by Stooq was
+  introduced (:issue:`447`).
 
+- A new data connector for data provided by the Bank of Canada was
+  introduced (:issue:`440`).
 
 .. contents:: What's new in v0.6.0
     :local:
diff --git a/pandas_datareader/bankofcanada.py b/pandas_datareader/bankofcanada.py
@@ -12,13 +12,15 @@ class BankOfCanadaReader(_BaseReader):
 
     @property
     def url(self):
+        """API URL"""
         if not isinstance(self.symbols, compat.string_types):
             raise ValueError('data name must be string')
 
         return '{0}/{1}/csv'.format(self._URL, self.symbols)
 
     @property
     def params(self):
+        """Parameters to use in API calls"""
         return {'start_date': self.start.strftime('%Y-%m-%d'),
                 'end_date': self.end.strftime('%Y-%m-%d')}
 
diff --git a/pandas_datareader/base.py b/pandas_datareader/base.py
@@ -62,11 +62,13 @@ def close(self):
 
     @property
     def url(self):
+        """API URL"""
         # must be overridden in subclass
         raise NotImplementedError
 
     @property
     def params(self):
+        """Parameters to use in API calls"""
         return None
 
     def read(self):
diff --git a/pandas_datareader/enigma.py b/pandas_datareader/enigma.py
@@ -63,6 +63,7 @@ def __init__(self,
         self._retry_delay = pause
 
     def read(self):
+        """Read data"""
         try:
             return self._read()
         finally:
diff --git a/pandas_datareader/eurostat.py b/pandas_datareader/eurostat.py
@@ -14,6 +14,7 @@ class EurostatReader(_BaseReader):
 
     @property
     def url(self):
+        """API URL"""
         if not isinstance(self.symbols, compat.string_types):
             raise ValueError('data name must be string')
 
@@ -23,6 +24,7 @@ def url(self):
 
     @property
     def dsd_url(self):
+        """API DSD URL"""
         if not isinstance(self.symbols, compat.string_types):
             raise ValueError('data name must be string')
 
diff --git a/pandas_datareader/famafrench.py b/pandas_datareader/famafrench.py
@@ -48,6 +48,7 @@ class FamaFrenchReader(_BaseReader):
 
     @property
     def url(self):
+        """API URL"""
         return ''.join([_URL, _URL_PREFIX, self.symbols, _URL_SUFFIX])
 
     def _read_zipfile(self, url):
diff --git a/pandas_datareader/fred.py b/pandas_datareader/fred.py
@@ -7,20 +7,22 @@
 class FredReader(_BaseReader):
     """
     Get data for the given name from the St. Louis FED (FRED).
-    Date format is datetime
-
-    Returns a DataFrame.
-
-    If multiple names are passed for "series" then the index of the
-    DataFrame is the outer join of the indicies of each series.
     """
 
     @property
     def url(self):
+        """API URL"""
         return "https://fred.stlouisfed.org/graph/fredgraph.csv"
 
     def read(self):
-        """Read data"""
+        """Read data
+
+        Returns
+        -------
+        data : DataFrame
+            If multiple names are passed for "series" then the index of the
+            DataFrame is the outer join of the indicies of each series.
+        """
         try:
             return self._read()
         finally:
@@ -35,6 +37,7 @@ def _read(self):
         urls = ["{}?id={}".format(self.url, n) for n in names]
 
         def fetch_data(url, name):
+            """Utillity to fetch data"""
             resp = self._read_url_as_StringIO(url)
             data = read_csv(resp, index_col=0, parse_dates=True,
                             header=None, skiprows=1, names=["DATE", name],
diff --git a/pandas_datareader/google/daily.py b/pandas_datareader/google/daily.py
@@ -44,6 +44,7 @@ def __init__(self, symbols=None, start=None, end=None, retry_count=3,
 
     @property
     def url(self):
+        """API URL"""
         return 'https://finance.google.com/finance/historical'
 
     def _get_params(self, symbol):
diff --git a/pandas_datareader/google/quotes.py b/pandas_datareader/google/quotes.py
@@ -19,6 +19,7 @@ def url(self):
 
     @property
     def params(self):
+        """Parameters to use in API calls"""
         if isinstance(self.symbols, pd.compat.string_types):
             sym_list = self.symbols
         else:
diff --git a/pandas_datareader/iex/__init__.py b/pandas_datareader/iex/__init__.py
@@ -28,16 +28,19 @@ def __init__(self, symbols=None, start=None, end=None, retry_count=3,
 
     @property
     def service(self):
+        """Service endpoint"""
         # This property will be overridden by the subclass
         raise NotImplementedError("IEX API service not specified.")
 
     @property
     def url(self):
+        """API URL"""
         qstring = urlencode(self._get_params(self.symbols))
         return "https://api.iextrading.com/1.0/{}?{}".format(self.service,
                                                              qstring)
 
     def read(self):
+        """Read data"""
         df = super(IEX, self).read()
         if isinstance(df, pd.DataFrame):
             df = df.squeeze()
diff --git a/pandas_datareader/iex/daily.py b/pandas_datareader/iex/daily.py
@@ -50,10 +50,12 @@ def __init__(self, symbols=None, start=None, end=None, retry_count=3,
 
     @property
     def url(self):
+        """API URL"""
         return 'https://api.iextrading.com/1.0/stock/market/batch'
 
     @property
     def endpoint(self):
+        """API endpoint"""
         return "chart"
 
     def _get_params(self, symbol):
@@ -83,7 +85,7 @@ def _range_string_from_date(self):
                 "Invalid date specified. Must be within past 5 years.")
 
     def read(self):
-        """read data"""
+        """Read data"""
         try:
             return self._read_one_data(self.url,
                                        self._get_params(self.symbols))
diff --git a/pandas_datareader/iex/deep.py b/pandas_datareader/iex/deep.py
@@ -9,6 +9,19 @@
 
 
 class Deep(IEX):
+    """
+    Retrieve order book data from IEX
+
+    Notes
+    -----
+    Real-time depth of book quotations direct from IEX. Returns aggregated
+    size of resting displayed orders at a price and side. Does not indicate
+    the size or number of individual orders at any price level. Non-displayed
+    orders and non-displayed portions of reserve orders are not counted.
+
+    Also provides last trade price and size information. Routed executions
+    are not reported.
+    """
     def __init__(self, symbols=None, service=None, start=None, end=None,
                  retry_count=3, pause=0.001, session=None):
         if isinstance(symbols, str):
@@ -24,6 +37,7 @@ def __init__(self, symbols=None, service=None, start=None, end=None,
 
     @property
     def service(self):
+        """Service endpoint"""
         ss = "/" + self.sub if self.sub is not None else ""
         return "deep{}".format(ss)
 
diff --git a/pandas_datareader/iex/market.py b/pandas_datareader/iex/market.py
@@ -8,6 +8,14 @@
 
 
 class MarketReader(IEX):
+    """
+    Near real-time traded volume
+
+    Notes
+    -----
+    Market data is captured by the IEX system between approximately 7:45 a.m.
+    and 5:15 p.m. ET.
+    """
     def __init__(self, symbols=None, start=None, end=None, retry_count=3,
                  pause=0.001, session=None):
         super(MarketReader, self).__init__(symbols=symbols,
@@ -17,6 +25,7 @@ def __init__(self, symbols=None, start=None, end=None, retry_count=3,
 
     @property
     def service(self):
+        """Service endpoint"""
         return "market"
 
     def _get_params(self, symbols):
diff --git a/pandas_datareader/iex/ref.py b/pandas_datareader/iex/ref.py
@@ -8,6 +8,14 @@
 
 
 class SymbolsReader(IEX):
+    """
+    Symbols available for trading on IEX
+
+    Notes
+    -----
+    Returns symbols IEX supports for trading. Updated daily as of 7:45 a.m.
+    ET.
+    """
     def __init__(self, symbols=None, start=None, end=None, retry_count=3,
                  pause=0.001, session=None):
         super(SymbolsReader, self).__init__(symbols=symbols,
@@ -17,6 +25,7 @@ def __init__(self, symbols=None, start=None, end=None, retry_count=3,
 
     @property
     def service(self):
+        """Service endpoint"""
         return "ref-data/symbols"
 
     def _get_params(self, symbols):
diff --git a/pandas_datareader/iex/stats.py b/pandas_datareader/iex/stats.py
diff --git a/pandas_datareader/iex/tops.py b/pandas_datareader/iex/tops.py
diff --git a/pandas_datareader/moex.py b/pandas_datareader/moex.py
diff --git a/pandas_datareader/oecd.py b/pandas_datareader/oecd.py
diff --git a/pandas_datareader/quandl.py b/pandas_datareader/quandl.py
diff --git a/pandas_datareader/stooq.py b/pandas_datareader/stooq.py
diff --git a/pandas_datareader/tsp.py b/pandas_datareader/tsp.py
diff --git a/pandas_datareader/wb.py b/pandas_datareader/wb.py
diff --git a/pandas_datareader/yahoo/quotes.py b/pandas_datareader/yahoo/quotes.py

Original file line number	Diff line number	Diff line change
`@@ -42,6 +42,7 @@`
`42`	`42`	`'sphinx.ext.autodoc',`
`43`	`43`	`'sphinx.ext.intersphinx',`
`44`	`44`	`'sphinx.ext.extlinks',`
	`45`	`+ 'sphinx.ext.napoleon',`
`45`	`46`	`'IPython.sphinxext.ipython_directive',`
`46`	`47`	`'IPython.sphinxext.ipython_console_highlighting'`
`47`	`48`	`]`