Metadata-Version: 2.4
Name: pyfaiz
Version: 0.1.0
Summary: TCMB Mevduat Faiz Oranları Kütüphanesi
Home-page: https://github.com/cagrigungor/pyfaiz
Author: Hasan Çağrı Güngör
Author-email: iletisim@cagrigungor.com
License: MIT
Project-URL: Homepage, https://github.com/hasancagrigungor/pyfaiz
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.0.0
Dynamic: author-email
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# pyfaiz

**TCMB Mevduat Faiz Oranlari Kutuphanesi (Unofficial)**

Bu kutuphane, Turkiye Cumhuriyet Merkez Bankasi (TCMB) tarafindan yayinlanan mevduat faiz oranlarini kolayca sorgulamanizi saglar. Veri seti 2002 yilindan gunumuze kadar olan gunluk faiz oranlarini icermektedir.

**ONEMLI:** Bu kutuphane resmi bir TCMB urunu degildir. Unofficial (gayri resmi) bir projedir ve TCMB ile herhangi bir baglantisi yoktur. Veriler bilgilendirme amaclidir, yatirim kararlari icin resmi kaynaklara basvurunuz.

---

## Ozellikler

- Tarih araliginda faiz oranlarini sorgulama
- Belirli bir gunun faiz oranlarini alma
- Bugunun faiz oranlarini aninda goruntuleme
- Pandas DataFrame formati ile kolay veri analizi
- Birden fazla tarih formati destegi (YYYY-MM-DD, DD-MM-YYYY, DD/MM/YYYY, YYYY/MM/DD)
- Secmeli sutun filtreleme

---

## Kurulum

### PyPI uzerinden kurulum

```bash
pip install pyfaiz
```

### Kaynak koddan kurulum

```bash
git clone https://github.com/cagrigungor/pyfaiz.git
cd pyfaiz
pip install -e .
```

---

## Hizli Baslangic

```python
from pyfaiz import faiz, faizgun, faizbugun

# Bugunun faiz oranlari
print(faizbugun())
# {'1ay': 42.97, '3ay': 44.38, '6ay': 43.33, '1yil': 41.05, '1yil+': 37.19}

# Belirli bir gunun faiz oranlari
print(faizgun('2024-01-15'))
# {'1ay': 45.12, '3ay': 46.50, '6ay': 47.20, '1yil': 48.00, '1yil+': 49.50}

# Tarih araliginda faiz oranlari (DataFrame)
df = faiz('2024-01-01', '2024-01-10')
print(df)
```

---

## Detayli Kullanim

### 1. faiz() - Tarih Araliginda Faiz Oranlari

Belirtilen tarih araligindaki tum faiz oranlarini Pandas DataFrame olarak dondurur.

```python
from pyfaiz import faiz

# Tum sutunlar
df = faiz('2024-01-01', '2024-01-31')
print(df)
#              1ay    3ay    6ay   1yil  1yil+
# 2024-01-01  45.12  46.50  47.20  48.00  49.50
# 2024-01-02  45.12  46.50  47.20  48.00  49.50
# ...

# Sadece belirli sutunlar
df = faiz('2024-01-01', '2024-01-31', columns=['1ay', '3ay'])
print(df)
#              1ay    3ay
# 2024-01-01  45.12  46.50
# 2024-01-02  45.12  46.50
# ...

# Farkli tarih formatlari
df = faiz('01-01-2024', '31-01-2024')  # DD-MM-YYYY
df = faiz('01/01/2024', '31/01/2024')  # DD/MM/YYYY
df = faiz('2024/01/01', '2024/01/31')  # YYYY/MM/DD
```

**Parametreler:**

| Parametre | Tip | Zorunlu | Aciklama |
|-----------|-----|---------|----------|
| baslangic | str | Evet | Baslangic tarihi |
| bitis | str | Evet | Bitis tarihi |
| columns | list | Hayir | Istenen sutunlar listesi |

**Donus Degeri:** `pandas.DataFrame`

---

### 2. faizgun() - Belirli Bir Gunun Faiz Oranlari

Belirtilen tarihteki faiz oranlarini dictionary olarak dondurur.

```python
from pyfaiz import faizgun

# Tum sutunlar
sonuc = faizgun('2024-06-15')
print(sonuc)
# {'1ay': 50.25, '3ay': 51.00, '6ay': 52.50, '1yil': 53.00, '1yil+': 54.20}

# Sadece belirli sutunlar
sonuc = faizgun('2024-06-15', columns=['1ay', '1yil'])
print(sonuc)
# {'1ay': 50.25, '1yil': 53.00}

# Degerlere erisim
print(sonuc['1ay'])  # 50.25
print(sonuc['1yil'])  # 53.00
```

**Parametreler:**

| Parametre | Tip | Zorunlu | Aciklama |
|-----------|-----|---------|----------|
| tarih | str | Evet | Sorgulanacak tarih |
| columns | list | Hayir | Istenen sutunlar listesi |

**Donus Degeri:** `dict`

---

### 3. faizbugun() - Bugunun Faiz Oranlari

Bugunun faiz oranlarini dictionary olarak dondurur. En son mevcut veri kullanilir.

```python
from pyfaiz import faizbugun

# Tum sutunlar
print(faizbugun())
# {'1ay': 42.97, '3ay': 44.38, '6ay': 43.33, '1yil': 41.05, '1yil+': 37.19}

# Sadece belirli sutunlar
print(faizbugun(columns=['1ay']))
# {'1ay': 42.97}

# Bir degisiklik takibi ornegi
bugun = faizbugun()
print(f"1 Aylik Mevduat Faizi: %{bugun['1ay']}")
print(f"1 Yillik Mevduat Faizi: %{bugun['1yil']}")
```

**Parametreler:**

| Parametre | Tip | Zorunlu | Aciklama |
|-----------|-----|---------|----------|
| columns | list | Hayir | Istenen sutunlar listesi |

**Donus Degeri:** `dict`

---

### 4. Yardimci Fonksiyonlar

#### mevcut_sutunlar()

Mevcut sutun isimlerini listeler.

```python
from pyfaiz import mevcut_sutunlar

print(mevcut_sutunlar())
# ['1ay', '3ay', '6ay', '1yil', '1yil+']
```

#### veri_araligi()

Veri setinin tarih araligini ve toplam gun sayisini dondurur.

```python
from pyfaiz import veri_araligi

print(veri_araligi())
# {'baslangic': '2002-04-19', 'bitis': '2026-03-06', 'gun_sayisi': 8722}
```

---

## Sutun Aciklamalari

| Sutun | Aciklama | Ornek Deger |
|-------|----------|-------------|
| `1ay` | 1 Aylik Mevduat Faiz Orani (%) | 42.97 |
| `3ay` | 3 Aylik Mevduat Faiz Orani (%) | 44.38 |
| `6ay` | 6 Aylik Mevduat Faiz Orani (%) | 43.33 |
| `1yil` | 1 Yillik Mevduat Faiz Orani (%) | 41.05 |
| `1yil+` | 1 Yildan Uzun Vadeli Mevduat Faiz Orani (%) | 37.19 |

---

## Ornek Kullanim Senaryolari

### Senaryo 1: Faiz Oranlarinin Zaman Serisi Analizi

```python
from pyfaiz import faiz
import matplotlib.pyplot as plt

# 2023 yili verilerini al
df = faiz('2023-01-01', '2023-12-31')

# Grafik ciz
plt.figure(figsize=(12, 6))
for col in df.columns:
    plt.plot(df.index, df[col], label=col)

plt.xlabel('Tarih')
plt.ylabel('Faiz Orani (%)')
plt.title('2023 Yili TCMB Mevduat Faiz Oranlari')
plt.legend()
plt.grid(True)
plt.xticks(rotation=45)
plt.tight_layout()
plt.show()
```

### Senaryo 2: Aylik Ortalama Faiz Hesaplama

```python
from pyfaiz import faiz
import pandas as pd

# 2024 yili verilerini al
df = faiz('2024-01-01', '2024-12-31')

# Index'i datetime'a cevir ve aylik ortalama hesapla
df.index = pd.to_datetime(df.index)
aylik_ortalama = df.resample('M').mean()

print(aylik_ortalama)
```

### Senaryo 3: Iki Tarih Arasindaki Faiz Degisimi

```python
from pyfaiz import faizgun

# Iki tarih arasindaki degisimi hesapla
tarih1 = '2024-01-01'
tarih2 = '2024-06-01'

faiz1 = faizgun(tarih1)
faiz2 = faizgun(tarih2)

print(f"Tarih: {tarih1} -> {tarih2}")
print("-" * 40)

for sutun in faiz1.keys():
    degisim = faiz2[sutun] - faiz1[sutun]
    yuzde = (degisim / faiz1[sutun]) * 100
    print(f"{sutun}: {faiz1[sutun]:.2f} -> {faiz2[sutun]:.2f} ({degisim:+.2f}, {yuzde:+.1f}%)")
```

### Senaryo 4: En Yuksek ve En Dusuk Faiz Oranlari

```python
from pyfaiz import faiz

# Tum veriyi al
df = faiz('2002-04-19', '2026-03-06')

print("En Yuksek Faiz Oranlari:")
print(df.max())
print()

print("En Dusuk Faiz Oranlari:")
print(df.min())
print()

print("Ortalama Faiz Oranlari:")
print(df.mean().round(2))
```

### Senaryo 5: CSV'ye Aktarma

```python
from pyfaiz import faiz

# Veriyi al ve CSV'ye kaydet
df = faiz('2020-01-01', '2024-12-31')
df.to_csv('faiz_verileri_2020_2024.csv')

print("Veriler CSV dosyasina kaydedildi.")
```

### Senaryo 6: Excel'e Aktarma

```python
from pyfaiz import faiz

# Veriyi al ve Excel'e kaydet
df = faiz('2020-01-01', '2024-12-31')
df.to_excel('faiz_verileri_2020_2024.xlsx', sheet_name='Faiz Oranlari')

print("Veriler Excel dosyasina kaydedildi.")
```

---

## Hata Yonetimi

Kutuphane, hatali kullanim durumlarinda aciklayici hata mesajlari dondurur.

```python
from pyfaiz import faiz, faizgun

# Gecersiz tarih formati
try:
    faizgun('2024/13/45')
except ValueError as e:
    print(e)
# Gecersiz tarih formati: 2024/13/45. Desteklenen formatlar: YYYY-MM-DD, DD-MM-YYYY, DD/MM/YYYY, YYYY/MM/DD

# Veri araliginin disinda
try:
    faizgun('1990-01-01')
except ValueError as e:
    print(e)
# Veri 2002-04-19 tarihinden basliyor.

# Gecersiz sutun ismi
try:
    faizgun('2024-01-01', columns=['1ay', 'gecersiz'])
except ValueError as e:
    print(e)
# Gecersiz sutun isimleri: ['gecersiz']. Gecerli sutunlar: ['1ay', '3ay', '6ay', '1yil', '1yil+']

# Baslangic tarihi bitis tarihinden buyuk
try:
    faiz('2024-12-31', '2024-01-01')
except ValueError as e:
    print(e)
# Baslangic tarihi bitis tarihinden buyuk olamaz.
```

---

## Veri Kaynagi

Bu kutuphanedeki veriler TCMB (Turkiye Cumhuriyet Merkez Bankasi) tarafindan yayinlanan mevduat faiz oranlarina dayanmaktadir.

**Resmi Kaynak:** [TCMB Elektronik Veri Dagitim Sistemi (EVDS)](https://evds2.tcmb.gov.tr/)

---

## Sinirlamalar

- Veriler 2002-04-19 tarihinden itibaren mevcuttur
- Gelecek tarihler icin sorgulama yapilamaz
- Veriler gunluk olarak guncellenmektedir
- Bu kutuphane offline calisir, canli veri cekimi yapmaz

---

## Gereksinimler

- Python >= 3.8
- pandas >= 1.0.0

---

## Lisans

MIT License

---

## Yazar

**Cagri Gungor**

- Web: [www.cagrigungor.com](https://www.cagrigungor.com)
- E-posta: iletisim@cagrigungor.com
- GitHub: [github.com/cagrigungor](https://github.com/cagrigungor)

---

## Katkida Bulunma

Katkida bulunmak isterseniz:

1. Projeyi fork edin
2. Yeni bir branch olusturun (`git checkout -b feature/yeni-ozellik`)
3. Degisikliklerinizi commit edin (`git commit -am 'Yeni ozellik eklendi'`)
4. Branch'i push edin (`git push origin feature/yeni-ozellik`)
5. Pull Request acin

---

## Degisiklik Gecmisi

### v0.1.0 (2026-03-06)

- Ilk surum
- `faiz()`, `faizgun()`, `faizbugun()` fonksiyonlari
- `mevcut_sutunlar()`, `veri_araligi()` yardimci fonksiyonlari
- 2002-2026 arasi veri seti

---

## Sorumluluk Reddi

Bu kutuphane resmi bir TCMB urunu DEGILDIR. Gayri resmi (unofficial) bir projedir ve TCMB ile herhangi bir baglantisi yoktur. Veriler yalnizca bilgilendirme amaclidir. Yatirim veya finansal kararlar icin resmi TCMB kaynaklarina basvurunuz. Yazar, bu kutuphanenin kullanimindan kaynaklanan herhangi bir zarar veya kayiptan sorumlu tutulamaz.
