psxdata — Python Library for Pakistan Stock Exchange (PSX) Data

Full documentation at psxdata.mintlify.app

Deprecated: ReadTheDocs hosting at psxdata.readthedocs.io is no longer the primary documentation source and may be removed in a future release.

psxdata is a Python library for downloading Pakistan Stock Exchange (PSX) data — historical OHLCV prices, real-time quotes, KSE-100 index constituents, sector summaries, fundamentals, debt market instruments, and margin-eligible stocks. Free, open-source, and actively maintained.

Installation

pip install psxdata

Requires Python 3.11+.

Quick Start

import psxdata

# Historical OHLCV data
df = psxdata.stocks("ENGRO", start="2024-01-01", end="2024-12-31")

# All listed tickers
all_tickers = psxdata.tickers()

# KSE-100 index constituents
kse100 = psxdata.indices("KSE100")

# Live quote
q = psxdata.quote("LUCK")

# Sector summary
sectors = psxdata.sectors()

# Debt market instruments
debt = psxdata.debt_market()

# Margin-eligible stocks
scrips = psxdata.eligible_scrips()

API Reference

Why psxdata

Existing solutions for PSX data tend to hardcode date formats and column positions that break silently when PSX changes its HTML. psxdata is designed differently:

• Dynamic column extraction from <th> tags — survives column reordering
• Multi-format date parsing with fuzzy fallback via dateutil
• Exponential backoff retries — 3 attempts, 1s/2s delays
• Disk cache (~/.psxdata/cache/) — historical data cached forever, live data for 15 min
• Data validation — OHLC constraint checks, duplicate/future date detection

REST API

A FastAPI REST service wrapping this library now lives in a standalone repository: mtauha/psxdata-api.

It exposes the same data as this library over HTTP (GET /stocks, GET /indices/{name}, GET /sectors, etc.), installs psxdata from PyPI, and ships its own Docker image (mtauha/psxdata-api on Docker Hub) and CI/CD pipeline. See that repo's README for endpoints, request/response formats, and Docker run instructions.

Development Status

See the roadmap issue for the full phase breakdown.

• ✅ Phase 0 — PSX endpoint research and HTML fixture capture
• ✅ Phase 0.5 — Repository setup, CI/CD, community files
• ✅ Phase 2 — Core engineering (BaseScraper, parsers, cache, utils)
• ✅ Phase 3 — Scrapers (historical, real-time, indices, sectors, fundamentals, screener, debt, eligible scrips)
• ✅ Phase 3 API — Public Python package interface
• ✅ Phase 4 — FastAPI REST layer (now at mtauha/psxdata-api)
• ✅ Phase 5 — Full test suite (API layer tests pending)
• ✅ Phase 6 — Packaging & PyPI publish
• ✅ Phase 7 — Documentation

Contributing

Contributions are welcome. See CONTRIBUTING.md and open an issue before starting non-trivial work.

Architecture

See ARCHITECTURE.md for the component diagram, data flow, and design decisions.