What would have been the best stocks to invest in for a given period?
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


What If Stocks

Based on a start and end period, and a pool of stocks and historical prices, calculates what would have been the best stocks to invest in for the given period.

Here's a demo of the app in action.


First, set your site's secret key as an environment variable. For example, add the following to .bashrc or .bash_profile:

export WHATIFSTOCKS_SECRET='something-really-secret'

Before running shell commands, set the FLASK_APP and FLASK_DEBUG environment variables:

export FLASK_APP=/path/to/autoapp.py
export FLASK_DEBUG=1

Then run the following commands to bootstrap your environment:

git clone user@server.here:/path/to/whatifstocks
cd whatifstocks
pip install -r requirements/dev.txt
flask run

You will see a pretty welcome screen.

DB config and migrations

You must specify the DB credentials before starting the site in normal mode:

export WHATIFSTOCKS_DATABASE_URI="postgresql://whatifstocks:whatifstocks@localhost:5432/whatifstocks"

This is for getting started with migrations (shouldn't need to ever run it, initial migrations are included in the codebase):

flask db init

Each time you need to create a new migration script, run the following:

flask db migrate

Run the following to create or upgrade the DB schema:

flask db upgrade

For a full migration command reference, run flask db --help.

Creating an exchange

To create an exchange that will appear in the "exchanges" drop-down on the front page, use the create_exchange command. For example, to create an exchange for Australian stocks:

flask stockanalysis create_exchange --exchange-symbol="AX" --title="Australian Stock Exchange"

Downloading historical prices

To download historical prices from Alpha Vantage, you should register for an Alpha Vantage API key. Then tell whatifstocks what the API key is:


You will need a text file that lists the stocks for which you would like to fetch prices. You may find this ASX stocks list handy to get started.

For example, to download prices for ASX stocks and save them to a CSV:

flask stockanalysis download_stock_monthly_prices --exchange-symbol="AX" --ticker-symbols-file=/path/to/asx-stocks.txt --monthly-prices-output-file=/path/to/asx-stock-prices.csv

Importing data

To import a list of stocks containing ticker symbols, descriptions, and sector names, use the import_stocks command. For example, to import ASX stocks:

flask stockanalysis import_stocks --exchange-symbol="AX" --company-info-file=- < /path/to/asx-company-info.csv

You may find this ASX company info CSV useful to get started.

To import historical prices, use the import_monthly_prices command. For example, to import historical ASX prices:

flask stockanalysis import_monthly_prices --exchange-symbol="AX" --monthly-prices-file=- < /path/to/asx-stock-prices.csv

You may find this ASX stock prices CSV useful to get started.

Querying price changes

To see the change in price for all stocks in a given exchange, between two given years, simply go to the front page URL, select an exchange, select a "from year", and select a "to year". You will see all stocks in a table, listed in descending order of price increase.


In your production environment, make sure the FLASK_DEBUG environment variable is unset or is set to 0, so that ProdConfig is used.


To open the interactive shell, run:

flask shell

By default, you will have access to app and db.

Running Tests

To run all tests, run:

flask test