Merge pull request #464 from bashtage/extend-docs

DOC: Add doc pages for specific connectors
pydata · Jan 21, 2018 · 30e6249 · 30e6249
2 parents 747a67b + 24a2b90
commit 30e6249
Show file tree

Hide file tree

Showing 24 changed files with 263 additions and 104 deletions.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -18,6 +18,7 @@ Contents:
    remote_data.rst
    cache.rst
    see-also.rst
+   readers/index
 
 
 Indices and tables

diff --git a/docs/source/readers/bank-of-canada.rst b/docs/source/readers/bank-of-canada.rst
@@ -0,0 +1,8 @@
+Bank of Canada
+--------------
+
+.. py:module:: pandas_datareader.bankofcanada
+
+.. autoclass:: BankOfCanadaReader
+   :members:
+   :inherited-members:
diff --git a/docs/source/readers/enigma.rst b/docs/source/readers/enigma.rst
@@ -0,0 +1,8 @@
+Engima
+------
+
+.. py:module:: pandas_datareader.enigma
+
+.. autoclass:: EnigmaReader
+   :members:
+   :inherited-members:
diff --git a/docs/source/readers/eurostat.rst b/docs/source/readers/eurostat.rst
@@ -0,0 +1,8 @@
+Eurostat
+--------
+
+.. py:module:: pandas_datareader.eurostat
+
+.. autoclass:: EurostatReader
+   :members:
+   :inherited-members:
diff --git a/docs/source/readers/famafrench.rst b/docs/source/readers/famafrench.rst
@@ -0,0 +1,10 @@
+Fama-French Data (Ken French's Data Library)
+--------------------------------------------
+
+.. py:module:: pandas_datareader.famafrench
+
+.. autoclass:: FamaFrenchReader
+   :members:
+   :inherited-members:
+
+.. autofunction:: get_available_datasets
diff --git a/docs/source/readers/fred.rst b/docs/source/readers/fred.rst
@@ -0,0 +1,10 @@
+Federal Reserve Economic Data (FRED)
+------------------------------------
+
+.. py:module:: pandas_datareader.fred
+
+.. autoclass:: FredReader
+   :members:
+   :inherited-members: read
+
+
diff --git a/docs/source/readers/iex.rst b/docs/source/readers/iex.rst
@@ -0,0 +1,48 @@
+The Investors Exchange (IEX)
+----------------------------
+
+.. py:module:: pandas_datareader.iex.market
+
+.. autoclass:: MarketReader
+   :members:
+   :inherited-members:
+
+.. py:module:: pandas_datareader.iex.ref
+
+.. autoclass:: SymbolsReader
+   :members:
+   :inherited-members:
+
+.. py:module:: pandas_datareader.iex.stats
+
+.. autoclass:: DailySummaryReader
+   :members:
+   :inherited-members:
+
+.. autoclass:: MonthlySummaryReader
+   :members:
+   :inherited-members:
+
+.. autoclass:: RecordsReader
+   :members:
+   :inherited-members:
+
+.. autoclass:: RecentReader
+   :members:
+   :inherited-members:
+
+.. py:module:: pandas_datareader.iex.deep
+
+.. autoclass:: Deep
+   :members:
+   :inherited-members:
+
+.. py:module:: pandas_datareader.iex.tops
+
+.. autoclass:: TopsReader
+   :members:
+   :inherited-members:
+
+.. autoclass:: LastReader
+   :members:
+   :inherited-members:
diff --git a/docs/source/readers/index.rst b/docs/source/readers/index.rst
@@ -0,0 +1,19 @@
+Data Readers
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+   fred
+   famafrench
+   bank-of-canada
+   enigma
+   eurostat
+   iex
+   moex
+   nasdaq-trader
+   oecd
+   quandl
+   stooq
+   tsp
+   world-bank
diff --git a/docs/source/readers/moex.rst b/docs/source/readers/moex.rst
@@ -0,0 +1,8 @@
+Moscow Exchange (MOEX)
+----------------------
+
+.. py:module:: pandas_datareader.moex
+
+.. autoclass:: MoexReader
+   :members:
+   :inherited-members:
diff --git a/docs/source/readers/nasdaq-trader.rst b/docs/source/readers/nasdaq-trader.rst
@@ -0,0 +1,6 @@
+NASDAQ
+------
+
+.. py:module:: pandas_datareader.nasdaq_trader
+
+.. autofunction:: get_nasdaq_symbols
diff --git a/docs/source/readers/oecd.rst b/docs/source/readers/oecd.rst
@@ -0,0 +1,8 @@
+Organisation for Economic Co-operation and Development (OECD)
+-------------------------------------------------------------
+
+.. py:module:: pandas_datareader.oecd
+
+.. autoclass:: OECDReader
+   :members:
+   :inherited-members:
diff --git a/docs/source/readers/quandl.rst b/docs/source/readers/quandl.rst
@@ -0,0 +1,8 @@
+Quandl
+------
+
+.. py:module:: pandas_datareader.quandl
+
+.. autoclass:: QuandlReader
+   :members:
+   :inherited-members:
diff --git a/docs/source/readers/stooq.rst b/docs/source/readers/stooq.rst
@@ -0,0 +1,8 @@
+Stooq.com
+---------
+
+.. py:module:: pandas_datareader.stooq
+
+.. autoclass:: StooqDailyReader
+   :members:
+   :inherited-members:
diff --git a/docs/source/readers/tsp.rst b/docs/source/readers/tsp.rst
@@ -0,0 +1,8 @@
+Thrift Savings Plan (TSP)
+-------------------------
+
+.. py:module:: pandas_datareader.tsp
+
+.. autoclass:: TSPReader
+   :members:
+   :inherited-members:
diff --git a/docs/source/readers/world-bank.rst b/docs/source/readers/world-bank.rst
@@ -0,0 +1,16 @@
+World Bank
+----------
+
+.. py:module:: pandas_datareader.wb
+
+.. autoclass:: WorldBankReader
+   :members:
+   :inherited-members:
+
+.. autofunction:: download
+
+.. autofunction:: get_countries
+
+.. autofunction:: get_indicators
+
+.. autofunction:: search
diff --git a/pandas_datareader/base.py b/pandas_datareader/base.py
@@ -15,25 +15,24 @@
 
 
 class _BaseReader(object):
-
     """
     Parameters
     ----------
-        symbols : {str, List[str]}
-            String symbol of like of symbols
-        start : string, (defaults to '1/1/2010')
-            Starting date, timestamp. Parses many different kind of date
-            representations (e.g., 'JAN-01-2010', '1/1/10', 'Jan, 1, 1980')
-        end : string, (defaults to today)
-            Ending date, timestamp. Same format as starting date.
-        retry_count : int, default 3
-            Number of times to retry query request.
-        pause : float, default 0.1
-            Time, in seconds, of the pause between retries.
-        session : Session, default None
-            requests.sessions.Session instance to be used
-        freq : {str, None}
-            Frequency to use in select readers
+    symbols : {str, List[str]}
+        String symbol of like of symbols
+    start : string, (defaults to '1/1/2010')
+        Starting date, timestamp. Parses many different kind of date
+        representations (e.g., 'JAN-01-2010', '1/1/10', 'Jan, 1, 1980')
+    end : string, (defaults to today)
+        Ending date, timestamp. Same format as starting date.
+    retry_count : int, default 3
+        Number of times to retry query request.
+    pause : float, default 0.1
+        Time, in seconds, of the pause between retries.
+    session : Session, default None
+        requests.sessions.Session instance to be used
+    freq : {str, None}
+        Frequency to use in select readers
     """
 
     _chunk_size = 1024 * 1024
@@ -58,7 +57,7 @@ def __init__(self, symbols, start=None, end=None,  retry_count=3,
         self.freq = freq
 
     def close(self):
-        """ close my session """
+        """Close network session"""
         self.session.close()
 
     @property
@@ -71,7 +70,7 @@ def params(self):
         return None
 
     def read(self):
-        """ read data """
+        """Read data from connector"""
         try:
             return self._read_one_data(self.url, self.params)
         finally:
@@ -193,7 +192,7 @@ def _get_params(self, *args, **kwargs):
         raise NotImplementedError
 
     def read(self):
-        """ read data """
+        """Read data"""
         # If a single symbol, (e.g., 'GOOG')
         if isinstance(self.symbols, (compat.string_types, int)):
             df = self._read_one_data(self.url,

diff --git a/pandas_datareader/enigma.py b/pandas_datareader/enigma.py
@@ -11,28 +11,21 @@
 class EnigmaReader(_BaseReader):
     """
     Collects current snapshot of Enigma data located at the specified
-    dataset ID and returns a pandas DataFrame.
+    data set ID and returns a pandas DataFrame.
 
-    # Example
-    Download current snapshot for the following Florida Inspections Dataset
+    Examples
+    --------
+    Download current snapshot for the following Florida Inspections Dataset:
     https://public.enigma.com/datasets/bedaf052-5fcd-4758-8d27-048ce8746c6a
 
-    Usage (high-level):
-    ```
-        import pandas_datareader as pdr
-        df = pdr.get_data_enigma('bedaf052-5fcd-4758-8d27-048ce8746c6a')
-
-        # in the event that ENIGMA_API_KEY does not exist in your env,
-        # it can be supplied as the second arg:
-        df = prd.get_data_enigma('bedaf052-5fcd-4758-8d27-048ce8746c6a',
-        ...                      'INSERT_API_KEY')
-    ```
-
-    Usage:
-    ```
-        df = EnigmaReader(dataset_id='bedaf052-5fcd-4758-8d27-048ce8746c6a',
-        ...               api_key='INSERT_API_KEY').read()
-    ```
+    >>> import pandas_datareader as pdr
+    >>> df = pdr.get_data_enigma('bedaf052-5fcd-4758-8d27-048ce8746c6a')
+
+    In the event that ENIGMA_API_KEY does not exist in your env, the key can
+    be supplied as the second argument or as the keyword argument `api_key`
+
+    >>> df = EnigmaReader(dataset_id='bedaf052-5fcd-4758-8d27-048ce8746c6a',
+    ...                   api_key='INSERT_API_KEY').read()
     """
     def __init__(self,
                  dataset_id=None,

diff --git a/pandas_datareader/eurostat.py b/pandas_datareader/eurostat.py
@@ -8,7 +8,6 @@
 
 
 class EurostatReader(_BaseReader):
-
     """Get data for the given name from Eurostat."""
 
     _URL = 'http://www.ec.europa.eu/eurostat/SDMX/diss-web/rest'

diff --git a/pandas_datareader/famafrench.py b/pandas_datareader/famafrench.py
@@ -44,11 +44,6 @@ class FamaFrenchReader(_BaseReader):
 
     For annual and monthly data, index is a pandas.PeriodIndex, otherwise
     it's a pandas.DatetimeIndex.
-
-    Returns
-    -------
-    df : a dictionary of pandas.DataFrame. Tables are accessed by integer keys.
-         See df['DESCR'] for a description of the dataset
     """
 
     @property
@@ -66,6 +61,18 @@ def _read_zipfile(self, url):
 
         return data
 
+    def read(self):
+        """
+        Read data
+
+        Returns
+        -------
+        df : dict
+            A dictionary of DataFrames. Tables are accessed by integer keys.
+            See df['DESCR'] for a description of the data set.
+        """
+        return super(FamaFrenchReader, self).read()
+
     def _read_one_data(self, url, params):
 
         params = {'index_col': 0,
@@ -128,9 +135,11 @@ def _read_one_data(self, url, params):
     def get_available_datasets(self):
         """
         Get the list of datasets available from the Fama/French data library.
+
         Returns
         -------
-        A list of valid inputs for get_data_famafrench.
+        datasets: list
+            A list of valid inputs for get_data_famafrench
         """
         try:
             from lxml.html import document_fromstring

diff --git a/pandas_datareader/fred.py b/pandas_datareader/fred.py
@@ -20,6 +20,7 @@ def url(self):
         return "https://fred.stlouisfed.org/graph/fredgraph.csv"
 
     def read(self):
+        """Read data"""
         try:
             return self._read()
         finally: