468class Ticker(TechnicalMixin):
 469    """
 470    A yfinance-like interface for Turkish stock data.
 471
 472    Examples:
 473        >>> import borsapy as bp
 474        >>> stock = bp.Ticker("THYAO")
 475        >>> stock.info
 476        {'symbol': 'THYAO', 'last': 268.5, ...}
 477        >>> stock.history(period="1mo")
 478                         Open    High     Low   Close    Volume
 479        Date
 480        2024-12-01    265.00  268.00  264.00  267.50  12345678
 481        ...
 482    """
 483
 484    def __init__(self, symbol: str):
 485        """
 486        Initialize a Ticker object.
 487
 488        Args:
 489            symbol: Stock symbol (e.g., "THYAO", "GARAN", "ASELS").
 490                    The ".IS" or ".E" suffix is optional and will be removed.
 491        """
 492        self._symbol = symbol.upper().replace(".IS", "").replace(".E", "")
 493        self._tradingview = get_tradingview_provider()
 494        self._isyatirim = None  # Lazy load for financial statements
 495        self._kap = None  # Lazy load for KAP disclosures
 496        self._isin_provider = None  # Lazy load for ISIN lookup
 497        self._hedeffiyat = None  # Lazy load for analyst price targets
 498        self._etf_provider = None  # Lazy load for ETF holders
 499
 500    def _get_isyatirim(self):
 501        """Lazy load İş Yatırım provider for financial statements."""
 502        if self._isyatirim is None:
 503            from borsapy._providers.isyatirim import get_isyatirim_provider
 504
 505            self._isyatirim = get_isyatirim_provider()
 506        return self._isyatirim
 507
 508    def _get_kap(self):
 509        """Lazy load KAP provider for disclosures and calendar."""
 510        if self._kap is None:
 511            from borsapy._providers.kap import get_kap_provider
 512
 513            self._kap = get_kap_provider()
 514        return self._kap
 515
 516    def _get_isin_provider(self):
 517        """Lazy load ISIN provider."""
 518        if self._isin_provider is None:
 519            from borsapy._providers.isin import get_isin_provider
 520
 521            self._isin_provider = get_isin_provider()
 522        return self._isin_provider
 523
 524    def _get_hedeffiyat(self):
 525        """Lazy load hedeffiyat.com.tr provider for analyst price targets."""
 526        if self._hedeffiyat is None:
 527            from borsapy._providers.hedeffiyat import get_hedeffiyat_provider
 528
 529            self._hedeffiyat = get_hedeffiyat_provider()
 530        return self._hedeffiyat
 531
 532    def _get_etf_provider(self):
 533        """Lazy load TradingView ETF provider for ETF holders."""
 534        if self._etf_provider is None:
 535            from borsapy._providers.tradingview_etf import get_tradingview_etf_provider
 536
 537            self._etf_provider = get_tradingview_etf_provider()
 538        return self._etf_provider
 539
 540    @property
 541    def symbol(self) -> str:
 542        """Return the ticker symbol."""
 543        return self._symbol
 544
 545    @property
 546    def fast_info(self) -> FastInfo:
 547        """
 548        Get fast access to common ticker information.
 549
 550        Returns a FastInfo object with quick access to frequently used data:
 551        - currency, exchange, timezone
 552        - last_price, open, day_high, day_low, previous_close, volume
 553        - market_cap, shares, pe_ratio, pb_ratio
 554        - year_high, year_low (52-week)
 555        - fifty_day_average, two_hundred_day_average
 556        - free_float, foreign_ratio
 557
 558        Examples:
 559            >>> stock = Ticker("THYAO")
 560            >>> stock.fast_info.market_cap
 561            370530000000
 562            >>> stock.fast_info['pe_ratio']
 563            2.8
 564            >>> stock.fast_info.keys()
 565            ['currency', 'exchange', 'timezone', ...]
 566        """
 567        if not hasattr(self, "_fast_info"):
 568            self._fast_info = FastInfo(self)
 569        return self._fast_info
 570
 571    @property
 572    def info(self) -> EnrichedInfo:
 573        """
 574        Get comprehensive ticker information with yfinance-compatible fields.
 575
 576        Returns:
 577            EnrichedInfo object providing dict-like access to:
 578
 579            Basic fields (always loaded, fast):
 580            - symbol, last, open, high, low, close, volume
 581            - change, change_percent, update_time
 582
 583            yfinance aliases (map to basic fields):
 584            - regularMarketPrice, currentPrice -> last
 585            - regularMarketOpen -> open
 586            - regularMarketDayHigh -> high
 587            - regularMarketDayLow -> low
 588            - regularMarketPreviousClose -> close
 589            - regularMarketVolume -> volume
 590
 591            Extended fields (lazy-loaded on access):
 592            - marketCap, trailingPE, priceToBook, enterpriseToEbitda
 593            - sharesOutstanding, fiftyTwoWeekHigh, fiftyTwoWeekLow
 594            - fiftyDayAverage, twoHundredDayAverage
 595            - floatShares, foreignRatio, netDebt
 596            - currency, exchange, timezone
 597
 598            Dividend fields (lazy-loaded on access):
 599            - dividendYield, exDividendDate
 600            - trailingAnnualDividendRate, trailingAnnualDividendYield
 601
 602        Examples:
 603            >>> stock = Ticker("THYAO")
 604            >>> stock.info['last']  # Basic field - fast
 605            268.5
 606            >>> stock.info['marketCap']  # Extended field - fetches İş Yatırım
 607            370530000000
 608            >>> stock.info['trailingPE']  # yfinance compatible name
 609            2.8
 610            >>> stock.info.get('dividendYield')  # Safe access
 611            1.28
 612            >>> stock.info.todict()  # Get all as regular dict
 613            {...}
 614        """
 615        if not hasattr(self, "_enriched_info"):
 616            self._enriched_info = EnrichedInfo(self)
 617        return self._enriched_info
 618
 619    def history(
 620        self,
 621        period: str = "1mo",
 622        interval: str = "1d",
 623        start: datetime | str | None = None,
 624        end: datetime | str | None = None,
 625        actions: bool = False,
 626    ) -> pd.DataFrame:
 627        """
 628        Get historical OHLCV data.
 629
 630        Args:
 631            period: How much data to fetch. Valid periods:
 632                    1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max.
 633                    Ignored if start is provided.
 634            interval: Data granularity. Valid intervals:
 635                      1m, 5m, 15m, 30m, 1h, 1d, 1wk, 1mo.
 636            start: Start date (string or datetime).
 637            end: End date (string or datetime). Defaults to today.
 638            actions: If True, include Dividends and Stock Splits columns.
 639                     Defaults to False.
 640
 641        Returns:
 642            DataFrame with columns: Open, High, Low, Close, Volume.
 643            If actions=True, also includes Dividends and Stock Splits columns.
 644            Index is the Date.
 645
 646        Examples:
 647            >>> stock = Ticker("THYAO")
 648            >>> stock.history(period="1mo")  # Last month
 649            >>> stock.history(period="1y", interval="1wk")  # Weekly for 1 year
 650            >>> stock.history(start="2024-01-01", end="2024-06-30")  # Date range
 651            >>> stock.history(period="1y", actions=True)  # With dividends/splits
 652        """
 653        # Parse dates if strings
 654        start_dt = self._parse_date(start) if start else None
 655        end_dt = self._parse_date(end) if end else None
 656
 657        df = self._tradingview.get_history(
 658            symbol=self._symbol,
 659            period=period,
 660            interval=interval,
 661            start=start_dt,
 662            end=end_dt,
 663        )
 664
 665        if actions and not df.empty:
 666            df = self._add_actions_to_history(df)
 667
 668        return df
 669
 670    def _add_actions_to_history(self, df: pd.DataFrame) -> pd.DataFrame:
 671        """
 672        Add Dividends and Stock Splits columns to historical data.
 673
 674        Args:
 675            df: Historical OHLCV DataFrame.
 676
 677        Returns:
 678            DataFrame with added Dividends and Stock Splits columns.
 679        """
 680        # Initialize columns with zeros
 681        df = df.copy()
 682        df["Dividends"] = 0.0
 683        df["Stock Splits"] = 0.0
 684
 685        # Get dividends
 686        try:
 687            divs = self.dividends
 688            if not divs.empty:
 689                for div_date, row in divs.iterrows():
 690                    # Use date() for timezone-agnostic comparison
 691                    div_date_only = pd.Timestamp(div_date).date()
 692                    for idx in df.index:
 693                        idx_date_only = pd.Timestamp(idx).date()
 694                        if div_date_only == idx_date_only:
 695                            df.loc[idx, "Dividends"] = row.get("Amount", 0)
 696                            break
 697        except Exception:
 698            pass
 699
 700        # Get stock splits (capital increases)
 701        try:
 702            splits = self.splits
 703            if not splits.empty:
 704                for split_date, row in splits.iterrows():
 705                    # Use date() for timezone-agnostic comparison
 706                    split_date_only = pd.Timestamp(split_date).date()
 707                    # Calculate split ratio
 708                    # BonusFromCapital + BonusFromDividend = total bonus percentage
 709                    bonus_pct = row.get("BonusFromCapital", 0) + row.get(
 710                        "BonusFromDividend", 0
 711                    )
 712                    if bonus_pct > 0:
 713                        # Convert percentage to split ratio (e.g., 20% bonus = 1.2 split)
 714                        split_ratio = 1 + (bonus_pct / 100)
 715                        for idx in df.index:
 716                            idx_date_only = pd.Timestamp(idx).date()
 717                            if split_date_only == idx_date_only:
 718                                df.loc[idx, "Stock Splits"] = split_ratio
 719                                break
 720        except Exception:
 721            pass
 722
 723        return df
 724
 725    @cached_property
 726    def dividends(self) -> pd.DataFrame:
 727        """
 728        Get dividend history.
 729
 730        Returns:
 731            DataFrame with dividend history:
 732            - Amount: Dividend per share (TL)
 733            - GrossRate: Gross dividend rate (%)
 734            - NetRate: Net dividend rate (%)
 735            - TotalDividend: Total dividend distributed (TL)
 736
 737        Examples:
 738            >>> stock = Ticker("THYAO")
 739            >>> stock.dividends
 740                           Amount  GrossRate  NetRate  TotalDividend
 741            Date
 742            2025-09-02     3.442    344.20   292.57  4750000000.0
 743            2025-06-16     3.442    344.20   292.57  4750000000.0
 744        """
 745        return self._get_isyatirim().get_dividends(self._symbol)
 746
 747    @cached_property
 748    def splits(self) -> pd.DataFrame:
 749        """
 750        Get capital increase (split) history.
 751
 752        Note: Turkish market uses capital increases instead of traditional splits.
 753        - RightsIssue: Paid capital increase (bedelli)
 754        - BonusFromCapital: Free shares from capital reserves (bedelsiz iç kaynak)
 755        - BonusFromDividend: Free shares from dividend (bedelsiz temettüden)
 756
 757        Returns:
 758            DataFrame with capital increase history:
 759            - Capital: New capital after increase (TL)
 760            - RightsIssue: Rights issue rate (%)
 761            - BonusFromCapital: Bonus from capital (%)
 762            - BonusFromDividend: Bonus from dividend (%)
 763
 764        Examples:
 765            >>> stock = Ticker("THYAO")
 766            >>> stock.splits
 767                             Capital  RightsIssue  BonusFromCapital  BonusFromDividend
 768            Date
 769            2013-06-26  1380000000.0         0.0             15.00               0.0
 770            2011-07-11  1200000000.0         0.0              0.00              20.0
 771        """
 772        return self._get_isyatirim().get_capital_increases(self._symbol)
 773
 774    @cached_property
 775    def actions(self) -> pd.DataFrame:
 776        """
 777        Get combined dividends and splits history.
 778
 779        Returns:
 780            DataFrame with combined dividend and split actions:
 781            - Dividends: Dividend per share (TL) or 0
 782            - Splits: Combined split ratio (0 if no split)
 783
 784        Examples:
 785            >>> stock = Ticker("THYAO")
 786            >>> stock.actions
 787                         Dividends  Splits
 788            Date
 789            2025-09-02      3.442    0.0
 790            2013-06-26      0.000   15.0
 791        """
 792        dividends = self.dividends
 793        splits = self.splits
 794
 795        # Merge on index (Date)
 796        if dividends.empty and splits.empty:
 797            return pd.DataFrame(columns=["Dividends", "Splits"])
 798
 799        # Extract relevant columns
 800        div_series = dividends["Amount"] if not dividends.empty else pd.Series(dtype=float)
 801        split_series = (
 802            splits["BonusFromCapital"] + splits["BonusFromDividend"]
 803            if not splits.empty
 804            else pd.Series(dtype=float)
 805        )
 806
 807        # Combine into single DataFrame
 808        result = pd.DataFrame({"Dividends": div_series, "Splits": split_series})
 809        result = result.fillna(0)
 810        result = result.sort_index(ascending=False)
 811
 812        return result
 813
 814    def get_balance_sheet(
 815        self, quarterly: bool = False, financial_group: str | None = None
 816    ) -> pd.DataFrame:
 817        """
 818        Get balance sheet data.
 819
 820        Args:
 821            quarterly: If True, return quarterly data. If False, return annual.
 822            financial_group: Financial group code. Use "UFRS" for banks,
 823                           "XI_29" for industrial companies. If None, defaults to XI_29.
 824
 825        Returns:
 826            DataFrame with balance sheet items as rows and periods as columns.
 827
 828        Examples:
 829            >>> stock = bp.Ticker("THYAO")
 830            >>> stock.get_balance_sheet()  # Annual, industrial
 831            >>> stock.get_balance_sheet(quarterly=True)  # Quarterly
 832
 833            >>> bank = bp.Ticker("AKBNK")
 834            >>> bank.get_balance_sheet(financial_group="UFRS")  # Banks need UFRS
 835        """
 836        return self._get_isyatirim().get_financial_statements(
 837            symbol=self._symbol,
 838            statement_type="balance_sheet",
 839            quarterly=quarterly,
 840            financial_group=financial_group,
 841        )
 842
 843    def get_income_stmt(
 844        self, quarterly: bool = False, financial_group: str | None = None
 845    ) -> pd.DataFrame:
 846        """
 847        Get income statement data.
 848
 849        Args:
 850            quarterly: If True, return quarterly data. If False, return annual.
 851            financial_group: Financial group code. Use "UFRS" for banks,
 852                           "XI_29" for industrial companies. If None, defaults to XI_29.
 853
 854        Returns:
 855            DataFrame with income statement items as rows and periods as columns.
 856
 857        Examples:
 858            >>> stock = bp.Ticker("THYAO")
 859            >>> stock.get_income_stmt()  # Annual
 860            >>> stock.get_income_stmt(quarterly=True)  # Quarterly
 861
 862            >>> bank = bp.Ticker("AKBNK")
 863            >>> bank.get_income_stmt(quarterly=True, financial_group="UFRS")
 864        """
 865        return self._get_isyatirim().get_financial_statements(
 866            symbol=self._symbol,
 867            statement_type="income_stmt",
 868            quarterly=quarterly,
 869            financial_group=financial_group,
 870        )
 871
 872    def get_cashflow(
 873        self, quarterly: bool = False, financial_group: str | None = None
 874    ) -> pd.DataFrame:
 875        """
 876        Get cash flow statement data.
 877
 878        Args:
 879            quarterly: If True, return quarterly data. If False, return annual.
 880            financial_group: Financial group code. Use "UFRS" for banks,
 881                           "XI_29" for industrial companies. If None, defaults to XI_29.
 882
 883        Returns:
 884            DataFrame with cash flow items as rows and periods as columns.
 885
 886        Examples:
 887            >>> stock = bp.Ticker("THYAO")
 888            >>> stock.get_cashflow()  # Annual
 889            >>> stock.get_cashflow(quarterly=True)  # Quarterly
 890
 891            >>> bank = bp.Ticker("AKBNK")
 892            >>> bank.get_cashflow(financial_group="UFRS")
 893        """
 894        return self._get_isyatirim().get_financial_statements(
 895            symbol=self._symbol,
 896            statement_type="cashflow",
 897            quarterly=quarterly,
 898            financial_group=financial_group,
 899        )
 900
 901    # Legacy property aliases for backward compatibility
 902    @cached_property
 903    def balance_sheet(self) -> pd.DataFrame:
 904        """Annual balance sheet (use get_balance_sheet() for more options)."""
 905        return self.get_balance_sheet(quarterly=False)
 906
 907    @cached_property
 908    def quarterly_balance_sheet(self) -> pd.DataFrame:
 909        """Quarterly balance sheet (use get_balance_sheet(quarterly=True) for more options)."""
 910        return self.get_balance_sheet(quarterly=True)
 911
 912    @cached_property
 913    def income_stmt(self) -> pd.DataFrame:
 914        """Annual income statement (use get_income_stmt() for more options)."""
 915        return self.get_income_stmt(quarterly=False)
 916
 917    @cached_property
 918    def quarterly_income_stmt(self) -> pd.DataFrame:
 919        """Quarterly income statement (use get_income_stmt(quarterly=True) for more options)."""
 920        return self.get_income_stmt(quarterly=True)
 921
 922    @cached_property
 923    def cashflow(self) -> pd.DataFrame:
 924        """Annual cash flow (use get_cashflow() for more options)."""
 925        return self.get_cashflow(quarterly=False)
 926
 927    @cached_property
 928    def quarterly_cashflow(self) -> pd.DataFrame:
 929        """Quarterly cash flow (use get_cashflow(quarterly=True) for more options)."""
 930        return self.get_cashflow(quarterly=True)
 931
 932    def _calculate_ttm(self, quarterly_df: pd.DataFrame) -> pd.DataFrame:
 933        """
 934        Calculate trailing twelve months (TTM) by summing last 4 quarters.
 935
 936        Args:
 937            quarterly_df: DataFrame with quarterly data (columns in YYYYQN format).
 938
 939        Returns:
 940            DataFrame with single TTM column containing summed values.
 941        """
 942        if quarterly_df.empty or len(quarterly_df.columns) < 4:
 943            return pd.DataFrame(columns=["TTM"])
 944
 945        # First 4 columns = last 4 quarters (most recent first)
 946        last_4_quarters = quarterly_df.iloc[:, :4]
 947
 948        # Convert to numeric, coercing errors to NaN
 949        numeric_df = last_4_quarters.apply(pd.to_numeric, errors="coerce")
 950
 951        return numeric_df.sum(axis=1).to_frame(name="TTM")
 952
 953    def get_ttm_income_stmt(self, financial_group: str | None = None) -> pd.DataFrame:
 954        """
 955        Get trailing twelve months (TTM) income statement.
 956
 957        Calculates TTM by summing the last 4 quarters of income statement data.
 958
 959        Args:
 960            financial_group: Financial group code. Use "UFRS" for banks,
 961                           "XI_29" for industrial companies. If None, defaults to XI_29.
 962
 963        Returns:
 964            DataFrame with TTM column containing summed values for each line item.
 965
 966        Examples:
 967            >>> stock = bp.Ticker("THYAO")
 968            >>> stock.get_ttm_income_stmt()
 969
 970            >>> bank = bp.Ticker("AKBNK")
 971            >>> bank.get_ttm_income_stmt(financial_group="UFRS")
 972        """
 973        quarterly = self.get_income_stmt(quarterly=True, financial_group=financial_group)
 974        return self._calculate_ttm(quarterly)
 975
 976    def get_ttm_cashflow(self, financial_group: str | None = None) -> pd.DataFrame:
 977        """
 978        Get trailing twelve months (TTM) cash flow statement.
 979
 980        Calculates TTM by summing the last 4 quarters of cash flow data.
 981
 982        Args:
 983            financial_group: Financial group code. Use "UFRS" for banks,
 984                           "XI_29" for industrial companies. If None, defaults to XI_29.
 985
 986        Returns:
 987            DataFrame with TTM column containing summed values for each line item.
 988
 989        Examples:
 990            >>> stock = bp.Ticker("THYAO")
 991            >>> stock.get_ttm_cashflow()
 992
 993            >>> bank = bp.Ticker("AKBNK")
 994            >>> bank.get_ttm_cashflow(financial_group="UFRS")
 995        """
 996        quarterly = self.get_cashflow(quarterly=True, financial_group=financial_group)
 997        return self._calculate_ttm(quarterly)
 998
 999    # Legacy property aliases
1000    @cached_property
1001    def ttm_income_stmt(self) -> pd.DataFrame:
1002        """TTM income statement (use get_ttm_income_stmt() for banks)."""
1003        return self.get_ttm_income_stmt()
1004
1005    @cached_property
1006    def ttm_cashflow(self) -> pd.DataFrame:
1007        """TTM cash flow (use get_ttm_cashflow() for banks)."""
1008        return self.get_ttm_cashflow()
1009
1010    @cached_property
1011    def major_holders(self) -> pd.DataFrame:
1012        """
1013        Get major shareholders (ortaklık yapısı).
1014
1015        Returns:
1016            DataFrame with shareholder names and percentages:
1017            - Index: Holder name
1018            - Percentage: Ownership percentage (%)
1019
1020        Examples:
1021            >>> stock = Ticker("THYAO")
1022            >>> stock.major_holders
1023                                     Percentage
1024            Holder
1025            Diğer                        50.88
1026            Türkiye Varlık Fonu          49.12
1027        """
1028        return self._get_isyatirim().get_major_holders(self._symbol)
1029
1030    @cached_property
1031    def recommendations(self) -> dict:
1032        """
1033        Get analyst recommendations and target price.
1034
1035        Returns:
1036            Dictionary with:
1037            - recommendation: Buy/Hold/Sell (AL/TUT/SAT)
1038            - target_price: Analyst target price (TL)
1039            - upside_potential: Expected upside (%)
1040
1041        Examples:
1042            >>> stock = Ticker("THYAO")
1043            >>> stock.recommendations
1044            {'recommendation': 'AL', 'target_price': 579.99, 'upside_potential': 116.01}
1045        """
1046        return self._get_isyatirim().get_recommendations(self._symbol)
1047
1048    @cached_property
1049    def recommendations_summary(self) -> dict[str, int]:
1050        """
1051        Get analyst recommendation summary with buy/hold/sell counts.
1052
1053        Aggregates individual analyst recommendations from hedeffiyat.com.tr
1054        into yfinance-compatible categories.
1055
1056        Returns:
1057            Dictionary with counts:
1058            - strongBuy: Strong buy recommendations
1059            - buy: Buy recommendations (includes "Endeks Üstü Getiri")
1060            - hold: Hold recommendations (includes "Nötr", "Endekse Paralel")
1061            - sell: Sell recommendations (includes "Endeks Altı Getiri")
1062            - strongSell: Strong sell recommendations
1063
1064        Examples:
1065            >>> stock = Ticker("THYAO")
1066            >>> stock.recommendations_summary
1067            {'strongBuy': 0, 'buy': 31, 'hold': 0, 'sell': 0, 'strongSell': 0}
1068        """
1069        return self._get_hedeffiyat().get_recommendations_summary(self._symbol)
1070
1071    @cached_property
1072    def news(self) -> pd.DataFrame:
1073        """
1074        Get recent KAP (Kamuyu Aydınlatma Platformu) disclosures for the stock.
1075
1076        Fetches directly from KAP - the official disclosure platform for
1077        publicly traded companies in Turkey.
1078
1079        Returns:
1080            DataFrame with columns:
1081            - Date: Disclosure date and time
1082            - Title: Disclosure headline
1083            - URL: Link to full disclosure on KAP
1084
1085        Examples:
1086            >>> stock = Ticker("THYAO")
1087            >>> stock.news
1088                              Date                                         Title                                         URL
1089            0  29.12.2025 19:21:18  Haber ve Söylentilere İlişkin Açıklama  https://www.kap.org.tr/tr/Bildirim/1530826
1090            1  29.12.2025 16:11:36  Payların Geri Alınmasına İlişkin Bildirim  https://www.kap.org.tr/tr/Bildirim/1530656
1091        """
1092        return self._get_kap().get_disclosures(self._symbol)
1093
1094    def get_news_content(self, disclosure_id: int | str) -> str | None:
1095        """
1096        Get full HTML content of a KAP disclosure by ID.
1097
1098        Args:
1099            disclosure_id: KAP disclosure ID from news DataFrame URL.
1100
1101        Returns:
1102            Raw HTML content or None if failed.
1103
1104        Examples:
1105            >>> stock = Ticker("THYAO")
1106            >>> html = stock.get_news_content(1530826)
1107        """
1108        return self._get_kap().get_disclosure_content(disclosure_id)
1109
1110    @cached_property
1111    def calendar(self) -> pd.DataFrame:
1112        """
1113        Get expected disclosure calendar for the stock from KAP.
1114
1115        Returns upcoming expected disclosures like financial reports,
1116        annual reports, sustainability reports, and corporate governance reports.
1117
1118        Returns:
1119            DataFrame with columns:
1120            - StartDate: Expected disclosure window start
1121            - EndDate: Expected disclosure window end
1122            - Subject: Type of disclosure (e.g., "Finansal Rapor")
1123            - Period: Report period (e.g., "Yıllık", "3 Aylık")
1124            - Year: Fiscal year
1125
1126        Examples:
1127            >>> stock = Ticker("THYAO")
1128            >>> stock.calendar
1129                  StartDate       EndDate               Subject   Period  Year
1130            0  01.01.2026  11.03.2026       Finansal Rapor   Yıllık  2025
1131            1  01.01.2026  11.03.2026    Faaliyet Raporu  Yıllık  2025
1132            2  01.04.2026  11.05.2026       Finansal Rapor  3 Aylık  2026
1133        """
1134        return self._get_kap().get_calendar(self._symbol)
1135
1136    @cached_property
1137    def isin(self) -> str | None:
1138        """
1139        Get ISIN (International Securities Identification Number) code.
1140
1141        ISIN is a 12-character alphanumeric code that uniquely identifies
1142        a security, standardized by ISO 6166.
1143
1144        Returns:
1145            ISIN code string (e.g., "TRATHYAO91M5") or None if not found.
1146
1147        Examples:
1148            >>> stock = Ticker("THYAO")
1149            >>> stock.isin
1150            'TRATHYAO91M5'
1151        """
1152        return self._get_isin_provider().get_isin(self._symbol)
1153
1154    @cached_property
1155    def analyst_price_targets(self) -> dict[str, float | int | None]:
1156        """
1157        Get analyst price target data from hedeffiyat.com.tr.
1158
1159        Returns aggregated price target information from multiple analysts.
1160
1161        Returns:
1162            Dictionary with:
1163            - current: Current stock price
1164            - low: Lowest analyst target price
1165            - high: Highest analyst target price
1166            - mean: Average target price
1167            - median: Median target price
1168            - numberOfAnalysts: Number of analysts covering the stock
1169
1170        Examples:
1171            >>> stock = Ticker("THYAO")
1172            >>> stock.analyst_price_targets
1173            {'current': 268.5, 'low': 388.0, 'high': 580.0, 'mean': 474.49,
1174             'median': 465.0, 'numberOfAnalysts': 19}
1175        """
1176        return self._get_hedeffiyat().get_price_targets(self._symbol)
1177
1178    @property
1179    def etf_holders(self) -> pd.DataFrame:
1180        """
1181        Get international ETFs that hold this stock.
1182
1183        Returns data from TradingView showing which ETFs hold this stock,
1184        including position value, weight, and ETF characteristics.
1185
1186        Returns:
1187            DataFrame with ETF holder information:
1188            - symbol: ETF ticker symbol
1189            - exchange: Exchange (AMEX, NASDAQ, LSE, etc.)
1190            - name: ETF full name
1191            - market_cap_usd: Position value in USD
1192            - holding_weight_pct: Weight percentage (0.09 = 0.09%)
1193            - issuer: ETF issuer (BlackRock, Vanguard, etc.)
1194            - management: Management style (Passive/Active)
1195            - focus: Investment focus (Total Market, Emerging Markets, etc.)
1196            - expense_ratio: Expense ratio (0.09 = 0.09%)
1197            - aum_usd: Total assets under management (USD)
1198            - price: Current ETF price
1199            - change_pct: Change percentage
1200
1201        Examples:
1202            >>> stock = Ticker("ASELS")
1203            >>> holders = stock.etf_holders
1204            >>> holders[['symbol', 'name', 'holding_weight_pct']].head()
1205               symbol                                      name  holding_weight_pct
1206            0    IEMG  iShares Core MSCI Emerging Markets ETF            0.090686
1207            1     VWO     Vanguard FTSE Emerging Markets ETF            0.060000
1208
1209            >>> print(f"Total ETFs: {len(holders)}")
1210            Total ETFs: 118
1211        """
1212        return self._get_etf_provider().get_etf_holders(self._symbol)
1213
1214    @cached_property
1215    def earnings_dates(self) -> pd.DataFrame:
1216        """
1217        Get upcoming earnings announcement dates.
1218
1219        Derived from KAP calendar, showing expected financial report dates.
1220        Compatible with yfinance earnings_dates format.
1221
1222        Returns:
1223            DataFrame with index as Earnings Date and columns:
1224            - EPS Estimate: Always None (not available for BIST)
1225            - Reported EPS: Always None (not available for BIST)
1226            - Surprise (%): Always None (not available for BIST)
1227
1228        Examples:
1229            >>> stock = Ticker("THYAO")
1230            >>> stock.earnings_dates
1231                            EPS Estimate  Reported EPS  Surprise(%)
1232            Earnings Date
1233            2026-03-11           None          None         None
1234            2026-05-11           None          None         None
1235        """
1236        cal = self.calendar
1237        if cal.empty:
1238            return pd.DataFrame(
1239                columns=["EPS Estimate", "Reported EPS", "Surprise(%)"]
1240            )
1241
1242        # Filter for financial reports only
1243        financial_reports = cal[
1244            cal["Subject"].str.contains("Finansal Rapor", case=False, na=False)
1245        ]
1246
1247        if financial_reports.empty:
1248            return pd.DataFrame(
1249                columns=["EPS Estimate", "Reported EPS", "Surprise(%)"]
1250            )
1251
1252        # Use EndDate as the earnings date (latest expected date)
1253        earnings_dates = []
1254        for _, row in financial_reports.iterrows():
1255            end_date = row.get("EndDate", "")
1256            if end_date:
1257                try:
1258                    # Parse Turkish date format (DD.MM.YYYY)
1259                    parsed = datetime.strptime(end_date, "%d.%m.%Y")
1260                    earnings_dates.append(parsed)
1261                except ValueError:
1262                    continue
1263
1264        if not earnings_dates:
1265            return pd.DataFrame(
1266                columns=["EPS Estimate", "Reported EPS", "Surprise(%)"]
1267            )
1268
1269        result = pd.DataFrame(
1270            {
1271                "EPS Estimate": [None] * len(earnings_dates),
1272                "Reported EPS": [None] * len(earnings_dates),
1273                "Surprise(%)": [None] * len(earnings_dates),
1274            },
1275            index=pd.DatetimeIndex(earnings_dates, name="Earnings Date"),
1276        )
1277        result = result.sort_index()
1278        return result
1279
1280    def _parse_date(self, date: str | datetime) -> datetime:
1281        """Parse a date string to datetime."""
1282        if isinstance(date, datetime):
1283            return date
1284        # Try common formats
1285        for fmt in ["%Y-%m-%d", "%Y/%m/%d", "%d-%m-%Y", "%d/%m/%Y"]:
1286            try:
1287                return datetime.strptime(date, fmt)
1288            except ValueError:
1289                continue
1290        raise ValueError(f"Could not parse date: {date}")
1291
1292    def _get_ta_symbol_info(self) -> tuple[str, str]:
1293        """Get TradingView symbol and screener for TA signals.
1294
1295        Returns:
1296            Tuple of (tv_symbol, screener) for TradingView Scanner API.
1297        """
1298        return (f"BIST:{self._symbol}", "turkey")
1299
1300    def __repr__(self) -> str:
1301        return f"Ticker('{self._symbol}')"