pypsx-toolkit 3.0.0__py3-none-any.whl

pypsx_toolkit/models.pyi

@@ -0,0 +1,199 @@
+"""Type stubs for pypsx.models — data model dataclasses."""
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class SymbolInfo:
+    """Basic metadata for a PSX-listed security."""
+    symbol: str
+    company_name: str
+    sector: str
+    listing_date: Optional[str]
+    face_value: Optional[float]
+    shares_outstanding: Optional[float]
+
+
+@dataclass
+class SectorSummary:
+    """Aggregate statistics for a PSX sector."""
+    sector_code: str
+    sector_name: str
+    companies_count: int
+    market_cap: float
+    change_pct: float
+    volume: int
+
+
+@dataclass
+class SectorCompany:
+    """A company entry within a sector listing."""
+    symbol: str
+    company_name: str
+    market_cap: float
+    change_pct: float
+    volume: int
+
+
+@dataclass
+class CompanyMarketWatch:
+    """Live market watch row for a single company."""
+    symbol: str
+    company_name: str
+    sector: str
+    ldcp: float
+    open: float
+    high: float
+    low: float
+    current: float
+    change: float
+    change_pct: float
+    volume: int
+    value: float
+    trades: int
+
+
+@dataclass
+class IndexConstituent:
+    """A single company entry in a PSX index."""
+    symbol: str
+    company_name: str
+    sector: str
+    weight: float
+    market_cap: float
+    shares: float
+    price: float
+    change_pct: float
+
+
+@dataclass
+class IndexMeta:
+    """Metadata and current value of a PSX index."""
+    index_code: str
+    index_name: str
+    current: float
+    change: float
+    change_pct: float
+    high: float
+    low: float
+    volume: int
+
+
+@dataclass
+class TradingBoardRow:
+    """Live trading board entry with bid/ask spread."""
+    symbol: str
+    bid: float
+    ask: float
+    ltp: float
+    volume: int
+    trades: int
+    high: float
+    low: float
+    ldcp: float
+    change_pct: float
+
+
+@dataclass
+class TopActiveStock:
+    """Most-active stock by volume."""
+    symbol: str
+    company_name: str
+    volume: int
+    value: float
+    change_pct: float
+
+
+@dataclass
+class TopAdvancer:
+    """Top gaining stock for the session."""
+    symbol: str
+    company_name: str
+    price: float
+    change_pct: float
+
+
+@dataclass
+class TopDecliner:
+    """Top declining stock for the session."""
+    symbol: str
+    company_name: str
+    price: float
+    change_pct: float
+
+
+@dataclass
+class IntradayBar:
+    """A single intraday price tick."""
+    time: str
+    price: float
+    volume: int
+    change: float
+    change_pct: float
+
+
+@dataclass
+class EODBar:
+    """End-of-day OHLCV bar."""
+    date: str
+    open: float
+    high: float
+    low: float
+    close: float
+    volume: int
+    change_pct: float
+
+
+@dataclass
+class ListingEntry:
+    """A PSX listing entry (from compliant/non-compliant/defaulter lists)."""
+    symbol: str
+    company_name: str
+    listing_type: str
+
+
+@dataclass
+class CompanyFundamentals:
+    """Company fundamental financial metrics."""
+    symbol: str
+    pe_ratio: Optional[float]
+    eps: Optional[float]
+    book_value: Optional[float]
+    dividend_yield: Optional[float]
+    roe: Optional[float]
+    roa: Optional[float]
+    debt_to_equity: Optional[float]
+    current_ratio: Optional[float]
+    market_cap: Optional[float]
+    shares_outstanding: Optional[float]
+
+
+@dataclass
+class Announcement:
+    """A PSX corporate announcement."""
+    date: str
+    category: str
+    subject: str
+    description: str
+
+
+@dataclass
+class DividendInfo:
+    """Latest dividend details for a symbol."""
+    symbol: str
+    dividend_type: str
+    rate: float
+    face_value: float
+    ex_date: Optional[str]
+    payment_date: Optional[str]
+
+
+@dataclass
+class DividendHistory:
+    """Historical dividend payment record."""
+    date: str
+    dividend_type: str
+    rate: float
+    face_value: float
+    announcement_date: Optional[str]

pypsx_toolkit/ticker.pyi

@@ -0,0 +1,237 @@
+"""Type stubs for pypsx.ticker — PSXTicker (yfinance-style interface)."""
+
+from typing import Any, Callable, Dict, List, Optional, Union
+import pandas as pd
+
+
+class PSXTicker:
+    """
+    PSX stock ticker — yfinance-compatible interface for Pakistan Stock Exchange data.
+
+    Supports equity symbols (e.g. "ENGRO", "HBL") and index symbols (e.g. "KSE100", "KMI30").
+
+    Example:
+        >>> import pypsx
+        >>> t = pypsx.Ticker("ENGRO")
+        >>> df = t.history(period="1y")
+        >>> print(df.head())
+        >>> print(t.info["sector"])
+    """
+
+    symbol: str
+
+    def __init__(self, symbol: str) -> None:
+        """
+        Create a ticker for a PSX-listed symbol.
+
+        Args:
+            symbol: PSX ticker symbol (case-insensitive), e.g. "ENGRO", "HBL", "KSE100".
+
+        Raises:
+            PSXNotFoundError: If the symbol is not listed on PSX.
+        """
+        ...
+
+    # -------------------------------------------------------------------------
+    # Properties
+    # -------------------------------------------------------------------------
+
+    @property
+    def info(self) -> Dict[str, Any]:
+        """
+        Comprehensive company information dictionary.
+
+        Keys include: symbol, company_name, sector, market_cap, pe_ratio,
+        eps, book_value, dividend_yield, shares_outstanding, float_shares,
+        current_price, fifty_two_week_high, fifty_two_week_low, volume,
+        average_volume, and more.
+
+        Returns:
+            dict with company fundamentals and market data.
+
+        Example:
+            >>> t = pypsx.Ticker("OGDC")
+            >>> print(t.info["pe_ratio"])
+        """
+        ...
+
+    @property
+    def fast_info(self) -> Dict[str, Any]:
+        """
+        Quick snapshot of key price metrics (lighter than .info).
+
+        Keys include: last_price, change, change_pct, volume, high, low,
+        open, prev_close.
+
+        Returns:
+            dict with real-time price snapshot.
+        """
+        ...
+
+    @property
+    def snapshot(self) -> Dict[str, Any]:
+        """
+        Multi-tab market snapshot (combines price, fundamentals, and trading stats).
+
+        Returns:
+            Nested dict with tabs: price, fundamentals, trading_stats, company.
+        """
+        ...
+
+    # -------------------------------------------------------------------------
+    # Historical / OHLCV data
+    # -------------------------------------------------------------------------
+
+    def history(
+        self,
+        period: str = "1mo",
+        interval: str = "1d",
+        to_csv: Optional[str] = None,
+    ) -> pd.DataFrame:
+        """
+        Fetch OHLCV history using a period shorthand (yfinance-compatible).
+
+        Args:
+            period: Time period string. Valid values:
+                "1d", "5d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd", "max"
+            interval: Bar interval. Currently only "1d" (daily) is supported.
+            to_csv: Optional file path to export the DataFrame as CSV.
+
+        Returns:
+            DataFrame with columns [Date, Open, High, Low, Close, Volume, Change%].
+            Date is the index.
+
+        Raises:
+            PSXNotFoundError: If the symbol does not exist.
+            PSXHTTPError: If the PSX server returns an error.
+
+        Example:
+            >>> t = pypsx.Ticker("ENGRO")
+            >>> df = t.history(period="1y")
+            >>> df = t.history(period="5y", to_csv="engro_5y.csv")
+        """
+        ...
+
+    def get_historical(
+        self,
+        start_date: str,
+        end_date: str,
+        max_workers: int = 4,
+        show_progress: bool = False,
+    ) -> pd.DataFrame:
+        """
+        Fetch historical OHLCV data between two specific dates.
+
+        Args:
+            start_date: Start date in "YYYY-MM-DD" format.
+            end_date: End date in "YYYY-MM-DD" format.
+            max_workers: Number of parallel HTTP workers (speeds up long date ranges).
+            show_progress: If True, show a tqdm progress bar.
+
+        Returns:
+            DataFrame with columns [Date, Open, High, Low, Close, Volume, Change%].
+
+        Example:
+            >>> t = pypsx.Ticker("HBL")
+            >>> df = t.get_historical("2020-01-01", "2024-12-31")
+        """
+        ...
+
+    # -------------------------------------------------------------------------
+    # Intraday / real-time
+    # -------------------------------------------------------------------------
+
+    def intraday(self) -> pd.DataFrame:
+        """
+        Fetch intraday tick data for the last 2 trading days.
+
+        Returns:
+            DataFrame with columns [Time, Price, Volume, Change, Change%].
+            Each row is a trade tick.
+
+        Example:
+            >>> t = pypsx.Ticker("SYS")
+            >>> ticks = t.intraday()
+        """
+        ...
+
+    def market_watch(self) -> pd.DataFrame:
+        """
+        Live market watch entry for this symbol (price, volume, change, etc.).
+
+        Returns:
+            Single-row DataFrame with live market data.
+        """
+        ...
+
+    def orderbook(self) -> pd.DataFrame:
+        """
+        Order book / market depth for this symbol.
+
+        Returns:
+            DataFrame with bid/ask price levels and volumes.
+        """
+        ...
+
+    # -------------------------------------------------------------------------
+    # Corporate actions
+    # -------------------------------------------------------------------------
+
+    def announcements(self) -> pd.DataFrame:
+        """
+        Fetch company announcements (dividends, results, AGM notices, etc.).
+
+        Returns:
+            DataFrame with columns [Date, Category, Subject, Description].
+
+        Example:
+            >>> t = pypsx.Ticker("ENGRO")
+            >>> df = t.announcements()
+        """
+        ...
+
+    def dividends(self) -> pd.DataFrame:
+        """
+        Dividend history for this symbol.
+
+        Returns:
+            DataFrame with columns [Date, Type, Rate, Face_Value, Announcement_Date].
+
+        Example:
+            >>> t = pypsx.Ticker("OGDC")
+            >>> df = t.dividends()
+        """
+        ...
+
+    # -------------------------------------------------------------------------
+    # Sector / index
+    # -------------------------------------------------------------------------
+
+    def sector(self) -> pd.DataFrame:
+        """
+        Sector membership and sector-level statistics for this symbol.
+
+        Returns:
+            DataFrame with sector name, peer companies, and sector indices.
+        """
+        ...
+
+    def constituents(self) -> pd.DataFrame:
+        """
+        For index symbols (e.g. "KSE100"), return all constituent companies.
+
+        Returns:
+            DataFrame with columns [Symbol, Company, Sector, Weight, Market_Cap].
+
+        Raises:
+            PSXScopeError: If called on an equity symbol (not an index).
+
+        Example:
+            >>> idx = pypsx.Ticker("KSE100")
+            >>> df = idx.constituents()
+        """
+        ...
+
+
+# Alias for yfinance-compatibility
+Ticker = PSXTicker