tefasfon v0.4.1

Türkçe tercih edenler için:

Those who prefer English can scroll down the page.

Açıklama

tefasfon, Türkiye Elektronik Fon Alım Satım Platformu (TEFAS) sitesinde yayımlanan yatırım/emeklilik fonu verilerinin çekilmesini ve analiz edilmesini sağlayan bir Python kütüphanesidir.

• Web'den tarih aralığı ve fon türüne göre veri çeker.
• Çekilen fiyat verileri üzerinden kümülatif getiri, yıllık getiri, yıllık volatilite ve Sharpe oranı gibi metrikleri hesaplar.
• Mesajlar Türkçe/İngilizce desteklidir; çıktılar doğrudan pandas.DataFrame olarak döner.

Özellikler

• Seçilen tarih aralığında ve fon türünde veri çekimi
• "Genel Bilgiler" veya "Portföy Dağılımı" sekmesi
• İsteğe bağlı Excel'e kaydetme
• Türkçe/İngilizce bilgi ve hata mesajları
• Basit veya logaritmik getiri ile performans analizi
• Selenium + ChromeDriver ile canlı web verisine erişim

Kurulum

Kütüphaneyi yüklemek için şu adımları izleyin:

1. Python'ı yükleyin: https://www.python.org/downloads/
2. Terminal veya komut istemcisinde aşağıdaki komutu çalıştırın:

pip install tefasfon

Belirli bir versiyonu yüklemek için:

pip install tefasfon==0.4.1

Yüklü versiyonu görüntülemek için:

pip show tefasfon

Fonksiyonlar

fetch_tefas_data

TEFAS web sitesinden fon veya portföy verisi çeker.

Parametreler:

• fund_type_code (int): Fon tipi kodu
  • 0: Menkul Kıymet Yatırım Fonları
  • 1: Emeklilik Fonları
  • 2: Borsa Yatırım Fonları
  • 3: Gayrimenkul Yatırım Fonları
  • 4: Girişim Sermayesi Yatırım Fonları
• tab_code (int): Sekme kodu
  • 0: Genel Bilgiler
  • 1: Portföy Dağılımı
• start_date (str): Başlangıç tarihi, 'gg.aa.yyyy' formatında (örn. '17.07.2025')
• end_date (str): Bitiş tarihi, 'gg.aa.yyyy' formatında (örn. '18.07.2025')
• fund_codes (list | None): "Fon Kodu" sütununda tam eşleşme için kod listesi (opsiyonel)
• fund_title_contains (list | None): "Fon Adı" sütununda kısmi arama için terim listesi (opsiyonel)
• lang (str): "tr" veya "en" (varsayılan "tr")
• save_to_excel (bool): True verilirse, Excel dosyasına kaydeder (varsayılan False)
• wait_seconds (int): Web işlemleri arası bekleme süresi (varsayılan 3)

Dönüş:

• pandas.DataFrame (veya veri yoksa boş DataFrame)

Örnek Kullanım

from tefasfon import fetch_tefas_data

df = fetch_tefas_data(
    fund_type_code=0,
    tab_code=0,
    start_date="01.09.2025",
    end_date="30.09.2025",
    save_to_excel=True
)

df_codes = fetch_tefas_data(
    fund_type_code=0,
    tab_code=0,
    start_date="01.09.2025",
    end_date="30.09.2025",
    fund_codes=["ABC", "XYZ"], # Fon kodu değerleri
    save_to_excel=False
)

df_title = fetch_tefas_data(
    fund_type_code=0,
    tab_code=0,
    start_date="01.09.2025",
    end_date="30.09.2025",
    fund_title_contains=["Altın", "Teknoloji"], # Ünvan içinde geçen terimler
    save_to_excel=False
)

analyze_funds

fetch_tefas_data() ile elde edilen fiyat verisi üzerinden performans metrikleri hesaplar.

Parametreler:

• df (pd.DataFrame): fetch_tefas_data() çıktısı (Genel Bilgiler sekmesi)
• price_col (str): Fiyat sütunu (varsayılan "Fiyat")
• fund_code_col (str): Fon kodu sütunu (varsayılan "Fon Kodu")
• fund_title_col (str): Fon adı sütunu (varsayılan "Fon Adı")
• date_col (str): Tarih sütunu (varsayılan "Tarih")
• freq (str): Getiri sıklığı. Desteklenen kısaltmalar:
  • "D" (günlük), "B" (iş günü), "W" (haftalık), "M" (aylık), "Q" (çeyreklik), "A"/"Y" (yıllık)
• risk_free_annual (float): Risksiz yıllık oran (örn. 0.10 = %10)
• periods_per_year (int | None): Yıllık dönem sayısı; boş bırakılırsa frekansa göre otomatik hesaplanır.
• method (str): "simple" veya "log" (varsayılan "simple")
• drop_empty (bool): Hatalı/eksik verili fonları dışarıda bırakır (varsayılan True)
• lang (str): "tr" veya "en" (varsayılan "tr")

Dönüş:

• pandas.DataFrame

Örnek Kullanım

from tefasfon import fetch_tefas_data, analyze_funds

df = fetch_tefas_data(
    fund_type_code=0,
    tab_code=0,
    start_date="01.09.2025",
    end_date="30.09.2025"
)

# İş günü frekansı + log getiri + %10 risksiz oran
metrics = analyze_funds(
    df,
    freq="B",
    method="log",
    risk_free_annual=0.10
)

Notlar

• Kütüphane, TEFAS'ın web sitesindeki verilere bağımlıdır. Herhangi bir değişiklikte veya bakımda, veri çekilemeyebilir. Lütfen TEFAS adresinden veri durumu ve güncelliğini kontrol edin.
• Selenium ve ChromeDriver kullanılır. Bilgisayarınızda Google Chrome kurulu olmalı ve güncel olmalıdır.
• Kütüphanenin geliştirilmesi ve iyileştirilmesi için geri bildirimlerinizi bekliyorum. GitHub reposuna katkıda bulunun: GitHub Repo
• Herhangi bir sorun veya öneride lütfen GitHub reposundaki "Issue" bölümünden yeni bir konu açarak bildirim sağlayın: GitHub Issues

Sürüm Notları

v0.4.1 - 18/10/2025

• fund_title_contains artık yalnızca tam kelime eşleşmelerini döndürüyor.

v0.4.0 - 18/10/2025

• analyze_funds fonksiyonu eklendi.
• Minimize edilen tarayıcı penceresi artık gösterilmiyor.

v0.3.0 - 15/10/2025

• fund_codes parametresi ile "Fon Kodu" üzerinden tam eşleşme filtresi eklendi.
• fund_title_contains parametresi ile "Fon Adı" içinde kısmi arama filtresi eklendi.

v0.2.0 - 05/09/2025

• Veri bulunmadığında güvenli dönüş sağlandı.
• WebDriver/TFLite logları kaldırıldı.
• Gün bazında ilerleme panelleri eklendi.
• Açılır menü hata mesajı yerelleştirildi.

v0.1.0 - 20/07/2025

• İlk sürüm yayınlandı.

Lisans

Bu proje MIT Lisansı altında lisanslanmıştır.

For those who prefer English:

Description

tefasfon is a Python library that allows fetching and analyzing investment and pension fund data published on the Turkey Electronic Fund Trading Platform (TEFAS) website.

• Fetches data from the web by date range and fund type.
• Calculates metrics such as cumulative return, annual return, annual volatility, and Sharpe ratio based on the fetched price data.
• Supports Turkish/English messages, with outputs returned directly as a pandas.DataFrame.

Features

• Fetches data for the selected date range and fund type.
• "General Information" or "Portfolio Breakdown" tabs
• Optional export to Excel
• Turkish/English info and error messages
• Performance analysis with simple or logarithmic returns
• Live web data access via Selenium + ChromeDriver

Installation

To use the package, follow these steps:

1. Install Python: https://www.python.org/downloads/
2. Open your terminal or command prompt and run:

pip install tefasfon

To install a specific version:

pip install tefasfon==0.4.1

To check the installed version:

pip show tefasfon

Functions

fetch_tefas_data

Fetches fund or portfolio data from the TEFAS website.

Parameters:

• fund_type_code (int): Fund type code
  • 0: Securities Mutual Funds
  • 1: Pension Funds
  • 2: Exchange Traded Funds
  • 3: Real Estate Investment Funds
  • 4: Venture Capital Investment Funds
• tab_code (int): Tab code
  • 0: General Information
  • 1: Portfolio Breakdown
• start_date (str): Start date, in 'dd.mm.yyyy' format (e.g. '17.07.2025')
• end_date (str): End date, in 'dd.mm.yyyy' format (e.g. '18.07.2025')
• fund_codes (list | None): List of codes for exact matching in the "Fund Code" column (optional)
• fund_title_contains (list | None): List of terms for substring matching in the "Fund Title" column (optional)
• lang (str): "tr" or "en" (default "tr")
• save_to_excel (bool): If True, saves the result to an Excel file (default: False)
• wait_seconds (int): Wait time between web actions (default: 3)

Returns:

• pandas.DataFrame (or an empty DataFrame if no data)

Example

from tefasfon import fetch_tefas_data

df = fetch_tefas_data(
    fund_type_code=0,
    tab_code=0,
    start_date="01.09.2025",
    end_date="30.09.2025",
    lang="en",
    save_to_excel=True
)

df_codes = fetch_tefas_data(
    fund_type_code=0,
    tab_code=0,
    start_date="01.09.2025",
    end_date="30.09.2025",
    fund_codes=["ABC", "XYZ"], # Exact fund codes
    lang="en",
    save_to_excel=False
)

df_title = fetch_tefas_data(
    fund_type_code=0,
    tab_code=0,
    start_date="01.09.2025",
    end_date="30.09.2025",
    fund_title_contains=["Gold", "Technology"], # Terms contained in the fund title
    lang="en",
    save_to_excel=False
)

analyze_funds

Calculates performance metrics based on the price data fetched using fetch_tefas_data().

Parameters:

• df (pd.DataFrame): Output of fetch_tefas_data() (General Information tab)
• price_col (str): Price column (default "Fiyat")
• fund_code_col (str): Fund code column (default "Fon Kodu")
• fund_title_col (str): Fund name column (default "Fon Adı")
• date_col (str): Date column (default "Tarih")
• freq (str): Return frequency. Supported abbreviations:
  • "D" (daily), "B" (business day), "W" (weekly), "M" (monthly), "Q" (quarterly), "A"/"Y" (annual / yearly)
• risk_free_annual (float): Annual risk-free rate (e.g., 0.10 = %10)
• periods_per_year (int | None): Number of periods per year; automatically inferred from frequency if left empty.
• method (str): "simple" or "log" (default "simple")
• drop_empty (bool): Excludes funds with invalid/missing data (default True)
• lang (str): "tr" or "en" (default "tr")

Returns:

• pandas.DataFrame

Example

from tefasfon import fetch_tefas_data, analyze_funds

df = fetch_tefas_data(
    fund_type_code=0,
    tab_code=0,
    start_date="01.09.2025",
    end_date="30.09.2025",
    lang="en"
)

# Business-day frequency + log returns + 10% risk-free rate
metrics = analyze_funds(
    df,
    freq="B",
    method="log",
    risk_free_annual=0.10,
    lang="en"
)

Notes

• The library depends on data from the TEFAS official website. In case of any changes or maintenance, data fetching may not be possible. Please check the data status and availability on TEFAS.
• Selenium and ChromeDriver are used. Google Chrome must be installed and up-to-date on your system.
• I welcome your feedback to improve and develop the library. You can contribute to the GitHub repository: GitHub Repo
• For any issues or suggestions, please open a new topic in the "Issue" section of the GitHub repository: GitHub Issues

Release Notes

v0.4.1 - 18/10/2025

• fund_title_contains returns only exact word matches.

v0.4.0 - 18/10/2025

• Added the analyze_funds function.
• The minimized browser window is no longer displayed.

v0.3.0 - 15/10/2025

• Added exact-match filtering on "Fund Code" via the fund_codes parameter.
• Added substring filtering on "Fund Title" via the fund_title_contains parameter.

v0.2.0 - 05/09/2025

• Safe return when no data.
• Suppressed WebDriver/TFLite logs.
• Added per-date progress panels.
• Localized dropdown error message.

v0.1.0 - 20/07/2025

• First release published.

License

This project is licensed under the MIT License.