Metadata-Version: 2.4
Name: psxdata
Version: 0.1.0a2
Summary: Python library and REST API for Pakistan Stock Exchange (PSX) data
License: Copyright 2026 Muhammad Tauha
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
Project-URL: Homepage, https://github.com/mtauha/psxdata
Project-URL: Source, https://github.com/mtauha/psxdata
Project-URL: Bug Tracker, https://github.com/mtauha/psxdata/issues
Project-URL: Changelog, https://github.com/mtauha/psxdata/blob/main/CHANGELOG.md
Keywords: psx,pakistan,stock,market,finance,data,kse,kse-100,karachi,stock-exchange,ohlcv,historical-data
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: requests>=2.28
Requires-Dist: httpx>=0.24
Requires-Dist: beautifulsoup4>=4.11
Requires-Dist: lxml>=4.9
Requires-Dist: pandas>=2.0
Requires-Dist: pyarrow>=14.0
Requires-Dist: python-dateutil>=2.8
Requires-Dist: tqdm>=4.64
Requires-Dist: diskcache>=5.4
Requires-Dist: pydantic>=2.0
Provides-Extra: api
Requires-Dist: fastapi>=0.100; extra == "api"
Requires-Dist: uvicorn>=0.22; extra == "api"
Requires-Dist: slowapi>=0.1; extra == "api"
Requires-Dist: redis>=4.5; extra == "api"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: pytest-timeout>=2.1; extra == "dev"
Requires-Dist: httpx>=0.24; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: types-requests>=2.28; extra == "dev"
Requires-Dist: types-python-dateutil>=2.8; extra == "dev"
Dynamic: license-file

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

[![CI](https://github.com/mtauha/psxdata/actions/workflows/ci.yml/badge.svg)](https://github.com/mtauha/psxdata/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/psxdata)](https://pypi.org/project/psxdata/)
[![Python](https://img.shields.io/pypi/pyversions/psxdata)](https://pypi.org/project/psxdata/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**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.

<details>
<summary>Alpha release note</summary>

`0.1.0a1` — Core scraping, caching, and public API are complete. The FastAPI REST layer and full documentation are in progress. APIs may change before `1.0`.

</details>

---

## Installation

```bash
pip install psxdata
```

Requires Python 3.11+.

---

## Quick Start

```python
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

| Function | Description |
|---|---|
| `psxdata.stocks(symbol, start, end)` | Historical OHLCV DataFrame for a ticker |
| `psxdata.tickers()` | All listed tickers (1000+) |
| `psxdata.quote(symbol)` | Live quote row for a ticker |
| `psxdata.indices(name)` | Constituents of a named index (e.g. `"KSE100"`) |
| `psxdata.sectors()` | Sector aggregates DataFrame (37 sectors) |
| `psxdata.fundamentals(symbol)` | Financial reports for a ticker |
| `psxdata.debt_market()` | Debt market instruments (TFCs, Sukuks, etc.) |
| `psxdata.eligible_scrips()` | Margin trading eligible stocks |

---

## 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

---

## Planned REST API

> The FastAPI layer is planned for Phase 4.

| Endpoint | Description |
|---|---|
| `GET /health` | Health check |
| `GET /stocks` | All tickers |
| `GET /stocks/{symbol}/historical?start=&end=` | Historical OHLCV |
| `GET /stocks/{symbol}/quote` | Real-time quote |
| `GET /stocks/{symbol}/fundamentals` | Fundamentals |
| `GET /indices/{name}` | Index constituents |
| `GET /sectors` | Sector aggregates |
| `GET /debt-market` | Debt instruments |
| `GET /eligible-scrips` | Margin eligible stocks |

All responses: `{"data": ..., "meta": {"timestamp": "...", "cached": bool}}`

---

## Development Status

See the [roadmap issue](https://github.com/mtauha/psxdata/issues/4) 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
- 🔲 Phase 5 — Full test suite (API layer tests pending)
- ✅ Phase 6 — Packaging & PyPI publish
- 🔲 Phase 7 — Documentation

---

## Contributing

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

---

## Architecture

See [ARCHITECTURE.md](ARCHITECTURE.md) for the component diagram, data flow, and design decisions.
