pypsx-toolkit 3.0.0__py3-none-any.whl

pypsx_toolkit/core/stream.pyi

@@ -0,0 +1,66 @@
+"""Type stubs for pypsx.core.stream — real-time PSX data streaming."""
+
+from typing import Any, Callable, Dict, List, Union
+
+
+class PSXStream:
+    """
+    Real-time PSX market data stream using polling (15-second interval by default).
+
+    Fetches live price ticks for one or more symbols and delivers them via a
+    callback function.
+
+    Example:
+        >>> import pypsx
+        >>>
+        >>> def on_tick(data: dict):
+        ...     print(f"{data['symbol']}: {data['price']} ({data['change_pct']:+.2f}%)")
+        >>>
+        >>> stream = pypsx.PSXStream(["ENGRO", "HBL", "SYS"])
+        >>> stream.subscribe(on_tick)
+        >>> # Stream runs until stream.stop() is called or KeyboardInterrupt
+    """
+
+    symbols: List[str]
+    interval: int
+
+    def __init__(
+        self,
+        symbols: Union[str, List[str]],
+        interval: int = 15,
+    ) -> None:
+        """
+        Create a real-time stream for one or more PSX symbols.
+
+        Args:
+            symbols: Single symbol string or list of symbols to monitor.
+            interval: Polling interval in seconds (minimum 15 to respect PSX rate limits).
+        """
+        ...
+
+    def subscribe(self, callback: Callable[[Dict[str, Any]], None]) -> None:
+        """
+        Start the stream and deliver ticks to the callback function.
+
+        The callback receives a dict with keys:
+            symbol (str), price (float), change (float), change_pct (float),
+            volume (int), high (float), low (float), timestamp (str).
+
+        This method blocks until stop() is called or an exception occurs.
+
+        Args:
+            callback: Function called with each price tick dict.
+
+        Example:
+            >>> stream = pypsx.PSXStream("OGDC", interval=30)
+            >>> stream.subscribe(lambda d: print(d["price"]))
+        """
+        ...
+
+    def stop(self) -> None:
+        """
+        Stop the stream gracefully.
+
+        Safe to call from within the callback or from another thread.
+        """
+        ...

pypsx_toolkit/endpoints/__init__.py

@@ -0,0 +1 @@
+# Endpoints module for PyPSX library

pypsx_toolkit/endpoints/constants.py

@@ -0,0 +1,121 @@
+"""
+PSX endpoint URL constants and builders.
+
+Centralizes all PSX data endpoint URLs for consistency and maintainability.
+"""
+
+# Base URL for all PSX endpoints
+PSX_BASE_URL = "https://dps.psx.com.pk"
+
+# Main endpoints
+MARKET_WATCH_URL = f"{PSX_BASE_URL}/market-watch"
+SECTOR_SUMMARY_URL = f"{PSX_BASE_URL}/sector-summary/sectorwise"
+PERFORMERS_URL = f"{PSX_BASE_URL}/performers"
+TRADING_BOARD_URL = f"{PSX_BASE_URL}/trading-board/REG/main"
+INDICES_OVERVIEW_URL = f"{PSX_BASE_URL}/indices"
+HISTORICAL_URL = f"{PSX_BASE_URL}/historical"
+PSX_MAIN_URL = f"{PSX_BASE_URL}"
+
+# URL builders for dynamic endpoints
+def get_index_url(index_code: str) -> str:
+    """
+    Get URL for index constituents.
+    
+    Args:
+        index_code: Index code (e.g., 'KSE100', 'KMI30', 'KSE30')
+        
+    Returns:
+        Full URL for the index endpoint
+    """
+    return f"{PSX_BASE_URL}/indices/{index_code}"
+
+
+def get_timeseries_intraday_url(symbol: str) -> str:
+    """
+    Get URL for intraday timeseries data.
+    
+    Args:
+        symbol: Stock symbol (e.g., 'OGDC', 'HBL')
+        
+    Returns:
+        Full URL for intraday timeseries endpoint
+    """
+    return f"{PSX_BASE_URL}/timeseries/int/{symbol.upper()}"
+
+
+def get_timeseries_eod_url(symbol: str) -> str:
+    """
+    Get URL for end-of-day timeseries data.
+    
+    Args:
+        symbol: Stock symbol (e.g., 'OGDC', 'HBL')
+        
+    Returns:
+        Full URL for EOD timeseries endpoint
+    """
+    return f"{PSX_BASE_URL}/timeseries/eod/{symbol.upper()}"
+
+
+def get_company_url(symbol: str) -> str:
+    """
+    Get URL for company information.
+    
+    Args:
+        symbol: Stock symbol (e.g., 'OGDC', 'HBL')
+        
+    Returns:
+        Full URL for company endpoint
+    """
+    return f"{PSX_BASE_URL}/company/{symbol.upper()}"
+
+
+def get_company_reports_url(symbol: str) -> str:
+    """
+    Get URL for company financial reports.
+    
+    Args:
+        symbol: Stock symbol (e.g., 'OGDC', 'HBL')
+        
+    Returns:
+        Full URL for company reports endpoint
+    """
+    return f"{PSX_BASE_URL}/company/reports/{symbol.upper()}"
+
+
+def get_listings_url(listing_type: str = "nc") -> str:
+    """
+    Get URL for listings table.
+    
+    Args:
+        listing_type: 'nc' for normal counter or 'dc' for defaulters counter
+        
+    Returns:
+        Full URL for listings table endpoint
+    """
+    if listing_type not in ("nc", "dc"):
+        raise ValueError("listing_type must be 'nc' or 'dc'")
+    return f"{PSX_BASE_URL}/listings-table/main/{listing_type}"
+
+
+def get_download_image_url(image_file: str) -> str:
+    """
+    Get URL for downloading images from PSX.
+    
+    Args:
+        image_file: Image filename
+        
+    Returns:
+        Full URL for image download endpoint
+    """
+    return f"{PSX_BASE_URL}/download/image/{image_file}"
+
+
+# Common index codes
+COMMON_INDICES = [
+    "KSE100",
+    "KMI30",
+    "KSE30",
+    "KSEALLSHR",
+    "KMIALLSHR",
+]
+

pypsx_toolkit/format/__init__.py

@@ -0,0 +1 @@
+# Format module for PyPSX library

pypsx_toolkit/market.pyi

@@ -0,0 +1,158 @@
+"""Type stubs for pypsx.market — market-level functions."""
+
+from typing import Any, Dict, List
+import pandas as pd
+
+
+def market_watch() -> pd.DataFrame:
+    """
+    Full live market watch — all PSX-listed securities with current prices.
+
+    Returns:
+        DataFrame with columns [Symbol, Company, Sector, LDCP, Open, High, Low,
+        Current, Change, Change%, Volume, Value, Trades].
+
+    Example:
+        >>> import pypsx
+        >>> mw = pypsx.market_watch()
+        >>> gainers = mw[mw["Change%"] > 5]
+    """
+    ...
+
+
+def performers() -> Dict[str, pd.DataFrame]:
+    """
+    Top gainers, top decliners, and most-active stocks for today.
+
+    Returns:
+        Dict with keys "top_gainers", "top_decliners", "top_actives".
+        Each value is a DataFrame with [Symbol, Company, Price, Change%].
+
+    Example:
+        >>> result = pypsx.performers()
+        >>> print(result["top_gainers"].head())
+    """
+    ...
+
+
+def sectors() -> pd.DataFrame:
+    """
+    List all PSX sectors with aggregate statistics.
+
+    Returns:
+        DataFrame with columns [Sector_Code, Sector_Name, Companies_Count,
+        Market_Cap, Change%, Volume].
+
+    Example:
+        >>> df = pypsx.sectors()
+    """
+    ...
+
+
+def trading_board() -> pd.DataFrame:
+    """
+    Live PSX trading board with bid/ask spreads and market depth summary.
+
+    Returns:
+        DataFrame with columns [Symbol, Bid, Ask, LTP, Volume, Trades,
+        High, Low, LDCP, Change%].
+
+    Example:
+        >>> board = pypsx.trading_board()
+    """
+    ...
+
+
+def get_symbols() -> List[str]:
+    """
+    Return a list of all currently listed PSX equity symbols.
+
+    Returns:
+        Sorted list of ticker strings, e.g. ["ABOT", "ABL", "ACPL", ...].
+
+    Example:
+        >>> symbols = pypsx.get_symbols()
+        >>> print(len(symbols), "listed symbols")
+    """
+    ...
+
+
+def listings_nc() -> List[str]:
+    """
+    Symbols of Non-Compliant (NC) listed companies on PSX.
+
+    Returns:
+        List of ticker strings.
+    """
+    ...
+
+
+def listings_dc() -> List[str]:
+    """
+    Symbols of companies on the Defaulters Counter (DC) on PSX.
+
+    Returns:
+        List of ticker strings.
+    """
+    ...
+
+
+def get_indices() -> pd.DataFrame:
+    """
+    List all PSX market indices with current values and changes.
+
+    Returns:
+        DataFrame with columns [Index, Current, Change, Change%, High, Low].
+
+    Example:
+        >>> indices = pypsx.get_indices()
+    """
+    ...
+
+
+def get_indices_breakdown() -> Dict[str, Any]:
+    """
+    Detailed breakdown of all PSX indices including sub-indices and sectors.
+
+    Returns:
+        Nested dict keyed by index code, with sector weights and constituent counts.
+    """
+    ...
+
+
+def get_sector_breakdown() -> Dict[str, Any]:
+    """
+    Market-wide sector breakdown with aggregate market cap and performance.
+
+    Returns:
+        Dict with sector codes as keys and aggregate stats as values.
+    """
+    ...
+
+
+def get_homepage_indices() -> pd.DataFrame:
+    """
+    Abbreviated index snapshot used on the PSX homepage.
+
+    Returns:
+        DataFrame with KSE-100, KSE-30, KMI-30, and All-Share index data.
+    """
+    ...
+
+
+def index_constituents(index_code: str) -> pd.DataFrame:
+    """
+    Get all companies that make up a specific PSX index.
+
+    Args:
+        index_code: Index identifier, e.g. "KSE100", "KMI30", "KSE30", "ALLSHR".
+
+    Returns:
+        DataFrame with columns [Symbol, Company, Sector, Weight, Market_Cap,
+        Shares, Price, Change%].
+
+    Example:
+        >>> df = pypsx.index_constituents("KMI30")   # KMI-30 index
+        >>> df = pypsx.index_constituents("KSE100")  # KSE-100 index
+    """
+    ...

pypsx_toolkit/models.py

@@ -0,0 +1,224 @@
+"""
+Data models for PyPSX library.
+
+Provides typed data structures for all PSX endpoints following the specifications
+in CHANGE.md. All models use normalized field names and ensure no nulls where
+data is guaranteed to exist.
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict, Any
+from datetime import datetime
+
+
+@dataclass
+class SymbolInfo:
+    """Symbol with optional status tags."""
+    symbol: str
+    tags: List[str] = field(default_factory=list)
+
+
+@dataclass
+class SectorSummary:
+    """Sector summary data from sector-summary endpoint."""
+    sector_code: str
+    sector_name: str
+    advance: int = 0
+    decline: int = 0
+    unchange: int = 0
+    turnover: float = 0.0
+    market_cap_b: float = 0.0  # Market cap in billions
+
+
+@dataclass
+class SectorCompany:
+    """Company within a sector."""
+    symbol: str
+    name: str
+    sector_code: str
+    last_close: float = 0.0
+    open: float = 0.0
+    high: float = 0.0
+    low: float = 0.0
+    current_price: float = 0.0
+    change: float = 0.0
+    change_pct: float = 0.0
+    volume: int = 0
+    tags: List[str] = field(default_factory=list)
+
+
+@dataclass
+class CompanyMarketWatch:
+    """Market watch entry for a company."""
+    symbol: str
+    sector: str
+    listed_in: List[str] = field(default_factory=list)
+    last_close: float = 0.0
+    open: float = 0.0
+    high: float = 0.0
+    low: float = 0.0
+    current_price: float = 0.0
+    change: float = 0.0
+    change_pct: float = 0.0
+    volume: int = 0
+    tags: List[str] = field(default_factory=list)
+
+
+@dataclass
+class IndexConstituent:
+    """Index constituent data."""
+    symbol: str
+    name: str
+    last_close: float = 0.0
+    current_price: float = 0.0
+    change: float = 0.0
+    change_pct: float = 0.0
+    index_weight_pct: float = 0.0
+    index_point: float = 0.0
+    volume: int = 0
+    freefloat_m: float = 0.0  # Free float in millions
+    market_cap_m: float = 0.0  # Market cap in millions
+    tags: List[str] = field(default_factory=list)
+
+
+@dataclass
+class IndexMeta:
+    """Index metadata."""
+    index_code: str
+    index_name: str
+    current_value: float = 0.0
+    change: float = 0.0
+    change_pct: float = 0.0
+    high: float = 0.0
+    low: float = 0.0
+    volume: int = 0
+
+
+@dataclass
+class TradingBoardRow:
+    """Trading board entry."""
+    symbol: str
+    name: str
+    bid_volume: int = 0
+    bid_price: float = 0.0
+    offer_volume: int = 0
+    offer_price: float = 0.0
+    last_close: float = 0.0
+    change: float = 0.0
+    volume: int = 0
+    tags: List[str] = field(default_factory=list)
+
+
+@dataclass
+class TopActiveStock:
+    """Top active stock entry."""
+    symbol: str
+    price: float = 0.0
+    change: float = 0.0
+    change_pct: float = 0.0
+    volume: int = 0
+    tags: List[str] = field(default_factory=list)
+
+
+@dataclass
+class TopAdvancer:
+    """Top advancer entry."""
+    symbol: str
+    price: float = 0.0
+    change: float = 0.0
+    change_pct: float = 0.0
+    volume: int = 0
+    tags: List[str] = field(default_factory=list)
+
+
+@dataclass
+class TopDecliner:
+    """Top decliner entry."""
+    symbol: str
+    price: float = 0.0
+    change: float = 0.0
+    change_pct: float = 0.0
+    volume: int = 0
+    tags: List[str] = field(default_factory=list)
+
+
+@dataclass
+class IntradayBar:
+    """Intraday data point."""
+    timestamp: datetime
+    price: float = 0.0
+    volume: int = 0
+
+
+@dataclass
+class EODBar:
+    """End-of-day data point."""
+    timestamp: datetime
+    close: float = 0.0
+    volume: int = 0
+    weighted_avg: float = 0.0
+    open: Optional[float] = None
+    high: Optional[float] = None
+    low: Optional[float] = None
+
+
+@dataclass
+class ListingEntry:
+    """Listing entry from listings table."""
+    symbol: str
+    name: str
+    sector: str
+    clearing_type: str = ""
+    shares: int = 0
+    free_float: int = 0
+    listed_in: List[str] = field(default_factory=list)
+    non_compliance: str = ""  # For DC listings
+    tags: List[str] = field(default_factory=list)
+
+
+@dataclass
+class CompanyFundamentals:
+    """Company fundamentals data."""
+    symbol: str
+    business_description: str = ""
+    address: str = ""
+    website: str = ""
+    key_people: Dict[str, str] = field(default_factory=dict)  # Name -> Title
+    equity_profile: Dict[str, Any] = field(default_factory=dict)
+    financials_annual: Dict[str, List[float]] = field(default_factory=dict)
+    financials_quarterly: Dict[str, List[float]] = field(default_factory=dict)
+    ratios: Dict[str, List[float]] = field(default_factory=dict)
+
+
+@dataclass
+class Announcement:
+    """Company announcement."""
+    symbol: str
+    date: str
+    title: str
+    section: str  # "Financial Results", "Board Meetings", "Others"
+    image_link: Optional[str] = None
+    pdf_link: Optional[str] = None
+
+
+@dataclass
+class DividendInfo:
+    """Dividend information."""
+    symbol: str
+    dividend_yield: Optional[float] = None
+    annual_dividend: Optional[float] = None
+    ex_dividend_date: Optional[str] = None
+    payout_frequency: Optional[str] = None
+    payout_ratio: Optional[float] = None
+    dividend_growth: Optional[str] = None
+
+
+@dataclass
+class DividendHistory:
+    """Dividend history entry."""
+    symbol: str
+    ex_dividend_date: str
+    cash_amount: str
+    record_date: Optional[str] = None
+    pay_date: Optional[str] = None
+