Metadata-Version: 2.4
Name: zigmq
Version: 0.1.0
Summary: A tiny, pythonic SDK for the ZigMQ text protocol.
Author: reasonz
Project-URL: Homepage, https://github.com/reasonz/zigMQ-python-SDK
Project-URL: Repository, https://github.com/reasonz/zigMQ-python-SDK
Keywords: zigmq,queue,pubsub,messaging
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# zigMQ Python SDK

`zigmq` is a tiny, pythonic SDK for the [ZigMQ](https://github.com/reasonz/zigMQ) text protocol.

By default, the SDK connects to `127.0.0.1:8388`.

The goal of this SDK is deliberately narrow:

- one small sync client for queue/admin commands
- one dedicated subscriber client for pub/sub delivery
- no dependency, no ORM-style abstraction, no magic reconnect layer
- protocol-compatible with the current ZigMQ server behavior

## Install

```bash
pip install zigmq
```

Local development:

```bash
cd zigMQ-python-SDK
pip install -e .
python -m unittest -v
```

## Quick Start

```python
from zigmq import Client

with Client() as mq:
    mq.send("jobs", "hello world")
    print(mq.recv("jobs"))
```

Pub/Sub:

```python
from zigmq import Client, Subscriber

with Subscriber() as sub:
    sub.subscribe("news")

    with Client() as mq:
        delivered = mq.publish("news", "shipped")
        print(delivered)

    event = sub.get()
    print(event.topic, event.message)
```

## API

### `Client`

- `ping() -> str`
- `info() -> Info`
- `send(queue, message) -> None`
- `recv(queue) -> str`
- `recv_bytes(queue) -> bytes`
- `peek(queue) -> str`
- `peek_bytes(queue) -> bytes`
- `queue_length(queue) -> int`
- `create_queue(queue) -> None`
- `list_queues() -> list[str]`
- `publish(topic, message) -> int`
- `list_topics() -> dict[str, int]`
- `subscriber(*topics) -> Subscriber`

Short protocol-style aliases are also available: `mq`, `len`, `queues`, `pub`, `topics`.

### `Subscriber`

- `subscribe(*topics) -> None`
- `unsubscribe(*topics) -> None`
- `get(timeout=None) -> Event`
- iteration support: `for event in sub: ...`

## Design Notes

- This SDK is text-first, because ZigMQ itself is a line-based text protocol.
- The default connection target is `127.0.0.1:8388`.
- Queue/topic names cannot contain whitespace or line breaks.
- Message bodies can contain spaces, but cannot contain `\\r` or `\\n`.
- `queues`, `topics`, and `info` follow the current ZigMQ server behavior and are parsed from multi-line responses.

## Publish To PyPI

Update `version` in [pyproject.toml](./pyproject.toml), then:

```bash
cd zigMQ-python-SDK
python -m build
twine upload dist/*
```
