borsapy 0.7.3
Turkish financial markets data library - yfinance-like API for BIST stocks, forex, crypto, and more
License: Apache-2.0
Requires Python: >=3.10
Keywords: bist, crypto, finance, forex, market-data, stocks, turkey

# borsapy

[![PyPI version](https://img.shields.io/pypi/v/borsapy)](https://pypi.org/project/borsapy/)
[![PyPI downloads](https://img.shields.io/pypi/dm/borsapy)](https://pypi.org/project/borsapy/)
[![Python version](https://img.shields.io/pypi/pyversions/borsapy)](https://pypi.org/project/borsapy/)
[![License](https://img.shields.io/pypi/l/borsapy)](https://github.com/saidsurucu/borsapy/blob/master/LICENSE)
[![Documentation](https://img.shields.io/badge/docs-API%20Reference-blue)](https://saidsurucu.github.io/borsapy/borsapy.html)

> **Sorumluluk Reddi / Disclaimer**
>
> Bu kütüphane yalnızca kişisel kullanım ve eğitim amaçlıdır. Ticari yazılım ürünleri geliştirmek, ticari hizmetlerde kullanmak veya herhangi bir ticari amaçla kullanılamaz. Ticari kullanım için uygun bir lisans satın almak üzere Borsa İstanbul ile iletişime geçmelisiniz.
>
> This library is for personal and educational use only. It cannot be used for developing commercial software products, commercial services, or any commercial purposes. For commercial use, you must contact Borsa Istanbul to purchase an appropriate license.

Türk finansal piyasaları için Python veri kütüphanesi. BIST hisseleri, döviz, kripto, yatırım fonları ve ekonomik veriler için yfinance benzeri API.

[![Star History Chart](https://api.star-history.com/svg?repos=saidsurucu/borsapy&type=date&legend=top-left)](https://www.star-history.com/#saidsurucu/borsapy&type=date&legend=top-left)

## Kurulum

```bash
pip install borsapy
```

## Hızlı Başlangıç

```python
import borsapy as bp

# Hisse senedi verisi
hisse = bp.Ticker("THYAO")
print(hisse.info)                    # Anlık fiyat ve şirket bilgileri
print(hisse.history(period="1ay"))   # Geçmiş OHLCV verileri
print(hisse.balance_sheet)           # Bilanço

# Çoklu hisse
data = bp.download(["THYAO", "GARAN", "AKBNK"], period="1ay")
print(data)

# Döviz
usd = bp.FX("USD")
print(usd.current)                   # Güncel kur
print(usd.history(period="1ay"))     # Geçmiş veriler

# Kripto
btc = bp.Crypto("BTCTRY")
print(btc.current)                   # Güncel fiyat

# Yatırım fonu
fon = bp.Fund("AAK")
print(fon.info)                      # Fon bilgileri

# Enflasyon
enf = bp.Inflation()
print(enf.latest())                  # Son TÜFE verileri
```

## Komut Satırı Arayüzü (CLI)

borsapy, terminal üzerinden hızlı veri erişimi için kapsamlı bir CLI sunar:

```bash
# Fiyat sorgula
borsapy price THYAO GARAN ASELS

# Geçmiş verileri CSV'ye kaydet
borsapy history THYAO --period 1y --output csv > thyao.csv

# Teknik sinyaller
borsapy signals THYAO --interval 1h

# Canlı izleme
borsapy watch THYAO GARAN --interval 0.5

# Teknik tarama
borsapy scan "rsi < 30 and volume > 1000000" --index XU100

# Temel tarama
borsapy screen --template high_dividend --index XU030
```

**[CLI Dokümantasyonu →](CLI.md)** | 25+ komut: fiyat, geçmiş, teknik analiz, mali tablolar, tarama ve daha fazlası.

---

## Ticker (Hisse Senedi)

`Ticker` sınıfı, BIST hisse senetleri için kapsamlı veri erişimi sağlar.

### Temel Kullanım

```python
import borsapy as bp

hisse = bp.Ticker("THYAO")

# Hızlı fiyat bilgisi (cache'den, API çağrısı yapmaz)
print(hisse.fast_info["last_price"])     # Son fiyat
print(hisse.fast_info["previous_close"]) # Önceki kapanış
print(hisse.fast_info["volume"])         # Hacim
print(hisse.fast_info["market_cap"])     # Piyasa değeri
print(hisse.fast_info["pe_ratio"])       # F/K oranı
print(hisse.fast_info["free_float"])     # Halka açıklık oranı
print(hisse.fast_info["foreign_ratio"])  # Yabancı oranı

# Detaylı bilgiler (tüm verileri yükler)
print(hisse.info["last"])           # Son fiyat
print(hisse.info["marketCap"])      # Piyasa değeri
print(hisse.info["trailingPE"])     # F/K oranı
print(hisse.info["dividendYield"])  # Temettü verimi
```

### Fiyat Geçmişi

> 💡 **TradingView Veri Kaynağı:** BIST fiyat verileri TradingView WebSocket API üzerinden sağlanır. Varsayılan olarak ~15 dakika gecikmeli. Gerçek zamanlı veri için [TradingView Kimlik Doğrulama](#tradingview-kimlik-doğrulama-gerçek-zamanlı-veri) bölümüne bakın.

```python
# Dönem bazlı
df = hisse.history(period="1ay")    # Son 1 ay
df = hisse.history(period="3ay")    # Son 3 ay
df = hisse.history(period="1y")     # Son 1 yıl
df = hisse.history(period="max")    # Tüm geçmiş

# Tarih aralığı
df = hisse.history(start="2024-01-01", end="2024-06-30")

# Farklı zaman dilimleri (interval)
df = hisse.history(period="1g", interval="1m")   # 1 dakikalık mumlar
df = hisse.history(period="1g", interval="3m")   # 3 dakikalık mumlar
df = hisse.history(period="1g", interval="5m")   # 5 dakikalık mumlar
df = hisse.history(period="1g", interval="15m")  # 15 dakikalık mumlar
df = hisse.history(period="1g", interval="30m")  # 30 dakikalık mumlar
df = hisse.history(period="1g", interval="45m")  # 45 dakikalık mumlar
df = hisse.history(period="5g", interval="1h")   # Saatlik mumlar
df = hisse.history(period="1ay", interval="1d")  # Günlük mumlar (varsayılan)
```

### Finansal Tablolar

```python
# Yıllık tablolar (sınai şirketler için)
print(hisse.balance_sheet)          # Bilanço
print(hisse.income_stmt)            # Gelir tablosu
print(hisse.cashflow)               # Nakit akış

# Çeyreklik tablolar
print(hisse.quarterly_balance_sheet)
print(hisse.quarterly_income_stmt)
print(hisse.quarterly_cashflow)

# TTM (Son 12 ay)
print(hisse.ttm_income_stmt)
print(hisse.ttm_cashflow)

# Bankalar için (UFRS formatı)
banka = bp.Ticker("AKBNK")
print(banka.get_balance_sheet(financial_group="UFRS"))
print(banka.get_income_stmt(financial_group="UFRS"))
print(banka.get_cashflow(financial_group="UFRS"))

# Banka çeyreklik tablolar
print(banka.get_balance_sheet(quarterly=True, financial_group="UFRS"))
print(banka.get_income_stmt(quarterly=True, financial_group="UFRS"))

# Banka TTM
print(banka.get_ttm_income_stmt(financial_group="UFRS"))
print(banka.get_ttm_cashflow(financial_group="UFRS"))
```

> **Not**: Sınai şirketler varsayılan olarak `XI_29` formatını kullanır. Bankalar için `financial_group="UFRS"` parametresi gereklidir.

### Temettü ve Sermaye Artırımları

```python
print(hisse.dividends)              # Temettü geçmişi
print(hisse.splits)                 # Sermaye artırımları
print(hisse.actions)                # Tüm kurumsal işlemler

# Geçmiş verilerde temettü ve split
df = hisse.history(period="1y", actions=True)
```

### Ortaklık Yapısı

```python
print(hisse.major_holders)          # Ana ortaklar
```

### Analist Verileri

```python
print(hisse.analyst_price_targets)  # Hedef fiyatlar
print(hisse.recommendations_summary) # AL/TUT/SAT dağılımı
print(hisse.recommendations)        # Detaylı tavsiyeler
```

### KAP Bildirimleri

```python
print(hisse.news)                   # Son bildirimler
print(hisse.calendar)               # Beklenen açıklamalar
print(hisse.earnings_dates)         # Finansal rapor tarihleri
```

### Diğer Bilgiler

```python
print(hisse.isin)                   # ISIN kodu
print(hisse.info["sector"])         # Sektör
print(hisse.info["industry"])       # Alt sektör
print(hisse.info["website"])        # Web sitesi
print(hisse.info["longBusinessSummary"])  # Faaliyet konusu
```

### ETF Sahipliği

Uluslararası ETF'lerin hisse pozisyonlarını görüntüleme.

```python
import borsapy as bp

stock = bp.Ticker("ASELS")

# ETF holder listesi (DataFrame)
holders = stock.etf_holders
print(holders)
#    symbol exchange                                      name  market_cap_usd  holding_weight_pct           issuer
# 0    IEMG     AMEX  iShares Core MSCI Emerging Markets ETF    118225730.76            0.090686  BlackRock, Inc.
# 1     VWO     AMEX     Vanguard FTSE Emerging Markets ETF     85480000.00            0.060000     Vanguard Inc

print(f"Total ETFs: {len(holders)}")
print(f"Top holder: {holders.iloc[0]['name']}")
print(f"Total weight: {holders['holding_weight_pct'].sum():.2f}%")
```

**DataFrame Sütunları:**

| Sütun | Açıklama |
|-------|----------|
| `symbol` | ETF sembolü (IEMG, VWO, TUR) |
| `exchange` | Borsa (AMEX, NASDAQ, LSE, XETR) |
| `name` | ETF tam adı |
| `market_cap_usd` | ETF'in bu hissedeki pozisyon değeri (USD) |
| `holding_weight_pct` | Ağırlık yüzdesi (0.09 = %0.09) |
| `issuer` | İhraççı (BlackRock, Vanguard, vb.) |
| `expense_ratio` | Gider oranı |
| `aum_usd` | Toplam varlık (USD) |

---

## Tickers ve download (Çoklu Hisse)

Birden fazla hisse için toplu veri çekme.

### Tickers Sınıfı

```python
import borsapy as bp

# Birden fazla hisse
hisseler = bp.Tickers(["THYAO", "GARAN", "AKBNK"])

# Her hissenin bilgilerine erişim
for sembol in hisseler.symbols:
    ticker = hisseler.tickers[sembol]
    print(f"{sembol}: {ticker.info['last']}")
```

### download Fonksiyonu

```python
# Basit kullanım
df = bp.download(["THYAO", "GARAN", "AKBNK"], period="1ay")

# Ticker bazlı gruplama
df = bp.download(["THYAO", "GARAN"], period="1ay", group_by="ticker")

# Sütun bazlı gruplama (varsayılan)
df = bp.download(["THYAO", "GARAN"], period="1ay", group_by="column")
```

---

## Index (Endeksler)

BIST endekslerine erişim - 79 endeks, bileşen listeleri dahil.

> 💡 **TradingView Veri Kaynağı:** Endeks fiyat verileri TradingView WebSocket API üzerinden sağlanır. Varsayılan olarak ~15 dakika gecikmeli. Gerçek zamanlı veri için [TradingView Kimlik Doğrulama](#tradingview-kimlik-doğrulama-gerçek-zamanlı-veri) bölümüne bakın.

### Temel Kullanım

```python
import borsapy as bp

# Mevcut endeksler (33 popüler endeks)
print(bp.indices())
# ['XU100', 'XU050', 'XU030', 'XKTUM', 'XK100', 'XK030', 'XBANK', ...]

# Detaylı liste (bileşen sayısı ile)
print(bp.indices(detailed=True))
# [{'symbol': 'XU100', 'name': 'BIST 100', 'count': 100}, ...]

# Tüm BIST endeksleri (79 endeks)
print(bp.all_indices())
# [{'symbol': 'X030C', 'name': 'BIST 30 Capped', 'count': 30}, ...]

# Endeks verisi
xu100 = bp.Index("XU100")
print(xu100.info)                    # Güncel değer, değişim
print(xu100.history(period="1ay"))   # OHLCV geçmişi
```

### Endeks Bileşenleri

```python
# Endeks içindeki hisseler
xu030 = bp.Index("XU030")
print(xu030.components)              # [{'symbol': 'AKBNK', 'name': 'AKBANK'}, ...]
print(xu030.component_symbols)       # ['AKBNK', 'ASELS', 'BIMAS', ...]
print(len(xu030.components))         # 30

# Katılım endeksleri
xk030 = bp.Index("XK030")            # BIST Katılım 30
print(xk030.components)              # Faizsiz finans uyumlu 30 hisse
print(xk030.component_symbols)

xktum = bp.Index("XKTUM")            # BIST Katılım Tüm
print(len(xktum.components))         # 218 hisse
```

### Desteklenen Endeksler

| Kategori | Endeksler |
|----------|-----------|
| Ana | XU100, XU050, XU030, XUTUM |
| Katılım | XKTUM, XK100, XK050, XK030, XKTMT |
| Sektör | XBANK, XUSIN, XUMAL, XUTEK, XGIDA, XHOLD, ... |
| Tematik | XSRDK, XKURY, XYLDZ, XSPOR, XGMYO, ... |
| Şehir | XSIST, XSANK, XSIZM, XSBUR, ... |

---

## FX (Döviz ve Emtia)

Döviz kurları ve emtia fiyatları. **65 döviz** desteği.

### Döviz Kurları

```python
import borsapy as bp

usd = bp.FX("USD")
print(usd.current)                  # Güncel kur
print(usd.history(period="1ay"))    # Geçmiş veriler (günlük)

# Majör dövizler
eur = bp.FX("EUR")
gbp = bp.FX("GBP")
chf = bp.FX("CHF")
jpy = bp.FX("JPY")
cad = bp.FX("CAD")
aud = bp.FX("AUD")

# Diğer dövizler (65 döviz destekleniyor)
rub = bp.FX("RUB")    # Rus Rublesi
cny = bp.FX("CNY")    # Çin Yuanı
sar = bp.FX("SAR")    # Suudi Riyali
aed = bp.FX("AED")    # BAE Dirhemi
inr = bp.FX("INR")    # Hindistan Rupisi
# ... ve daha fazlası
```

### Dakikalık/Saatlik Veri (TradingView)

Bazı döviz çiftleri için intraday (dakikalık/saatlik) veri TradingView üzerinden sağlanır.

> 💡 **Gerçek Zamanlı Veri:** TradingView verileri varsayılan olarak ~15 dakika gecikmeli. Gerçek zamanlı veri için [TradingView Kimlik Doğrulama](#tradingview-kimlik-doğrulama-gerçek-zamanlı-veri) bölümüne bakın.

```python
import borsapy as bp

usd = bp.FX("USD")

# Dakikalık veri
df = usd.history(period="1g", interval="1m")    # Son 1 gün, 1 dakikalık
df = usd.history(period="1g", interval="5m")    # 5 dakikalık
df = usd.history(period="1g", interval="15m")   # 15 dakikalık
df = usd.history(period="1g", interval="30m")   # 30 dakikalık

# Saatlik veri
df = usd.history(period="5g", interval="1h")    # Son 5 gün, saatlik
df = usd.history(period="1ay", interval="4h")   # Son 1 ay, 4 saatlik

# Günlük ve üstü (varsayılan, canlidoviz kullanır)
df = usd.history(period="1ay", interval="1d")   # Günlük
df = usd.history(period="1ay")                  # Günlük (varsayılan)
```

**İntraday Destekleyen Dövizler (TradingView):**

| Döviz | Symbol | Not |
|-------|--------|-----|
| USD/TRY | `USD` | FX:USDTRY |
| EUR/TRY | `EUR` | FX:EURTRY |
| GBP/TRY | `GBP` | PEPPERSTONE:GBPTRY |
| TRY/JPY | `JPY` | FX:TRYJPY (ters çift) |

**İntraday Destekleyen Emtialar (TradingView):**

| Emtia | Symbol | Not |
|-------|--------|-----|
| Altın (Ons/USD) | `ons-altin` veya `XAU` | OANDA:XAUUSD |
| Gümüş (Ons/USD) | `XAG` | OANDA:XAGUSD |
| Platin (USD) | `XPT` | OANDA:XPTUSD |
| Paladyum (USD) | `XPD` | OANDA:XPDUSD |
| Brent Petrol | `BRENT` | TVC:UKOIL |
| WTI Petrol | `WTI` | TVC:USOIL |

> **Not**: Diğer dövizler (CHF, CAD, AUD, vb.) için TradingView'da TRY çifti bulunmadığından sadece günlük veri mevcuttur (canlidoviz.com). İntraday desteklenmeyen bir döviz için interval belirtilirse hata verir.

### Desteklenen Dövizler

| Kategori | Dövizler |
|----------|----------|
| Majör | USD, EUR, GBP, CHF, JPY, CAD, AUD, NZD |
| Avrupa | DKK, SEK, NOK, PLN, CZK, HUF, RON, BGN, HRK, RSD, BAM, MKD, ALL, MDL, UAH, BYR, ISK |
| Ortadoğu & Afrika | AED, SAR, QAR, KWD, BHD, OMR, JOD, IQD, IRR, LBP, SYP, EGP, LYD, TND, DZD, MAD, ZAR, ILS |
| Asya & Pasifik | CNY, INR, PKR, LKR, IDR, MYR, THB, PHP, KRW, KZT, AZN, GEL, SGD, HKD, TWD |
| Amerika | MXN, BRL, ARS, CLP, COP, PEN, UYU, CRC |
| Diğer | RUB, DVZSP1 (Sepet Kur) |

### Banka Kurları

```python
import borsapy as bp

usd = bp.FX("USD")

# Tüm bankaların kurları
print(usd.bank_rates)               # DataFrame: bank, buying, selling, updated
#          bank  buying  selling              updated
# 0      Akbank   34.85    35.15  2024-01-15 10:30:00
# 1    Garanti   34.82    35.12  2024-01-15 10:28:00
# ...

# Tek banka kuru
print(usd.bank_rate("akbank"))      # {'buying': 34.85, 'selling': 35.15, ...}
print(usd.bank_rate("garanti"))

# Desteklenen bankalar
print(bp.banks())                   # ['akbank', 'garanti', 'isbank', ...]
```

### Altın ve Emtialar

```python
# Altın (TRY)
gram_altin = bp.FX("gram-altin")
ceyrek = bp.FX("ceyrek-altin")
yarim = bp.FX("yarim-altin")
tam = bp.FX("tam-altin")
cumhuriyet = bp.FX("cumhuriyet-altin")
ata = bp.FX("ata-altin")

# Diğer değerli metaller (TRY)
gumus = bp.FX("gram-gumus")
ons_altin = bp.FX("ons-altin")
platin = bp.FX("gram-platin")

# Emtia (USD)
brent = bp.FX("BRENT")           # Brent Petrol
silver = bp.FX("XAG-USD")        # Gümüş Ons
platinum = bp.FX("XPT-USD")      # Platin Spot
palladium = bp.FX("XPD-USD")     # Paladyum Spot

print(gram_altin.current)
print(gram_altin.history(period="1ay"))
```

### Kurum Fiyatları (Kuyumcu/Banka)

```python
# Değerli metal kurum fiyatları
gold = bp.FX("gram-altin")

# Tüm kurumların fiyatları
print(gold.institution_rates)
#       institution institution_name       asset      buy     sell  spread
# 0     altinkaynak      Altınkaynak  gram-altin  6315.00  6340.00    0.40
# 1          akbank           Akbank  gram-altin  6310.00  6330.00    0.32

# Tek kurum fiyatı
print(gold.institution_rate("kapalicarsi"))
print(gold.institution_rate("akbank"))

# Desteklenen emtialar
print(bp.metal_institutions())
# ['gram-altin', 'gram-gumus', 'ons-altin', 'gram-platin']
```

### Kurum Bazlı Geçmiş (Metal + Döviz)

```python
# Metal geçmişi
gold = bp.FX("gram-altin")
gold.institution_history("akbank", period="1mo")       # Akbank 1 aylık
gold.institution_history("kapalicarsi", period="3mo")  # Kapalıçarşı 3 aylık

# Döviz geçmişi
usd = bp.FX("USD")
usd.institution_history("akbank", period="1mo")        # Akbank USD 1 aylık
usd.institution_history("garanti-bbva", period="5d")   # Garanti 5 günlük

# 27 kurum destekleniyor (bankalar + kuyumcular)
# Kuyumcular (kapalicarsi, harem, altinkaynak) OHLC verir
# Bankalar (akbank, garanti) sadece Close verir
```

---

## Crypto (Kripto Para)

BtcTurk üzerinden kripto para verileri.

```python
import borsapy as bp

# Mevcut çiftler
print(bp.crypto_pairs())

# Bitcoin/TRY
btc = bp.Crypto("BTCTRY")
print(btc.current)                  # Güncel fiyat
print(btc.history(period="1ay"))    # OHLCV geçmişi

# Ethereum/TRY
eth = bp.Crypto("ETHTRY")
print(eth.current)
```

---

## Fund (Yatırım ve Emeklilik Fonları)

TEFAS üzerinden yatırım fonu ve emeklilik fonu verileri.

### Temel Kullanım

```python
import borsapy as bp

# Fon arama
print(bp.search_funds("banka"))

# Yatırım Fonu (YAT) - varsayılan
fon = bp.Fund("AAK")
print(fon.info)                     # Fon bilgileri
print(fon.history(period="1mo"))    # Fiyat geçmişi
print(fon.performance)              # Performans verileri

# Emeklilik Fonu (EMK) - explicit
emk = bp.Fund("KJM", fund_type="EMK")
print(emk.info)                     # Emeklilik fonu bilgileri
print(emk.history(period="1mo"))    # Fiyat geçmişi

# Auto-detection: fund_type belirtilmezse otomatik algılanır
emk = bp.Fund("KJM")                # Otomatik olarak EMK algılanır
print(emk.fund_type)                # "EMK"
```

### Fon Tipleri

| Kod | Açıklama | Örnek |
|-----|----------|-------|
| `YAT` | Yatırım Fonları (Investment Funds) | `bp.Fund("AAK")` |
| `EMK` | Emeklilik Fonları (Pension Funds) | `bp.Fund("KJM", fund_type="EMK")` |

> **Not**: `fund_type` belirtilmezse otomatik algılama yapılır (önce YAT, sonra EMK denenir).

### Varlık Dağılımı

```python
# Portföy varlık dağılımı
print(fon.allocation)               # Son 7 günlük dağılım
print(fon.allocation_history(period="3ay"))  # Son 3 ay (max ~100 gün)
#         date     asset_type    asset_name  weight
# 0 2024-01-15   Hisse Senedi        Stocks   45.2
# 1 2024-01-15      Ters-Repo  Reverse Repo   30.1
# ...

# info içinde de mevcut (ekstra API çağrısı yok)
print(fon.info['allocation'])
print(fon.info['isin'])             # ISIN kodu
print(fon.info['daily_return'])     # Günlük getiri
print(fon.info['weekly_return'])    # Haftalık getiri
print(fon.info['category_rank'])    # Kategori sırası (örn: 20/181)
```

### Fon Tarama

```python
# Yatırım fonlarını filtrele (varsayılan)
df = bp.screen_funds(fund_type="YAT", min_return_1y=50)   # >%50 1Y getiri
df = bp.screen_funds(min_return_1m=5)                     # Son 1 ayda >%5

# Emeklilik fonlarını filtrele
df = bp.screen_funds(fund_type="EMK")                     # Tüm emeklilik fonları
df = bp.screen_funds(fund_type="EMK", min_return_ytd=20)  # >%20 YTD getiri
df = bp.screen_funds(fund_type="EMK", min_return_1y=30)   # >%30 1Y getiri

# Fon tipleri: "YAT" (yatırım - varsayılan), "EMK" (emeklilik)
```

### Fon Karşılaştırma

```python
# Birden fazla fonu karşılaştır (max 10)
result = bp.compare_funds(["AAK", "TTE", "AFO"])

print(result['funds'])              # Fon detayları listesi
print(result['rankings'])           # Sıralamalar
#   by_return_1y: ['AFO', 'TTE', 'AAK']
#   by_size: ['AFO', 'TTE', 'AAK']
#   by_risk_asc: ['AAK', 'TTE', 'AFO']

print(result['summary'])            # Özet
#   fund_count: 3
#   total_size: 23554985554.72
#   avg_return_1y: 53.65
#   best_return_1y: 100.84
#   worst_return_1y: 28.15
```

### Risk Metrikleri

```python
fon = bp.Fund("YAY")

# Sharpe oranı (10Y tahvil faizi ile)
print(fon.sharpe_ratio())              # 1Y Sharpe
print(fon.sharpe_ratio(period="3y"))   # 3Y Sharpe

# Tüm risk metrikleri
metrics = fon.risk_metrics(period="1y")
print(metrics['annualized_return'])     # Yıllık getiri (%)
print(metrics['annualized_volatility']) # Yıllık volatilite (%)
print(metrics['sharpe_ratio'])          # Sharpe oranı
print(metrics['sortino_ratio'])         # Sortino oranı (downside risk)
print(metrics['max_drawdown'])          # Maksimum düşüş (%)

# Uzun dönem desteği
fon.history(period="3y")   # 3 yıllık veri
fon.history(period="5y")   # 5 yıllık veri
fon.history(period="max")  # Tüm veri (5 yıla kadar)
```

---

## Portfolio (Portföy Yönetimi)

Çoklu varlık portföylerini yönetme, performans takibi ve risk metrikleri.

### Temel Kullanım

```python
import borsapy as bp
from datetime import date

# Portföy oluşturma
portfolio = bp.Portfolio()

# Varlık ekleme (4 tip destekleniyor)
portfolio.add("THYAO", shares=100, cost=280.0)          # Hisse - adet + maliyet
portfolio.add("GARAN", shares=200)                       # Hisse - güncel fiyattan
portfolio.add("gram-altin", shares=10, asset_type="fx")  # Emtia/Döviz (FX)
portfolio.add("USD", shares=1000, asset_type="fx")       # Döviz
portfolio.add("BTCTRY", shares=0.5)                      # Kripto (auto-detect)
portfolio.add("YAY", shares=1000, asset_type="fund")     # Yatırım Fonu

# Alım tarihi ile ekleme (getiri hesaplamaları için)
portfolio.add("ASELS", shares=50, cost=120.0, purchase_date="2024-01-15")  # String format
portfolio.add("BIMAS", shares=30, cost=150.0, purchase_date=date(2024, 6, 1))  # date objesi

# Benchmark ayarlama (Index karşılaştırması için)
portfolio.set_benchmark("XU100")                         # XU030, XK030 da olabilir

# Portföy durumu
print(portfolio.holdings)     # DataFrame: symbol, shares, cost, value, weight, pnl, purchase_date, holding_days
print(portfolio.value)        # Toplam değer (TL)
print(portfolio.cost)         # Toplam maliyet
print(portfolio.pnl)          # Kar/zarar (TL)
print(portfolio.pnl_pct)      # Kar/zarar (%)
print(portfolio.weights)      # {'THYAO': 0.45, 'GARAN': 0.35, ...}
```

### Alım Tarihi (purchase_date)

Holdinglere alım tarihi eklenerek daha isabetli getiri hesaplamaları yapılabilir:

```python
import borsapy as bp
from datetime import date

portfolio = bp.Portfolio()

# Farklı tarihlerde alınmış hisseler
portfolio.add("THYAO", shares=100, cost=280.0, purchase_date="2024-01-15")
portfolio.add("GARAN", shares=200, cost=45.0, purchase_date=date(2024, 6, 1))
portfolio.add("ASELS", shares=50, cost=120.0)  # Tarih verilmezse bugün

# Holdings DataFrame'de purchase_date ve holding_days sütunları
print(portfolio.holdings[['symbol', 'cost', 'purchase_date', 'holding_days']])
#   symbol  cost purchase_date  holding_days
# 0  THYAO   280    2024-01-15           380
# 1  GARAN    45    2024-06-01           242
# 2  ASELS   120    2026-01-29             0

# Risk metrikleri artık holding bazlı tarih kullanır
# Her holding için sadece purchase_date sonrası veriler dahil edilir
metrics = portfolio.risk_metrics(period="1y")
```

**Desteklenen Tarih Formatları:**
| Format | Örnek | Açıklama |
|--------|-------|----------|
| `str` | `"2024-01-15"` | ISO format (YYYY-MM-DD) |
| `date` | `date(2024, 1, 15)` | Python date objesi |
| `datetime` | `datetime(2024, 1, 15)` | Sadece tarih kısmı kullanılır |
| `None` | - | Bugünün tarihi varsayılan |

### Desteklenen Varlık Tipleri

| Tip | Sınıf | Otomatik Algılama | Örnekler |
|-----|-------|-------------------|----------|
| **stock** | `Ticker` | Varsayılan | THYAO, GARAN, ASELS |
| **fx** | `FX` | ✅ 65 döviz + metaller + emtia | USD, EUR, gram-altin, BRENT |
| **crypto** | `Crypto` | ✅ *TRY pattern (6+ karakter) | BTCTRY, ETHTRY |
| **fund** | `Fund` | ❌ `asset_type="fund"` gerekli | AAK, TTE, YAY |

**Not**: Index'ler (XU100, XU030) satın alınamaz, **benchmark** olarak kullanılır.

### Performans ve Geçmiş

```python
# Geçmiş performans (mevcut pozisyonlarla)
hist = portfolio.history(period="1y")
print(hist)
#                   Value  Daily_Return
# Date
# 2024-01-02  150000.00           NaN
# 2024-01-03  152300.00      0.0153
# ...

# Performans özeti
print(portfolio.performance)
# {'total_return': 25.5, 'total_value': 187500.0, 'total_cost': 150000.0, 'total_pnl': 37500.0}
```

### Risk Metrikleri

```python
# Tüm risk metrikleri
metrics = portfolio.risk_metrics(period="1y")
print(metrics)
# {'annualized_return': 18.2,
#  'annualized_volatility': 22.5,
#  'sharpe_ratio': 0.65,
#  'sortino_ratio': 0.82,
#  'max_drawdown': -15.3,
#  'beta': 1.12,
#  'alpha': 2.5,
#  'risk_free_rate': 28.0,
#  'trading_days': 252}

# Kısa yollar
print(portfolio.sharpe_ratio())           # Sharpe oranı
print(portfolio.sortino_ratio())          # Sortino oranı
print(portfolio.beta())                   # Benchmark'a göre beta (varsayılan: XU100)
print(portfolio.beta(benchmark="XU030"))  # Farklı benchmark

# Korelasyon matrisi
corr = portfolio.correlation_matrix(period="1y")
print(corr)
#          THYAO    GARAN  gram-altin
# THYAO     1.00     0.75       0.15
# GARAN     0.75     1.00       0.12
# gram-altin 0.15    0.12       1.00
```

### Varlık Yönetimi

```python
# Varlık güncelleme
portfolio.update("THYAO", shares=150, cost=290.0)

# Varlık kaldırma
portfolio.remove("GARAN")

# Portföyü temizle
portfolio.clear()

# Method chaining
portfolio.add("THYAO", shares=100, cost=280).add("GARAN", shares=200, cost=50).set_benchmark("XU030")
```

### Import/Export

```python
# Dict olarak export
data = portfolio.to_dict()
print(data)
# {'benchmark': 'XU100', 'holdings': [
#     {'symbol': 'THYAO', 'shares': 100, 'cost_per_share': 280.0,
#      'asset_type': 'stock', 'purchase_date': '2024-01-15'},
#     ...
# ]}

# Dict'ten import (purchase_date korunur)
portfolio2 = bp.Portfolio.from_dict(data)

# JSON'a kaydetme
import json
with open("portfolio.json", "w") as f:
    json.dump(portfolio.to_dict(), f)

# JSON'dan yükleme
with open("portfolio.json") as f:
    portfolio3 = bp.Portfolio.from_dict(json.load(f))
```

### Teknik Analiz (TechnicalMixin)

Portfolio sınıfı TechnicalMixin'den miras aldığı için teknik göstergeleri de kullanabilir:

```python
# Portfolio history üzerinde teknik analiz
portfolio.rsi()                    # RSI
portfolio.sma()                    # SMA
portfolio.macd()                   # MACD
portfolio.bollinger_bands()        # Bollinger Bands
```

---

## Teknik Analiz

Tüm varlık sınıfları için teknik analiz göstergeleri (Ticker, Index, Crypto, FX, Fund).

> 💡 **TradingView Entegrasyonu:** Teknik göstergeler (RSI, MACD, BB, ADX, ATR, Stochastic) TradingView Scanner API üzerinden hesaplanır. Bu sayede TradingView'daki değerlerle birebir uyumlu sonuçlar alırsınız. Varsayılan olarak ~15 dakika gecikmeli veri kullanılır. Gerçek zamanlı veri için [TradingView Kimlik Doğrulama](#tradingview-kimlik-doğrulama-gerçek-zamanlı-veri) bölümüne bakın.

### Tekil Değerler

```python
import borsapy as bp

hisse = bp.Ticker("THYAO")

# RSI (Relative Strength Index)
print(hisse.rsi())                    # 65.2 (son değer)
print(hisse.rsi(rsi_period=7))        # 7 periyotluk RSI

# Hareketli Ortalamalar
print(hisse.sma())                    # 20 günlük SMA
print(hisse.sma(sma_period=50))       # 50 günlük SMA
print(hisse.ema(ema_period=12))       # 12 günlük EMA

# MACD
print(hisse.macd())
# {'macd': 2.5, 'signal': 1.8, 'histogram': 0.7}

# Bollinger Bands
print(hisse.bollinger_bands())
# {'upper': 310.2, 'middle': 290.5, 'lower': 270.8}

# Stochastic
print(hisse.stochastic())
# {'k': 75.2, 'd': 68.5}

# ATR (Average True Range)
print(hisse.atr())                    # 4.25

# OBV (On-Balance Volume)
print(hisse.obv())                    # 1250000

# VWAP (Volume Weighted Average Price)
print(hisse.vwap())                   # 285.5

# ADX (Average Directional Index)
print(hisse.adx())                    # 32.5
```

### TechnicalAnalyzer ile Tam Seriler

```python
import borsapy as bp

hisse = bp.Ticker("THYAO")

# TechnicalAnalyzer oluştur
ta = hisse.technicals(period="1y")

# Tüm göstergelerin son değerleri
print(ta.latest)
# {'sma_20': 285.5, 'ema_12': 287.2, 'rsi_14': 65.2, 'macd': 2.5, ...}

# Tek tek seriler (pd.Series)
print(ta.rsi())                       # 252 değerlik RSI serisi
print(ta.sma(20))                     # 20 günlük SMA serisi
print(ta.ema(12))                     # 12 günlük EMA serisi

# DataFrame döndürenler
print(ta.macd())                      # MACD, Signal, Histogram sütunları
print(ta.bollinger_bands())           # BB_Upper, BB_Middle, BB_Lower
print(ta.stochastic())                # Stoch_K, Stoch_D
```

### DataFrame ile Tüm Göstergeler

```python
import borsapy as bp

hisse = bp.Ticker("THYAO")

# OHLCV + tüm göstergeler tek DataFrame'de
df = hisse.history_with_indicators(period="3ay")
print(df.columns)
# ['Open', 'High', 'Low', 'Close', 'Volume', 'SMA_20', 'EMA_12',
#  'RSI_14', 'MACD', 'Signal', 'Histogram', 'BB_Upper', 'BB_Middle',
#  'BB_Lower', 'ATR_14', 'Stoch_K', 'Stoch_D', 'OBV', 'VWAP', 'ADX_14']

# Sadece belirli göstergeler
df = hisse.history_with_indicators(period="1ay", indicators=["sma", "rsi", "macd"])
```

### Tüm Varlık Sınıflarında Çalışır

```python
import borsapy as bp

# Hisse
bp.Ticker("THYAO").rsi()

# Endeks
bp.Index("XU100").macd()

# Kripto
bp.Crypto("BTCTRY").bollinger_bands()

# Döviz (Volume gerektiren göstergeler NaN döner)
bp.FX("USD").rsi()

# Yatırım Fonu
bp.Fund("AAK").stochastic()

# Altın
bp.FX("gram-altin").sma()
```

### Standalone Fonksiyonlar

```python
import borsapy as bp
from borsapy.technical import (
    calculate_sma, calculate_ema, calculate_rsi, calculate_macd,
    calculate_bollinger_bands, calculate_atr, calculate_stochastic,
    calculate_obv, calculate_vwap, calculate_adx, calculate_supertrend,
    calculate_tilson_t3, add_indicators
)

# Herhangi bir DataFrame üzerinde kullanım
df = bp.download("THYAO", period="1y")

# Tekil göstergeler
rsi = calculate_rsi(df, period=14)
macd_df = calculate_macd(df, fast=12, slow=26, signal=9)
bb_df = calculate_bollinger_bands(df, period=20, std_dev=2.0)

# Tüm göstergeleri ekle
df_with_indicators = add_indicators(df)
df_with_indicators = add_indicators(df, indicators=["sma", "rsi"])  # Sadece belirli göstergeler
```

### Desteklenen Göstergeler

| Gösterge | Metod | Açıklama |
|----------|-------|----------|
| SMA | `sma()` | Basit Hareketli Ortalama |
| EMA | `ema()` | Üstel Hareketli Ortalama |
| RSI | `rsi()` | Göreceli Güç Endeksi (0-100) |
| MACD | `macd()` | Hareketli Ortalama Yakınsama/Iraksama |
| Bollinger Bands | `bollinger_bands()` | Üst/Orta/Alt bantlar |
| ATR | `atr()` | Ortalama Gerçek Aralık |
| Stochastic | `stochastic()` | Stokastik Osilatör (%K, %D) |
| OBV | `obv()` | Denge Hacmi (Volume gerektirir) |
| VWAP | `vwap()` | Hacim Ağırlıklı Ortalama Fiyat (Volume gerektirir) |
| ADX | `adx()` | Ortalama Yön Endeksi (0-100) |
| Supertrend | `supertrend()` | Trend takip göstergesi (ATR-tabanlı) |
| Tilson T3 | `tilson_t3()` | Triple-smoothed EMA (düşük gecikme) |

### Supertrend

ATR-tabanlı trend takip göstergesi.

```python
import borsapy as bp

stock = bp.Ticker("THYAO")

# Son değerler
st = stock.supertrend()
print(st['value'])       # 282.21 (Supertrend çizgisi)
print(st['direction'])   # 1 (bullish) veya -1 (bearish)
print(st['upper'])       # 303.69 (üst band)
print(st['lower'])       # 282.21 (alt band)

# Custom parametreler
st = stock.supertrend(period="6mo", atr_period=7, multiplier=2.0)

# TechnicalAnalyzer ile tüm seriler
ta = stock.technicals(period="1y")
st_df = ta.supertrend()  # DataFrame: Supertrend, Direction, Upper, Lower

# Pure function
df = stock.history(period="1y")
st_df = bp.calculate_supertrend(df, atr_period=10, multiplier=3.0)
```

**Supertrend Yorumlama:**
- `direction = 1`: Bullish trend (fiyat Supertrend üzerinde)
- `direction = -1`: Bearish trend (fiyat Supertrend altında)
- Trend değişimi: direction'ın işaret değiştirmesi

### Tilson T3

Triple-smoothed EMA ile düşük gecikmeli hareketli ortalama.

```python
import borsapy as bp

stock = bp.Ticker("THYAO")

# Son değer
t3 = stock.tilson_t3()              # 296.24
t3 = stock.tilson_t3(t3_period=8)   # Farklı period

# TechnicalAnalyzer ile
ta = stock.technicals(period="1y")
t3_series = ta.tilson_t3(period=5, vfactor=0.7)

# Pure function
df = stock.history(period="1y")
t3_series = bp.calculate_tilson_t3(df, period=5, vfactor=0.7)
```

**Tilson T3 Parametreleri:**
- `period`: T3 periyodu (varsayılan 5)
- `vfactor`: Volume faktörü (varsayılan 0.7)
  - 0.5 = daha responsive (hızlı tepki)
  - 0.7 = Tilson'ın önerisi
  - 0.9 = daha smooth (pürüzsüz)

### Heikin Ashi Charts

Alternatif mum grafiği hesaplama yöntemi.

```python
import borsapy as bp

stock = bp.Ticker("THYAO")

# Pure function ile
df = stock.history(period="1y")
ha_df = bp.calculate_heikin_ashi(df)
# Sütunlar: HA_Open, HA_High, HA_Low, HA_Close, Volume

# Convenience method
ha_df = stock.heikin_ashi(period="1y")

# TechnicalAnalyzer ile
ta = stock.technicals(period="1y")
ha_df = ta.heikin_ashi()
```

**Heikin Ashi Formülü:**
```
HA_Close = (Open + High + Low + Close) / 4
HA_Open  = (Prev_HA_Open + Prev_HA_Close) / 2  (ilk satır: (O+C)/2)
HA_High  = max(High, HA_Open, HA_Close)
HA_Low   = min(Low, HA_Open, HA_Close)
```

### TradingView TA Sinyalleri

TradingView Scanner API ile teknik analiz sinyalleri (AL/SAT/TUT).

> 💡 **Gerçek Zamanlı Veri:** Varsayılan olarak ~15 dakika gecikmeli. Gerçek zamanlı sinyaller için [TradingView Kimlik Doğrulama](#tradingview-kimlik-doğrulama-gerçek-zamanlı-veri) bölümüne bakın.

```python
import borsapy as bp

stock = bp.Ticker("THYAO")

# Tek timeframe (varsayılan: günlük)
signals = stock.ta_signals()
print(signals['summary']['recommendation'])  # "STRONG_BUY", "BUY", "NEUTRAL", "SELL", "STRONG_SELL"
print(signals['summary']['buy'])             # 12 (AL sinyali veren gösterge sayısı)
print(signals['oscillators']['compute']['RSI'])  # "BUY", "SELL", "NEUTRAL"
print(signals['moving_averages']['values']['EMA20'])  # 285.5

# Belirli timeframe
signals_1h = stock.ta_signals(interval="1h")   # Saatlik
signals_4h = stock.ta_signals(interval="4h")   # 4 saatlik
signals_1w = stock.ta_signals(interval="1W")   # Haftalık

# Tüm timeframe'ler tek seferde
all_signals = stock.ta_signals_all_timeframes()
print(all_signals['1h']['summary']['recommendation'])
print(all_signals['1d']['summary']['recommendation'])
print(all_signals['1W']['summary']['recommendation'])

# Diğer varlık sınıfları için de çalışır
bp.Index("XU100").ta_signals()
bp.FX("USD").ta_signals()
bp.Crypto("BTCTRY").ta_signals()
```

**Desteklenen Timeframe'ler:** `1m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `1d`, `1W`, `1M`

**Sinyal Çıktı Formatı:**
```python
{
    "symbol": "THYAO",
    "exchange": "BIST",
    "interval": "1d",
    "summary": {
        "recommendation": "BUY",  # STRONG_BUY, BUY, NEUTRAL, SELL, STRONG_SELL
        "buy": 12, "sell": 5, "neutral": 9
    },
    "oscillators": {
        "recommendation": "NEUTRAL",
        "buy": 2, "sell": 2, "neutral": 7,
        "compute": {"RSI": "NEUTRAL", "MACD": "SELL", ...},
        "values": {"RSI": 48.95, "MACD.macd": 3.78, ...}
    },
    "moving_averages": {
        "recommendation": "BUY",
        "buy": 10, "sell": 3, "neutral": 2,
        "compute": {"EMA10": "BUY", "SMA20": "BUY", ...},
        "values": {"EMA10": 285.5, "SMA20": 284.2, ...}
    }
}
```

---

## Gerçek Zamanlı Veri Akışı (TradingView Streaming)

Düşük gecikmeli, yüksek verimli gerçek zamanlı veri akışı. Persistent WebSocket bağlantısı ile anlık fiyat ve mum verisi.

> ⚠️ **Önemli:** Varsayılan olarak TradingView verileri ~15 dakika gecikmeli. Gerçek zamanlı BIST verisi için TradingView Pro hesabı ve BIST veri paketi gerekir. Detaylar için [TradingView Kimlik Doğrulama](#tradingview-kimlik-doğrulama-gerçek-zamanlı-veri) bölümüne bakın.

### Temel Kullanım

```python
import borsapy as bp

# Stream oluştur ve bağlan
stream = bp.TradingViewStream()
stream.connect()

# Sembollere abone ol
stream.subscribe("THYAO")
stream.subscribe("GARAN")
stream.subscribe("ASELS")

# Anlık fiyat al (cached, <1ms)
quote = stream.get_quote("THYAO")
print(quote['last'])           # 299.0
print(quote['bid'])            # 298.9
print(quote['ask'])            # 299.1
print(quote['volume'])         # 12345678
print(quote['change_percent']) # 2.5

# İlk quote için bekle (blocking)
quote = stream.wait_for_quote("THYAO", timeout=5.0)

# Callback ile real-time updates
def on_price_update(symbol, quote):
    print(f"{symbol}: {quote['last']} ({quote['change_percent']:+.2f}%)")

stream.on_quote("THYAO", on_price_update)

# Tüm semboller için callback
stream.on_any_quote(lambda s, q: print(f"{s}: {q['last']}"))

# Bağlantıyı kapat
stream.disconnect()
```

### Context Manager Kullanımı

```python
import borsapy as bp

with bp.TradingViewStream() as stream:
    stream.subscribe("THYAO")
    quote = stream.wait_for_quote("THYAO", timeout=5.0)
    print(quote['last'])
```

### Chart Verileri (OHLCV Streaming)

Gerçek zamanlı mum grafiği verisi.

```python
import borsapy as bp

stream = bp.TradingViewStream()
stream.connect()

# Mum grafiği aboneliği
stream.subscribe_chart("THYAO", "1m")   # 1 dakikalık mumlar
stream.subscribe_chart("GARAN", "5m")   # 5 dakikalık mumlar
stream.subscribe_chart("ASELS", "1h")   # Saatlik mumlar

# Callback ile mum güncellemeleri
def on_candle(symbol, interval, candle):
    print(f"{symbol} {interval}: O={candle['open']} H={candle['high']} L={candle['low']} C={candle['close']}")

stream.on_candle("THYAO", "1m", on_candle)

# Tüm mumlar için callback
stream.on_any_candle(lambda s, i, c: print(f"{s} {i}: {c['close']}"))

# Cached mum verisi al
candle = stream.get_candle("THYAO", "1m")
candles = stream.get_candles("THYAO", "1m")  # Tüm mumlar (list)

# İlk mum için bekle
candle = stream.wait_for_candle("THYAO", "1m", timeout=10.0)

stream.disconnect()
```

**Desteklenen Timeframe'ler:** `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`, `1wk`, `1mo`

### TradingView Kimlik Doğrulama (Gerçek Zamanlı Veri)

Varsayılan olarak TradingView verileri ~15 dakika gecikmeli. Gerçek zamanlı BIST verisi için TradingView'da aşağıdaki aboneliklere ihtiyacınız var:

1. **Essential** veya üzeri plan (Pro, Pro+, Premium)
2. **BIST Real-time Market Data** paketi (ek ücretli)

> TradingView hesabınızda: Profil → Hesap ve Faturalama → Piyasa Verileri Abonelikleri → "Borsa Istanbul" ekleyin.

```python
import borsapy as bp

# Yöntem 1: Username/Password ile login
bp.set_tradingview_auth(
    username="user@email.com",
    password="mypassword"
)

# Yöntem 2: Mevcut session token ile
bp.set_tradingview_auth(
    session="abc123...",          # sessionid cookie
    session_sign="xyz789..."      # sessionid_sign cookie
)

# Artık gerçek zamanlı veri
stream = bp.TradingViewStream()
stream.connect()
stream.subscribe("THYAO")
quote = stream.wait_for_quote("THYAO")
print(quote['last'])  # Gerçek zamanlı fiyat

# Logout
bp.clear_tradingview_auth()
```

**Session süresi:** ~30 gün (remember=on ile)

**Chrome DevTools ile Cookie Alma:**

1. TradingView'a giriş yapın (tradingview.com)
2. `F12` veya `Ctrl+Shift+I` ile DevTools'u açın
3. **Application** sekmesine gidin
4. Sol menüden **Cookies** → `https://www.tradingview.com` seçin
5. Aşağıdaki cookie'leri bulun ve değerlerini kopyalayın:
   - `sessionid` → `session` parametresi
   - `sessionid_sign` → `session_sign` parametresi

```python
bp.set_tradingview_auth(
    session="kopyaladığınız_sessionid_değeri",
    session_sign="kopyaladığınız_sessionid_sign_değeri"
)
```

### Quote