rls 0.3.5 (#88)

* Upped version to 0.3.5

* Repair unraised exception with bad ticker historical data

* Add historical intraday, clean for release

* Update depr warning

* DOC: Reconcile moved functions

CHANGELOG.md

@@ -1,3 +1,3 @@
 # Changelog
 
-See [here](https://addisonlynch.github.io/whatsnew.html).
+See [here](https://addisonlynch.github.io/stable/whatsnew.html).

README.rst

@@ -14,21 +14,26 @@ iexfinance
     :target: https://opensource.org/licenses/Apache-2.0
 
 
-Python module to retrieve stock data from the
+Python wrapper around the
 `Investors Exchange (IEX) <https://iextrading.com/>`__
-`Developer API <https://iextrading.com/developer/>`__
-platform. iexfinance provides real-time financial data from the various IEX
-endpoints, including:
+`Developer API <https://iextrading.com/developer/>`__.
 
+An easy-to-use interface to obtain:
 
+- Real-time quotes
+- Historical data
+- Fundamentals,
+- Actions (dividends, splits), Sector Performance
+- Trading analyses (gainers, losers, etc.)
+- IEX Market Data & Stats
 
-This data includes stock quotes, fundamentals, actions, and information. In
-addition, support for IEX market data and statistics is provided.
+iexfinance provides real-time financial data from the various IEX
+endpoints, including:
 
-- `Stocks <https://iextrading.com/developer/docs/#stocks>`__
-- `Reference Data <https://iextrading.com/developer/docs/#reference-data>`__
-- `IEX Market Data <https://iextrading.com/developer/docs/#iex-market-data>`__
-- `IEX Stats <https://iextrading.com/developer/docs/#iex-stats>`__
+- Stocks (`IEX Docs <https://iextrading.com/developer/docs/#stocks>`__)
+- Reference Data (`IEX Docs <https://iextrading.com/developer/docs/#reference-data>`__)
+- IEX Market Data (`IEX Docs <https://iextrading.com/developer/docs/#iex-market-data>`__)
+- IEX Stats (`IEX Docs <https://iextrading.com/developer/docs/#iex-stats>`__)
 
 Documentation
 -------------
@@ -52,60 +57,126 @@ From development repository (dev version):
      $ cd iexfinance
      $ python3 setup.py install
 
-Usage Examples
---------------
+Common Usage Examples
+---------------------
 
-The `iex-examples <https://github.com/addisonlynch/iex-examples>`__ repository provides a number of detailed examples of ``iexfinance`` usage. Basic examples are also provided below.
+The `iex-examples <https://github.com/addisonlynch/iex-examples>`__ repository provides a number of detailed examples of iexfinance usage. Basic examples are also provided below.
 
 Using iexfinance to access data from IEX is quite easy. The most commonly-used
 endpoints are the `Stocks <https://iextrading.com/developer/docs/#stocks>`__
 endpoints, which allow access to various information regarding equities,
 including quotes, historical prices, dividends, and much more.
 
-All top-level functions (such as ``Stock`` and ``get_historical_data``)
+Real-time Quotes
+^^^^^^^^^^^^^^^^
 
-Stock Endpoints
-^^^^^^^^^^^^^^^
+To obtain real-time quotes for one or more symbols, use the ``get_price``
+method of the ``Stock`` object:
 
 .. code:: python
 
-    from iexfinance import Stock
+    from iexfinance.stocks import Stock
     tsla = Stock('TSLA')
-    tsla.get_open()
     tsla.get_price()
 
-It's also possible to obtain historical data from the ``get_historical_data``
-top-level function. This will return a daily time-series of the ticker
-requested over the desired date range (``start`` and ``end`` passed as
-``datetime.datetime`` objects).
+or for multiple symbols, use a list or list-like object (Tuple, Pandas Series,
+etc.):
 
-Pandas DataFrame and JSON (dict) output formatting are selected with the
-``output_format`` parameter.
+.. code:: python
+
+    batch = Stock(["TSLA", "AAPL"])
+    batch.get_price()
+
+
+Historical Data
+^^^^^^^^^^^^^^^
+
+It's possible to obtain historical data the ``get_historical_data`` and
+``get_historical_intraday``.
 
-**Historical Data**
+Daily
+~~~~~
+
+To obtain daily historical price data for one or more symbols, use the
+``get_historical_data`` function. This will return a daily time-series of the ticker
+requested over the desired date range (``start`` and ``end`` passed as
+``datetime.datetime`` objects):
 
 .. code:: python
 
-	from iexfinance import get_historical_data
-	from datetime import datetime
+    from datetime import datetime
+    from iexfinance.stocks import get_historical_data
+
+    start = datetime(2017, 1, 1)
+    end = datetime(2018, 1, 1)
 
-	start = datetime(2017, 2, 9)
-	end = datetime(2017, 5, 24)
+    df = get_historical_data("TSLA", start, end)
 
-	df = get_historical_data("AAPL", start=start, end=end, output_format='pandas')
-	df.head()
 
-The resulting DataFrame will indexed by date, with a column for each OHLC
-datapoint.
+For Pandas DataFrame output formatting, pass ``output_format``:
+
+.. code:: python
+
+    df = get_historical_data("TSLA", start, end, output_format='pandas')
 
 It's really simple to plot this data, using `matplotlib <https://matplotlib.org/>`__:
 
 .. code:: python
 
-	import matplotlib.pyplot as plt
+    import matplotlib.pyplot as plt
+
+    df.plot()
+    plt.show()
+
+
+Minutely (Intraday)
+~~~~~~~~~~~~~~~~~~~
+
+To obtain historical intraday data, use ``get_historical_intraday`` as follows.
+Pass an optional ``date`` to specify a date within three months prior to the
+current day (default is current date):
+
+.. code:: python
+
+    from datetime import datetime
+    from iexfinance.stocks import get_historical_intraday
+
+    date = datetime(2018, 11, 27)
+
+    get_historical_intraday("AAPL", date)
+
+or for a Pandas Dataframe indexed by each minute:
+
+.. code:: python
+
+    get_historical_intraday("AAPL", output_format='pandas')
+
+
+Endpoints
+---------
+
+Stock Endpoints
+^^^^^^^^^^^^^^^
+
+The ``Stock`` function creates a ``StockReader`` instance which has a method to
+retrieve each of the Stocks endpoints (``get_quote``, ``get_book``,
+``get_volume_by_venue``, etc.):
+
+.. code:: python
+
+    from iexfinance.stocks import Stock
+    tsla = Stock('TSLA')
+    tsla.get_open()
+    tsla.get_price()
+
+Pandas DataFrame and JSON (dict) output formatting are selected with the
+``output_format`` parameter when calling ``Stock``.
+
+.. code:: python
+
+    tsla = Stock("TSLA", output_format='pandas')
+    tsla.get_quote()
 
-	df.plot()
-	plt.show()
 
 IEX Reference Data
 ^^^^^^^^^^^^^^^^^^
@@ -140,7 +211,6 @@ and ``get_market_deep``.
 	get_market_tops()
 
 
-
 IEX Stats
 ^^^^^^^^^
 
@@ -165,7 +235,7 @@ for `Request Parameters <https://addisonlynch.github.io/usage.html#parameters>`_
 include ``retry_count``, ``pause``, and ``session``. These parameters are
 entirely optional. The first two deal with how unsuccessful requests are
 handled, and the third allows for the passing of a cached ``requests-cache``
-session (see `caching <https://addisonlynch.github.io/iexfinance/caching.html>`__).
+session (see `caching <https://addisonlynch.github.io/iexfinance/stable/caching.html>`__).
 
 Contact
 -------

docs/source/caching.rst

@@ -22,7 +22,7 @@ top-level function you are using:
 .. ipython:: python
 
     import datetime
-    from iexfinance import Stock
+    from iexfinance.stocks import Stock
     import requests_cache
 
     expiry = datetime.timedelta(days=3)

docs/source/conf.py

@@ -58,9 +58,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.3.4'
+version = '0.3.5'
 # The full version, including alpha/beta/rc tags.
-release = '0.3.4'
+release = '0.3.5'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/historical.rst

@@ -1,25 +1,35 @@
 .. _historical:
 
-.. currentmodule:: iexfinance
+.. currentmodule:: iexfinance.stocks
 
 
 Historical Data
 ===============
 
-Historical time series data is available through the top-level
-``get_historical_data`` method, which sources the
+Historical time series data is available through the
+``get_historical_data`` and ``get_historical_intraday`` functions of
+``stocks``, which
+source the
 `chart <https://iextrading.com/developer/docs/#chart>`__ endpoint.
 
-.. autofunction:: get_historical_data
-
-Data can be retrieved from up to 5 years before the current date.
+Daily data can be retrieved from up to 5 years before the current date, and
+historical data up to 3 months prior to the current date.
 
 Usage
 -----
 
+Daily
+^^^^^
+
+To obtain daily historical data, use ``get_historical_data``.
+
+.. autofunction:: get_historical_data
+
+
 If no date parameters are passed, the start date will default to 2015/1/1
 and the end date will default to the current date.
 
+
 .. ipython:: python
     :okwarning:
 
@@ -32,6 +42,27 @@ and the end date will default to the current date.
     f = get_historical_data('AAPL', start, end, output_format='pandas')
     f.loc["2017-02-09"]
 
+
+Minutely
+^^^^^^^^
+
+To obtain one-minute intraday data for a given date, use
+``get_historical_intraday``. **Note: this endpoint has a maximum of one symbol
+and a single date.**
+
+.. autofunction:: get_historical_intraday
+
+.. ipython:: python
+
+    from datetime import datetime
+    from iexfinance.stocks import get_historical_intraday
+
+    date = datetime(2018, 11, 27)
+
+    data = get_historical_intraday("AAPL", date, output_format='pandas')
+    data.head()
+
+
 Plotting
 --------
 

docs/source/stocks.rst

@@ -36,13 +36,11 @@ additional parameters (it uses the defaults) and does not allow Pandas DataFrame
 
 .. ipython:: python
 
-    from iexfinance import Stock
+    from iexfinance.stocks import Stock
     aapl = Stock("aapl")
     aapl.get_price()
 
 
-.. autoclass:: iexfinance.stocks.base.StockReader
-
 
 Formatting
 ----------
@@ -73,7 +71,7 @@ passing
 
 .. ipython:: python
 
-    from iexfinance import Stock
+    from iexfinance.stocks import Stock
     aapl = Stock("aapl", output_format='pandas')
     aapl.get_quote().head()
 
@@ -387,7 +385,7 @@ A single symbol request will return data *exactly* as it appears in the IEX docs
 
 .. ipython:: python
 
-    from iexfinance import Stock
+    from iexfinance.stocks import Stock
     aapl = Stock("AAPL")
     aapl.get_price()
 
@@ -402,7 +400,7 @@ Most endpoints can be formatted as a `pandas.DataFrame`. Multi-symbol requests w
 
 .. ipython:: python
 
-    from iexfinance import Stock as iex
+    from iexfinance.stocks import Stock as iex
     air_transport = Stock(['AAL', 'DAL', 'LUV'], output_format='pandas')
     air_transport.get_quote().head()
 
@@ -420,7 +418,7 @@ reserved word in Python:
 
 .. ipython:: python
 
-    from iexfinance import Stock as iex
+    from iexfinance.stocks import Stock as iex
     aapl = Stock("AAPL", output_format='pandas')
     aapl.get_quote(filter_='ytdChange')