Metadata-Version: 2.4
Name: jetsocket
Version: 0.1.0
Summary: Production-grade, resilient WebSocket library for Python with Cython-powered performance
Author-email: Omid Roshani <hello@omid.ai>
License-Expression: MIT
Project-URL: Homepage, https://github.com/omidroshani/jetsocket
Project-URL: Documentation, https://github.com/omidroshani/jetsocket#readme
Project-URL: Repository, https://github.com/omidroshani/jetsocket
Project-URL: Issues, https://github.com/omidroshani/jetsocket/issues
Keywords: websocket,async,trading,llm,streaming,resilient
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Cython
Classifier: Framework :: AsyncIO
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: pydantic
Requires-Dist: pydantic>=2.0; extra == "pydantic"
Provides-Extra: orjson
Requires-Dist: orjson>=3.9; extra == "orjson"
Provides-Extra: uvloop
Requires-Dist: uvloop>=0.19; sys_platform != "win32" and extra == "uvloop"
Provides-Extra: truststore
Requires-Dist: truststore>=0.8; extra == "truststore"
Provides-Extra: all
Requires-Dist: pydantic>=2.0; extra == "all"
Requires-Dist: orjson>=3.9; extra == "all"
Requires-Dist: uvloop>=0.19; sys_platform != "win32" and extra == "all"
Requires-Dist: truststore>=0.8; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="docs/assets/banner.jpeg" alt="JetSocket" width="100%">
</p>

<p align="center">
  <a href="https://pypi.org/project/jetsocket/"><img src="https://img.shields.io/pypi/v/jetsocket" alt="PyPI"></a>
  <a href="https://pypi.org/project/jetsocket/"><img src="https://img.shields.io/pypi/pyversions/jetsocket" alt="Python"></a>
  <a href="https://github.com/omidroshani/jetsocket/blob/main/LICENSE"><img src="https://img.shields.io/github/license/omidroshani/jetsocket" alt="License"></a>
</p>

# JetSocket

Production-grade, resilient WebSocket library for Python with Cython-powered performance.

Every existing Python WebSocket library gives you a raw pipe. JetSocket gives you a production-grade client with automatic reconnection, heartbeat management, message buffering, and multiplexing — with a Cython-optimized core that beats websockets by 20-30%.

## Quick Start

```python
import asyncio
import jetsocket

async def main():
    async with jetsocket.connect("wss://example.com/ws") as ws:
        await ws.send({"subscribe": "trades"})
        async for message in ws:
            print(message)

asyncio.run(main())
```

## Installation

```bash
pip install jetsocket
```

With optional extras:

```bash
pip install jetsocket[pydantic]   # Typed messages with Pydantic
pip install jetsocket[all]        # All extras
```

## Features

- **Cython-optimized core** — C-speed frame parsing, masking, and permessage-deflate compression
- **Automatic reconnection** — Exponential backoff with jitter, configurable max attempts
- **Heartbeat management** — WebSocket and application-level ping/pong
- **Message buffering** — Ring buffer with replay-on-reconnect
- **Multiplexing** — Multiple subscriptions over a single connection
- **Typed messages** — Pydantic model validation via `message_type=`
- **Both async and sync** — Native asyncio API and synchronous wrapper
- **Zero runtime dependencies** — Only Python stdlib required

## Usage

### Async (primary API)

```python
from jetsocket import WebSocket

async with WebSocket("wss://stream.example.com/ws", reconnect=True) as ws:
    await ws.send({"subscribe": "trades"})
    async for message in ws:
        print(message)
```

### Sync

```python
from jetsocket import SyncWebSocket

with SyncWebSocket("wss://stream.example.com/ws") as ws:
    ws.send({"subscribe": "trades"})
    msg = ws.recv(timeout=5.0)
    print(msg)
```

### Scalar Config Shorthands

```python
# Simple: just a number
ws = WebSocket("wss://...", heartbeat=20.0, buffer=1000)

# Advanced: full config object
from jetsocket import HeartbeatConfig, BufferConfig
ws = WebSocket("wss://...",
    heartbeat=HeartbeatConfig(interval=20.0, timeout=10.0),
    buffer=BufferConfig(capacity=10_000, overflow_policy="drop_oldest"),
)
```

### Typed Messages

```python
from pydantic import BaseModel
from jetsocket import WebSocket

class Trade(BaseModel):
    symbol: str
    price: float
    quantity: float

async with WebSocket("wss://...", message_type=Trade) as ws:
    async for trade in ws:  # trade: Trade (fully typed)
        print(f"{trade.symbol}: ${trade.price:.2f}")
```

### Multiplexing

```python
from jetsocket import Multiplex

async with Multiplex(
    "wss://stream.binance.com:9443/ws",
    channel_extractor=lambda msg: f"{msg['s'].lower()}@trade" if "s" in msg else None,
    subscribe_msg=lambda ch: {"method": "SUBSCRIBE", "params": [ch]},
    heartbeat=20.0,
) as mux:
    btc = await mux.subscribe("btcusdt@trade")
    eth = await mux.subscribe("ethusdt@trade")

    async for trade in btc:
        print(f"BTC: {trade}")
```

### Presets

```python
from jetsocket.presets import trading, llm_stream

# Optimized for crypto exchanges
ws = trading("wss://stream.binance.com/ws")

# Optimized for LLM streaming
ws = llm_stream("wss://api.example.com/v1/stream")
```

## Examples

Run the included examples to see JetSocket in action:

```bash
# Real-time Binance trade streaming with multiplexing
uv run --extra pydantic python examples/binance_trades.py

# Live terminal dashboard tracking 5 crypto pairs
uv run python examples/multi_symbol_dashboard.py

# Sync price fetching and analysis
uv run python examples/sync_simple.py

# OpenAI LLM streaming via WebSocket
OPENAI_API_KEY="sk-..." uv run python examples/llm_streaming.py
```

See [`examples/README.md`](examples/README.md) for details.

## Architecture

```mermaid
graph TB
    subgraph "User API"
        A["WebSocket / SyncWebSocket"]
        B["Multiplex"]
        C["connect()"]
    end
    subgraph "Manager Layer"
        D["Reconnect + Backoff"]
        E["Heartbeat"]
        F["Message Buffer"]
    end
    subgraph "Transport Layer"
        G["AsyncTransport"]
        H["SyncTransport"]
    end
    subgraph "Cython Core"
        I["Frame Parser"]
        J["C-speed Masking"]
        K["permessage-deflate"]
        L["UTF-8 Validation"]
    end

    C --> A
    B --> A
    A --> D & E & F
    D --> G & H
    G & H --> I & J & K & L
```

## Development

```bash
git clone https://github.com/omid/jetsocket && cd jetsocket
uv sync && make build
uv run pytest                    # Run tests
uv run mypy src/ && uv run ruff check .  # Type check + lint
```

## License

MIT
