diff --git a/.gitignore b/.gitignore index 0f438e7..480dead 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,9 @@ "iexenv/" "stfpconfig.json" +.DS_Store +*.DS_Store + /.pytest_cache # Byte-compiled / optimized / DLL files __pycache__/ diff --git a/README.rst b/README.rst index 59eb613..3c8a71a 100644 --- a/README.rst +++ b/README.rst @@ -34,7 +34,7 @@ Forex/Currencies, Options, Commodities, Bonds, and Cryptocurrencies: Example ------- -.. image:: https://addisonlynch.github.io/public/img/iexexample.gif +.. image:: https://raw.githubusercontent.com/addisonlynch/iexfinance/master/docs/source/images/iexexample.gif Documentation @@ -63,8 +63,8 @@ From development repository (dev version): -Authentication --------------- +What's Needed to Access IEX Cloud? +---------------------------------- An IEX Cloud account is required to acecss the IEX Cloud API. Various `plans `__ are availalbe, free, paid, and pay-as-you-go. @@ -82,7 +82,7 @@ The authentication token can also be passed to any function call: from iexfinance.refdata import get_symbols - get_symbols(output_format='pandas', token="") + get_symbols(token="") or at the instantiation of a ``Stock`` object: @@ -90,7 +90,7 @@ or at the instantiation of a ``Stock`` object: from iexfinance.stocks import Stock - a = Stock("AAPL", token="") + a = Stock("AAPL", token="") a.get_quote() @@ -136,40 +136,6 @@ group, obtain the `Social Sentiment `__ ``DataFrame`` output -formatting is available for most endpoints. - -pandas ``DataFrame`` output formatting can be selected by setting the -``IEX_OUTPUT_FORMAT`` environment variable to ``pandas`` or by passing -``output_format`` as an argument to any function call (or at the instantiation -of a ``Stock`` object). - Common Usage Examples --------------------- @@ -387,6 +353,64 @@ API Status get_api_status() + +Configuration +------------- +.. _config.formatting: + +Output Formatting +----------------- + +By default, ``iexfinance`` returns data for most endpoints in a `pandas `__ ``DataFrame``. + +Selecting ``json`` as the output format returns data formatted *exactly* as received from +the IEX Endpoint. Configuring ``iexfinance``'s output format can be done in two ways: + +.. _config.formatting.env: + +Environment Variable (Recommended) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For persistent configuration of a specified output format, use the environment +variable ``IEX_OUTPUT_FORMAT``. This value will be overridden by the +``output_format`` argument if it is passed. + +macOS/Linux +^^^^^^^^^^^ + +Type the following command into your terminal: + +.. code-block:: bash + + $ export IEX_OUTPUT_FORMAT=pandas + +Windows +^^^^^^^ + +See `here `__ for instructions on setting environment variables in Windows operating systems. + +.. _config.formatting.arg: + +``output_format`` Argument +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Pass ``output_format`` as an argument to any function call: + +.. code-block:: python + + from iexfinance.refdata import get_symbols + + get_symbols(output_format='pandas').head() + +or at the instantiation of a ``Stock`` object: + +.. code-block:: python + + from iexfinance.stocks import Stock + + aapl = Stock("AAPL", output_format='pandas') + aapl.get_quote().head() + Contact ------- diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 3e7d975..cdf6ca5 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -8,40 +8,51 @@ There are four core components of ``iexfinance``'s configuration: * :ref:`config.auth` - setting your IEX Cloud Authentication Token * :ref:`config.formatting` - configuring desired output format (mirror IEX output or Pandas DataFrame) -* :ref:`config.api_version` - specifying version of IEX Cloud to use +* :ref:`config.api-version` - specifying version of IEX Cloud to use * :ref:`config.debugging` - cached sessions, request retries, and more -.. _config.api_version: +.. _config.auth: -API Version ------------ +Authentication +-------------- -The desired IEX API version can be specified using the ``IEX_API_VERSION`` -environment variable. The following versions are currently supported: +An IEX Cloud account and authentication token are required to acecss the IEX Cloud API. The IEX Cloud token is accessible via the IEX Cloud Console. -* ``stable`` - **default** -* ``beta`` -* ``v1`` -* ``latest`` -* ``sandbox`` *for testing purposes* +.. seealso:: For more information about signing up for an IEX Cloud account, see the pricing_ section of the IEX Cloud website. -.. seealso:: For more information on API versioning, see the IEX Cloud - documentation_. +.. _pricing: https://iexcloud.io/pricing -.. _documentation: https://iexcloud.io/docs/api/#versioning +Your IEX Cloud (secret) authentication token can be be stored in the ``IEX_TOKEN`` environment variable. It can also be passed to any function or at the instantiation of a ``Stock`` :ref:`object `. +Instructions for both authentication methods are below. -.. _config.auth: +.. _config.auth.env: -Authentication --------------- +Environment Variable (Recommended) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -An IEX Cloud account and authentication token are required to acecss the IEX Cloud API. +The easiest (and recommended) way to authenticate your IEX Cloud account is by +storing your authentication token (secret key beginning with ``sk_``) in the +``IEX_TOKEN`` environment variable. -Your IEX Cloud (secret) authentication token can be passed to any function or at the instantiation of a ``Stock`` :ref:`object `. -It can also be stored in the ``IEX_TOKEN`` environment variable. +.. _config.auth.env.unix: + +macOS/Linux +^^^^^^^^^^^ + +Type the following command into your terminal: + +.. code-block:: bash + + $ export IEX_TOKEN= + +.. _config.auth.env.windows: + +Windows +^^^^^^^ + +See `here `__ for instructions on setting environment variables in Windows operating systems. -The IEX Cloud token is accessible via the IEX Cloud Console. .. _config.auth.argument: @@ -66,16 +77,26 @@ or at the instantiation of a ``Stock`` object: a = Stock("AAPL", token="") a.get_quote() -.. _config.auth.env: +Where ```` is your IEX Cloud authentication token. + +.. _config.formatting: + +Output Formatting +----------------- + +By default, ``iexfinance`` returns data for most endpoints in a `pandas `__ ``DataFrame``. + +Selecting ``json`` as the output format returns data formatted *exactly* as received from +the IEX Endpoint. Configuring ``iexfinance``'s output format can be done in two ways: + +.. _config.formatting.env: Environment Variable (Recommended) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The easiest (and recommended) way to authenticate your IEX Cloud account is by -storing your authentication token (secret key beginning with ``sk_``) in the -``IEX_TOKEN`` environment variable. - -.. _config.auth.env.unix: +For persistent configuration of a specified output format, use the environment +variable ``IEX_OUTPUT_FORMAT``. This value will be overridden by the +``output_format`` argument if it is passed. macOS/Linux ^^^^^^^^^^^ @@ -84,24 +105,14 @@ Type the following command into your terminal: .. code-block:: bash - $ export IEX_TOKEN= - -.. _config.auth.env.windows: + $ export IEX_OUTPUT_FORMAT=pandas Windows ^^^^^^^ See `here `__ for instructions on setting environment variables in Windows operating systems. -.. _config.formatting: - -Output Formatting ------------------ - -By default, ``iexfinance`` returns data for most endpoints in a `pandas `__ ``DataFrame``. - -Selecting ``json`` as the output format returns data formatted *exactly* as received from -the IEX Endpoint. Configuring ``iexfinance``'s output format can be done in two ways: +.. _config.formatting.arg: ``output_format`` Argument ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -123,26 +134,25 @@ or at the instantiation of a ``Stock`` object: aapl = Stock("AAPL", output_format='pandas') aapl.get_quote().head() -Environment Variable -~~~~~~~~~~~~~~~~~~~~ +.. _config.api-version: -For persistent configuration of a specified output format, use the environment -variable ``IEX_OUTPUT_FORMAT``. This value will be overridden by the -``output_format`` argument if it is passed. - -macOS/Linux -^^^^^^^^^^^ +API Version +----------- -Type the following command into your terminal: +The desired IEX API version can be specified using the ``IEX_API_VERSION`` +environment variable. The following versions are currently supported: -.. code-block:: bash +* ``stable`` - **default** +* ``beta`` +* ``v1`` +* ``latest`` +* ``sandbox`` *for testing purposes* - $ export IEX_OUTPUT_FORMAT=pandas +.. seealso:: For more information on API versioning, see the IEX Cloud + documentation_. -Windows -^^^^^^^ +.. _documentation: https://iexcloud.io/docs/api/#versioning -See `here `__ for instructions on setting environment variables in Windows operating systems. .. _config.debugging: diff --git a/docs/source/images/iexexample.gif b/docs/source/images/iexexample.gif new file mode 100644 index 0000000..0a45640 Binary files /dev/null and b/docs/source/images/iexexample.gif differ diff --git a/docs/source/index.rst b/docs/source/index.rst index 37f73c0..272f9cf 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -7,6 +7,8 @@ Welcome to iexfinance's documentation! - :ref:`endpoints` - (mostly) 1:1 mirror of the `IEX Cloud documentation `__ - :ref:`package_info` - additional package information, developer/testing documentation +.. note:: iexfinance is now a pandas-driven library. The default output format is now a pandas ``DataFrame``. + .. warning:: Support for Python 2 has ended as of ``iexfinance`` version 0.5.0. .. _account: https://iexcloud.io/pricing/ @@ -20,11 +22,11 @@ Full Contents :maxdepth: 1 :caption: Getting Started + usage whatsnew install configuration sandbox - usage .. _endpoints: diff --git a/docs/source/install.rst b/docs/source/install.rst index 96ef971..58e8b50 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -1,8 +1,8 @@ .. _install: -Install -======= +Installation +============ Dependencies ------------ diff --git a/docs/source/sandbox.rst b/docs/source/sandbox.rst index a371ba6..65177a9 100644 --- a/docs/source/sandbox.rst +++ b/docs/source/sandbox.rst @@ -9,3 +9,5 @@ accessed by setting ``IEX_API_VERSION`` to ``iexcloud-sandbox``. This will set ` .. note:: Test keys (beginning with ``Tsk`` and ``Tpk``) must be used with the sandbox environment. To obtain these keys, select the "Viewing test data" toggler on the left side of the IEX Cloud console. .. _`sandbox environment`: https://iexcloud.io/docs/api/#sandbox + +The sandbox environment is recommended for testing purposes. Messages used in the sandbox environment will not count against a user's monthly message limit. \ No newline at end of file diff --git a/docs/source/testing.rst b/docs/source/testing.rst index 67b68aa..d2aa20f 100644 --- a/docs/source/testing.rst +++ b/docs/source/testing.rst @@ -24,6 +24,7 @@ All testing dependencies can be installed via ``pip install -r requirements-dev. - codecov - flake8 - flake8-bugbear +- flake8-rst - pytest - pytest-runner - tox @@ -32,7 +33,6 @@ All documentation dependencies can be installed via ``pip install -r docs/requir **Docs** -- flake8-rst - ipython - matplotlib - requests-cache