📈 Stock Price Downloader

Production-grade Python application for downloading, analyzing, and exporting historical stock price data with advanced financial metrics and comprehensive data validation

---

🎯 Overview

Stock Price Downloader is a robust, professional-grade application designed for quantitative analysts, financial engineers, and traders who need reliable, validated historical stock market data. Built with production-grade standards including type hints, comprehensive error handling, and extensive test coverage.

Perfect for:

• Quantitative finance research
• Algorithmic trading strategy backtesting
• Portfolio analysis and optimization
• Financial data engineering
• Academic financial research

---

✨ Key Features

📊 Multi-Ticker Support

Simultaneously download historical data for 50+ stock tickers without blocking. Optimized fetching with rate-limiting and error recovery.

📅 Flexible Date Ranges

Support for 2-10 year historical analysis. Custom date range selection. Holiday and market closure handling.

💰 Comprehensive Financial Metrics

Automatically calculated metrics:

• Sharpe Ratio: Risk-adjusted returns
• Volatility (Annualized): Standard deviation of returns
• Maximum Drawdown: Peak-to-trough decline
• Annualized Returns: Total return over time period
• Cumulative Return: Total percentage gain/loss
• Sortino Ratio: Downside risk metric

✅ Intelligent Data Validation

• Automatic handling of stock splits
• Dividend adjustment detection
• Missing value imputation with forward/backward fill
• Data consistency checks
• Outlier detection and flagging

📄 Professional Excel Export

• Formatted spreadsheets with charts
• Summary statistics sheet
• Detailed metrics per security
• Custom styling and conditional formatting
• Support for multiple sheets

🛡️ Production-Grade Error Handling

• Comprehensive exception handling
• Detailed logging at multiple levels
• Graceful degradation with fallbacks
• API rate limit handling
• Network retry logic with exponential backoff

🔒 Type Safety

• Full type hints across all modules
• MyPy strict mode compatible
• IDE autocomplete support
• Type-checked error messages

🧪 Comprehensive Testing

• Unit test coverage >85%
• Integration tests included
• Unittest and pytest compatible
• Test fixtures for reproducibility
• Continuous integration ready

---

🚀 Quick Start

Prerequisites

• Python 3.8+
• pip or conda

Installation

# Clone the repository
git clone https://github.com/DarkenSoul-oo1/bitchyList.git
cd bitchyList/stock-price-downloader

# Install dependencies
pip install -r requirements.txt

Basic Usage

from src.data_fetcher import StockDataFetcher
from src.data_processor import DataProcessor
from src.excel_exporter import ExcelExporter
from datetime import datetime, timedelta

# Initialize components
fetcher = StockDataFetcher()
processor = DataProcessor()
exporter = ExcelExporter()

# Download data for multiple stocks
tickers = ['AAPL', 'MSFT', 'GOOGL', 'TSLA', 'AMZN']
end_date = datetime.now()
start_date = end_date - timedelta(days=365*5)  # 5 years

data = fetcher.fetch_stocks(
    tickers=tickers,
    start_date=start_date,
    end_date=end_date,
    validate=True
)

# Calculate metrics and validate
processed_data = processor.process(
    data=data,
    calculate_returns=True,
    calculate_volatility=True
)

# Export results
exporter.export(
    filename='stock_analysis.xlsx',
    data=processed_data,
    include_charts=True
)

print("✅ Analysis complete! Check 'stock_analysis.xlsx'")

---

📦 Project Structure

stock-price-downloader/
├── src/
│   ├── __init__.py
│   ├── data_fetcher.py           # Yahoo Finance API integration
│   ├── data_processor.py         # Metrics calculation & validation
│   ├── excel_exporter.py         # Excel output formatting
│   ├── utils.py                  # Helper functions
│   └── config.py                 # Configuration constants
├── tests/
│   ├── __init__.py
│   ├── test_data_fetcher.py      # Fetcher unit tests
│   ├── test_data_processor.py    # Processor unit tests
│   ├── test_excel_exporter.py    # Exporter unit tests
│   └── fixtures.py               # Test data fixtures
├── docs/
│   ├── API_REFERENCE.md          # Detailed API documentation
│   ├── EXAMPLES.md               # Usage examples
│   └── TROUBLESHOOTING.md        # Common issues & solutions
├── main.py                       # CLI entry point
├── requirements.txt              # Python dependencies
├── .gitignore                    # Git ignore rules
└── README.md                     # This file

---

🔧 Configuration

Edit src/config.py to customize:

# API Settings
YAHOO_FINANCE_TIMEOUT = 30  # seconds
MAX_RETRIES = 3
RETRY_BACKOFF = 2  # exponential multiplier

# Data Validation
MIN_DATA_POINTS = 100
MAX_MISSING_PERCENT = 5  # %

# Output
EXCEL_DECIMAL_PLACES = 4
EXCEL_INCLUDE_CHARTS = True

---

💾 Dependencies

• yfinance (>=0.2.0): Yahoo Finance data fetching
• pandas (>=1.3.0): Data manipulation and analysis
• openpyxl (>=3.6.0): Excel file handling
• numpy (>=1.21.0): Numerical computations
• python-dateutil (>=2.8.0): Date utilities

See requirements.txt for complete list with pinned versions.

---

🧪 Running Tests

# Run all tests
python -m pytest tests/

# Run with coverage
python -m pytest --cov=src tests/

# Run specific test file
python -m pytest tests/test_data_fetcher.py -v

# Run tests using unittest
python -m unittest discover -s tests -p "test_*.py"

---

📊 Example Outputs

Processed Data Format

{
    'AAPL': {
        'prices': pd.DataFrame(...),
        'metrics': {
            'sharpe_ratio': 1.45,
            'volatility': 0.28,
            'max_drawdown': -0.35,
            'annual_return': 0.22,
            'cumulative_return': 2.8
        },
        'validation': {
            'missing_values': 0,
            'outliers': 2,
            'data_quality': 'EXCELLENT'
        }
    },
    # ... more securities
}

---

🐛 Troubleshooting

Network Errors

# Increase timeout and retry attempts
fetcher = StockDataFetcher(
    timeout=60,
    max_retries=5
)

Missing Data

# Use different imputation method
processor = DataProcessor(
    missing_value_method='interpolate'
)

See docs/TROUBLESHOOTING.md for more solutions.

---

📈 Performance Benchmarks

Typical performance on standard hardware:

• Data fetching: ~100 tickers in 5-10 seconds
• Processing: ~1000 data points in <100ms
• Excel export: ~50 sheets in <2 seconds

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Add tests for new functionality
4. Ensure all tests pass (pytest tests/)
5. Commit changes (git commit -m 'Add amazing feature')
6. Push to branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Code Style

• Follow PEP 8 guidelines
• Use type hints
• Write docstrings for all functions
• Maintain >85% test coverage

---

👤Garv_Kothari

DarkenSoul-oo1 - Quantitative Finance Engineer

• GitHub: @DarkenSoul-oo1
• Portfolio: bitchyList

---

⭐ Show Your Support

If this project was helpful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs and issues
• 💡 Suggesting new features
• 📢 Sharing with others

---

🔔 Disclaimer

This tool is provided for educational and research purposes. Past performance does not guarantee future results. Always validate data independently and conduct thorough due diligence before making investment decisions.

---

Last Updated: January 2026 | Status: Active Development ✅