Metadata-Version: 2.3
Name: psx-terminal
Version: 0.1.2
Summary: Realtime market feed dashboard for L1/L2 PSX data using curses.
Author: nordixsoft
License-File: LICENSE
Classifier: Environment :: Console :: Curses
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Requires-Dist: requests
Requires-Dist: windows-curses; sys_platform == 'win32'
Description-Content-Type: text/markdown

# psx-terminal

A fast, data‑dense terminal dashboard for Pakistan Stock Exchange market feeds. This is a read‑only trading terminal focusing on realtime data visibility (L1, MBP, MBO), designed to be highly accessible right from your command line.

## Highlights
- **Realtime L1 + L2**: Watchlist, market depth (MBP/MBO), and movers.
- **Curses UI**: Clean, high‑contrast layout designed for long sessions.
- **Keyboard‑first navigation**: Tabs and symbol selection optimized for speed.
- **Resilient networking**: Auto‑reconnect and safe parsing for noisy feeds.

## Installation

You can install `psx-terminal` securely and easily using `pip`:

```bash
pip install psx-terminal
```

To update `psx-terminal` to the latest version, run:
```bash
pip install --upgrade psx-terminal
```

## Quickstart

Once installed, simply type `psx-terminal` in your terminal to launch the interface:

```bash
psx-terminal
```

## CLI Usage (Advanced)

```bash
psx-terminal -s HUBC,EFERT -f 4
```

### Flags
- `-s`, `--symbols` Comma‑separated symbols (default: loaded from your saved watchlist or EFERT if none).
- `-f`, `--feeds` Feed mode: `1`=L1, `2`=MBP, `3`=MBO, `4`=All

## Controls
- `1`, `2`, `3`, `4`, `5` Switch main tabs
- `Left/Right` Cycle main tabs
- `Up/Down` Change focused symbol
- `/` Add a symbol to watchlist (persisted safely to `~/.psx_terminal/`)
- `X` Remove selected symbol
- `Q` Quit
- In Analytics (`4`): Press `A`-`D` or use `<`/`>` to cycle subtabs.

## Programmatic Usage

For headless environments or custom integrations, you can use the library programmatically:

### Using Installed Package

```python
from psx_terminal.feed_parser import fetch_quotes, fetch_trades

# Get L1 quotes for EFERT
quotes = fetch_quotes("EFERT")
for quote in quotes[-5:]:  # Last 5 quotes
    print(f"{quote.time} bid={quote.bid} ask={quote.ask}")

# Get trade data for EFERT
trades = fetch_trades("EFERT")
for trade in trades[-5:]:  # Last 5 trades
    print(f"{trade.time} price={trade.price} vol={trade.volume}")
```

### Example Scripts

Two example scripts are provided to demonstrate usage:

- **`fetch_market_data.py`** - Uses local source code (for development)
- **`market_data_client.py`** - Uses installed psx-terminal package

Both scripts provide the same functionality:

```bash
# Full market snapshot
python fetch_market_data.py EFERT

# Search for symbols
python fetch_market_data.py --search ABAN

# Get only quotes or trades
python fetch_market_data.py EFERT --quotes
python fetch_market_data.py EFERT --trades

# Limit results
python fetch_market_data.py EFERT --limit 10
```

**Note:** `market_data_client.py` requires `pip install psx-terminal` first.

## Data Panels
- **Watchlist (L1)**: Last, change, bid/ask, volume, high/low
- **Market Depth (L2)**: MBP or MBO with best bid/ask + spread
- **Movers & Alerts**: Market movers and circuit breaker notices
- **Analytics**: Session summary, price ladder, trade flow, and intraday.

## Design Goals
- Data density without sacrificing scan‑ability
- Clear bid/ask contrast and change emphasis
- Safe behavior on small terminals with graceful resizing

## Recent Updates

### v0.1.1 - Trade Data Parsing Enhancement
- **Fixed**: Improved robustness of trade volume parsing to handle edge cases where volume is returned as `'0.0'`
- **Improved**: Added comprehensive error handling in `feed_parser.py` for both quote and trade data parsing
- Enhanced field stripping to handle whitespace variations in API responses
- Both quote and trade parsers now gracefully skip records with invalid data instead of crashing

## Development & Publishing
This project is authored by **nordixsoft**. 
For documentation on publishing updates to PyPI, refer to `PUBLISHING.md`.

## Notes
- Requires network access to the PSX feed host.
- This project does not place trades. It is display‑only.

## License
MIT License
