stock-analysis-toolkit 1.0.44

A comprehensive toolkit for stock market analysis and reporting

Corporate Bonds Analysis

Provide a CSV with your corporate bonds and pass it via --bonds-csv. Optionally pass a --benchmark-yield (percent) to compute spreads.

Expected CSV columns (headers are case-insensitive):

isin,issuer,coupon,frequency,maturity_date,clean_price,face_value,settlement_date,day_count,rating,benchmark_yield
INE001A08034,ABC Corp 2028,7.75,2,2028-12-15,101.25,100,2025-09-10,ACT/365,AA,7.10
INE002B08057,XYZ Infra 2030,8.20,2,2030-06-30,98.50,100,2025-09-10,ACT/365,AA-,7.10
INE003C08012,LMN Finance 2027,9.25,4,2027-03-31,103.10,100,2025-09-10,30/360,A+,7.10

• coupon: annual coupon rate in percent
• frequency: coupon payments per year (1, 2, 4, or 12)
• maturity_date / settlement_date: YYYY-MM-DD
• day_count: one of ACT/365, ACT/360, 30/360
• clean_price: price per 100 face (ex-accrued)
• benchmark_yield: optional per-bond benchmark; global --benchmark-yield overrides if provided

Optional fields:

quantity                       # numeric, units per bond (default 1.0)
call_dates, call_prices        # semicolon-separated lists, e.g., "2027-06-15;2028-06-15" and "101.0;100.5"
put_dates, put_prices          # semicolon-separated lists (same format as above)

Outputs added to the report:

• YTC (Yield-to-Call) for the nearest call date (if provided)
• YTW (Yield-to-Worst): minimum of YTM/YTC/Yield-to-Put (when put schedule provided)
• Position Market Value = Dirty Price/100 * Face Value * Quantity
• Portfolio aggregates (if multiple bonds):
  • Total Market Value
  • Weighted Modified Duration (MV-weighted)
  • Weighted Convexity (MV-weighted)

Example run:

stock-analyzer --bonds-csv data/bonds_sample.csv --benchmark-yield 7.10 -s SBI.NS --indices ^NSEI -e [e-mail] --send-email

Stock Analysis Toolkit

A comprehensive Python toolkit for analyzing stocks using technical and fundamental analysis. This package provides tools to fetch stock data, perform in-depth analysis, generate visualizations, and create detailed reports.

✨ Features

• Multi-source Data Collection

  • BSE stocks (e.g., 500325.BO for RELIANCE)
  • NSE stocks (e.g., RELIANCE.NS or NSE:RELIANCE)
  • Market indices (e.g., ^NSEI for NIFTY 50)
  • Mutual funds (by name or code)

• Technical Analysis

  • RSI, MACD, Bollinger Bands
  • Moving Averages (SMA, EMA)
  • Volume indicators
  • Custom technical indicators

• Fundamental Analysis

  • P/E, P/B, P/S ratios
  • ROE, ROA, and other profitability metrics
  • Debt/Equity and other leverage ratios
  • Dividend yield and history

• Reporting & Visualization

  • Interactive charts with Plotly
  • Detailed HTML reports
  • Email notifications with reports
  • Custom report templates

🚀 Installation

Basic Installation

pip install stock-analysis-toolkit

With Optional Dependencies

pip install "stock-analysis-toolkit[full]"

For Development

git clone https://github.com/pranav87/stock_analysis.git
cd stock_analysis
pip install -e ".[dev]"

TA-Lib Installation (Required for Technical Analysis)

• macOS: brew install ta-lib
• Linux: sudo apt-get install -y python3-ta-lib
• Windows: Download the appropriate wheel from here

📝 Configuration

Create a .env file in your project root with the following variables:

# Required for Alpha Vantage API
ALPHA_VANTAGE_API_KEY=your_api_key_here

# Optional: Email settings
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SENDER_EMAIL=[e-mail]
SENDER_PASSWORD=your_app_specific_password

SENDER_EMAIL=[e-mail] SENDER_PASSWORD=your_app_specific_password

## Usage

Once installed, you can use the `stock-analyzer` command from your terminal.

### Command-Line Interface

```bash
stock-analyzer --help

usage: stock-analyzer [-h] [-s STOCKS] [-mf MUTUAL_FUNDS [MUTUAL_FUNDS ...]] [--mf-codes MF_CODES [MF_CODES ...]] [-d DAYS] [-e EMAIL] [--no-cache] [-v] [--send-email] [--indices [INDICES ...]] [--bonds-csv BONDS_CSV] [--benchmark-yield BENCHMARK_YIELD]

Stock and Mutual Fund Analysis Tool

options:
  -h, --help            show this help message and exit
  -s STOCKS, --stocks STOCKS
                        Stock symbol to analyze. Can be specified multiple times (e.g., -s RELIANCE.NS -s TCS.NS)
  -mf MUTUAL_FUNDS [MUTUAL_FUNDS ...], --mutual_funds MUTUAL_FUNDS [MUTUAL_FUNDS ...]
                        Mutual fund name to analyze. Can be specified multiple times. For multi-word names, wrap in quotes.
  --mf-codes MF_CODES [MF_CODES ...]
                        Mutual fund scheme codes to analyze. Can be specified multiple times (e.g., --mf-codes 108467 120757).
  -d DAYS, --days DAYS  Number of days for historical data analysis (default: 90)
  -e EMAIL, --email EMAIL
                        Email address to send the report to.
  --no-cache            Disable caching of analysis results
  -v, --verbose         Enable verbose logging for debugging
  --send-email          Flag to send the report via email. Requires --email to be set.
  --indices [INDICES ...]
                        A list of index symbols to analyze (e.g., ^NSEI ^CRSMID)
  --bonds-csv BONDS_CSV
                        Path to a CSV containing corporate bonds to analyze
  --benchmark-yield BENCHMARK_YIELD
                        Benchmark government yield (percent) used to compute spreads

Sample Run Command

Here is an example command to analyze two stocks and two mutual funds, and then email the report:

stock-analyzer -s RELIANCE.NS -s TCS.NS --mf-codes 107578 120465 -e [e-mail] --send-email

This command analyzes Reliance and TCS, along with the mutual funds for "Mirae Asset Large Cap Fund" (107578) and "Axis Bluechip Fund" (120465).

Project Structure

stock-analysis/
├── config/                 # Configuration files
│   └── config.py           # Application configuration
├── data/                   # Data storage
│   └── cache/              # Cached stock data
├── logs/                   # Log files
├── reports/                # Generated reports
│   └── charts/             # Chart visualizations
├── src/                    # Source code
│   ├── data_fetcher.py     # Data collection from APIs
│   ├── technical_analysis.py # Technical indicators and analysis
│   ├── visualization.py    # Data visualization
│   └── main.py             # Main application and CLI
├── .env.example            # Example environment variables
├── requirements.txt        # Python dependencies
└── README.md               # This file

Supported Stock Exchanges

• BSE (Bombay Stock Exchange): Use .BO suffix (e.g., RELIANCE.BO)
• NSE (National Stock Exchange): Use .NS suffix (e.g., RELIANCE.NS)

Data Sources

• Primary: Google Finance
• Fallback: Yahoo Finance
• Additional: Alpha Vantage (for fundamental data, requires API key)

Email Configuration

To enable email notifications:

1. Enable "Less secure app access" in your Gmail account settings or generate an App Password
2. Set the following environment variables in your .env file:

   SENDER_EMAIL=[e-mail]
   SENDER_PASSWORD=your_app_specific_password
   

Limitations

• Free API tiers may have rate limits
• Some fundamental data may not be available for all stocks
• Analysis should be used for informational purposes only

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This tool is for educational and informational purposes only. It does not constitute financial advice. Always do your own research and consult with a licensed financial advisor before making investment decisions.