shashankvemuri/Finance: a Python toolkit for indicators, backtests and portfolio research

What shashankvemuri/Finance actually covers

This is a Python package for quantitative research on equities, not a brokerage client and not a signal service. The README lists eight capability areas: data, indicators, analytics, screening, strategies, backtesting, portfolio and models, plus reports and integrations. The breadth is the point. A relative strength screen, an RSI series, a moving-average crossover target and a portfolio frontier all live in the same install and share the same conventions about what a return is and when a trade fills.

The intended user is someone who already writes Python and wants the plumbing done. The README states that calculations use explicit inputs, a small dependency set and tested execution conventions, and that runnable examples are the starting point. Core dependencies are only NumPy and pandas. Everything heavier, from SciPy to PyTorch to Streamlit, sits behind optional extras, so a reader who only wants indicators never pulls in a machine-learning stack. If you are looking for a hosted dashboard or a managed data feed, this is the wrong shape of project.

How the data, indicators and backtester fit together

The flow is deliberately linear. A data source returns a pandas frame of adjusted OHLCV. Indicator functions take a price series and return a series of the same shape. Strategy functions take prices and return targets. The backtest function takes open, close and targets, and prints a metrics object. Nothing is hidden in a global configuration, which is why the README insists on explicit inputs.

The execution convention is the part worth reading twice. Signals are generated at the close and executed at the next open. The README describes the backtester as modest and says it tracks cash, fractional shares, long and short fills, commission, slippage and borrow costs. Returns and rates are expressed as fractions, RSI runs from 0 to 100, and warm-up values stay missing rather than being filled. That last detail matters: a 50-period moving average will produce a target series whose first 49 entries are absent, and any downstream code that calls fillna without thinking has quietly invented data.

The README points to docs/methodology.md for the full calculation and execution conventions and tells you to read it before interpreting results. Take that literally. The metrics dictionary is only as meaningful as those conventions.

Installing the toolkit and running a first backtest

The README requires Python 3.12 or newer and installs from a clone rather than from a package index. The commands below are the ones the README gives, including the editable install.

git clone https://github.com/shashankvemuri/Finance.git
cd Finance
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install -e .

That base install gives you NumPy and pandas only. To download prices you need the data extra, which the README says adds public data, Finviz and financial statements.

python -m pip install -e '.[data]'

With that in place, the README's first example pulls normalized, consistently adjusted OHLCV.

from finance.data import YahooFinance

prices = YahooFinance().history('AAPL', '2023-01-01', '2025-01-01')

Indicators need no network at all, which makes them the cheapest thing to try first.

from finance.indicators import bollinger_bands, rsi

strength = rsi(prices['close'], window=14)
bands = bollinger_bands(prices['close'], window=20)

The full loop, from target generation to a metrics dictionary, is three calls. Note that commission is passed as a fraction.

from finance.backtesting import backtest
from finance.strategies import moving_average

targets = moving_average(prices['close'], fast=20, slow=50)
result = backtest(prices['open'], prices['close'], targets, commission=0.001)
print(result.metrics)

If you would rather not write any of this yet, the repository ships runnable scripts. The README says examples use synthetic inputs by default and that adding --live switches them to public data, while download_market_data.py always uses the network.

python examples/calculate_indicators.py
python examples/backtest_moving_average.py --live
streamlit run apps/research.py

The Streamlit app requires the apps extra, which the README installs with python -m pip install -e '.[apps,reports]'.

The backtester is intentionally small, and that is a real limit

The README calls the backtester modest, and the word is doing work. It models fills, commission, slippage and borrow costs, but there is no order book, no partial fill logic described, and no queue position. Anyone who has tried to reproduce a live equity strategy will recognise the gap between a next-open fill assumption and what happens when a thin name gaps through your price.

The larger constraint is stated plainly in the README: current constituents and fundamentals are snapshots, not historical point-in-time inputs. That single sentence disqualifies a whole class of research. If you screen for Minervini-style setups or relative strength using today's index membership, you are testing on a universe that did not exist at the time, and the resulting equity curve contains survivorship and look-ahead bias you cannot remove from inside this package. The screening and analytics modules are useful for studying current conditions, not for reconstructing what a screen would have returned in 2019.

Provider behaviour is the other failure mode. The README warns that public providers can throttle or change schemas and points to docs/providers.md for provider contracts. There are no retrieved releases for this repository, so there is no changelog to check when a provider silently changes a field. The repository does carry integration tests: pyproject.toml defines an integration marker described as explicit live provider checks that are not part of offline CI. That tells you the maintainers know live calls are unstable, and it also tells you the default test run will not catch a broken provider.

Extras, optional models and what you are actually installing

The dependency set is the most opinionated part of the project. Base install is numpy>=2.0,<3 and pandas>=2.2,<4. From there you opt in: data pulls yfinance and lxml; portfolio pulls SciPy; models pulls scikit-learn and statsmodels; sentiment pulls vaderSentiment; neural pulls torch; prophet pulls prophet; apps pulls SciPy, Streamlit, matplotlib, lxml and yfinance; reports pulls openpyxl and matplotlib; plot pulls matplotlib alone. The dev extra adds pytest, ruff, build and ta.

That structure is a genuine design choice with a cost. You can install the toolkit without a 2 GB deep-learning dependency, which is the right default. The cost is that the optional paths are less exercised by default. The offline CI, per the pytest configuration, runs without the integration marker, so a change in a provider schema or a Streamlit version bump lands on the user first.

The README is careful about the modelling side: forecast experiments report held-out errors against simple baselines and make no claim of predictive advantage. That is an unusually honest sentence in a repository that also ships ARIMA diagnostics, PCA, regime detection and clustering. Treat the models module as a place to run experiments with a baseline attached, not as a source of edge.

Compared with building on pandas and a dedicated backtesting library

The obvious alternative is to assemble the same stack yourself: pandas for the frames, a technical-analysis package for indicators, and a dedicated event-driven backtesting framework for fills. The difference is in where the conventions live. A dedicated backtester typically owns the event loop and asks you to express strategies as callbacks; this toolkit owns the conventions and asks you to express strategies as target series. The target-series model is simpler to test, because a strategy becomes a pure function of prices, but it cannot express intraday logic, order amendments or anything that depends on the state of a live book.

The second alternative is a full research platform with point-in-time data. That is a different purchase entirely, and it addresses the snapshot limitation this README admits to. The toolkit's advantage is the opposite one: MIT licensed, two core dependencies, and every intermediate value visible in a pandas object you can inspect. If your work is exploratory and your universe is small, that transparency is worth more than an event loop you will not use.

Licence, maintenance and upgrade cost

The project is MIT licensed, and pyproject.toml declares license = "MIT" with the author listed as Shashank Vemuri. MIT is permissive: you can use, modify and redistribute the code, including in commercial work, provided the copyright notice and permission notice are retained. That is a statement about the licence text, not legal advice for your situation.

Maintenance signals are mixed and worth stating precisely. The repository is not archived, and the last push was on 2026-09-08, which is recent. There are no retrieved releases, and the version in pyproject.toml is 0.0.0, so there is no tagged version to pin against. Upgrading therefore means pulling the master branch and re-running your own tests. The dependency ranges are wide but bounded, and the optional extras mean an upgrade only touches the areas you installed. The practical upgrade cost sits in the live provider paths, where a yfinance or lxml change can break data retrieval without any change in this repository. The integration marker exists for exactly that check; running it before an upgrade is the cheap way to find out.

Editorial conclusion

Adopt it if you want a single Python package where indicators, screening, strategy targets and a next-open backtester share one set of conventions, and you are willing to read docs/methodology.md before trusting a metrics dictionary. Do not adopt it as an execution system: brokerage and delivery need separate credentials, and the README calls the models and trading rules research tools. Before writing your own code, run the shipped examples, then verify two things against your own data: that YahooFinance().history returns the adjustment behaviour you expect, and that backtest with commission set to your real cost still produces the trade report you can reconcile.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. shashankvemuri/Finance on GitHub