reportify-sdk 0.2.8__py3-none-any.whl → 0.2.10__py3-none-any.whl

reportify_sdk/stock.py

@@ -72,17 +72,30 @@ class StockModule:
         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", [])
 
     # -------------------------------------------------------------------------
@@ -93,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
@@ -111,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(
@@ -122,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
@@ -139,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
@@ -167,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(
@@ -303,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:
@@ -333,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", [])

reportify_sdk/user.py

@@ -0,0 +1,44 @@
+"""
+User Module
+
+Provides access to user-related tools and data.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from reportify_sdk.client import Reportify
+
+
+class UserModule:
+    """
+    User module for accessing user-related tools
+
+    Access through the main client:
+        >>> client = Reportify(api_key="xxx")
+        >>> companies = client.user.followed_companies()
+    """
+
+    def __init__(self, client: "Reportify"):
+        self._client = client
+
+    def _get(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self._client._get(path, params=params)
+
+    def followed_companies(self) -> list[dict[str, Any]]:
+        """
+        Get all companies followed by the user
+
+        Returns a list of companies that the user is following,
+        including company details like symbol, name, logo, and follow timestamp.
+
+        Returns:
+            List of followed company information
+
+        Example:
+            >>> companies = client.user.followed_companies()
+            >>> for company in companies:
+            ...     print(f"{company['symbol']}: {company['name']}")
+        """
+        response = self._get("/v1/tools/user/followed-companies")
+        return response.get("companies", [])

{reportify_sdk-0.2.8.dist-info → reportify_sdk-0.2.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reportify-sdk
-Version: 0.2.8
+Version: 0.2.10
 Summary: Python SDK for Reportify API - Financial data and document search
 Author-email: Reportify <support@reportify.cn>
 License-Expression: MIT