Metadata-Version: 2.4
Name: bq-nats-client
Version: 0.1.0
Summary: Python gRPC client for NATS Go sidecar
Author-email: Marcus Lee <marcuslee@balaenaquant.com>
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Requires-Python: >=3.11
Requires-Dist: grpcio>=1.60.0
Requires-Dist: protobuf>=5.0.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: grpcio-tools>=1.60.0; extra == 'dev'
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# bq-nats-client

Python gRPC client for a NATS Go sidecar. Exposes publish, subscribe, and JetStream operations via a thin async API that mirrors `nats.py`.

## Architecture

```
Python app  ──gRPC──►  Go sidecar  ──NATS──►  NATS server
```

The Go sidecar handles the NATS connection; this library talks to it over gRPC on `localhost:50052` (or any address you configure).

## Install

```bash
pip install bq-nats-client
```

## Usage

```python
import asyncio
from nats_client import NATSClient, Msg

async def main():
    nc = NATSClient("localhost:50052")

    # plain publish
    await nc.publish("orders.new", b'{"id": 1}')

    # JetStream
    await nc.jetstream()
    ack = await nc.js_publish("orders.new", b'{"id": 2}')
    print(f"ack: stream={ack.stream} seq={ack.seq}")

    # subscribe
    async def on_msg(msg: Msg):
        print(f"[{msg.subject}] {msg.data}")

    await nc.subscribe("orders.>", cb=on_msg)
    await asyncio.sleep(10)
    await nc.close()

asyncio.run(main())
```

## API

### `NATSClient(grpc_addr="localhost:50052")`

| Method | Description |
|--------|-------------|
| `publish(subject, payload, reply, headers)` | Core NATS publish |
| `jetstream(prefix, domain, timeout)` | Configure JetStream context (call once) |
| `js_publish(subject, payload, ...)` → `PubAck` | JetStream publish |
| `subscribe(subject, cb, queue, ...)` → `Task` | Subscribe; cb fires per message |
| `close()` | Cancel subscribers and close gRPC channel |

## Requirements

- Go sidecar running (`go run ./go/main.go` or compiled binary)
- NATS server reachable from the sidecar
