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