pypsx-toolkit 3.0.0__py3-none-any.whl

pypsx_toolkit/analysis/__init__.pyi

@@ -0,0 +1,348 @@
+"""
+Type stubs for pypsx.analysis — statistical analysis, technical indicators,
+performance metrics, and AI-powered insights.
+
+Example:
+    >>> import pypsx
+    >>> t = pypsx.Ticker("ENGRO")
+    >>> df = t.history(period="1y")
+    >>>
+    >>> # Technical indicators
+    >>> sma_20 = pypsx.analysis.moving_average(df, window=20)
+    >>> upper, mid, lower = pypsx.analysis.bollinger_bands(df)
+    >>> rsi = pypsx.analysis.rsi(df)
+    >>>
+    >>> # Performance metrics
+    >>> print(pypsx.analysis.sharpe_ratio(df))
+    >>> print(pypsx.analysis.max_drawdown(df))
+    >>>
+    >>> # Full summary
+    >>> summary = pypsx.analysis.performance_summary(df)
+"""
+
+from typing import Any, Callable, Dict, List, Optional, Tuple
+import pandas as pd
+
+# =============================================================================
+# Statistical Functions
+# =============================================================================
+
+def returns(df: pd.DataFrame) -> float:
+    """Total return for the period."""
+    ...
+
+def volatility(df: pd.DataFrame, annualize: bool = True) -> float:
+    """Annualised return volatility (std dev of log returns)."""
+    ...
+
+def correlation(df1: pd.DataFrame, df2: pd.DataFrame) -> float:
+    """Pearson correlation coefficient between two price series."""
+    ...
+
+def correlation_matrix(portfolio_data: Dict[str, pd.DataFrame]) -> pd.DataFrame:
+    """Correlation matrix for a portfolio of symbols."""
+    ...
+
+def beta(df: pd.DataFrame, market_returns: pd.Series) -> float:
+    """Beta coefficient relative to a market index."""
+    ...
+
+def skewness(df: pd.DataFrame) -> float:
+    """Skewness of the return distribution."""
+    ...
+
+def kurtosis(df: pd.DataFrame) -> float:
+    """Excess kurtosis of the return distribution."""
+    ...
+
+def var(df: pd.DataFrame, confidence: float = 0.95) -> float:
+    """Historical Value at Risk at the given confidence level."""
+    ...
+
+def cvar(df: pd.DataFrame, confidence: float = 0.95) -> float:
+    """Conditional Value at Risk (Expected Shortfall)."""
+    ...
+
+def autocorrelation(df: pd.DataFrame, lag: int = 1) -> float:
+    """Autocorrelation of returns at the given lag."""
+    ...
+
+# =============================================================================
+# Technical Indicators
+# =============================================================================
+
+def moving_average(df: pd.DataFrame, window: int = 20) -> pd.Series:
+    """Simple Moving Average (SMA).
+
+    Args:
+        df: OHLCV DataFrame (uses Close column).
+        window: Rolling window in bars (default 20).
+
+    Returns:
+        pd.Series of SMA values.
+    """
+    ...
+
+def exponential_moving_average(df: pd.DataFrame, window: int = 20) -> pd.Series:
+    """Exponential Moving Average (EMA).
+
+    Args:
+        df: OHLCV DataFrame.
+        window: Span for EMA calculation.
+
+    Returns:
+        pd.Series of EMA values.
+    """
+    ...
+
+def bollinger_bands(
+    df: pd.DataFrame,
+    window: int = 20,
+    num_std: float = 2.0,
+) -> Tuple[pd.Series, pd.Series, pd.Series]:
+    """
+    Bollinger Bands.
+
+    Returns:
+        Tuple of (upper_band, middle_band, lower_band) as pd.Series.
+    """
+    ...
+
+def rsi(df: pd.DataFrame, window: int = 14) -> pd.Series:
+    """Relative Strength Index (0–100)."""
+    ...
+
+def macd(
+    df: pd.DataFrame,
+    fast: int = 12,
+    slow: int = 26,
+    signal: int = 9,
+) -> Tuple[pd.Series, pd.Series, pd.Series]:
+    """
+    MACD indicator.
+
+    Returns:
+        Tuple of (macd_line, signal_line, histogram).
+    """
+    ...
+
+def stochastic(
+    df: pd.DataFrame,
+    window: int = 14,
+) -> Tuple[pd.Series, pd.Series]:
+    """
+    Stochastic Oscillator (%K and %D).
+
+    Returns:
+        Tuple of (%K, %D) as pd.Series.
+    """
+    ...
+
+def williams_r(df: pd.DataFrame, window: int = 14) -> pd.Series:
+    """Williams %R oscillator (-100 to 0)."""
+    ...
+
+def atr(df: pd.DataFrame, window: int = 14) -> pd.Series:
+    """Average True Range."""
+    ...
+
+def adx(df: pd.DataFrame, window: int = 14) -> pd.Series:
+    """Average Directional Index (trend strength 0–100)."""
+    ...
+
+def cci(df: pd.DataFrame, window: int = 20) -> pd.Series:
+    """Commodity Channel Index."""
+    ...
+
+def obv(df: pd.DataFrame) -> pd.Series:
+    """On-Balance Volume."""
+    ...
+
+def vwap(df: pd.DataFrame) -> pd.Series:
+    """Volume Weighted Average Price."""
+    ...
+
+# =============================================================================
+# Performance Metrics
+# =============================================================================
+
+def sharpe_ratio(df: pd.DataFrame, risk_free_rate: float = 0.10) -> float:
+    """
+    Annualised Sharpe Ratio.
+
+    Args:
+        df: OHLCV DataFrame with daily close prices.
+        risk_free_rate: Annual risk-free rate (default 10% for Pakistan T-bills).
+
+    Returns:
+        Sharpe ratio (higher is better; >1 is acceptable, >2 is excellent).
+    """
+    ...
+
+def sortino_ratio(df: pd.DataFrame, risk_free_rate: float = 0.10) -> float:
+    """Annualised Sortino Ratio (penalises only downside volatility)."""
+    ...
+
+def calmar_ratio(df: pd.DataFrame) -> float:
+    """Calmar Ratio = annualised return / max drawdown."""
+    ...
+
+def cumulative_returns(df: pd.DataFrame) -> float:
+    """Total cumulative return for the period as a decimal (e.g. 0.35 = 35%)."""
+    ...
+
+def annualized_return(df: pd.DataFrame) -> float:
+    """Compound Annual Growth Rate (CAGR)."""
+    ...
+
+def annualized_volatility(df: pd.DataFrame) -> float:
+    """Annualised standard deviation of daily returns."""
+    ...
+
+def drawdown(df: pd.DataFrame) -> pd.Series:
+    """Rolling drawdown series (0 to -1 scale)."""
+    ...
+
+def max_drawdown(df: pd.DataFrame) -> float:
+    """Maximum peak-to-trough drawdown as a negative decimal (e.g. -0.35 = -35%)."""
+    ...
+
+def drawdown_duration(df: pd.DataFrame) -> int:
+    """Length of the longest drawdown period in trading days."""
+    ...
+
+def information_ratio(df: pd.DataFrame, benchmark: pd.DataFrame) -> float:
+    """Information Ratio = active return / tracking error."""
+    ...
+
+def treynor_ratio(df: pd.DataFrame, beta_value: float) -> float:
+    """Treynor Ratio = excess return / beta."""
+    ...
+
+def jensen_alpha(df: pd.DataFrame, expected_return: float) -> float:
+    """Jensen's Alpha = actual return - CAPM-expected return."""
+    ...
+
+def win_rate(trades: pd.DataFrame) -> float:
+    """Percentage of profitable trades (0.0–1.0)."""
+    ...
+
+def profit_loss_ratio(trades: pd.DataFrame) -> float:
+    """Average profit of winning trades / average loss of losing trades."""
+    ...
+
+def recovery_factor(trades: pd.DataFrame) -> float:
+    """Net profit / max drawdown."""
+    ...
+
+def performance_summary(df: pd.DataFrame) -> Dict[str, Any]:
+    """
+    Compute a comprehensive performance report.
+
+    Returns:
+        Dict with keys: total_return, annualized_return, annualized_volatility,
+        sharpe_ratio, sortino_ratio, calmar_ratio, max_drawdown, win_rate,
+        best_day, worst_day, positive_days_pct.
+
+    Example:
+        >>> summary = pypsx.analysis.performance_summary(df)
+        >>> print(summary["sharpe_ratio"])
+    """
+    ...
+
+# =============================================================================
+# Insights & Pattern Recognition
+# =============================================================================
+
+def interpret_stock(df: pd.DataFrame, symbol: str) -> Dict[str, Any]:
+    """
+    AI-powered interpretation of a stock's technical and statistical profile.
+
+    Returns:
+        Dict with keys: trend, momentum, volatility_level, support, resistance,
+        signals, outlook.
+    """
+    ...
+
+def interpret_portfolio(
+    portfolio_data: Dict[str, pd.DataFrame],
+    risk_free_rate: float = 0.10,
+) -> Dict[str, Any]:
+    """
+    Holistic portfolio analysis including diversification and risk metrics.
+
+    Args:
+        portfolio_data: Dict mapping symbol → OHLCV DataFrame.
+        risk_free_rate: Annual risk-free rate.
+
+    Returns:
+        Dict with per-symbol and aggregate metrics.
+    """
+    ...
+
+def detect_patterns(df: pd.DataFrame, symbol: str) -> Dict[str, Any]:
+    """
+    Detect common chart patterns (head-and-shoulders, double top/bottom, etc.).
+
+    Returns:
+        Dict with pattern names as keys and confidence scores as values.
+    """
+    ...
+
+def generate_trading_signals(df: pd.DataFrame, symbol: str) -> Dict[str, Any]:
+    """
+    Generate buy/sell/hold signals based on technical indicator confluence.
+
+    Returns:
+        Dict with keys: signal ("BUY"/"SELL"/"HOLD"), confidence (0–1),
+        indicators_agreed, indicators_disagreed.
+    """
+    ...
+
+def market_sentiment_analysis(
+    portfolio_data: Dict[str, pd.DataFrame],
+) -> Dict[str, Any]:
+    """
+    Aggregate sentiment analysis across a portfolio.
+
+    Returns:
+        Dict with overall_sentiment, bullish_count, bearish_count, neutral_count.
+    """
+    ...
+
+def quick_analysis(df: pd.DataFrame, symbol: str) -> Dict[str, Any]:
+    """
+    Fast single-call analysis combining key indicators and a brief narrative.
+
+    Returns:
+        Dict with price_action, trend, momentum, key_levels, one_line_summary.
+    """
+    ...
+
+def portfolio_analysis(
+    portfolio_data: Dict[str, pd.DataFrame],
+    risk_free_rate: float = 0.10,
+) -> Dict[str, Any]:
+    """Full portfolio-level analysis including correlation, risk, and attribution."""
+    ...
+
+# =============================================================================
+# Short-form aliases
+# =============================================================================
+
+ma = moving_average
+ema = exponential_moving_average
+bb = bollinger_bands
+sharpe = sharpe_ratio
+sortino = sortino_ratio
+calmar = calmar_ratio
+cum_returns = cumulative_returns
+max_dd = max_drawdown
+win_rate_pct = win_rate
+pl_ratio = profit_loss_ratio
+recovery = recovery_factor
+perf_summary = performance_summary
+interpret = interpret_stock
+patterns = detect_patterns
+signals = generate_trading_signals
+sentiment = market_sentiment_analysis

pypsx_toolkit/api.pyi

@@ -0,0 +1,294 @@
+"""Type stubs for pypsx.api — high-level data retrieval functions."""
+
+from typing import Any, Dict, List, Optional, Union
+import pandas as pd
+
+
+def download(
+    symbols: Union[str, List[str]],
+    period: str = "1mo",
+    interval: str = "1d",
+    to_csv: Optional[str] = None,
+) -> pd.DataFrame:
+    """
+    Download historical OHLCV data for one or more PSX symbols (yfinance-style).
+
+    Args:
+        symbols: Single symbol string or list of symbols, e.g. ["ENGRO", "HBL", "OGDC"].
+        period: Time period — "1d","5d","1mo","3mo","6mo","1y","2y","5y","10y","ytd","max".
+        interval: Bar interval. Only "1d" is currently supported.
+        to_csv: Optional path to save the result as CSV.
+
+    Returns:
+        For a single symbol: DataFrame with [Open, High, Low, Close, Volume, Change%].
+        For multiple symbols: Multi-level column DataFrame keyed by (field, symbol).
+
+    Example:
+        >>> import pypsx
+        >>> df = pypsx.download("ENGRO", period="1y")
+        >>> df = pypsx.download(["ENGRO", "HBL", "OGDC"], period="6mo")
+    """
+    ...
+
+
+def get_historical(
+    symbol: str,
+    start_date: str,
+    end_date: str,
+    max_workers: int = 4,
+    show_progress: bool = False,
+) -> pd.DataFrame:
+    """
+    Fetch historical daily OHLCV data for a specific date range.
+
+    Args:
+        symbol: PSX ticker symbol, e.g. "ENGRO".
+        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 for large date ranges.
+        show_progress: Show tqdm progress bar if True.
+
+    Returns:
+        DataFrame with columns [Date, Open, High, Low, Close, Volume, Change%].
+
+    Example:
+        >>> df = pypsx.get_historical("OGDC", "2019-01-01", "2024-12-31")
+    """
+    ...
+
+
+def get_intraday(symbol: str) -> pd.DataFrame:
+    """
+    Fetch intraday tick data for the last 2 trading days.
+
+    Runs on the user's local machine to distribute scraping traffic.
+
+    Args:
+        symbol: PSX ticker symbol.
+
+    Returns:
+        DataFrame with columns [Time, Price, Volume, Change, Change%].
+
+    Example:
+        >>> ticks = pypsx.get_intraday("SYS")
+    """
+    ...
+
+
+def get_intraday_multiple(symbols: List[str]) -> pd.DataFrame:
+    """
+    Fetch intraday tick data for multiple symbols in parallel.
+
+    Args:
+        symbols: List of PSX ticker symbols.
+
+    Returns:
+        Concatenated DataFrame with an additional "Symbol" column.
+
+    Example:
+        >>> df = pypsx.get_intraday_multiple(["ENGRO", "HBL", "SYS"])
+    """
+    ...
+
+
+def get_quote(
+    symbol: str,
+    as_dict: bool = False,
+) -> Union[pd.DataFrame, Dict[str, Any]]:
+    """
+    Get the latest price quote for a single symbol.
+
+    Args:
+        symbol: PSX ticker symbol.
+        as_dict: If True, return a dict instead of a DataFrame.
+
+    Returns:
+        DataFrame row or dict with fields: symbol, price, change, change_pct,
+        volume, high, low, open, prev_close, market_cap.
+
+    Example:
+        >>> quote = pypsx.get_quote("ENGRO")
+        >>> quote = pypsx.get_quote("ENGRO", as_dict=True)
+    """
+    ...
+
+
+def get_quote_batch(
+    symbols: List[str],
+    as_dict: bool = False,
+) -> Union[pd.DataFrame, Dict[str, Any]]:
+    """
+    Get latest price quotes for multiple symbols at once.
+
+    Args:
+        symbols: List of PSX ticker symbols.
+        as_dict: If True, return a dict keyed by symbol.
+
+    Returns:
+        DataFrame with one row per symbol, or nested dict if as_dict=True.
+
+    Example:
+        >>> df = pypsx.get_quote_batch(["ENGRO", "HBL", "OGDC"])
+    """
+    ...
+
+
+def get_company_fundamentals(
+    symbol: str,
+    as_dict: bool = False,
+) -> Union[pd.DataFrame, Dict[str, Any]]:
+    """
+    Fetch company fundamental data (P/E, EPS, book value, ROE, etc.).
+
+    Args:
+        symbol: PSX ticker symbol.
+        as_dict: Return dict instead of DataFrame if True.
+
+    Returns:
+        DataFrame or dict with keys: pe_ratio, eps, book_value, dividend_yield,
+        roe, roa, debt_to_equity, current_ratio, market_cap, shares_outstanding.
+
+    Example:
+        >>> fundamentals = pypsx.get_company_fundamentals("HUBC")
+    """
+    ...
+
+
+def get_announcements(
+    symbol: str,
+    as_dict: bool = False,
+) -> Union[pd.DataFrame, Dict[str, Any]]:
+    """
+    Fetch PSX corporate announcements for a symbol.
+
+    Args:
+        symbol: PSX ticker symbol.
+        as_dict: Return list of dicts if True.
+
+    Returns:
+        DataFrame with columns [Date, Category, Subject, Description].
+
+    Example:
+        >>> df = pypsx.get_announcements("ENGRO")
+    """
+    ...
+
+
+def get_dividend_info(
+    symbol: str,
+    as_dict: bool = False,
+) -> Union[pd.DataFrame, Dict[str, Any]]:
+    """
+    Get current/latest dividend information for a symbol.
+
+    Args:
+        symbol: PSX ticker symbol.
+        as_dict: Return dict if True.
+
+    Returns:
+        DataFrame or dict with last dividend rate, type, ex-date, payment date.
+
+    Example:
+        >>> info = pypsx.get_dividend_info("OGDC")
+    """
+    ...
+
+
+def get_dividend_history(
+    symbol: str,
+    as_dict: bool = False,
+) -> Union[pd.DataFrame, Dict[str, Any]]:
+    """
+    Full dividend payment history for a symbol (cash, stock, bonus, rights).
+
+    Args:
+        symbol: PSX ticker symbol.
+        as_dict: Return list of dicts if True.
+
+    Returns:
+        DataFrame with columns [Date, Type, Rate, Face_Value, Announcement_Date].
+
+    Example:
+        >>> history = pypsx.get_dividend_history("ENGRO")
+    """
+    ...
+
+
+def get_snapshot(
+    symbol: str,
+    as_dict: bool = False,
+) -> Union[Dict[str, Any], pd.DataFrame]:
+    """
+    Multi-tab market snapshot combining price, fundamentals, and trading stats.
+
+    Args:
+        symbol: PSX ticker symbol.
+        as_dict: Return nested dict if True (default).
+
+    Returns:
+        Nested dict / DataFrame with tabs: price, fundamentals, trading_stats, company.
+
+    Example:
+        >>> snap = pypsx.get_snapshot("SYS")
+        >>> print(snap["price"]["last_price"])
+    """
+    ...
+
+
+def get_sector_constituents(
+    sector_code: str,
+    as_dict: bool = False,
+) -> Union[pd.DataFrame, Dict[str, Any]]:
+    """
+    Get all companies belonging to a PSX sector by sector code.
+
+    Args:
+        sector_code: PSX sector code (e.g. "BAN" for Banking, "OGX" for Oil & Gas).
+        as_dict: Return list of dicts if True.
+
+    Returns:
+        DataFrame with columns [Symbol, Company, Market_Cap, Change%, Volume].
+
+    Example:
+        >>> df = pypsx.get_sector_constituents("BAN")
+    """
+    ...
+
+
+def get_symbols_by_sector(
+    sector_name: str,
+    as_dict: bool = False,
+) -> Union[pd.DataFrame, Dict[str, Any]]:
+    """
+    Get symbols belonging to a PSX sector by human-readable sector name.
+
+    Args:
+        sector_name: Full sector name, e.g. "Banking", "Automobile Assembler",
+                     "Oil & Gas Exploration Companies".
+        as_dict: Return list of dicts if True.
+
+    Returns:
+        DataFrame with constituent symbols and company names.
+
+    Example:
+        >>> df = pypsx.get_symbols_by_sector("Banking")
+        >>> df = pypsx.get_symbols_by_sector("Cement")
+    """
+    ...
+
+
+def get_business_description(symbol: str) -> str:
+    """
+    Return a plain-text business description for a PSX-listed company.
+
+    Args:
+        symbol: PSX ticker symbol.
+
+    Returns:
+        String with the company's business overview.
+
+    Example:
+        >>> desc = pypsx.get_business_description("ENGRO")
+        >>> print(desc[:200])
+    """
+    ...

pypsx_toolkit/core/__init__.py

@@ -0,0 +1,6 @@
+# Core cache module
+
+# Lazy import to avoid circular dependency
+# from pypsx_toolkit.core.stream import PSXStream
+
+__all__ = []

pypsx_toolkit/core/errors.pyi

@@ -0,0 +1,38 @@
+"""Type stubs for pypsx.core.errors — custom exception hierarchy."""
+
+
+class PSXError(Exception):
+    """Base exception for all pypsx errors."""
+    ...
+
+
+class PSXHTTPError(PSXError):
+    """
+    Raised when the PSX server returns an unexpected HTTP status code.
+
+    Attributes:
+        status_code: The HTTP status code received.
+        url: The URL that triggered the error.
+    """
+    status_code: int
+    url: str
+    ...
+
+
+class PSXTimeoutError(PSXError):
+    """Raised when an HTTP request to PSX exceeds the configured timeout."""
+    ...
+
+
+class PSXNotFoundError(PSXError):
+    """Raised when a requested symbol, sector, or index does not exist on PSX."""
+    ...
+
+
+class PSXScopeError(PSXError):
+    """
+    Raised when a method is called on the wrong ticker type.
+
+    Example: calling .constituents() on an equity ticker instead of an index ticker.
+    """
+    ...