bistanbul 0.1.0

Borsa Istanbul hisseleri icin hafif terminal araci

BISTanbul

A lightweight Python CLI tool for retrieving and analyzing Borsa Istanbul (BIST) stock data directly in your terminal.

Overview

BISTanbul leverages the borsapy library to fetch real-time and historical stock data, providing actionable insights through structured output formats. The tool supports individual stock reports, multi-symbol comparisons, market context snapshots, screening presets, and monitoring with threshold alerts.

Features

• Single Stock Reports — Concise, decision-support summaries with price, returns, dividends, valuation metrics, and analyst targets
• Multi-Symbol Comparison — Side-by-side analysis with benchmark-relative performance rankings
• Market Context — Curated macro snapshot including index, FX rates, gold, and interest/inflation data
• Screening Presets — Six locked discovery filters: high return, high volume, dividend, value, momentum, and oversold
• Monitoring with Alerts — Recurring monitoring cycles with configurable price and return thresholds
• Graceful Data Handling — Missing or incomplete data is clearly labeled; the tool never crashes on partial data

Quick Start

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies and package
pip install -r requirements.txt
pip install -e .

Basic Usage

# Query a single stock
python -m bistanbul report THYAO

# Compare multiple stocks
python -m bistanbul compare THYAO GARAN AKBNK

# View market macro snapshot
python -m bistanbul market

# Screen for high-return stocks (from XU100)
python -m bistanbul screen yuksek_getiri

# Monitor with threshold alerts
python -m bistanbul monitor THYAO --price-above THYAO:320 --price-below GARAN:100

For the complete command reference, including all available options for each subcommand, see USAGE.md.

Command Overview

Command	Description
report <symbol>	Single stock decision-support report
compare <symbols...>	Multi-stock comparison with benchmark
market	Macro snapshot (index, FX, gold, rates)
screen <preset>	Filtered stock discovery
monitor <symbols...>	Recurring monitoring with alerts

Running Tests

PYTHONPATH=src python -m unittest discover -s tests

Project Structure

.
├── main.py                 # Legacy entry point
├── pyproject.toml          # Package metadata
├── requirements.txt        # Dependencies
├── USAGE.md                # Complete usage reference
├── src/bistanbul/
│   ├── __init__.py
│   ├── __main__.py
│   ├── cli.py              # Command-line interface
│   ├── core.py             # Core data fetching
│   ├── report.py           # Single-stock report
│   ├── compare.py           # Multi-stock comparison
│   ├── market.py           # Market context
│   ├── screen.py           # Screening presets
│   ├── monitor.py          # Monitoring & alerts
│   └── render.py           # Output formatters
└── tests/
    └── test_core.py

Notes

• Missing data fields are gracefully handled and displayed as "N/A" with explanatory notes
• All outputs include disclaimers indicating the information is for informational purposes only and not investment advice
• Data may be delayed; verify with additional sources before making investment decisions
• main.py is retained for backward compatibility

License

MIT