reportify-sdk 0.1.0__py3-none-any.whl

reportify_sdk/stock.py

@@ -0,0 +1,430 @@
+"""
+Stock Module
+
+Provides access to stock market data including prices, financial statements,
+and company information. Time series data is returned as pandas DataFrame.
+"""
+
+from typing import TYPE_CHECKING, Any, Literal
+
+import pandas as pd
+
+if TYPE_CHECKING:
+    from reportify_sdk.client import Reportify
+
+
+class StockModule:
+    """
+    Stock data module for financial data and market information
+
+    Access through the main client:
+        >>> client = Reportify(api_key="xxx")
+        >>> income = client.stock.income_statement("US:AAPL")
+    """
+
+    def __init__(self, client: "Reportify"):
+        self._client = client
+
+    def _post(self, path: str, json: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self._client._post(path, json=json)
+
+    # -------------------------------------------------------------------------
+    # Company Information
+    # -------------------------------------------------------------------------
+
+    def overview(self, symbol: str) -> 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")
+
+        Returns:
+            Company information dictionary
+
+        Example:
+            >>> info = client.stock.overview("US:AAPL")
+            >>> print(info["name"], info["sector"])
+        """
+        response = self._post("/v1/stock/company-overview", json={"symbol": symbol})
+        return response
+
+    def shareholders(self, symbol: str) -> list[dict[str, Any]]:
+        """
+        Get list of major shareholders
+
+        Args:
+            symbol: Stock symbol
+
+        Returns:
+            List of shareholders with ownership details
+        """
+        response = self._post("/v1/stock/company-shareholders", json={"symbol": symbol})
+        return response if isinstance(response, list) else response.get("shareholders", [])
+
+    # -------------------------------------------------------------------------
+    # Financial Statements (returns DataFrame)
+    # -------------------------------------------------------------------------
+
+    def income_statement(
+        self,
+        symbol: str,
+        *,
+        period: Literal["annual", "quarterly"] = "annual",
+        limit: int = 10,
+    ) -> pd.DataFrame:
+        """
+        Get income statement data
+
+        Args:
+            symbol: Stock symbol (e.g., "US:AAPL")
+            period: "annual" or "quarterly"
+            limit: Number of periods to return
+
+        Returns:
+            DataFrame with income statement data, indexed by date
+
+        Example:
+            >>> 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},
+        )
+        return self._to_dataframe(response)
+
+    def balance_sheet(
+        self,
+        symbol: str,
+        *,
+        period: Literal["annual", "quarterly"] = "annual",
+        limit: int = 10,
+    ) -> pd.DataFrame:
+        """
+        Get balance sheet data
+
+        Args:
+            symbol: Stock symbol
+            period: "annual" or "quarterly"
+            limit: Number of periods to return
+
+        Returns:
+            DataFrame with balance sheet data, indexed by date
+
+        Example:
+            >>> 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},
+        )
+        return self._to_dataframe(response)
+
+    def cashflow_statement(
+        self,
+        symbol: str,
+        *,
+        period: Literal["annual", "quarterly"] = "annual",
+        limit: int = 10,
+    ) -> pd.DataFrame:
+        """
+        Get cash flow statement data
+
+        Args:
+            symbol: Stock symbol
+            period: "annual" or "quarterly"
+            limit: Number of periods to return
+
+        Returns:
+            DataFrame with cash flow data, indexed by date
+
+        Example:
+            >>> 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")
+
+        Returns:
+            DataFrame with revenue breakdown data
+        """
+        response = self._post(
+            "/v1/stock/company-revenue-breakdown",
+            json={"symbol": symbol, "breakdown_type": breakdown_type},
+        )
+        return self._to_dataframe(response)
+
+    # -------------------------------------------------------------------------
+    # Price Data (returns DataFrame)
+    # -------------------------------------------------------------------------
+
+    def prices(
+        self,
+        symbol: str,
+        *,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        limit: int = 100,
+    ) -> pd.DataFrame:
+        """
+        Get historical stock prices with market data
+
+        Args:
+            symbol: Stock symbol
+            start_date: Start date (YYYY-MM-DD)
+            end_date: End date (YYYY-MM-DD)
+            limit: Maximum number of records
+
+        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())
+        """
+        data: dict[str, Any] = {"symbol": symbol, "limit": limit}
+        if start_date:
+            data["start_date"] = start_date
+        if end_date:
+            data["end_date"] = end_date
+
+        response = self._post("/v1/stock/company-prices", json=data)
+        return self._to_dataframe(response)
+
+    def kline(
+        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
+
+        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)
+
+        Example:
+            >>> kline = client.stock.kline("US:TSLA", interval="1d", limit=100)
+            >>> print(kline.tail())
+        """
+        data: dict[str, Any] = {
+            "symbol": symbol,
+            "interval": interval,
+            "adjust": adjust,
+            "limit": limit,
+        }
+        if start_date:
+            data["start_date"] = start_date
+        if end_date:
+            data["end_date"] = end_date
+
+        response = self._post("/v1/stock/kline", json=data)
+        return self._to_dataframe(response)
+
+    def quote(self, symbols: str | list[str]) -> pd.DataFrame:
+        """
+        Get real-time stock quotes
+
+        Args:
+            symbols: Single symbol or list of symbols
+
+        Returns:
+            DataFrame with real-time quote data
+
+        Example:
+            >>> quotes = client.stock.quote(["US:AAPL", "US:MSFT"])
+            >>> print(quotes[["symbol", "price", "change_percent"]])
+        """
+        if isinstance(symbols, str):
+            symbols = [symbols]
+
+        response = self._post("/v1/stock/quote-realtime", json={"symbols": symbols})
+        return self._to_dataframe(response)
+
+    def index_prices(
+        self,
+        symbol: str,
+        *,
+        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)
+
+        Args:
+            symbol: Index symbol
+            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}
+        if start_date:
+            data["start_date"] = start_date
+        if end_date:
+            data["end_date"] = end_date
+
+        response = self._post("/v1/stock/index-prices", json=data)
+        return self._to_dataframe(response)
+
+    # -------------------------------------------------------------------------
+    # Screening and Calendar
+    # -------------------------------------------------------------------------
+
+    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,
+    ) -> 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
+
+        Returns:
+            DataFrame with screened stocks
+        """
+        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
+
+        response = self._post("/v1/stock/screener", json=data)
+        return self._to_dataframe(response)
+
+    def earnings_calendar(
+        self,
+        *,
+        area: Literal["us", "hk", "cn"] = "us",
+        start_date: str | None = None,
+        end_date: str | None = None,
+        symbol: str | None = None,
+    ) -> pd.DataFrame:
+        """
+        Get earnings announcement calendar
+
+        Args:
+            area: Market area ("us", "hk", "cn")
+            start_date: Start date (YYYY-MM-DD)
+            end_date: End date (YYYY-MM-DD)
+            symbol: Filter by specific symbol
+
+        Returns:
+            DataFrame with earnings calendar data
+        """
+        data: dict[str, Any] = {"area": area}
+        if start_date:
+            data["start_date"] = start_date
+        if end_date:
+            data["end_date"] = end_date
+        if symbol:
+            data["symbol"] = symbol
+
+        response = self._post("/v1/stock/earnings-calendar", json=data)
+        return self._to_dataframe(response)
+
+    def ipo_calendar_hk(
+        self,
+        status: Literal["Filing", "Hearing", "Priced"] = "Filing",
+    ) -> pd.DataFrame:
+        """
+        Get Hong Kong IPO calendar
+
+        Args:
+            status: IPO status filter ("Filing", "Hearing", "Priced")
+
+        Returns:
+            DataFrame with IPO calendar data
+        """
+        response = self._post("/v1/stock/ipo-calendar-hk", json={"status": status})
+        return self._to_dataframe(response)
+
+    # -------------------------------------------------------------------------
+    # Helper Methods
+    # -------------------------------------------------------------------------
+
+    def _to_dataframe(self, data: Any) -> pd.DataFrame:
+        """Convert API response to DataFrame"""
+        if isinstance(data, list):
+            df = pd.DataFrame(data)
+        elif isinstance(data, dict):
+            # Handle nested data structures
+            if "data" in data:
+                df = pd.DataFrame(data["data"])
+            elif "items" in data:
+                df = pd.DataFrame(data["items"])
+            elif "records" in data:
+                df = pd.DataFrame(data["records"])
+            else:
+                # Try to create DataFrame from dict values
+                df = pd.DataFrame([data])
+        else:
+            df = pd.DataFrame()
+
+        # Set date column as index if present
+        date_columns = ["date", "period", "fiscal_date", "report_date"]
+        for col in date_columns:
+            if col in df.columns:
+                df[col] = pd.to_datetime(df[col])
+                df = df.set_index(col)
+                break
+
+        return df

reportify_sdk/timeline.py

@@ -0,0 +1,127 @@
+"""
+Timeline Module
+
+Provides access to timeline feeds based on user's followed entities
+(companies, topics, institutes, media).
+"""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from reportify_sdk.client import Reportify
+
+
+class TimelineModule:
+    """
+    Timeline module for following-based content feeds
+
+    Access through the main client:
+        >>> client = Reportify(api_key="xxx")
+        >>> timeline = client.timeline.companies(num=20)
+    """
+
+    def __init__(self, client: "Reportify"):
+        self._client = client
+
+    def _post(self, path: str, json: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self._client._post(path, json=json)
+
+    def companies(self, *, num: int = 10) -> list[dict[str, Any]]:
+        """
+        Get timeline for followed companies
+
+        Returns recent content related to companies the user is following,
+        including financial reports, news, research reports, and announcements.
+
+        Args:
+            num: Number of items to return (default: 10, max: 100)
+
+        Returns:
+            List of timeline items (documents) from followed companies
+
+        Example:
+            >>> timeline = client.timeline.companies(num=20)
+            >>> for item in timeline:
+            ...     print(item["title"], item["published_at"])
+        """
+        response = self._post("/v1/tools/timeline/companies", json={"num": num})
+        return response.get("docs", [])
+
+    def topics(self, *, num: int = 10) -> list[dict[str, Any]]:
+        """
+        Get timeline for followed topics
+
+        Returns recent content related to custom topics the user is following.
+
+        Args:
+            num: Number of items to return (default: 10, max: 100)
+
+        Returns:
+            List of timeline items related to followed topics
+
+        Example:
+            >>> timeline = client.timeline.topics(num=20)
+            >>> for item in timeline:
+            ...     print(item["title"])
+        """
+        response = self._post("/v1/tools/timeline/topics", json={"num": num})
+        return response.get("docs", [])
+
+    def institutes(self, *, num: int = 10) -> list[dict[str, Any]]:
+        """
+        Get timeline for followed professional institutes
+
+        Returns recent content from research institutions, banks,
+        and other professional organizations the user is following.
+
+        Args:
+            num: Number of items to return (default: 10, max: 100)
+
+        Returns:
+            List of timeline items from followed institutes
+
+        Example:
+            >>> timeline = client.timeline.institutes(num=20)
+            >>> for item in timeline:
+            ...     print(item["channel_name"], item["title"])
+        """
+        response = self._post("/v1/tools/timeline/institutes", json={"num": num})
+        return response.get("docs", [])
+
+    def public_media(self, *, num: int = 10) -> list[dict[str, Any]]:
+        """
+        Get timeline for followed public media
+
+        Returns recent content from public media accounts (WeChat, etc.)
+        the user is following.
+
+        Args:
+            num: Number of items to return (default: 10, max: 100)
+
+        Returns:
+            List of timeline items from followed public media
+
+        Example:
+            >>> timeline = client.timeline.public_media(num=20)
+        """
+        response = self._post("/v1/tools/timeline/public-media", json={"num": num})
+        return response.get("docs", [])
+
+    def social_media(self, *, num: int = 10) -> list[dict[str, Any]]:
+        """
+        Get timeline for followed social media
+
+        Returns recent content from social media accounts (Twitter, etc.)
+        the user is following.
+
+        Args:
+            num: Number of items to return (default: 10, max: 100)
+
+        Returns:
+            List of timeline items from followed social media
+
+        Example:
+            >>> timeline = client.timeline.social_media(num=20)
+        """
+        response = self._post("/v1/tools/timeline/social-media", json={"num": num})
+        return response.get("docs", [])