reportify-sdk 0.2.7__py3-none-any.whl → 0.2.9__py3-none-any.whl

reportify_sdk/stock.py

@@ -32,34 +32,70 @@ class StockModule:
     # Company Information
     # -------------------------------------------------------------------------
 
-    def overview(self, symbol: str) -> dict[str, Any]:
+    def overview(
+        self, symbols: str | None = None, names: str | None = None
+    ) -> dict[str, Any] | list[dict[str, Any]]:
         """
         Get company overview including business description, sector, and key metrics
 
         Args:
-            symbol: Stock symbol (e.g., "US:AAPL", "HK:0700", "CN:600519")
+            symbols: Stock symbols. You can enter multiple items, separated by commas(,)
+                    Example: "US:AAPL,US:MSFT"
+            names: Stock names. You can enter multiple items, separated by commas(,)
+                  Example: "Apple Inc.,Microsoft"
 
         Returns:
-            Company information dictionary
+            Dictionary or list of dictionaries with company overview data
 
         Example:
-            >>> info = client.stock.overview("US:AAPL")
+            >>> # Single stock by symbol
+            >>> info = client.stock.overview(symbols="US:AAPL")
             >>> print(info["name"], info["sector"])
+            
+            >>> # Multiple stocks by symbols
+            >>> infos = client.stock.overview(symbols="US:AAPL,US:MSFT")
+            >>> for info in infos:
+            ...     print(info["name"])
+            
+            >>> # Search by name
+            >>> info = client.stock.overview(names="Apple Inc.")
         """
-        response = self._post("/v1/stock/company-overview", json={"symbol": symbol})
+        if not symbols and not names:
+            raise ValueError("Either symbols or names must be provided")
+
+        data = {}
+        if symbols:
+            data["symbols"] = symbols
+        if names:
+            data["names"] = names
+
+        response = self._post("/v1/stock/company-overview", json=data)
         return response
 
-    def shareholders(self, symbol: str) -> list[dict[str, Any]]:
+    def shareholders(
+        self,
+        symbol: str,
+        *,
+        type: Literal["shareholders", "outstanding_shareholders"] = "shareholders",
+        limit: int = 10,
+    ) -> list[dict[str, Any]]:
         """
         Get list of major shareholders
 
         Args:
             symbol: Stock symbol
+            type: Type of shareholders to return
+                - "shareholders": All shareholders
+                - "outstanding_shareholders": Outstanding shareholders only
+            limit: Number of shareholders to return (default: 10)
 
         Returns:
             List of shareholders with ownership details
         """
-        response = self._post("/v1/stock/company-shareholders", json={"symbol": symbol})
+        response = self._post(
+            "/v1/stock/company-shareholders",
+            json={"symbol": symbol, "type": type, "limit": limit},
+        )
         return response if isinstance(response, list) else response.get("shareholders", [])
 
     # -------------------------------------------------------------------------
@@ -70,16 +106,26 @@ class StockModule:
         self,
         symbol: str,
         *,
-        period: Literal["annual", "quarterly"] = "annual",
-        limit: int = 10,
+        period: Literal["annual", "quarterly", "cumulative quarterly"] = "annual",
+        limit: int = 8,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        calendar: Literal["calendar", "fiscal"] = "fiscal",
+        fiscal_year: str | None = None,
+        fiscal_quarter: str | None = None,
     ) -> pd.DataFrame:
         """
         Get income statement data
 
         Args:
             symbol: Stock symbol (e.g., "US:AAPL")
-            period: "annual" or "quarterly"
-            limit: Number of periods to return
+            period: Report cycle ("annual", "quarterly", "cumulative quarterly")
+            limit: Return latest N records (default: 8)
+            start_date: Start date (YYYY-MM-DD)
+            end_date: End date (YYYY-MM-DD)
+            calendar: "calendar" or "fiscal" (default: "fiscal")
+            fiscal_year: Specific fiscal year (e.g., "2023")
+            fiscal_quarter: Specific fiscal quarter (Q1, Q2, Q3, Q4, FY, H1, "Q3 (9 months)")
 
         Returns:
             DataFrame with income statement data, indexed by date
@@ -88,10 +134,22 @@ class StockModule:
             >>> income = client.stock.income_statement("US:AAPL", period="quarterly")
             >>> print(income[["revenue", "net_income"]].head())
         """
-        response = self._post(
-            "/v1/stock/company-income-statement",
-            json={"symbol": symbol, "period": period, "limit": limit},
-        )
+        data: dict[str, Any] = {
+            "symbol": symbol,
+            "period": period,
+            "limit": limit,
+            "calendar": calendar,
+        }
+        if start_date:
+            data["start_date"] = start_date
+        if end_date:
+            data["end_date"] = end_date
+        if fiscal_year:
+            data["fiscal_year"] = fiscal_year
+        if fiscal_quarter:
+            data["fiscal_quarter"] = fiscal_quarter
+
+        response = self._post("/v1/stock/company-income-statement", json=data)
         return self._to_dataframe(response)
 
     def balance_sheet(
@@ -99,15 +157,25 @@ class StockModule:
         symbol: str,
         *,
         period: Literal["annual", "quarterly"] = "annual",
-        limit: int = 10,
+        limit: int = 8,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        calendar: Literal["calendar", "fiscal"] = "fiscal",
+        fiscal_year: str | None = None,
+        fiscal_quarter: str | None = None,
     ) -> pd.DataFrame:
         """
         Get balance sheet data
 
         Args:
             symbol: Stock symbol
-            period: "annual" or "quarterly"
-            limit: Number of periods to return
+            period: Report cycle ("annual", "quarterly")
+            limit: Return latest N records (default: 8)
+            start_date: Start date (YYYY-MM-DD)
+            end_date: End date (YYYY-MM-DD)
+            calendar: "calendar" or "fiscal" (default: "fiscal")
+            fiscal_year: Specific fiscal year (e.g., "2023")
+            fiscal_quarter: Specific fiscal quarter (Q1, Q2, Q3, Q4, FY)
 
         Returns:
             DataFrame with balance sheet data, indexed by date
@@ -116,26 +184,48 @@ class StockModule:
             >>> balance = client.stock.balance_sheet("US:AAPL")
             >>> print(balance[["total_assets", "total_liabilities"]].head())
         """
-        response = self._post(
-            "/v1/stock/company-balance-sheet",
-            json={"symbol": symbol, "period": period, "limit": limit},
-        )
+        data: dict[str, Any] = {
+            "symbol": symbol,
+            "period": period,
+            "limit": limit,
+            "calendar": calendar,
+        }
+        if start_date:
+            data["start_date"] = start_date
+        if end_date:
+            data["end_date"] = end_date
+        if fiscal_year:
+            data["fiscal_year"] = fiscal_year
+        if fiscal_quarter:
+            data["fiscal_quarter"] = fiscal_quarter
+
+        response = self._post("/v1/stock/company-balance-sheet", json=data)
         return self._to_dataframe(response)
 
     def cashflow_statement(
         self,
         symbol: str,
         *,
-        period: Literal["annual", "quarterly"] = "annual",
-        limit: int = 10,
+        period: Literal["annual", "quarterly", "cumulative quarterly"] = "annual",
+        limit: int = 8,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        calendar: Literal["calendar", "fiscal"] = "fiscal",
+        fiscal_year: str | None = None,
+        fiscal_quarter: str | None = None,
     ) -> pd.DataFrame:
         """
         Get cash flow statement data
 
         Args:
             symbol: Stock symbol
-            period: "annual" or "quarterly"
-            limit: Number of periods to return
+            period: Report cycle ("annual", "quarterly", "cumulative quarterly")
+            limit: Return latest N records (default: 8)
+            start_date: Start date (YYYY-MM-DD)
+            end_date: End date (YYYY-MM-DD)
+            calendar: "calendar" or "fiscal" (default: "fiscal")
+            fiscal_year: Specific fiscal year (e.g., "2023")
+            fiscal_quarter: Specific fiscal quarter (Q1, Q2, Q3, Q4, FY, H1, "Q3 (9 months)")
 
         Returns:
             DataFrame with cash flow data, indexed by date
@@ -144,134 +234,111 @@ class StockModule:
             >>> cashflow = client.stock.cashflow_statement("US:AAPL")
             >>> print(cashflow[["operating_cashflow", "free_cashflow"]].head())
         """
-        response = self._post(
-            "/v1/stock/company-cashflow-statement",
-            json={"symbol": symbol, "period": period, "limit": limit},
-        )
-        return self._to_dataframe(response)
-
-    def revenue_breakdown(
-        self,
-        symbol: str,
-        *,
-        breakdown_type: Literal["segment", "product", "region"] = "segment",
-    ) -> pd.DataFrame:
-        """
-        Get revenue breakdown by segment, product, or region
-
-        Args:
-            symbol: Stock symbol
-            breakdown_type: Type of breakdown ("segment", "product", or "region")
+        data: dict[str, Any] = {
+            "symbol": symbol,
+            "period": period,
+            "limit": limit,
+            "calendar": calendar,
+        }
+        if start_date:
+            data["start_date"] = start_date
+        if end_date:
+            data["end_date"] = end_date
+        if fiscal_year:
+            data["fiscal_year"] = fiscal_year
+        if fiscal_quarter:
+            data["fiscal_quarter"] = fiscal_quarter
 
-        Returns:
-            DataFrame with revenue breakdown data
-        """
-        response = self._post(
-            "/v1/stock/company-revenue-breakdown",
-            json={"symbol": symbol, "breakdown_type": breakdown_type},
-        )
+        response = self._post("/v1/stock/company-cashflow-statement", json=data)
         return self._to_dataframe(response)
 
-    # -------------------------------------------------------------------------
-    # Price Data (returns DataFrame)
-    # -------------------------------------------------------------------------
-
-    def prices(
+    def revenue_breakdown(
         self,
         symbol: str,
         *,
+        period: str | None = None,
+        limit: int = 6,
         start_date: str | None = None,
         end_date: str | None = None,
-        limit: int = 100,
+        fiscal_year: str | None = None,
     ) -> pd.DataFrame:
         """
-        Get historical stock prices with market data
+        Get revenue breakdown
 
         Args:
             symbol: Stock symbol
+            period: Report cycle (e.g., "FY", "Q2")
+            limit: Return latest N records (default: 6)
             start_date: Start date (YYYY-MM-DD)
             end_date: End date (YYYY-MM-DD)
-            limit: Maximum number of records
+            fiscal_year: Specific fiscal year (e.g., "2023")
 
         Returns:
-            DataFrame with price data (date, close, volume, market_cap, pe, ps)
-
-        Example:
-            >>> prices = client.stock.prices("US:AAPL", limit=30)
-            >>> print(prices[["close", "volume"]].tail())
+            DataFrame with revenue breakdown data
         """
         data: dict[str, Any] = {"symbol": symbol, "limit": limit}
+        if period:
+            data["period"] = period
         if start_date:
             data["start_date"] = start_date
         if end_date:
             data["end_date"] = end_date
+        if fiscal_year:
+            data["fiscal_year"] = fiscal_year
 
-        response = self._post("/v1/stock/company-prices", json=data)
+        response = self._post("/v1/stock/company-revenue-breakdown", json=data)
         return self._to_dataframe(response)
 
-    def kline(
+    # -------------------------------------------------------------------------
+    # Price Data (returns DataFrame)
+    # -------------------------------------------------------------------------
+
+    def prices(
         self,
         symbol: str,
         *,
-        interval: Literal["1d", "1w", "1m"] = "1d",
-        adjust: Literal["forward", "backward", "none"] = "forward",
         start_date: str | None = None,
         end_date: str | None = None,
-        limit: int = 100,
     ) -> pd.DataFrame:
         """
-        Get K-line (candlestick) data
+        Get historical stock prices with market data
 
         Args:
             symbol: Stock symbol
-            interval: Time interval ("1d" daily, "1w" weekly, "1m" monthly)
-            adjust: Price adjustment type
-                - "forward": Forward adjusted (前复权)
-                - "backward": Backward adjusted (后复权)
-                - "none": Unadjusted (不复权)
             start_date: Start date (YYYY-MM-DD)
             end_date: End date (YYYY-MM-DD)
-            limit: Maximum number of records
 
         Returns:
-            DataFrame with OHLCV data (date, open, high, low, close, volume)
+            DataFrame with price data (date, close, volume, market_cap, pe, ps)
 
         Example:
-            >>> kline = client.stock.kline("US:TSLA", interval="1d", limit=100)
-            >>> print(kline.tail())
+            >>> prices = client.stock.prices("US:AAPL")
+            >>> print(prices[["close", "volume"]].tail())
         """
-        data: dict[str, Any] = {
-            "symbol": symbol,
-            "interval": interval,
-            "adjust": adjust,
-            "limit": limit,
-        }
+        data: dict[str, Any] = {"symbol": symbol}
         if start_date:
             data["start_date"] = start_date
         if end_date:
             data["end_date"] = end_date
 
-        response = self._post("/v1/stock/kline", json=data)
+        response = self._post("/v1/stock/company-prices", json=data)
         return self._to_dataframe(response)
 
-    def quote(self, symbols: str | list[str]) -> pd.DataFrame:
+    def quote(self, symbol: str) -> pd.DataFrame:
         """
-        Get real-time stock quotes
+        Get real-time stock quote
 
         Args:
-            symbols: Single symbol or list of symbols
+            symbol: Stock symbol (e.g., "US:AAPL", "688001", "00700")
 
         Returns:
             DataFrame with real-time quote data
 
         Example:
-            >>> quotes = client.stock.quote(["US:AAPL", "US:MSFT"])
-            >>> print(quotes[["symbol", "price", "change_percent"]])
+            >>> quote = client.stock.quote("US:AAPL")
+            >>> print(quote[["symbol", "price", "change_percent"]])
         """
-        if isinstance(symbols, str):
-            symbols = [symbols]
-
-        response = self._post("/v1/stock/quote-realtime", json={"symbols": symbols})
+        response = self._post("/v1/stock/quote-realtime", json={"symbol": symbol})
         return self._to_dataframe(response)
 
     def index_prices(
@@ -280,21 +347,19 @@ class StockModule:
         *,
         start_date: str | None = None,
         end_date: str | None = None,
-        limit: int = 100,
     ) -> pd.DataFrame:
         """
-        Get stock index prices (e.g., S&P 500, NASDAQ)
+        Get stock index prices (e.g., HSI, SPX, DJI)
 
         Args:
-            symbol: Index symbol
+            symbol: Index symbol (e.g., "HSI", "SPX", "DJI")
             start_date: Start date (YYYY-MM-DD)
             end_date: End date (YYYY-MM-DD)
-            limit: Maximum number of records
 
         Returns:
             DataFrame with index price data
         """
-        data: dict[str, Any] = {"symbol": symbol, "limit": limit}
+        data: dict[str, Any] = {"symbol": symbol}
         if start_date:
             data["start_date"] = start_date
         if end_date:
@@ -310,42 +375,82 @@ class StockModule:
     def screener(
         self,
         *,
-        market: str | None = None,
-        sector: str | None = None,
-        min_market_cap: float | None = None,
-        max_market_cap: float | None = None,
-        min_pe: float | None = None,
-        max_pe: float | None = None,
-        limit: int = 50,
+        market_cap_more_than: float | None = None,
+        market_cap_lower_than: float | None = None,
+        price_more_than: float | None = None,
+        price_lower_than: float | None = None,
+        change_percentage_more_than: float | None = None,
+        change_percentage_lower_than: float | None = None,
+        volume_more_than: int | None = None,
+        volume_lower_than: int | None = None,
+        country: str | None = None,
+        exchange: str | None = None,
+        dividend_yield_more_than: float | None = None,
+        dividend_yield_lower_than: float | None = None,
+        pe_ttm_more_than: float | None = None,
+        pe_ttm_lower_than: float | None = None,
+        limit: int = 100,
     ) -> pd.DataFrame:
         """
         Screen stocks based on various criteria
 
         Args:
-            market: Filter by market (US, HK, CN)
-            sector: Filter by sector
-            min_market_cap: Minimum market cap
-            max_market_cap: Maximum market cap
-            min_pe: Minimum P/E ratio
-            max_pe: Maximum P/E ratio
-            limit: Maximum number of results
+            market_cap_more_than: Market cap greater than
+            market_cap_lower_than: Market cap less than
+            price_more_than: Stock price greater than
+            price_lower_than: Stock price less than
+            change_percentage_more_than: Change percentage greater than (e.g., 0.02 for 2%)
+            change_percentage_lower_than: Change percentage less than (e.g., 0.04 for 4%)
+            volume_more_than: Trading volume greater than
+            volume_lower_than: Trading volume less than
+            country: Country code (e.g., "US", "CN", "HK")
+            exchange: Exchange code (e.g., "NASDAQ", "NYSE", "HKEX")
+            dividend_yield_more_than: Dividend yield greater than
+            dividend_yield_lower_than: Dividend yield less than
+            pe_ttm_more_than: PE TTM greater than
+            pe_ttm_lower_than: PE TTM less than
+            limit: Maximum number of results (default: 100)
 
         Returns:
             DataFrame with screened stocks
+
+        Example:
+            >>> # Find US stocks with PE < 15 and market cap > 1B
+            >>> stocks = client.stock.screener(
+            ...     country="US",
+            ...     pe_ttm_lower_than=15,
+            ...     market_cap_more_than=1000000000
+            ... )
         """
         data: dict[str, Any] = {"limit": limit}
-        if market:
-            data["market"] = market
-        if sector:
-            data["sector"] = sector
-        if min_market_cap is not None:
-            data["min_market_cap"] = min_market_cap
-        if max_market_cap is not None:
-            data["max_market_cap"] = max_market_cap
-        if min_pe is not None:
-            data["min_pe"] = min_pe
-        if max_pe is not None:
-            data["max_pe"] = max_pe
+        if market_cap_more_than is not None:
+            data["market_cap_more_than"] = market_cap_more_than
+        if market_cap_lower_than is not None:
+            data["market_cap_lower_than"] = market_cap_lower_than
+        if price_more_than is not None:
+            data["price_more_than"] = price_more_than
+        if price_lower_than is not None:
+            data["price_lower_than"] = price_lower_than
+        if change_percentage_more_than is not None:
+            data["change_percentage_more_than"] = change_percentage_more_than
+        if change_percentage_lower_than is not None:
+            data["change_percentage_lower_than"] = change_percentage_lower_than
+        if volume_more_than is not None:
+            data["volume_more_than"] = volume_more_than
+        if volume_lower_than is not None:
+            data["volume_lower_than"] = volume_lower_than
+        if country:
+            data["country"] = country
+        if exchange:
+            data["exchange"] = exchange
+        if dividend_yield_more_than is not None:
+            data["dividend_yield_more_than"] = dividend_yield_more_than
+        if dividend_yield_lower_than is not None:
+            data["dividend_yield_lower_than"] = dividend_yield_lower_than
+        if pe_ttm_more_than is not None:
+            data["pe_ttm_more_than"] = pe_ttm_more_than
+        if pe_ttm_lower_than is not None:
+            data["pe_ttm_lower_than"] = pe_ttm_lower_than
 
         response = self._post("/v1/stock/screener", json=data)
         return self._to_dataframe(response)

reportify_sdk/timeline.py

@@ -3,14 +3,28 @@ Timeline Module
 
 Provides access to timeline feeds based on user's followed entities
 (companies, topics, institutes, media).
+
+NOTE: This module uses internal APIs that are not documented in the public OpenAPI spec.
+These endpoints may change without notice.
 """
 
+import warnings
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     from reportify_sdk.client import Reportify
 
 
+def _timeline_deprecation_warning(method_name: str) -> None:
+    """Emit deprecation warning for timeline methods."""
+    warnings.warn(
+        f"timeline.{method_name}() uses an internal API not documented in the public OpenAPI spec. "
+        "This endpoint may change without notice.",
+        DeprecationWarning,
+        stacklevel=3,
+    )
+
+
 class TimelineModule:
     """
     Timeline module for following-based content feeds
@@ -30,6 +44,9 @@ class TimelineModule:
         """
         Get timeline for followed companies
 
+        .. deprecated::
+            This method uses an internal API not documented in the public OpenAPI spec.
+
         Returns recent content related to companies the user is following,
         including financial reports, news, research reports, and announcements.
 
@@ -44,6 +61,7 @@ class TimelineModule:
             >>> for item in timeline:
             ...     print(item["title"], item["published_at"])
         """
+        _timeline_deprecation_warning("companies")
         response = self._post("/v1/tools/timeline/companies", json={"num": num})
         return response.get("docs", [])
 
@@ -51,6 +69,9 @@ class TimelineModule:
         """
         Get timeline for followed topics
 
+        .. deprecated::
+            This method uses an internal API not documented in the public OpenAPI spec.
+
         Returns recent content related to custom topics the user is following.
 
         Args:
@@ -64,6 +85,7 @@ class TimelineModule:
             >>> for item in timeline:
             ...     print(item["title"])
         """
+        _timeline_deprecation_warning("topics")
         response = self._post("/v1/tools/timeline/topics", json={"num": num})
         return response.get("docs", [])
 
@@ -71,6 +93,9 @@ class TimelineModule:
         """
         Get timeline for followed professional institutes
 
+        .. deprecated::
+            This method uses an internal API not documented in the public OpenAPI spec.
+
         Returns recent content from research institutions, banks,
         and other professional organizations the user is following.
 
@@ -85,6 +110,7 @@ class TimelineModule:
             >>> for item in timeline:
             ...     print(item["channel_name"], item["title"])
         """
+        _timeline_deprecation_warning("institutes")
         response = self._post("/v1/tools/timeline/institutes", json={"num": num})
         return response.get("docs", [])
 
@@ -92,6 +118,9 @@ class TimelineModule:
         """
         Get timeline for followed public media
 
+        .. deprecated::
+            This method uses an internal API not documented in the public OpenAPI spec.
+
         Returns recent content from public media accounts (WeChat, etc.)
         the user is following.
 
@@ -104,6 +133,7 @@ class TimelineModule:
         Example:
             >>> timeline = client.timeline.public_media(num=20)
         """
+        _timeline_deprecation_warning("public_media")
         response = self._post("/v1/tools/timeline/public-media", json={"num": num})
         return response.get("docs", [])
 
@@ -111,6 +141,9 @@ class TimelineModule:
         """
         Get timeline for followed social media
 
+        .. deprecated::
+            This method uses an internal API not documented in the public OpenAPI spec.
+
         Returns recent content from social media accounts (Twitter, etc.)
         the user is following.
 
@@ -123,5 +156,6 @@ class TimelineModule:
         Example:
             >>> timeline = client.timeline.social_media(num=20)
         """
+        _timeline_deprecation_warning("social_media")
         response = self._post("/v1/tools/timeline/social-media", json={"num": num})
         return response.get("docs", [])