Merge pull request #706 from bashtage/uniform-docs

DOC: Use a uniform docstring structure

pandas_datareader/_utils.py

@@ -22,9 +22,9 @@ def _sanitize_dates(start, end):
 
     Parameters
     ----------
-    start: str, int, date, datetime, timestamp
+    start : str, int, date, datetime, Timestamp
         Desired start date
-    end: str, int, date, datetime, timestamp
+    end : str, int, date, datetime, Timestamp
         Desired end date
     """
     if is_number(start):

pandas_datareader/av/time_series.py

@@ -13,11 +13,11 @@ class AVTimeSeriesReader(AlphaVantage):
     ----------
     symbols : string
         Single stock symbol (ticker)
-    start : string, int, date, datetime, timestamp
+    start : string, int, date, datetime, Timestamp
         Starting date. Parses many different kind of date
         representations (e.g., 'JAN-01-2010', '1/1/10', 'Jan, 1, 1980'). Defaults to
         20 years before current date.
-    end : string, int, date, datetime, timestamp
+    end : string, int, date, datetime, Timestamp
         Ending date
     retry_count : int, default 3
         Number of times to retry query request.

pandas_datareader/base.py

@@ -28,10 +28,10 @@ class _BaseReader(object):
     ----------
     symbols : {str, List[str]}
         String symbol of like of symbols
-    start : string, int, date, datetime, timestamp
+    start : string, int, date, datetime, Timestamp
         Starting date. Parses many different kind of date
         representations (e.g., 'JAN-01-2010', '1/1/10', 'Jan, 1, 1980')
-    end : string, int, date, datetime, timestamp
+    end : string, int, date, datetime, Timestamp
         Ending date
     retry_count : int, default 3
         Number of times to retry query request.
@@ -186,8 +186,14 @@ def _output_error(self, out):
         """If necessary, a service can implement an interpreter for any non-200
          HTTP responses.
 
-        :param out: raw output from an HTTP request
-        :return: boolean
+        Parameters
+        ----------
+        out: bytes
+            The raw output from an HTTP request
+
+        Returns
+        -------
+        boolean
         """
         return False
 

pandas_datareader/data.py

@@ -155,7 +155,9 @@ def get_markets_iex(*args, **kwargs):
 
     Reference: https://www.iextrading.com/developer/docs/#markets
 
-    :return: DataFrame
+    Returns
+    -------
+    DataFrame
     """
     from pandas_datareader.iex.market import MarketReader
 
@@ -167,10 +169,12 @@ 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.
+    Parameters
+    ----------
+    start : string, int, date, datetime, Timestamp
+        The beginning of the date range.
+    end : string, int, date, datetime, Timestamp
+        The end of the date range.
 
     Reference: https://www.iextrading.com/developer/docs/#historical-daily
 
@@ -188,12 +192,14 @@ def get_summary_iex(*args, **kwargs):
     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:
+    start : string, int, date, datetime, Timestamp
         A datetime object - the beginning of the date range.
-    :param end:
+    end : string, int, date, datetime, Timestamp
         A datetime object - the end of the date range.
 
-    :return: DataFrame
+    Returns
+    -------
+    DataFrame
     """
     from pandas_datareader.iex.stats import MonthlySummaryReader
 
@@ -223,7 +229,9 @@ def get_recent_iex(*args, **kwargs):
 
     Reference: https://www.iextrading.com/developer/docs/#recent
 
-    :return: DataFrame
+    Returns
+    -------
+    DataFrame
     """
     from pandas_datareader.iex.stats import RecentReader
 
@@ -249,19 +257,25 @@ def get_iex_book(*args, **kwargs):
     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:
+    Parameters
+    ----------
+    symbols : str, List[str]
         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
+    service : str
+        One of:
+
+        - '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
+
+    Returns
+    -------
+    DataFrame
     """
     return IEXDeep(*args, **kwargs).read()
 
@@ -290,9 +304,9 @@ def DataReader(
         accept a list of names.
     data_source: {str, None}
         the data source ("iex", "fred", "ff")
-    start : {datetime, None}
+    start : string, int, date, datetime, Timestamp
         left boundary for range (defaults to 1/1/2010)
-    end : {datetime, None}
+    end : string, int, date, datetime, Timestamp
         right boundary for range (defaults to today)
     retry_count : {int, 3}
         Number of times to retry query request.

pandas_datareader/iex/__init__.py

@@ -64,7 +64,10 @@ 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
+        Parameters
+        ----------
+        out: bytes
+            The raw output from an HTTP request
         """
         try:
             content = json.loads(out.text)
@@ -80,8 +83,14 @@ 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
+        Parameters
+        ----------
+        out: bytes
+            The raw output from an HTTP request
+
+        Returns
+        -------
+        DataFrame
         """
 
         # IEX will return a blank line for invalid tickers:

pandas_datareader/iex/daily.py

@@ -27,11 +27,11 @@ class IEXDailyReader(_DailyBaseReader):
     symbols : string, array-like object (list, tuple, Series), or DataFrame
         Single stock symbol (ticker), array-like object of symbols or
         DataFrame with index containing stock symbols.
-    start : string, int, date, datetime, timestamp
+    start : string, int, date, datetime, Timestamp
         Starting date. Parses many different kind of date
         representations (e.g., 'JAN-01-2010', '1/1/10', 'Jan, 1, 1980'). Defaults to
         15 years before current date
-    end : string, int, date, datetime, timestamp
+    end : string, int, date, datetime, Timestamp
         Ending date
     retry_count : int, default 3
         Number of times to retry query request.

pandas_datareader/iex/deep.py

@@ -59,8 +59,14 @@ def _read_lines(self, out):
         """
         IEX depth of book data varies and shouldn't always be returned in a DF
 
-        :param out: Raw HTTP Output
-        :return: DataFrame
+        Parameters
+        ----------
+        out: bytes
+            The raw output from an HTTP request
+
+        Returns
+        -------
+        DataFrame
         """
 
         # Runs appropriate output functions per the service being accessed.

pandas_datareader/moex.py

@@ -15,11 +15,11 @@ class MoexReader(_DailyBaseReader):
     symbols : str, an array-like object (list, tuple, Series), or a DataFrame
         A single stock symbol (secid), an array-like object of symbols or
         a DataFrame with an index containing stock symbols.
-    start : string, int, date, datetime, timestamp
+    start : string, int, date, datetime, Timestamp
         Starting date. Parses many different kind of date
         representations (e.g., 'JAN-01-2010', '1/1/10', 'Jan, 1, 1980'). Defaults to
         20 years before current date.
-    end : string, int, date, datetime, timestamp
+    end : string, int, date, datetime, Timestamp
         Ending date
     retry_count : int, default 3
         The number of times to retry query request.

pandas_datareader/quandl.py

@@ -23,11 +23,11 @@ class QuandlReader(_DailyBaseReader):
         Beware of ambiguous symbols (different securities per country)!
         Note: Cannot use more than a single string because of the inflexible
         way the URL is composed of url and _get_params in the superclass
-    start : string, int, date, datetime, timestamp
+    start : string, int, date, datetime, Timestamp
         Starting date. Parses many different kind of date
         representations (e.g., 'JAN-01-2010', '1/1/10', 'Jan, 1, 1980'). Defaults to
         20 years before current date.
-    end : string, int, date, datetime, timestamp
+    end : string, int, date, datetime, Timestamp
         Ending date
     retry_count : int, default 3
         Number of times to retry query request.

pandas_datareader/stooq.py

@@ -12,11 +12,11 @@ class StooqDailyReader(_DailyBaseReader):
     symbols : string, array-like object (list, tuple, Series), or DataFrame
         Single stock symbol (ticker), array-like object of symbols or
         DataFrame with index containing stock symbols.
-    start : string, int, date, datetime, timestamp
+    start : string, int, date, datetime, Timestamp
         Starting date. Parses many different kind of date
         representations (e.g., 'JAN-01-2010', '1/1/10', 'Jan, 1, 1980'). Defaults to
         20 years before current date.
-    end : string, int, date, datetime, timestamp
+    end : string, int, date, datetime, Timestamp
         Ending date
     retry_count : int, default 3
         Number of times to retry query request.

pandas_datareader/tiingo.py

@@ -34,11 +34,11 @@ class TiingoIEXHistoricalReader(_BaseReader):
         ----------
         symbols : {str, List[str]}
             String symbol of like of symbols
-        start : string, int, date, datetime, timestamp
+        start : string, int, date, datetime, Timestamp
             Starting date. Parses many different kind of date
             representations (e.g., 'JAN-01-2010', '1/1/10', 'Jan, 1, 1980'). Defaults to
             20 years before current date.
-        end : string, int, date, datetime, timestamp
+        end : string, int, date, datetime, Timestamp
             Ending date
         retry_count : int, default 3
             Number of times to retry query request.
@@ -140,10 +140,11 @@ class TiingoDailyReader(_BaseReader):
     ----------
     symbols : {str, List[str]}
         String symbol of like of symbols
-    start : str, (defaults to '1/1/2010')
+    start : string, int, date, datetime, Timestamp
         Starting date, timestamp. Parses many different kind of date
-        representations (e.g., 'JAN-01-2010', '1/1/10', 'Jan, 1, 1980')
-    end : str, (defaults to today)
+        representations (e.g., 'JAN-01-2010', '1/1/10', 'Jan, 1, 1980').
+        Default is '1/1/2010'.
+    end : string, int, date, datetime, Timestamp
         Ending date, timestamp. Same format as starting date.
     retry_count : int, default 3
         Number of times to retry query request.
@@ -241,9 +242,9 @@ class TiingoMetaDataReader(TiingoDailyReader):
     ----------
     symbols : {str, List[str]}
         String symbol of like of symbols
-    start : str, (defaults to '1/1/2010')
+    start : string, int, date, datetime, Timestamp
         Not used.
-    end : str, (defaults to today)
+    end : string, int, date, datetime, Timestamp
         Not used.
     retry_count : int, default 3
         Number of times to retry query request.
@@ -299,9 +300,9 @@ class TiingoQuoteReader(TiingoDailyReader):
     ----------
     symbols : {str, List[str]}
         String symbol of like of symbols
-    start : str, (defaults to '1/1/2010')
+    start : string, int, date, datetime, Timestamp
         Not used.
-    end : str, (defaults to today)
+    end : string, int, date, datetime, Timestamp
         Not used.
     retry_count : int, default 3
         Number of times to retry query request.

pandas_datareader/tsp.py

@@ -12,11 +12,11 @@ class TSPReader(_BaseReader):
     symbols : str, array-like object (list, tuple, Series), or DataFrame
         Single stock symbol (ticker), array-like object of symbols or
         DataFrame with index containing stock symbols.
-    start : string, int, date, datetime, timestamp
+    start : string, int, date, datetime, Timestamp
         Starting date. Parses many different kind of date
         representations (e.g., 'JAN-01-2010', '1/1/10', 'Jan, 1, 1980'). Defaults to
         20 years before current date.
-    end : string, int, date, datetime, timestamp
+    end : string, int, date, datetime, Timestamp
         Ending date
     retry_count : int, default 3
         Number of times to retry query request.

pandas_datareader/wb.py

@@ -537,9 +537,9 @@ class WorldBankReader(_BaseReader):
         can be mixed.
         The two ISO lists of countries, provided by wikipedia, are hardcoded
         into pandas as of 11/10/2014.
-    start: Timestamp or int
+    start : string, int, date, datetime, Timestamp
         First year of the data series. Month and day are ignored.
-    end: Timestamp or int
+    end : string, int, date, datetime, Timestamp
         Last year of the data series (inclusive). Month and day are ignored.
     errors: str {'ignore', 'warn', 'raise'}, default 'warn'
         Country codes are validated against a hardcoded list.  This controls

pandas_datareader/yahoo/daily.py

@@ -22,11 +22,11 @@ class YahooDailyReader(_DailyBaseReader):
     symbols : string, array-like object (list, tuple, Series), or DataFrame
         Single stock symbol (ticker), array-like object of symbols or
         DataFrame with index containing stock symbols.
-    start : string, int, date, datetime, timestamp
+    start : string, int, date, datetime, Timestamp
         Starting date. Parses many different kind of date
         representations (e.g., 'JAN-01-2010', '1/1/10', 'Jan, 1, 1980'). Defaults to
         5 years before current date.
-    end : string, int, date, datetime, timestamp
+    end : string, int, date, datetime, Timestamp
         Ending date
     retry_count : int, default 3
         Number of times to retry query request.

pandas_datareader/yahoo/fx.py

@@ -18,11 +18,12 @@ class YahooFXReader(YahooDailyReader):
     symbols : string, array-like object (list, tuple, Series), or DataFrame
         Single stock symbol (ticker), array-like object of symbols or
         DataFrame with index containing stock symbols.
-    start : string, (defaults to '1/1/2010')
+    start : string, int, date, datetime, Timestamp
         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.
+        representations (e.g., 'JAN-01-2010', '1/1/10', 'Jan, 1, 1980').
+        Defaults to '1/1/2010'.
+    end : string, int, date, datetime, Timestamp
+        Ending date, timestamp. Same format as starting date. Defaults to today.
     retry_count : int, default 3
         Number of times to retry query request.
     pause : int, default 0.1