Skip to main content

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

Metadata

Release files for bistanbul 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for bistanbul 0.1.0
File Size Uploaded Provenance Actions
bistanbul-0.1.0.tar.gz 28.5 kB Without provenance Details for bistanbul-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for bistanbul 0.1.0
File Interpreter ABI Platform Actions
bistanbul-0.1.0-py3-none-any.whl Python 3 none any Details for bistanbul-0.1.0-py3-none-any.whl

Total release size: 53.2 kB

Release files / bistanbul-0.1.0.tar.gz

Download URL bistanbul-0.1.0.tar.gz
Size 28.5 kB
Tags Source
SHA-256 checksum
How to use checksums
ca8a63aafa6d2db1ee71ffb514683b7d8c023e80fc84792ac19526387cfb0f17
BLAKE2b-256 checksum
How to use checksums
fc2cc405455a7ee8b9c558657ef7fea4e4fa642aca0bc43e10902d06253eb217
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.7

Release files / bistanbul-0.1.0-py3-none-any.whl

Download URL bistanbul-0.1.0-py3-none-any.whl
Size 24.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
efadc5b720a9664814da7f6d7b85683e506aaa3941e35e1a11efb87d099034ef
BLAKE2b-256 checksum
How to use checksums
5f0a795c14852077f5067ae560b00246382eb2b19f3a6c177a46506dae5b6104
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.7

Security for bistanbul 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page