connectmq 1.0.0__tar.gz

connectmq-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ConnectMQ
+
+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.

connectmq-1.0.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.5
+Name: connectmq
+Version: 1.0.0
+Summary: Publish and subscribe on the free public MQTT broker broker.connectmq.com in one line. Preconfigured paho-mqtt client and CLI for TCP, TLS, WebSocket and secure WebSocket.
+Project-URL: Homepage, https://connectmq.com
+Project-URL: Documentation, https://connectmq.com/blog/free-public-mqtt-broker
+Author: ConnectMQ Team
+License-Expression: MIT
+License-File: LICENSE
+Keywords: connectmq,free-mqtt-broker,iot,mqtt,mqtt-broker,mqtt-client,paho-mqtt,public-mqtt-broker,pubsub
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications
+Classifier: Topic :: Internet
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: paho-mqtt<3,>=2.0
+Description-Content-Type: text/markdown
+
+# connectmq
+
+Publish and subscribe on the free public MQTT broker **broker.connectmq.com** in one line, with no account needed.
+The package is a preconfigured [paho-mqtt](https://pypi.org/project/paho-mqtt/) client and CLI for TCP, TLS, WebSocket and secure WebSocket.
+It also works with private brokers created on [connectmq.com](https://connectmq.com).
+
+```bash
+pip install connectmq
+connectmq test
+# OK  mqtts://broker.connectmq.com:8883  connect 220 ms, round-trip 46 ms
+```
+
+Requires Python 3.9 or later.
+
+## Quick start
+
+```python
+import connectmq
+
+prefix = connectmq.topic_prefix()  # e.g. "connectmq/demo/7f3a91"
+
+# Publish (dicts and lists are sent as JSON)
+connectmq.publish(f"{prefix}/temperature", {"value": 21.5}, retain=True)
+
+# Subscribe: iterate over incoming messages
+for msg in connectmq.subscribe(f"{prefix}/#", count=1, timeout=10):
+    print(msg.topic, msg.json())
+```
+
+The public area is shared, so use a random prefix to keep your topics apart from other testers.
+
+## Reuse one connection
+
+```python
+import connectmq
+
+with connectmq.Client(transport="tls") as client:
+    # Callback style: returns a function that unsubscribes
+    stop = client.subscribe("connectmq/demo/7f3a91/#", lambda m: print(m.topic, m.payload))
+
+    for i in range(10):
+        client.publish("connectmq/demo/7f3a91/counter", i, qos=1)
+
+    reply = client.once("connectmq/demo/7f3a91/reply", timeout=5)  # raises TimeoutError
+    stop()
+```
+
+## API
+
+| Function | Description |
+|---|---|
+| `publish(topic, payload, qos=0, retain=False, **options)` | Publish one message with a short-lived connection |
+| `subscribe(topics, qos=0, count=0, timeout=None, **options)` | Iterator over messages; stops after `count` messages or `timeout` seconds of silence |
+| `once(topic, timeout=30, **options)` | Next message on a topic filter; raises `TimeoutError` |
+| `connect(**options)` / `Client(**options)` | Connected client; use as a context manager |
+| `test(transport="tls", **options)` | Connects, publishes, receives; returns `TestResult(ok, url, connect_ms, round_trip_ms, error)` |
+| `broker_info()` | Endpoints and limits of the public broker |
+| `topic_prefix(root="connectmq/demo")` | Random topic prefix |
+| `broker_url(transport, host, port)` | URL for `tcp`, `tls`, `ws` or `wss` |
+| `topic_matches(filter, topic)` | Wildcard matching for `+`, `#` and `$share/...` |
+
+`Client` methods: `publish()`, `subscribe(topics, callback, qos)`, `messages(topics, qos, count, timeout)`, `once()` and `close()`.
+The underlying paho client is available as `client.mqtt`.
+
+Callbacks are registered before the broker acknowledges a subscription, so retained messages are never missed.
+
+`Message` has `topic`, `payload` (UTF-8 string), `raw` (bytes), `qos`, `retain`, `received` (datetime) and `json()`.
+
+### Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `transport` | `"tls"` | `tcp` 1883, `tls` 8883, `ws` 8083, `wss` 8084 (`/mqtt`) |
+| `host` | `"broker.connectmq.com"` | Any MQTT broker |
+| `port` | Standard port | |
+| `client_id` | `py-` plus a random suffix | Must be unique and non-empty |
+| `username`, `password` | `None` | Not needed on the public broker |
+| `protocol` | `5` | `5` for MQTT 5.0, `4` for MQTT 3.1.1 |
+| `keepalive`, `timeout` | `60`, `10.0` | Seconds |
+
+## Examples
+
+**Send sensor readings**
+
+```python
+import random, time, connectmq
+
+with connectmq.Client() as client:
+    while True:
+        client.publish("connectmq/demo/7f3a91/sensor", {"temperature": round(random.uniform(20, 25), 1)})
+        time.sleep(5)
+```
+
+**Log messages to CSV**
+
+```python
+import csv, connectmq
+
+with open("mqtt-log.csv", "a", newline="") as f:
+    writer = csv.writer(f)
+    for msg in connectmq.subscribe("connectmq/demo/7f3a91/#"):
+        writer.writerow([msg.received.isoformat(), msg.topic, msg.payload])
+```
+
+**Private ConnectMQ broker**
+
+```python
+import os, connectmq
+
+client = connectmq.connect(
+    host="YOUR_BROKER_HOST",
+    transport="tls",
+    username=os.environ["MQTT_USERNAME"],
+    password=os.environ["MQTT_PASSWORD"],
+)
+```
+
+## CLI
+
+```bash
+connectmq test                                  # connectivity and round-trip
+connectmq info                                  # endpoints and limits
+connectmq prefix                                # random topic prefix
+connectmq sub "connectmq/demo/7f3a91/#"
+connectmq pub connectmq/demo/7f3a91/temp '{"value":21.5}' -q 1 -r
+echo hello | connectmq pub connectmq/demo/7f3a91/msg
+python -m connectmq test                        # if the script folder is not on PATH
+```
+
+| Option | Description |
+|---|---|
+| `-t, --transport` | `tcp`, `tls` (default), `ws`, `wss` |
+| `-H, --host`, `-P, --port` | Broker host and port |
+| `-q, --qos` | 0, 1 or 2 |
+| `-r, --retain` | Retained message (`pub`) |
+| `-n, --count` | Exit after n messages (`sub`) |
+| `-j, --json` | JSON line output (`sub`) |
+| `-u, --username`, `-p, --password` | Credentials for private brokers |
+
+## Public broker
+
+| Protocol | URL |
+|---|---|
+| MQTT (TCP) | `mqtt://broker.connectmq.com:1883` |
+| MQTT over TLS | `mqtts://broker.connectmq.com:8883` |
+| WebSocket | `ws://broker.connectmq.com:8083/mqtt` |
+| Secure WebSocket | `wss://broker.connectmq.com:8084/mqtt` |
+
+Access is anonymous, but the client ID must not be empty. Limits: 64 KB per message, 10 messages per second and 10 subscriptions per client, topics up to 8 levels deep, and sessions expire after at most 30 minutes.
+
+> **Everything on the public broker is public.** Any client can subscribe to `#`.
+> Use the broker only for testing, and always under a random topic prefix.
+> For production, create a private broker with its own credentials at [connectmq.com](https://connectmq.com).
+
+More: [Free Public MQTT Broker for Testing](https://connectmq.com/blog/free-public-mqtt-broker).
+Also available for Node.js (`@connectmq/mqtt`), .NET (`ConnectMQ.Mqtt`), Node-RED (`node-red-contrib-connectmq`) and PowerShell (`MQTTBroker`).
+
+## License
+
+MIT

connectmq-1.0.0/README.md

@@ -0,0 +1,160 @@
+# connectmq
+
+Publish and subscribe on the free public MQTT broker **broker.connectmq.com** in one line, with no account needed.
+The package is a preconfigured [paho-mqtt](https://pypi.org/project/paho-mqtt/) client and CLI for TCP, TLS, WebSocket and secure WebSocket.
+It also works with private brokers created on [connectmq.com](https://connectmq.com).
+
+```bash
+pip install connectmq
+connectmq test
+# OK  mqtts://broker.connectmq.com:8883  connect 220 ms, round-trip 46 ms
+```
+
+Requires Python 3.9 or later.
+
+## Quick start
+
+```python
+import connectmq
+
+prefix = connectmq.topic_prefix()  # e.g. "connectmq/demo/7f3a91"
+
+# Publish (dicts and lists are sent as JSON)
+connectmq.publish(f"{prefix}/temperature", {"value": 21.5}, retain=True)
+
+# Subscribe: iterate over incoming messages
+for msg in connectmq.subscribe(f"{prefix}/#", count=1, timeout=10):
+    print(msg.topic, msg.json())
+```
+
+The public area is shared, so use a random prefix to keep your topics apart from other testers.
+
+## Reuse one connection
+
+```python
+import connectmq
+
+with connectmq.Client(transport="tls") as client:
+    # Callback style: returns a function that unsubscribes
+    stop = client.subscribe("connectmq/demo/7f3a91/#", lambda m: print(m.topic, m.payload))
+
+    for i in range(10):
+        client.publish("connectmq/demo/7f3a91/counter", i, qos=1)
+
+    reply = client.once("connectmq/demo/7f3a91/reply", timeout=5)  # raises TimeoutError
+    stop()
+```
+
+## API
+
+| Function | Description |
+|---|---|
+| `publish(topic, payload, qos=0, retain=False, **options)` | Publish one message with a short-lived connection |
+| `subscribe(topics, qos=0, count=0, timeout=None, **options)` | Iterator over messages; stops after `count` messages or `timeout` seconds of silence |
+| `once(topic, timeout=30, **options)` | Next message on a topic filter; raises `TimeoutError` |
+| `connect(**options)` / `Client(**options)` | Connected client; use as a context manager |
+| `test(transport="tls", **options)` | Connects, publishes, receives; returns `TestResult(ok, url, connect_ms, round_trip_ms, error)` |
+| `broker_info()` | Endpoints and limits of the public broker |
+| `topic_prefix(root="connectmq/demo")` | Random topic prefix |
+| `broker_url(transport, host, port)` | URL for `tcp`, `tls`, `ws` or `wss` |
+| `topic_matches(filter, topic)` | Wildcard matching for `+`, `#` and `$share/...` |
+
+`Client` methods: `publish()`, `subscribe(topics, callback, qos)`, `messages(topics, qos, count, timeout)`, `once()` and `close()`.
+The underlying paho client is available as `client.mqtt`.
+
+Callbacks are registered before the broker acknowledges a subscription, so retained messages are never missed.
+
+`Message` has `topic`, `payload` (UTF-8 string), `raw` (bytes), `qos`, `retain`, `received` (datetime) and `json()`.
+
+### Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `transport` | `"tls"` | `tcp` 1883, `tls` 8883, `ws` 8083, `wss` 8084 (`/mqtt`) |
+| `host` | `"broker.connectmq.com"` | Any MQTT broker |
+| `port` | Standard port | |
+| `client_id` | `py-` plus a random suffix | Must be unique and non-empty |
+| `username`, `password` | `None` | Not needed on the public broker |
+| `protocol` | `5` | `5` for MQTT 5.0, `4` for MQTT 3.1.1 |
+| `keepalive`, `timeout` | `60`, `10.0` | Seconds |
+
+## Examples
+
+**Send sensor readings**
+
+```python
+import random, time, connectmq
+
+with connectmq.Client() as client:
+    while True:
+        client.publish("connectmq/demo/7f3a91/sensor", {"temperature": round(random.uniform(20, 25), 1)})
+        time.sleep(5)
+```
+
+**Log messages to CSV**
+
+```python
+import csv, connectmq
+
+with open("mqtt-log.csv", "a", newline="") as f:
+    writer = csv.writer(f)
+    for msg in connectmq.subscribe("connectmq/demo/7f3a91/#"):
+        writer.writerow([msg.received.isoformat(), msg.topic, msg.payload])
+```
+
+**Private ConnectMQ broker**
+
+```python
+import os, connectmq
+
+client = connectmq.connect(
+    host="YOUR_BROKER_HOST",
+    transport="tls",
+    username=os.environ["MQTT_USERNAME"],
+    password=os.environ["MQTT_PASSWORD"],
+)
+```
+
+## CLI
+
+```bash
+connectmq test                                  # connectivity and round-trip
+connectmq info                                  # endpoints and limits
+connectmq prefix                                # random topic prefix
+connectmq sub "connectmq/demo/7f3a91/#"
+connectmq pub connectmq/demo/7f3a91/temp '{"value":21.5}' -q 1 -r
+echo hello | connectmq pub connectmq/demo/7f3a91/msg
+python -m connectmq test                        # if the script folder is not on PATH
+```
+
+| Option | Description |
+|---|---|
+| `-t, --transport` | `tcp`, `tls` (default), `ws`, `wss` |
+| `-H, --host`, `-P, --port` | Broker host and port |
+| `-q, --qos` | 0, 1 or 2 |
+| `-r, --retain` | Retained message (`pub`) |
+| `-n, --count` | Exit after n messages (`sub`) |
+| `-j, --json` | JSON line output (`sub`) |
+| `-u, --username`, `-p, --password` | Credentials for private brokers |
+
+## Public broker
+
+| Protocol | URL |
+|---|---|
+| MQTT (TCP) | `mqtt://broker.connectmq.com:1883` |
+| MQTT over TLS | `mqtts://broker.connectmq.com:8883` |
+| WebSocket | `ws://broker.connectmq.com:8083/mqtt` |
+| Secure WebSocket | `wss://broker.connectmq.com:8084/mqtt` |
+
+Access is anonymous, but the client ID must not be empty. Limits: 64 KB per message, 10 messages per second and 10 subscriptions per client, topics up to 8 levels deep, and sessions expire after at most 30 minutes.
+
+> **Everything on the public broker is public.** Any client can subscribe to `#`.
+> Use the broker only for testing, and always under a random topic prefix.
+> For production, create a private broker with its own credentials at [connectmq.com](https://connectmq.com).
+
+More: [Free Public MQTT Broker for Testing](https://connectmq.com/blog/free-public-mqtt-broker).
+Also available for Node.js (`@connectmq/mqtt`), .NET (`ConnectMQ.Mqtt`), Node-RED (`node-red-contrib-connectmq`) and PowerShell (`MQTTBroker`).
+
+## License
+
+MIT

connectmq-1.0.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "connectmq"
+version = "1.0.0"
+description = "Publish and subscribe on the free public MQTT broker broker.connectmq.com in one line. Preconfigured paho-mqtt client and CLI for TCP, TLS, WebSocket and secure WebSocket."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "ConnectMQ Team" }]
+keywords = ["mqtt", "mqtt-broker", "public-mqtt-broker", "free-mqtt-broker", "mqtt-client", "iot", "pubsub", "paho-mqtt", "connectmq"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Communications",
+    "Topic :: Internet",
+    "Topic :: System :: Networking",
+    "Typing :: Typed",
+]
+dependencies = ["paho-mqtt>=2.0,<3"]
+
+[project.urls]
+Homepage = "https://connectmq.com"
+Documentation = "https://connectmq.com/blog/free-public-mqtt-broker"
+
+[project.scripts]
+connectmq = "connectmq.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/connectmq"]

connectmq-1.0.0/src/connectmq/__init__.py

@@ -0,0 +1,43 @@
+"""Publish and subscribe on the free public MQTT broker broker.connectmq.com.
+
+>>> import connectmq
+>>> connectmq.publish("connectmq/demo/7f3a91/temp", {"value": 21.5})
+>>> for msg in connectmq.subscribe("connectmq/demo/7f3a91/#", count=1):
+...     print(msg.topic, msg.payload)
+"""
+
+from .client import (
+    BROKER_HOST,
+    ENDPOINTS,
+    Client,
+    Message,
+    TestResult,
+    broker_info,
+    broker_url,
+    connect,
+    once,
+    publish,
+    subscribe,
+    test,
+    topic_matches,
+    topic_prefix,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "BROKER_HOST",
+    "ENDPOINTS",
+    "Client",
+    "Message",
+    "TestResult",
+    "broker_info",
+    "broker_url",
+    "connect",
+    "once",
+    "publish",
+    "subscribe",
+    "test",
+    "topic_matches",
+    "topic_prefix",
+]

connectmq-1.0.0/src/connectmq/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

connectmq-1.0.0/src/connectmq/cli.py

@@ -0,0 +1,97 @@
+"""Command-line interface: ``connectmq test | info | prefix | sub | pub``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import List, Optional
+
+from . import Client, broker_info, test, topic_prefix
+
+EPILOG = """examples:
+  connectmq test
+  connectmq sub "connectmq/demo/7f3a91/#"
+  connectmq pub connectmq/demo/7f3a91/temp '{"value":21.5}' -q 1
+
+Public area: anyone can read your messages. Private brokers: https://connectmq.com"""
+
+
+def _parser() -> argparse.ArgumentParser:
+    connection = argparse.ArgumentParser(add_help=False)
+    connection.add_argument("-t", "--transport", choices=["tcp", "tls", "ws", "wss"], default="tls", help="default: tls")
+    connection.add_argument("-H", "--host", default="broker.connectmq.com", help="default: broker.connectmq.com")
+    connection.add_argument("-P", "--port", type=int, help="override the transport's standard port")
+    connection.add_argument("-u", "--username", help="for private brokers")
+    connection.add_argument("-p", "--password", help="for private brokers")
+    connection.add_argument("-q", "--qos", type=int, choices=[0, 1, 2], default=0)
+
+    parser = argparse.ArgumentParser(
+        prog="connectmq",
+        description="MQTT client for the free public broker broker.connectmq.com",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    commands = parser.add_subparsers(dest="command")
+    commands.add_parser("test", parents=[connection], help="check connectivity and message round-trip (default)")
+    commands.add_parser("info", help="show public broker endpoints and limits")
+    commands.add_parser("prefix", help="print a random topic prefix")
+    sub = commands.add_parser("sub", parents=[connection], help="subscribe and print messages")
+    sub.add_argument("topics", nargs="+")
+    sub.add_argument("-n", "--count", type=int, default=0, help="exit after n messages")
+    sub.add_argument("-j", "--json", action="store_true", help="print JSON lines")
+    pub = commands.add_parser("pub", parents=[connection], help="publish a message (stdin if omitted)")
+    pub.add_argument("topic")
+    pub.add_argument("message", nargs="?")
+    pub.add_argument("-r", "--retain", action="store_true")
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = _parser().parse_args(argv)
+    command = args.command or "test"
+    if command == "info":
+        print(json.dumps(broker_info(), indent=2))
+        return 0
+    if command == "prefix":
+        print(topic_prefix())
+        return 0
+
+    options = {
+        "transport": getattr(args, "transport", "tls"),
+        "host": getattr(args, "host", "broker.connectmq.com"),
+        "port": getattr(args, "port", None),
+        "username": getattr(args, "username", None),
+        "password": getattr(args, "password", None),
+    }
+    try:
+        if command == "test":
+            r = test(**options)
+            if r.ok:
+                print(f"OK  {r.url}  connect {r.connect_ms:.0f} ms, round-trip {r.round_trip_ms:.0f} ms")
+                return 0
+            print(f"FAIL  {r.url}  {r.error}")
+            return 1
+        with Client(**options) as client:
+            if command == "pub":
+                message = args.message if args.message is not None else sys.stdin.read().rstrip("\r\n")
+                client.publish(args.topic, message, qos=args.qos, retain=args.retain)
+                print(f"Published to {args.topic}", file=sys.stderr)
+            else:
+                print(f"Subscribed to {', '.join(args.topics)}. Press Ctrl+C to stop.", file=sys.stderr)
+                for m in client.messages(args.topics, qos=args.qos, count=args.count):
+                    if args.json:
+                        record = {"topic": m.topic, "payload": m.payload, "qos": m.qos, "retain": m.retain, "received": m.received.isoformat()}
+                        print(json.dumps(record), flush=True)
+                    else:
+                        print(f"{m.received.astimezone():%H:%M:%S} {m.topic} {m.payload}", flush=True)
+        return 0
+    except KeyboardInterrupt:
+        return 0
+    except Exception as err:  # noqa: BLE001 - CLI reports errors as text
+        print(f"Error: {err}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

connectmq-1.0.0/src/connectmq/client.py

@@ -0,0 +1,352 @@
+"""MQTT client preconfigured for the ConnectMQ public broker (broker.connectmq.com), built on paho-mqtt."""
+
+from __future__ import annotations
+
+import json
+import queue
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Iterable, Iterator, List, Optional, Tuple, Union
+
+import paho.mqtt.client as mqtt
+
+BROKER_HOST = "broker.connectmq.com"
+
+ENDPOINTS: Dict[str, Tuple[str, int, Optional[str]]] = {
+    "tcp": ("mqtt", 1883, None),
+    "tls": ("mqtts", 8883, None),
+    "ws": ("ws", 8083, "/mqtt"),
+    "wss": ("wss", 8084, "/mqtt"),
+}
+
+Payload = Union[str, bytes, bytearray, int, float, dict, list, None]
+
+
+@dataclass(frozen=True)
+class Message:
+    """A received MQTT message."""
+
+    topic: str
+    raw: bytes
+    qos: int
+    retain: bool
+    received: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    @property
+    def payload(self) -> str:
+        """Payload decoded as UTF-8."""
+        return self.raw.decode("utf-8", errors="replace")
+
+    def json(self) -> Any:
+        """Payload parsed as JSON."""
+        return json.loads(self.raw)
+
+
+@dataclass(frozen=True)
+class TestResult:
+    """Result of :func:`test`."""
+
+    url: str
+    ok: bool
+    connect_ms: Optional[float]
+    round_trip_ms: Optional[float]
+    error: Optional[str]
+
+
+def broker_url(transport: str = "tls", host: str = BROKER_HOST, port: Optional[int] = None) -> str:
+    """URL of the broker for a transport: ``tcp``, ``tls``, ``ws`` or ``wss``."""
+    scheme, default_port, path = _endpoint(transport)
+    return f"{scheme}://{host}:{port or default_port}{path or ''}"
+
+
+def broker_info() -> Dict[str, Any]:
+    """Endpoints and limits of the public broker."""
+    return {
+        "host": BROKER_HOST,
+        "urls": {name: broker_url(name) for name in ENDPOINTS},
+        "authentication": "Anonymous (non-empty client ID required)",
+        "limits": {
+            "max_message_size": "64 KB",
+            "publish_rate": "10 messages/second per client",
+            "subscriptions": 10,
+            "max_topic_depth": 8,
+            "qos": [0, 1, 2],
+            "session_expiry": "30 minutes",
+        },
+        "note": "Public area: anyone can read your messages. Get a private broker at https://connectmq.com",
+    }
+
+
+def topic_prefix(root: str = "connectmq/demo") -> str:
+    """Random topic prefix such as ``connectmq/demo/7f3a91``, to avoid collisions on the shared public area."""
+    return f"{root}/{uuid.uuid4().hex[:6]}"
+
+
+def topic_matches(topic_filter: str, topic: str) -> bool:
+    """MQTT topic filter matching with ``+``, ``#`` and ``$share/group/`` prefixes."""
+    if topic_filter.startswith("$share/"):
+        topic_filter = topic_filter.split("/", 2)[2] if topic_filter.count("/") >= 2 else ""
+    return mqtt.topic_matches_sub(topic_filter, topic)
+
+
+def _endpoint(transport: str) -> Tuple[str, int, Optional[str]]:
+    try:
+        return ENDPOINTS[transport]
+    except KeyError:
+        raise ValueError(f"Unknown transport {transport!r}. Use tcp, tls, ws or wss.") from None
+
+
+def _encode(payload: Payload) -> Union[str, bytes, bytearray, None]:
+    if payload is None or isinstance(payload, (str, bytes, bytearray)):
+        return payload
+    if isinstance(payload, (dict, list)):
+        return json.dumps(payload)
+    return str(payload)
+
+
+class Client:
+    """Connected MQTT client. Use it as a context manager, or call :meth:`close` when done.
+
+    >>> with Client() as c:
+    ...     c.publish("connectmq/demo/7f3a91/hello", "Hi")
+    """
+
+    def __init__(
+        self,
+        transport: str = "tls",
+        host: str = BROKER_HOST,
+        port: Optional[int] = None,
+        client_id: Optional[str] = None,
+        username: Optional[str] = None,
+        password: Optional[str] = None,
+        protocol: int = 5,
+        keepalive: int = 60,
+        timeout: float = 10.0,
+    ) -> None:
+        scheme, default_port, path = _endpoint(transport)
+        self.url = broker_url(transport, host, port)
+        self.client_id = client_id or f"py-{uuid.uuid4().hex[:8]}"
+        self.timeout = timeout
+        self._handlers: Dict[int, Tuple[List[str], Callable[[Message], None]]] = {}
+        self._next_handler = 0
+        self._lock = threading.Lock()
+        self._acks: Dict[int, "queue.Queue[Any]"] = {}
+        self._connected = threading.Event()
+        self._connect_result: Optional[str] = None
+
+        version = mqtt.MQTTv5 if protocol == 5 else mqtt.MQTTv311
+        self.mqtt = mqtt.Client(
+            mqtt.CallbackAPIVersion.VERSION2,
+            client_id=self.client_id,
+            protocol=version,
+            transport="websockets" if path else "tcp",
+            **({} if version == mqtt.MQTTv5 else {"clean_session": True}),
+        )
+        if path:
+            self.mqtt.ws_set_options(path=path)
+        if scheme in ("mqtts", "wss"):
+            self.mqtt.tls_set()
+        if username is not None:
+            self.mqtt.username_pw_set(username, password)
+        self.mqtt.on_connect = self._on_connect
+        self.mqtt.on_message = self._on_message
+        self.mqtt.on_subscribe = self._on_ack
+        self.mqtt.on_unsubscribe = self._on_ack
+
+        self.mqtt.connect_timeout = timeout
+        try:
+            self.mqtt.connect(host, port or default_port, keepalive)
+        except OSError as err:
+            raise ConnectionError(f"Could not connect to {self.url}: {err}") from err
+        self.mqtt.loop_start()
+        if not self._connected.wait(timeout):
+            self._stop()
+            raise TimeoutError(f"Timed out connecting to {self.url}.")
+        if self._connect_result:
+            self._stop()
+            raise ConnectionError(f"Broker refused the connection: {self._connect_result}")
+
+    # paho callbacks -------------------------------------------------------
+
+    def _on_connect(self, client, userdata, flags, reason_code, properties) -> None:
+        if reason_code.is_failure:
+            self._connect_result = str(reason_code)
+        self._connected.set()
+
+    def _on_ack(self, client, userdata, mid, reason_codes, properties) -> None:
+        with self._lock:
+            waiter = self._acks.get(mid)
+        if waiter is not None:
+            waiter.put(reason_codes)
+
+    def _on_message(self, client, userdata, msg) -> None:
+        message = Message(msg.topic, bytes(msg.payload), msg.qos, bool(msg.retain))
+        with self._lock:
+            handlers = list(self._handlers.values())
+        for filters, handler in handlers:
+            if any(topic_matches(f, msg.topic) for f in filters):
+                handler(message)
+
+    # public API -----------------------------------------------------------
+
+    @property
+    def is_connected(self) -> bool:
+        return self.mqtt.is_connected()
+
+    def publish(self, topic: str, payload: Payload = None, qos: int = 0, retain: bool = False) -> None:
+        """Publish a message. ``dict`` and ``list`` payloads are sent as JSON.
+        Publish ``""`` with ``retain=True`` to clear a retained message."""
+        info = self.mqtt.publish(topic, _encode(payload), qos=qos, retain=retain)
+        if info.rc != mqtt.MQTT_ERR_SUCCESS:
+            raise ConnectionError(f"Publish to {topic!r} failed: {mqtt.error_string(info.rc)}")
+        if qos > 0:
+            info.wait_for_publish(self.timeout)
+            if not info.is_published():
+                raise TimeoutError(f"Publish to {topic!r} was not acknowledged within {self.timeout} s.")
+
+    def subscribe(
+        self, topics: Union[str, Iterable[str]], callback: Callable[[Message], None], qos: int = 0
+    ) -> Callable[[], None]:
+        """Call ``callback(message)`` for every message on the topic filter(s).
+        Returns a function that unsubscribes. The callback is registered before the broker
+        acknowledges the subscription, so retained messages are not missed."""
+        filters = [topics] if isinstance(topics, str) else list(topics)
+        if not filters:
+            raise ValueError("At least one topic filter is required.")
+        with self._lock:
+            handler_id = self._next_handler
+            self._next_handler += 1
+            self._handlers[handler_id] = (filters, callback)
+        try:
+            codes = self._request(lambda: self.mqtt.subscribe([(f, qos) for f in filters]))
+            rejected = [f for f, c in zip(filters, codes) if getattr(c, "is_failure", False) or c == 128]
+            if rejected:
+                raise ValueError(f"Subscription rejected: {', '.join(rejected)}")
+        except Exception:
+            with self._lock:
+                self._handlers.pop(handler_id, None)
+            raise
+
+        def unsubscribe() -> None:
+            with self._lock:
+                if self._handlers.pop(handler_id, None) is None:
+                    return
+                still_used = {f for fs, _ in self._handlers.values() for f in fs}
+            unused = [f for f in filters if f not in still_used]
+            if unused and self.is_connected:
+                self._request(lambda: self.mqtt.unsubscribe(unused))
+
+        return unsubscribe
+
+    def messages(
+        self, topics: Union[str, Iterable[str]], qos: int = 0, count: int = 0, timeout: Optional[float] = None
+    ) -> Iterator[Message]:
+        """Iterate over messages on the topic filter(s). Stops after ``count`` messages or
+        ``timeout`` seconds without a message (both optional)."""
+        inbox: "queue.Queue[Message]" = queue.Queue()
+        unsubscribe = self.subscribe(topics, inbox.put, qos)
+        try:
+            received = 0
+            while not count or received < count:
+                try:
+                    yield inbox.get(timeout=timeout)
+                except queue.Empty:
+                    return
+                received += 1
+        finally:
+            unsubscribe()
+
+    def once(self, topic: str, timeout: float = 30.0, qos: int = 0) -> Message:
+        """Wait for the next message on a topic filter. Raises ``TimeoutError``."""
+        for message in self.messages(topic, qos=qos, count=1, timeout=timeout):
+            return message
+        raise TimeoutError(f"No message on {topic!r} within {timeout} s.")
+
+    def close(self) -> None:
+        """Disconnect and stop the network thread."""
+        self._stop()
+
+    def _request(self, send: Callable[[], Tuple[int, Optional[int]]]) -> Any:
+        waiter: "queue.Queue[Any]" = queue.Queue()
+        with self._lock:
+            rc, mid = send()
+            if rc != mqtt.MQTT_ERR_SUCCESS or mid is None:
+                raise ConnectionError(f"Request failed: {mqtt.error_string(rc)}")
+            self._acks[mid] = waiter
+        try:
+            return waiter.get(timeout=self.timeout)
+        except queue.Empty:
+            raise TimeoutError("The broker did not acknowledge the request.") from None
+        finally:
+            with self._lock:
+                self._acks.pop(mid, None)
+
+    def _stop(self) -> None:
+        try:
+            if self.mqtt.is_connected():
+                self.mqtt.disconnect()
+        finally:
+            self.mqtt.loop_stop()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"<connectmq.Client {self.url} client_id={self.client_id!r} connected={self.is_connected}>"
+
+
+def connect(**options: Any) -> Client:
+    """Connect to broker.connectmq.com (or another broker) and return a :class:`Client`.
+    Options: transport, host, port, client_id, username, password, protocol, keepalive, timeout."""
+    return Client(**options)
+
+
+def publish(topic: str, payload: Payload = None, qos: int = 0, retain: bool = False, **options: Any) -> None:
+    """Publish one message using a short-lived connection."""
+    with Client(**options) as client:
+        client.publish(topic, payload, qos=qos, retain=retain)
+
+
+def subscribe(
+    topics: Union[str, Iterable[str]], qos: int = 0, count: int = 0, timeout: Optional[float] = None, **options: Any
+) -> Iterator[Message]:
+    """Iterate over messages using its own connection, which closes when iteration ends.
+
+    >>> for msg in subscribe("connectmq/demo/7f3a91/#", count=3):
+    ...     print(msg.topic, msg.payload)
+    """
+    with Client(**options) as client:
+        yield from client.messages(topics, qos=qos, count=count, timeout=timeout)
+
+
+def once(topic: str, timeout: float = 30.0, qos: int = 0, **options: Any) -> Message:
+    """Wait for the next message on a topic filter using a short-lived connection."""
+    with Client(**options) as client:
+        return client.once(topic, timeout=timeout, qos=qos)
+
+
+def test(transport: str = "tls", **options: Any) -> TestResult:
+    """Connect, subscribe, publish and receive a test message. Never raises; check ``ok``."""
+    url = broker_url(transport, options.get("host", BROKER_HOST), options.get("port"))
+    started = time.perf_counter()
+    connect_ms = None
+    try:
+        with Client(transport=transport, **options) as client:
+            connect_ms = (time.perf_counter() - started) * 1000
+            topic = f"{topic_prefix()}/ping"
+            token = uuid.uuid4().hex
+            received = threading.Event()
+            client.subscribe(topic, lambda m: m.payload == token and received.set())
+            sent = time.perf_counter()
+            client.publish(topic, token)
+            if not received.wait(10):
+                raise TimeoutError("Round-trip timed out.")
+            return TestResult(url, True, connect_ms, (time.perf_counter() - sent) * 1000, None)
+    except Exception as err:  # noqa: BLE001 - reported in the result
+        return TestResult(url, False, connect_ms, None, str(err))