Metadata-Version: 2.4
Name: bistanbul
Version: 0.1.0
Summary: Borsa Istanbul hisseleri icin hafif terminal araci
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: borsapy
Requires-Dist: matplotlib
Requires-Dist: pandas

# 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

```bash
# 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

```bash
# 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](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

```bash
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
