# Python interface to stock quotes providers
`stockdata77` provides the `Stocks` class which facilitates interfacing with real-time information providers of securities trading data. Currently it supports APIs of Financial Modeling Prep, Alpha Vantage, Yahoo Finance and MOEX. Please note that FMP and AV providers will require an API key. It is designed primarily to be used with stock and ETF symbols, though FMP will also provide FOREX data.
## Usage summary
`Stocks` class creates and maintains a dictionary of traded securities quotes. Currently supported API providers are Yahoo Finance API and MOEX. Stored values are the current price and the change to previous close. The price is stored in the currency of the security for a nominal of 1. The change is stored as a fraction of the price, i.e. a change of 2% will be stored as 0.02.
Use `append(ticker, api)` method to fill it with individual stock quotes.
Once you have all the quotes you need, you can use `Stocks[key]` to obtain trading data as a list of values. Alternatively, call individual `getXXXXXX()` methods to obtain various components of the list. Prior to calling any of these you can use the `in` operator to check if a `key` has a corresponding record.
The `key` is composed out of the stock ticker and the name of the API provider. `makeKey(ticker, api)` will
get you the `key`. Or you can simply store the value returned by `append()` or `update()`. Use `splitKey()` to reverse `makeKey()`.
The instances of the `Stocks` class are iterable. Trying this code
import stockdata77
stocks = Stocks()
stocks.append("AAPL")
stocks.append("U")
for entry in stocks:
print(entry)
will print tuples of `(key, [name, price, change])` like this:
('AAPL:YF', ['Apple Inc.', 155.74, 0.0755525])
('U:YF', ['Unity Software Inc.', 29.23, 0.048421822])
Attempting to cast the whole instance to `str` type will get you a formatted table with the current quotes. For instance appending
print(stocks)
to the example above will get you this:
TICKER NAME PRICE CHANGE
----------- ------------------- -------- ---------
AAPL:YF Apple Inc. 155.74 7.56%
U:YF Unity Software ... 29.23 4.84%
Use `maintain(interval)` to fork a thread that updates the quotes at the given intervals in seconds. Invoking `desist()` will stop the updates. See the included `sample_cli.py` script for an example.
## `Stocks` class methods
> `Stocks` class does not expose any fields. Use the methods described below to obtain the necessary. In addition to these you can iterate through an instance of `Stocks`, read individual records by indexing it with a `key` (see `append()` for the explanation of keys), and cast it to `str` type which returns a table with full stored data.
`append(ticker:str, api:str, api_key:str = "", forceUpdate = False)` - appends the internal dictionary with the current trading data for the `ticker`. It must be a valid symbol like "AAPL", `api` must be one of "FMP, "AV", "YF" or "MOEX". The information is appended only in case the internal dictionary does not yet have an entry with the same key. Otherwise, it is neither appended nor updated, which allows
skipping the web API calls. To force the update set `forceUpdate` to `True`. It is mandatory to provide `api_key` if either "FMP" or "AV" is used.
It is the recommended way to fill up the `Stocks` instance initially. The tickers in this case can come from a source that might contain duplicates. Skiping the web API calls for duplicate tickers will optimise your code for speed and minimise the impact on the API providers.
The returned value is the `key` to the the internal dictionary for the record of this ticker/api pair. If the returned `key` is not stored in the calling code it can be constructed again by calling the `makeKey()` menthod. If either the supplied `ticker` or the `api` names are invalid, `append()` returns `None`.
`update(ticker:str, api:str, api_key:str = "")` - same as `append()` but with `forceUpdate` set to `True`.
`remove(ticker:str, api:str)` - removes the quote for the `ticker`. `ticker` and `api` are the same as when calling `append()`. If there is no entry for the ticker/api pair in the internal database, `remove()` returns silently.
`maintain(interval:int)` - start updating stock quotes at regular intervals (in seconds). This method forks a thread that keeps calling the relevant APIs and updating the internal dictionary with new data. Use `desist()` to stop.
`desist()` - stop updating stock quotes.
`makeKey(ticker:str, api:str)` - makes a `key` used in the internal dictionary maintained by `Stocks` to address the trading data records. Returns a `str` value of the `key`.
`splitKey(key:str)` - reverses `makeKey()` and returns a tuple of `(ticker, api)`.
`getCompanyName(key:str)` - obtains a long company name for the ticker used to make the `key`.
`getPrice(key:str)` - obtains a `float` value of the current price for the ticker used to make the `key`.
`getPriceChng(key:str)` - obtains a `float` value of the current price change from previous close for the ticker used to make the `key`.
## Final notes
### Usage scenarios
> Note: As of October 2023 Yahoo Finance provider was not operational. The examples below use "YF" simply to avoid using `api_key` paramater.
There are at least two scenarios the `Stocks` class was designed for.
#### Static
Add quotes with `append()` and then use them without updating. Sample code:
import stockdata77
stocks = Stocks()
key = stocks.append("AAPL", "YF")
print("Stock quote for AAPL")
print("Name = " + stocks.getCompanyName(key))
print("Price = {0:.2f}".format(stocks.getPrice(key)))
print("Change = {0:.2f}%".format(stocks.getPriceChng(key)*100))
#### Dynamic
Add quotes with `append()` and then keep them alive to use in some dymnamic way like plotting real-time price graphs or directing business logic. Sample code:
from time import sleep
from stockdata77 import Stocks
stocks = Stocks()
stocks.append("AAPL", "YF")
stocks.append("U", "YF")
stocks.append("MSFT", "YF")
stocks.maintain(2) # start updating the quotes at 2 second intervals
for i in range(4):
sleep(2) # wait for updates
if i == 2: # replace a symbol at some point for some reason
stocks.remove("U", "YF")
stocks.append("GOOGL", "YF")
print(stocks) # display updated quotes
stocks.desist() # stop updating the quotes
### Thread safety
> `Stocks` class _iterator is not thread-safe_.
Avoid iterating through an instance of `Stocks` class in more than one thread at a time. Use [barrier objects](https://docs.python.org/3/library/threading.html?highlight=barriers#barrier-objects) or other means of resource mutual exclusion to contol this in your code.
The methods of the `Stocks` class itself do not use the implemented iterator. For instance, `maintain()` or `__str__()` methods though iterating through the records in the internal dictionary, use other means for this. You can use these methods (almost) safely in your multi-threaded applications as long as you avoid `remove()`-ing. If you need to `remove()` a quote while `maintain()`-ing, call `desist()` first to pause the updates, then call `remove()` and invoke `maintain()` again.
Raw data
{
"_id": null,
"home_page": "",
"name": "stockdata77",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "AV,Alpha Vantage,FMP,MOEX,NYSE,Nasdaq,Yahoo Finance,stocks,trading",
"author": "",
"author_email": "Dandelion Systems <dandelion.systems@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/0e/58/e274bb86b894e7d9ba1dc65ab7e01754e923b6fa3c2f7ea20f3ec5ffc6bb/stockdata77-0.0.2.tar.gz",
"platform": null,
"description": "# Python interface to stock quotes providers\n\n`stockdata77` provides the `Stocks` class which facilitates interfacing with real-time information providers of securities trading data. Currently it supports APIs of Financial Modeling Prep, Alpha Vantage, Yahoo Finance and MOEX. Please note that FMP and AV providers will require an API key. It is designed primarily to be used with stock and ETF symbols, though FMP will also provide FOREX data.\n\n## Usage summary\n\n`Stocks` class creates and maintains a dictionary of traded securities quotes. Currently supported API providers are Yahoo Finance API and MOEX. Stored values are the current price and the change to previous close. The price is stored in the currency of the security for a nominal of 1. The change is stored as a fraction of the price, i.e. a change of 2% will be stored as 0.02.\n\nUse `append(ticker, api)` method to fill it with individual stock quotes. \n\nOnce you have all the quotes you need, you can use `Stocks[key]` to obtain trading data as a list of values. Alternatively, call individual `getXXXXXX()` methods to obtain various components of the list. Prior to calling any of these you can use the `in` operator to check if a `key` has a corresponding record.\n\nThe `key` is composed out of the stock ticker and the name of the API provider. `makeKey(ticker, api)` will \nget you the `key`. Or you can simply store the value returned by `append()` or `update()`. Use `splitKey()` to reverse `makeKey()`.\n\nThe instances of the `Stocks` class are iterable. Trying this code\n\n\timport stockdata77\n\n\tstocks = Stocks()\n\tstocks.append(\"AAPL\")\n\tstocks.append(\"U\")\n\tfor entry in stocks:\n\t\tprint(entry)\n\nwill print tuples of `(key, [name, price, change])` like this:\n\n\t('AAPL:YF', ['Apple Inc.', 155.74, 0.0755525])\n\t('U:YF', ['Unity Software Inc.', 29.23, 0.048421822])\n\nAttempting to cast the whole instance to `str` type will get you a formatted table with the current quotes. For instance appending \n\n\tprint(stocks)\n\nto the example above will get you this:\n\n\tTICKER NAME PRICE CHANGE \n\t----------- ------------------- -------- ---------\n\tAAPL:YF Apple Inc. 155.74 7.56%\n\tU:YF Unity Software ... 29.23 4.84%\n\nUse `maintain(interval)` to fork a thread that updates the quotes at the given intervals in seconds. Invoking `desist()` will stop the updates. See the included `sample_cli.py` script for an example.\n\n## `Stocks` class methods\n\n> `Stocks` class does not expose any fields. Use the methods described below to obtain the necessary. In addition to these you can iterate through an instance of `Stocks`, read individual records by indexing it with a `key` (see `append()` for the explanation of keys), and cast it to `str` type which returns a table with full stored data.\n\n`append(ticker:str, api:str, api_key:str = \"\", forceUpdate = False)` - appends the internal dictionary with the current trading data for the `ticker`. It must be a valid symbol like \"AAPL\", `api` must be one of \"FMP, \"AV\", \"YF\" or \"MOEX\". The information is appended only in case the internal dictionary does not yet have an entry with the same key. Otherwise, it is neither appended nor updated, which allows \nskipping the web API calls. To force the update set `forceUpdate` to `True`. It is mandatory to provide `api_key` if either \"FMP\" or \"AV\" is used.\n\nIt is the recommended way to fill up the `Stocks` instance initially. The tickers in this case can come from a source that might contain duplicates. Skiping the web API calls for duplicate tickers will optimise your code for speed and minimise the impact on the API providers.\n\nThe returned value is the `key` to the the internal dictionary for the record of this ticker/api pair. If the returned `key` is not stored in the calling code it can be constructed again by calling the `makeKey()` menthod. If either the supplied `ticker` or the `api` names are invalid, `append()` returns `None`.\n\n`update(ticker:str, api:str, api_key:str = \"\")` - same as `append()` but with `forceUpdate` set to `True`.\n\n`remove(ticker:str, api:str)` - removes the quote for the `ticker`. `ticker` and `api` are the same as when calling `append()`. If there is no entry for the ticker/api pair in the internal database, `remove()` returns silently.\n\n`maintain(interval:int)` - start updating stock quotes at regular intervals (in seconds). This method forks a thread that keeps calling the relevant APIs and updating the internal dictionary with new data. Use `desist()` to stop.\n\n`desist()` - stop updating stock quotes.\n\n`makeKey(ticker:str, api:str)` - makes a `key` used in the internal dictionary maintained by `Stocks` to address the trading data records. Returns a `str` value of the `key`.\n\n`splitKey(key:str)` - reverses `makeKey()` and returns a tuple of `(ticker, api)`.\n\n`getCompanyName(key:str)` - obtains a long company name for the ticker used to make the `key`.\n\n`getPrice(key:str)` - obtains a `float` value of the current price for the ticker used to make the `key`.\n\n`getPriceChng(key:str)` - obtains a `float` value of the current price change from previous close for the ticker used to make the `key`.\n\n## Final notes\n\n### Usage scenarios\n\n> Note: As of October 2023 Yahoo Finance provider was not operational. The examples below use \"YF\" simply to avoid using `api_key` paramater.\n\nThere are at least two scenarios the `Stocks` class was designed for.\n\n#### Static\nAdd quotes with `append()` and then use them without updating. Sample code:\n\t\n\timport stockdata77\n\n\tstocks = Stocks()\n\tkey = stocks.append(\"AAPL\", \"YF\")\n\t\n\tprint(\"Stock quote for AAPL\")\n\tprint(\"Name = \" + stocks.getCompanyName(key))\n\tprint(\"Price = {0:.2f}\".format(stocks.getPrice(key)))\n\tprint(\"Change = {0:.2f}%\".format(stocks.getPriceChng(key)*100))\n\n#### Dynamic\nAdd quotes with `append()` and then keep them alive to use in some dymnamic way like plotting real-time price graphs or directing business logic. Sample code:\n\n\tfrom time import sleep\n\tfrom stockdata77 import Stocks\n\n\tstocks = Stocks()\n\tstocks.append(\"AAPL\", \"YF\")\n\tstocks.append(\"U\", \"YF\")\n\tstocks.append(\"MSFT\", \"YF\")\n\n\tstocks.maintain(2) # start updating the quotes at 2 second intervals\n\n\tfor i in range(4):\n\t\tsleep(2) # wait for updates\n\t\tif i == 2: # replace a symbol at some point for some reason\n\t\t\tstocks.remove(\"U\", \"YF\")\n\t\t\tstocks.append(\"GOOGL\", \"YF\")\n\t\tprint(stocks) # display updated quotes\n\n\tstocks.desist() # stop updating the quotes\n\n### Thread safety\n\n> `Stocks` class _iterator is not thread-safe_.\n\nAvoid iterating through an instance of `Stocks` class in more than one thread at a time. Use [barrier objects](https://docs.python.org/3/library/threading.html?highlight=barriers#barrier-objects) or other means of resource mutual exclusion to contol this in your code.\n\nThe methods of the `Stocks` class itself do not use the implemented iterator. For instance, `maintain()` or `__str__()` methods though iterating through the records in the internal dictionary, use other means for this. You can use these methods (almost) safely in your multi-threaded applications as long as you avoid `remove()`-ing. If you need to `remove()` a quote while `maintain()`-ing, call `desist()` first to pause the updates, then call `remove()` and invoke `maintain()` again.\n",
"bugtrack_url": null,
"license": "",
"summary": "Interface to providers of securities trading data",
"version": "0.0.2",
"project_urls": {
"Bug Tracker": "https://github.com/dandelion-systems/stockdata77/issues",
"Homepage": "https://github.com/dandelion-systems/stockdata77"
},
"split_keywords": [
"av",
"alpha vantage",
"fmp",
"moex",
"nyse",
"nasdaq",
"yahoo finance",
"stocks",
"trading"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7a22ff83dca1da6071ea3be9c304c8b6f10c39da8fe93bb8a5d64a2fb428c0fc",
"md5": "5d27a667234c59c708fb1ae3e38d5db3",
"sha256": "36d98302c751a1cffaa50728d2edd3db76bcb0bedc21acd1b9be4233f69a2d6b"
},
"downloads": -1,
"filename": "stockdata77-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5d27a667234c59c708fb1ae3e38d5db3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 20224,
"upload_time": "2023-11-01T09:18:56",
"upload_time_iso_8601": "2023-11-01T09:18:56.909391Z",
"url": "https://files.pythonhosted.org/packages/7a/22/ff83dca1da6071ea3be9c304c8b6f10c39da8fe93bb8a5d64a2fb428c0fc/stockdata77-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0e58e274bb86b894e7d9ba1dc65ab7e01754e923b6fa3c2f7ea20f3ec5ffc6bb",
"md5": "3e95ba2f34210a4d5f1577df2af802c5",
"sha256": "5114b261b3e796e8736591894163a5ff4b0325a092fed3cee8dfe65b0935ec7d"
},
"downloads": -1,
"filename": "stockdata77-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "3e95ba2f34210a4d5f1577df2af802c5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 19434,
"upload_time": "2023-11-01T09:18:58",
"upload_time_iso_8601": "2023-11-01T09:18:58.807851Z",
"url": "https://files.pythonhosted.org/packages/0e/58/e274bb86b894e7d9ba1dc65ab7e01754e923b6fa3c2f7ea20f3ec5ffc6bb/stockdata77-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-01 09:18:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dandelion-systems",
"github_project": "stockdata77",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "stockdata77"
}
JSON
