shashankvemuri/Finance: A Python Toolkit Where Backtest Execution Rules Are Written Down

What shashankvemuri/Finance Is For, and Who Ends Up Using It

This is not a trading system. It is a set of Python modules for people who already write Python and want market data, indicator math, screening rules, backtests and portfolio optimization to live in one installable package instead of five notebooks. The README frames the whole thing as research tooling: models and trading rules are research tools, and the runnable examples are described as the starting point rather than finished strategies.

The audience that fits is narrow but real. A quant-curious developer who wants to compute RSI on a price series without pulling a TA-Lib binary. A data scientist who needs CAPM or OLS regressions on returns and does not want to assemble the data layer. Someone teaching a course on backtesting who needs a backtester small enough to read. The repository also ships a Streamlit app and Excel export paths, which suggests it is used for exploratory work and reporting, not for unattended execution.

The README is explicit that this is educational material and not professional investment advice. That disclaimer is not boilerplate here. It matches what the code surface actually offers: research primitives with documented conventions, not a production trading stack.

The Next-Open Execution Rule Is the Design Decision That Matters

Most of the toolkit is conventional. The part worth reading closely is the backtest convention. The README gives this example: strategies generate targets from the close, and the backtester executes them at the next open.

That single choice removes a common source of inflated results. If a moving-average crossover is computed on today's close and filled at today's close, the backtest has quietly assumed you knew the closing price before the close happened. Filling at the next open is the more defensible convention, and the repository states it plainly instead of leaving it implicit. The README also says the backtester tracks cash, fractional shares, long and short fills, commission, slippage and borrow costs. In the example call, commission is passed as a decimal fraction: commission=0.001.

A second convention is stated with equal directness: returns and rates are fractions, RSI is 0 to 100, and warm-up values remain missing. That last point matters more than it looks. A 50-period moving average produces NaN for the first 49 rows, and any code that fills those with zero or with the first valid value will change the strategy's early behavior. The library leaves them missing, which pushes the decision to the caller.

The README directs readers to docs/methodology.md before interpreting results. That document is not reproduced in the supplied material, so the exact slippage model, borrow-cost formula and benchmark construction cannot be confirmed here. What can be confirmed is that the project treats the execution model as something you are expected to read, not something you are expected to infer.

Installing Only the Extras You Need

The install path is a clone plus an editable install, and it requires Python 3.12 or newer. Core dependencies are NumPy and pandas. Everything else is an optional extra:

python -m pip install -e '.[data]' python -m pip install -e '.[portfolio,models]' python -m pip install -e '.[plot,sentiment]' python -m pip install -e '.[apps,reports]'

The extras map to capability groups. data covers public data, Finviz and financial statements. portfolio and models cover optimization and statistical or machine-learning experiments. plot and sentiment cover charts and VADER text scoring. apps and reports cover the interactive app and Excel exports.

This split is the most practical thing about the packaging. A user who only wants indicators never installs the data providers. The README states that indicators can be calculated without any network access, which the example demonstrates: bollinger_bands and rsi take a price series and return values. That makes the indicator layer testable offline, and it means a failing data provider does not break a notebook that only does math.

The examples follow the same pattern. Most use synthetic inputs by default, and --live switches to public data. The README notes one exception: download_market_data.py always uses the network. So the default experience of running the examples is offline and deterministic, which is a reasonable choice for a repository whose examples double as documentation.

Where the Toolkit Stops: Snapshots, Throttling and Missing Warm-Up Rows

The limitations are stated by the project itself, which is unusual and useful. First, current constituents and fundamentals are snapshots, not historical point-in-time inputs. This is a hard boundary. Any screen that ranks stocks by growth or ownership, or any study that uses index membership, is working with today's list applied to the past. That is survivorship bias by construction, and the README does not pretend otherwise. If your research question depends on what the S&P 500 contained in 2015, this toolkit will not answer it correctly.

Second, public providers can throttle or change schemas. The README points to docs/providers.md for provider contracts. That document is not in the supplied material, so the specific retry behavior and schema-validation strategy cannot be confirmed. What is clear is that the data layer is a thin wrapper over external services, and its reliability is bounded by theirs.

Third, warm-up values remain missing. This is a limitation only if you expected otherwise, but it is the kind of thing that silently corrupts results when a caller fills NaNs without thinking. The library's choice to leave them missing is defensible; the burden it creates is real.

Fourth, the forecast models make no claim of predictive advantage. The README says forecast experiments report held-out errors against simple baselines. That is a statement about scope, not a bug, but it means the models module should be read as a way to run experiments, not as a source of signals.

How It Compares to Backtrader and vectorbt

The obvious alternatives are Backtrader and vectorbt, and the difference is mostly about what each one optimizes for.

Backtrader is an event-driven framework with a broker simulation, a strategy class hierarchy and a live-trading bridge. You write a Strategy subclass with next() methods, and the engine walks bars. That structure scales to complex order logic and multi-instrument portfolios, and it carries a larger API surface and a steeper learning curve. shashankvemuri/Finance takes the opposite approach: a strategy is a function that returns target positions from a close series, and backtest() consumes those targets alongside open and close prices. There is no event loop to learn. The trade-off is that anything requiring intrabar logic, partial fills or order types beyond what the backtester models is out of scope.

vectorbt is built around NumPy broadcasting and is designed for running large parameter sweeps quickly. Its mental model is arrays in, arrays out, and it rewards users who think in vectorized terms. shashankvemuri/Finance is closer to plain pandas: explicit inputs, a small dependency set, and tested execution conventions, to quote the README's own framing. If your goal is to sweep ten thousand parameter combinations, vectorbt is the more natural tool. If your goal is to read the backtest code and understand exactly what it did, this repository is smaller and more legible.

The comparison is not about which is better. It is about which failure mode you can tolerate. A large framework can hide an execution assumption in a default. A small one can simply lack the feature you need.

Maintenance, Extras and the MIT Licence

The repository is not archived, and the last push recorded in the supplied metadata is 2026-09-08. No releases were retrieved, which means installation is from the master branch rather than from a tagged version. That has a practical consequence: python -m pip install -e . pulls whatever is currently on master, so pinning to a commit hash is the only way to freeze behavior. There is no version number to cite in a requirements file.

The optional extras are where upgrade cost concentrates. The data extra depends on public providers whose schemas can change, and the README warns about exactly that. The models extra pulls in statistical and machine-learning dependencies, including optional neural and Prophet experiments. The sentiment extra pulls in VADER. Each of these can break independently of the core, and each adds install weight. A user who stays on the core plus indicators has a dependency set of NumPy and pandas and very little upgrade surface. A user who installs apps and reports takes on Streamlit and Excel-writing dependencies as well.

The licence is MIT. That permits commercial use, modification and redistribution provided the copyright notice and permission notice are included. It also means the author offers no warranty. This is a description of the licence text, not legal advice; if the toolkit ends up inside a product, the disclaimer in the README about educational use is worth reading alongside the licence itself.

One more maintenance detail: the README credits technical-indicator references to the Stock_Analysis_For_Quant project by LastAncientOne. That is an attribution to check if you plan to reuse indicator code, since the provenance of the formulas matters for anything you redistribute.

Running the Examples Before Writing Any Strategy Code

The README lists six entry points:

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

The ordering is informative. The indicator example runs offline. The backtest and watchlist examples need --live to hit public data. The portfolio and models examples run on synthetic inputs by default. The Streamlit app is a separate surface and needs the apps extra.

A sensible first pass is to run calculate_indicators.py to confirm the install, then backtest_moving_average.py --live to see a real result with real costs applied. The printed result.metrics dictionary is the thing to inspect, because the README's claims about commission, slippage and borrow costs are only meaningful if you can see which of them the run actually charged. The example passes commission=0.001 explicitly; whether slippage and borrow are also set in that script is not stated in the README, so read the script rather than assuming.

After that, docs/methodology.md is the document that determines whether the numbers mean anything. The README links it directly and tells you to read it before interpreting results. That instruction is the strongest signal in the whole file about how the author expects the toolkit to be used.

Editorial conclusion

Adopt shashankvemuri/Finance if you want a small-dependency Python library where the backtest execution rule is stated up front and indicators run without network access, and you are willing to read docs/methodology.md before trusting any equity curve. Do not adopt it if you need point-in-time fundamentals for historical screening: the README says current constituents and fundamentals are snapshots, not historical point-in-time inputs. Before writing strategy code, install with python -m pip install -e '.[data]' and run python examples/backtest_moving_average.py --live, then read the printed metrics against docs/methodology.md so you know which costs the run actually charged.

Official sources

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