pypsx-toolkit 3.0.0__py3-none-any.whl

pypsx_toolkit/__init__.py

@@ -0,0 +1,304 @@
+"""
+PSX yfinance-style API
+"""
+
+__version__ = "3.0.0"
+__author__ = "PyPSX Team"
+__email__ = "pypsx@example.com"
+
+from pypsx_toolkit.ticker import PSXTicker, Ticker
+
+# Backward compatibility alias
+class PSXSymbol(Ticker):
+    pass
+
+from pypsx_toolkit.api import (
+    download,
+    sectors,
+    performers,
+    market_watch,
+    listings_nc,
+    listings_dc,
+    trading_board,
+    index_constituents,
+    get_indices,
+    get_intraday_multiple,
+    get_historical,
+    symbols_nc,
+    symbols_dc,
+    get_symbols,
+)
+
+from pypsx_toolkit.endpoints.company import get_quote, get_quote_batch
+from pypsx_toolkit.endpoints.company_fundamentals import get_company_fundamentals
+from pypsx_toolkit.endpoints.announcements import get_announcements as _get_announcements
+from pypsx_toolkit.endpoints.dividends import get_dividend_info as _get_dividend_info, get_dividend_history as _get_dividend_history
+from pypsx_toolkit.endpoints.sectors import get_sector_constituents as _get_sector_constituents
+from pypsx_toolkit.endpoints.compliant_listings import get_symbols_by_sector as _get_symbols_by_sector
+from pypsx_toolkit.endpoints.snapshot import get_snapshot
+
+from pypsx_toolkit.market import (
+    top_performers,
+    sector_summary,
+    market_watch as market_watch_func,
+    get_indices as get_indices_func,
+    get_indices_breakdown,
+    get_sector_breakdown,
+    get_homepage_indices,
+)
+
+from pypsx_toolkit.core.stream import PSXStream
+
+# Models
+from pypsx_toolkit.models import (
+    SymbolInfo,
+    SectorSummary,
+    SectorCompany,
+    CompanyMarketWatch,
+    IndexConstituent,
+    IndexMeta,
+    TradingBoardRow,
+    TopActiveStock,
+    TopAdvancer,
+    TopDecliner,
+    IntradayBar,
+    EODBar,
+    ListingEntry,
+    CompanyFundamentals,
+    Announcement,
+    DividendInfo,
+    DividendHistory,
+)
+
+# Analysis module (optional - requires analysis package)
+try:
+    from pypsx_toolkit.analysis import (
+        interpret_stock,
+        sharpe_ratio,
+        rsi,
+        macd,
+        bollinger_bands,
+    )
+except ImportError:
+    # Analysis module not available
+    pass
+
+__all__ = [
+    "__version__",
+    "PSXTicker",
+    "Ticker",
+    "PSXSymbol",
+    "PSXStream",
+    "download",
+    "sectors",
+    "performers",
+    "market_watch",
+    "top_performers",
+    "sector_summary",
+    "get_indices",
+    "get_indices_breakdown",
+    "get_sector_breakdown",
+    "get_homepage_indices",
+    "listings_nc",
+    "listings_dc",
+    "trading_board",
+    "index_constituents",
+    "get_intraday_multiple",
+    "get_historical",
+    "symbols_nc",
+    "symbols_dc",
+    "get_symbols",
+    # Convenience wrappers
+    "get_market_watch",
+    "get_most_active",
+    "get_top_gainers",
+    "get_top_losers",
+    "get_orderbook",
+    "get_intraday",
+    "get_history",
+    "get_index",
+    "get_symbols_nc",
+    "get_symbols_dc",
+    "get_quote",
+    "get_quote_batch",
+    "get_company_fundamentals",
+    "get_announcements",
+    "get_dividend_info",
+    "get_dividend_history",
+    "get_business_description",
+    "get_sector_constituents",
+    "get_symbols_by_sector",
+    "get_snapshot",
+    # Models
+    "SymbolInfo",
+    "SectorSummary",
+    "SectorCompany",
+    "CompanyMarketWatch",
+    "IndexConstituent",
+    "IndexMeta",
+    "TradingBoardRow",
+    "TopActiveStock",
+    "TopAdvancer",
+    "TopDecliner",
+    "IntradayBar",
+    "EODBar",
+    "ListingEntry",
+    "CompanyFundamentals",
+    "Announcement",
+    "DividendInfo",
+    "DividendHistory",
+]
+
+
+# Legacy compatibility wrappers used by audit script (clean outputs only)
+
+def get_market_watch():
+    return market_watch()
+
+
+def get_most_active():
+    return performers().get("top_actives")
+
+
+def get_top_gainers():
+    return performers().get("top_gainers")
+
+
+def get_top_losers():
+    return performers().get("top_decliners")
+
+
+def get_orderbook(symbol: str | None = None):
+    if symbol:
+        return Ticker(symbol).orderbook()
+    return trading_board()
+
+
+def get_intraday(symbol: str):
+    return Ticker(symbol).history(period="1d", interval="1m")
+
+
+def get_history(symbol: str, period: str = "1y"):
+    """Get historical data for a symbol (convenience function)."""
+    return PSXTicker(symbol).history(period=period, interval="1d")
+
+
+def get_index(index_name: str, format: str = 'dataframe'):
+    """Get index constituents data (convenience function)."""
+    return index_constituents(index_name)
+
+
+
+
+def get_symbols_nc():
+    import pandas as _pd
+    return _pd.DataFrame({"Symbol": symbols_nc()})
+
+
+def get_symbols_dc():
+    import pandas as _pd
+    return _pd.DataFrame({"Symbol": symbols_dc()})
+
+
+def get_announcements(symbol: str, format: str = 'dataframe'):
+    """Get company announcements (convenience function)."""
+    return _get_announcements(symbol, format)
+
+
+def get_dividend_info(symbol: str, format: str = 'dataframe'):
+    """Get dividend information (convenience function)."""
+    return _get_dividend_info(symbol, format)
+
+
+def get_dividend_history(symbol: str, format: str = 'dataframe'):
+    """Get dividend history (convenience function)."""
+    return _get_dividend_history(symbol, format)
+
+
+def get_sector_constituents(sector_code: str, format: str = 'dataframe'):
+    """
+    Get all companies in a specific sector.
+    
+    Args:
+        sector_code: Sector code (e.g., '0801' for AUTOMOBILE ASSEMBLER) or sector name
+        format: Output format - 'dataframe' or 'json'
+        
+    Returns:
+        DataFrame with sector constituents or JSON dict
+        
+    Example:
+        >>> import pypsx_toolkit
+        >>> df = pypsx_toolkit.get_sector_constituents('0801')  # Automobile Assembler
+        >>> print(df.head())
+    """
+    return _get_sector_constituents(sector_code, format)
+
+
+def get_symbols_by_sector(sector_name: str, format: str = 'dataframe'):
+    """
+    Get all symbols in a specific sector by sector name (supports partial matching).
+    
+    Args:
+        sector_name: Sector name (e.g., 'automobile', 'AUTOMOBILE ASSEMBLER', 'Automobile Assembler')
+        format: Output format - 'dataframe' or 'json'
+        
+    Returns:
+        DataFrame with symbols in the sector or JSON dict
+        
+    Example:
+        >>> import pypsx_toolkit
+        >>> df = pypsx_toolkit.get_symbols_by_sector('automobile')
+        >>> print(df.head())
+    """
+    return _get_symbols_by_sector(sector_name, format)
+
+
+def get_business_description(symbol: str) -> str:
+    """
+    Get business description for a company.
+    
+    Args:
+        symbol: Stock symbol
+        
+    Returns:
+        Business description string, or empty string if not found
+    """
+    import pandas as pd
+    try:
+        df = get_company_fundamentals(symbol, format='dataframe')
+        if df is None or df.empty:  # type: ignore[union-attr]
+            return ""
+        
+        # Look for Business Description in the fundamentals DataFrame
+        if isinstance(df, pd.DataFrame):
+            # Try resetting index first (handles both regular and MultiIndex)
+            df_reset = df.reset_index()
+            
+            # Check if we have METRIC and VALUE columns
+            if 'METRIC' in df_reset.columns and 'VALUE' in df_reset.columns:
+                desc_row = df_reset[df_reset['METRIC'] == 'Business Description']
+                if not desc_row.empty:
+                    value = desc_row['VALUE'].iloc[0]
+                    # Return clean string, not DataFrame representation
+                    if pd.notna(value):
+                        return str(value).strip()
+            
+            # Alternative: check if it's indexed by METRIC (MultiIndex) - try direct access
+            if hasattr(df.index, 'get_level_values') and isinstance(df.index, pd.MultiIndex):
+                if 'Business Description' in df.index.get_level_values('METRIC').tolist():
+                    try:
+                        # Sort index first to avoid PerformanceWarning
+                        df_sorted = df.sort_index()
+                        value = df_sorted.loc[(symbol.upper(), 'Profile', 'Business Description'), 'VALUE']
+                        if pd.notna(value):
+                            return str(value).strip()
+                    except (KeyError, IndexError):
+                        pass
+        
+        return ""
+    except Exception:
+        return ""
+
+
+ 
+

pypsx_toolkit/__init__.pyi

@@ -0,0 +1,99 @@
+"""
+pypsx-toolkit — Pakistan Stock Exchange data library (yfinance-style API).
+
+Optional, supplementary to the pypsx trading SDK - not required for trading,
+backtesting, or standard data fetching (see the pypsx package for that).
+
+Install:
+    pip install pypsx-toolkit
+
+Quick start:
+    import pypsx_toolkit
+
+    # Single ticker
+    t = pypsx_toolkit.Ticker("ENGRO")
+    df = t.history(period="1y")
+
+    # Batch download
+    df = pypsx_toolkit.download(["ENGRO", "HBL", "OGDC"], period="6mo")
+
+    # Market overview
+    mw = pypsx_toolkit.market_watch()
+"""
+
+from typing import List, Optional, Union
+import pandas as pd
+
+from .ticker import PSXTicker as PSXTicker, PSXTicker as Ticker
+from .models import (
+    SymbolInfo as SymbolInfo,
+    SectorSummary as SectorSummary,
+    SectorCompany as SectorCompany,
+    CompanyMarketWatch as CompanyMarketWatch,
+    IndexConstituent as IndexConstituent,
+    IndexMeta as IndexMeta,
+    TradingBoardRow as TradingBoardRow,
+    TopActiveStock as TopActiveStock,
+    TopAdvancer as TopAdvancer,
+    TopDecliner as TopDecliner,
+    IntradayBar as IntradayBar,
+    EODBar as EODBar,
+    ListingEntry as ListingEntry,
+    CompanyFundamentals as CompanyFundamentals,
+    Announcement as Announcement,
+    DividendInfo as DividendInfo,
+    DividendHistory as DividendHistory,
+)
+from .core.errors import (
+    PSXError as PSXError,
+    PSXHTTPError as PSXHTTPError,
+    PSXTimeoutError as PSXTimeoutError,
+    PSXNotFoundError as PSXNotFoundError,
+    PSXScopeError as PSXScopeError,
+)
+from .core.stream import PSXStream as PSXStream
+from .api import (
+    download as download,
+    get_historical as get_historical,
+    get_intraday as get_intraday,
+    get_intraday_multiple as get_intraday_multiple,
+    get_quote as get_quote,
+    get_quote_batch as get_quote_batch,
+    get_company_fundamentals as get_company_fundamentals,
+    get_announcements as get_announcements,
+    get_dividend_info as get_dividend_info,
+    get_dividend_history as get_dividend_history,
+    get_snapshot as get_snapshot,
+    get_sector_constituents as get_sector_constituents,
+    get_symbols_by_sector as get_symbols_by_sector,
+    get_business_description as get_business_description,
+)
+from .market import (
+    market_watch as market_watch,
+    performers as performers,
+    sectors as sectors,
+    trading_board as trading_board,
+    get_symbols as get_symbols,
+    listings_nc as listings_nc,
+    listings_dc as listings_dc,
+    get_indices as get_indices,
+    get_indices_breakdown as get_indices_breakdown,
+    get_sector_breakdown as get_sector_breakdown,
+    get_homepage_indices as get_homepage_indices,
+    index_constituents as index_constituents,
+)
+from .analysis import (
+    moving_average as moving_average,
+    exponential_moving_average as exponential_moving_average,
+    bollinger_bands as bollinger_bands,
+    rsi as rsi,
+    macd as macd,
+    sharpe_ratio as sharpe_ratio,
+    sortino_ratio as sortino_ratio,
+    performance_summary as performance_summary,
+    interpret_stock as interpret_stock,
+    portfolio_analysis as portfolio_analysis,
+)
+
+__version__: str
+__all__: List[str]

pypsx_toolkit/analysis/__init__.py

@@ -0,0 +1,222 @@
+"""
+PyPSX Analysis Module
+
+This module provides comprehensive financial analysis tools for Pakistan Stock Exchange data,
+including statistical functions, technical indicators, performance metrics, and automated insights.
+
+Main Components:
+- stats: Core statistical functions (returns, volatility, correlation, etc.)
+- indicators: Technical analysis indicators (RSI, MACD, Bollinger Bands, etc.)
+- performance: Financial performance metrics (Sharpe ratio, drawdown, etc.)
+- insights: Automated insight generation and pattern detection
+
+Usage:
+    import pypsx_toolkit
+    from pypsx_toolkit.analysis import interpret_stock, sharpe_ratio, bollinger_bands
+    
+    # Get stock data
+    ticker = pypsx_toolkit.PSXTicker("OGDC")
+    df = ticker.history(period="1y")
+    
+    # Generate insights
+    insights = interpret_stock(df, "OGDC")
+    print(insights['insights'])
+    
+    # Calculate metrics
+    sharpe = sharpe_ratio(df)
+    ma, upper, lower = bollinger_bands(df)
+"""
+
+# Core statistical functions
+from .stats import (
+    returns, volatility, correlation, correlation_matrix, beta,
+    skewness, kurtosis, var, cvar, autocorrelation
+)
+
+# Technical indicators
+from .indicators import (
+    moving_average, exponential_moving_average, bollinger_bands,
+    rsi, macd, stochastic, williams_r, atr, adx, cci, obv, vwap
+)
+
+# Performance metrics
+from .performance import (
+    sharpe_ratio, sortino_ratio, calmar_ratio, cumulative_returns,
+    annualized_return, annualized_volatility, drawdown, max_drawdown,
+    drawdown_duration, information_ratio, treynor_ratio, jensen_alpha,
+    win_rate, profit_loss_ratio, recovery_factor, performance_summary
+)
+
+# Insight engine
+from .insights import (
+    interpret_stock, interpret_portfolio, detect_patterns,
+    generate_trading_signals, market_sentiment_analysis
+)
+
+__all__ = [
+    # Statistical functions
+    'returns', 'volatility', 'correlation', 'correlation_matrix', 'beta',
+    'skewness', 'kurtosis', 'var', 'cvar', 'autocorrelation',
+    
+    # Technical indicators
+    'moving_average', 'exponential_moving_average', 'bollinger_bands',
+    'rsi', 'macd', 'stochastic', 'williams_r', 'atr', 'adx', 'cci', 'obv', 'vwap',
+    
+    # Performance metrics
+    'sharpe_ratio', 'sortino_ratio', 'calmar_ratio', 'cumulative_returns',
+    'annualized_return', 'annualized_volatility', 'drawdown', 'max_drawdown',
+    'drawdown_duration', 'information_ratio', 'treynor_ratio', 'jensen_alpha',
+    'win_rate', 'profit_loss_ratio', 'recovery_factor', 'performance_summary',
+    
+    # Insight engine
+    'interpret_stock', 'interpret_portfolio', 'detect_patterns',
+    'generate_trading_signals', 'market_sentiment_analysis'
+]
+
+
+def quick_analysis(df, symbol=None):
+    """
+    Quick analysis function that provides a comprehensive overview of stock performance.
+    
+    Args:
+        df: Stock DataFrame with OHLCV data
+        symbol: Stock symbol (optional)
+    
+    Returns:
+        Dictionary containing key metrics and insights
+        
+    Example:
+        >>> import pypsx_toolkit
+        >>> ticker = pypsx_toolkit.PSXTicker("OGDC")
+        >>> df = ticker.history(period="1y")
+        >>> analysis = quick_analysis(df, "OGDC")
+        >>> print(f"Sharpe Ratio: {analysis['sharpe_ratio']:.3f}")
+        >>> print(f"Total Return: {analysis['total_return']:.2%}")
+    """
+    if df is None or df.empty:
+        return {"error": "No data available for analysis"}
+    
+    try:
+        # Get comprehensive insights
+        insights = interpret_stock(df, symbol)
+        
+        # Get performance summary
+        perf_summary = performance_summary(df)
+        
+        # Get technical patterns
+        patterns = detect_patterns(df, symbol)
+        
+        # Get trading signals
+        signals = generate_trading_signals(df, symbol)
+        
+        # Merge performance summary metrics at top level for easy access
+        result = {
+            "symbol": symbol,
+            "performance": perf_summary,
+            "insights": insights.get('insights', []),
+            "patterns": patterns.get('patterns', []),
+            "trading_signal": signals.get('primary_signal', 'HOLD'),
+            "signal_confidence": signals.get('confidence', 0),
+            "key_metrics": {
+                "total_return": insights.get('total_return', 0),
+                "volatility": insights.get('volatility', 0),
+                "sharpe_ratio": insights.get('sharpe_ratio', 0),
+                "max_drawdown": insights.get('max_drawdown', 0),
+                "rsi": insights.get('rsi', 50)
+            }
+        }
+        
+        # Also add top-level access for backward compatibility
+        # These match the keys that users are accessing directly
+        if perf_summary:
+            result["sharpe_ratio"] = perf_summary.get('sharpe_ratio', insights.get('sharpe_ratio', 0))
+            result["max_drawdown"] = perf_summary.get('max_drawdown', insights.get('max_drawdown', 0))
+            result["total_return"] = perf_summary.get('total_return', insights.get('total_return', 0))
+            result["annualized_return"] = perf_summary.get('annualized_return', 0)
+            result["annualized_volatility"] = perf_summary.get('annualized_volatility', 0)
+        
+        return result
+        
+    except Exception as e:
+        return {
+            "symbol": symbol,
+            "error": str(e),
+            "insights": ["Error in analysis"]
+        }
+
+
+def portfolio_analysis(portfolio_data, risk_free_rate=0.08):
+    """
+    Comprehensive portfolio analysis function.
+    
+    Args:
+        portfolio_data: Dictionary of symbol -> DataFrame
+        risk_free_rate: Risk-free rate for calculations (default: 0.08)
+    
+    Returns:
+        Dictionary containing portfolio analysis results
+        
+    Example:
+        >>> portfolio = {
+        ...     "OGDC": pypsx_toolkit.PSXTicker("OGDC").history(period="1y"),
+        ...     "PPL": pypsx_toolkit.PSXTicker("PPL").history(period="1y"),
+        ...     "KEL": pypsx_toolkit.PSXTicker("KEL").history(period="1y")
+        ... }
+        >>> analysis = portfolio_analysis(portfolio)
+        >>> print(f"Portfolio insights: {analysis['portfolio_insights']}")
+    """
+    if not portfolio_data:
+        return {"error": "No portfolio data provided"}
+    
+    try:
+        # Get portfolio insights
+        portfolio_insights = interpret_portfolio(portfolio_data, risk_free_rate)
+        
+        # Get market sentiment
+        sentiment = market_sentiment_analysis(portfolio_data)
+        
+        # Individual stock analysis
+        individual_analyses = {}
+        for symbol, df in portfolio_data.items():
+            if df is not None and not df.empty:
+                individual_analyses[symbol] = quick_analysis(df, symbol)
+        
+        return {
+            "portfolio_insights": portfolio_insights.get('portfolio_insights', []),
+            "portfolio_metrics": portfolio_insights.get('portfolio_metrics', {}),
+            "market_sentiment": sentiment.get('overall_sentiment', 'NEUTRAL'),
+            "sentiment_strength": sentiment.get('sentiment_strength', 'Mixed'),
+            "individual_analyses": individual_analyses,
+            "summary": {
+                "total_stocks": len(portfolio_data),
+                "analyzed_stocks": len(individual_analyses),
+                "bullish_stocks": sentiment.get('bullish_stocks', 0),
+                "bearish_stocks": sentiment.get('bearish_stocks', 0),
+                "neutral_stocks": sentiment.get('neutral_stocks', 0)
+            }
+        }
+        
+    except Exception as e:
+        return {
+            "error": str(e),
+            "portfolio_insights": ["Error in portfolio analysis"]
+        }
+
+
+# Add convenience 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