An honest, slightly creaky template for ML stock picking

What it does The project provides an end-to-end pipeline for training a scikit-learn classifier to predict which S&P 500 stocks will outperform the index over the next year based on historical fundamentals—think P/E ratios, debt-to-equity, and free cash flow. It covers data acquisition, preprocessing, model training, backtesting, and finally generating predictions on current data, all glued together with pandas. The author explicitly frames it as a purely educational starting point rather than a production trading system.

The interesting bit What sets it apart is its refreshing transparency: the README confesses this was the author’s first Python project, first encounter with machine learning, and first time using Git, and it still warns that “minor issues may remain.” That same honesty extends to the finance side—the author claims to have achieved roughly 20% backtested and 10–15% live returns with code based on this project, yet still tells you not to live trade with this exact repository.

Key highlights

• Uses historical stock fundamentals (valuation, financials, trading info) from Yahoo Finance HTML dumps spanning 2003–2013.
• Benchmarks predictions against the S&P 500 index rather than raw price changes, so a 5% gain is judged relative to the market.
• Ships with pre-baked CSV fallbacks because the original Yahoo Finance data pipelines broke repeatedly.
• Includes a simple backtester and a forward-prediction step on current fundamentals.
• Suggests pairing with the author’s PyPortfolioOpt library to turn predicted outperformers into actual portfolios.

Caveats

• No longer actively maintained as of February 2021, and the author expected data issues to accumulate even before then.
• Fundamental data is parsed from HTML with regex, which the author notes is “really not recommended” and inherently brittle.
• The Yahoo Finance price download scripts have been deprecated and inconsistent for years; the project relies on uploaded static CSVs to keep the demo runnable.

Verdict Grab this if you want a concrete, warts-and-all introduction to the mechanics of quantitative stock prediction. Skip it if you are looking for a maintained, production-ready trading bot or a clean, modern data pipeline.