Coverage for src / zmqtt / client.py: 91%
430 statements
« prev ^ index » next coverage.py v7.13.4, created at 2026-11-12 08:49 +0000
« prev ^ index » next coverage.py v7.13.4, created at 2026-11-12 08:49 +0000
1"""High-level MQTT client — public API layer."""
3import asyncio
4import contextlib
5import dataclasses
6import logging
7import os
8import ssl
9from collections.abc import AsyncIterator, Awaitable, Callable, Sequence
10from dataclasses import dataclass
11from typing import Final, Literal, Protocol, overload
13from zmqtt._internal._compat import Self, defer_cancellation, wait_for
14from zmqtt._internal.packets.auth import Auth
15from zmqtt._internal.packets.connect import ConnAck, Connect, Will
16from zmqtt._internal.packets.properties import (
17 AuthProperties,
18 ConnAckProperties,
19 ConnectProperties,
20 PublishProperties,
21 UnsubAckProperties,
22)
23from zmqtt._internal.packets.publish import Publish
24from zmqtt._internal.packets.subscribe import SubscriptionRequest, UnsubAck
25from zmqtt._internal.protocol import MQTTProtocol
26from zmqtt._internal.request_response import _RequestDispatcher
27from zmqtt._internal.state import SessionState
28from zmqtt._internal.subscription_index import SubscriptionEntry
29from zmqtt._internal.topic_matching import _DEFAULT_STRIPPED_PREFIXES
30from zmqtt._internal.transport.base import Transport
31from zmqtt._internal.transport.tcp import open_tcp
32from zmqtt._internal.transport.tls import open_tls
33from zmqtt._internal.types.message import Message
34from zmqtt._internal.types.qos import QoS
35from zmqtt._internal.types.retain_handling import RetainHandling
36from zmqtt._internal.types.topic import validate_publish, validate_response_topic, validate_subscribe_topic
37from zmqtt.errors import MQTTConnectError, MQTTDisconnectedError, MQTTTimeoutError
39__all__ = (
40 "ConnectionInfo",
41 "MQTTClient",
42 "MQTTClientV5",
43 "MQTTClientV311",
44 "ReconnectConfig",
45 "Subscription",
46 "Transport",
47 "UnsubscribeResult",
48 "create_client",
49)
51TransportFactory = Callable[[str, int, ssl.SSLContext | bool | None], Awaitable[Transport]]
53# MQTT 5.0 §3.8.2.1.2: a subscription identifier is a variable-byte integer.
54_MAX_SUBSCRIPTION_IDENTIFIER = 268_435_455
56_UNSUBACK_REJECTION_THRESHOLD: Final = 0x80
58# MQTT 5.0 §3.1.2.11: CONNECT property value limits.
59_MAX_SESSION_EXPIRY_INTERVAL: Final = 0xFFFF_FFFF
60_MAX_RECEIVE_MAXIMUM: Final = 65_535
61# §2.1.4: 1-byte header + 4-byte Remaining Length of at most 268,435,455. The
62# property itself allows up to 2**32 - 1, but no larger packet can be decoded.
63_MAX_PACKET_SIZE: Final = 268_435_460
64# §1.5.4: UTF-8 Encoded Strings are length-prefixed by a Two Byte Integer.
65_MAX_STRING_BYTES: Final = 65_535
67log = logging.getLogger(__name__)
70def _validate_user_properties(pairs: Sequence[tuple[str, str]]) -> tuple[tuple[str, str], ...]:
71 for pair in pairs:
72 if not (isinstance(pair, tuple) and len(pair) == 2 and all(isinstance(s, str) for s in pair)): # noqa: PLR2004
73 msg = f"user_properties must contain (name, value) string pairs, got {pair!r}"
74 raise TypeError(msg)
75 for s in pair:
76 try:
77 size = len(s.encode())
78 except UnicodeEncodeError as e:
79 msg = f"user_properties strings must be valid UTF-8: {s!r}"
80 raise ValueError(msg) from e
81 if size > _MAX_STRING_BYTES:
82 msg = f"user_properties strings must not exceed {_MAX_STRING_BYTES} UTF-8 bytes"
83 raise ValueError(msg)
84 if "\x00" in s:
85 msg = f"user_properties strings must not contain U+0000: {s!r}"
86 raise ValueError(msg)
87 return tuple(pairs)
90def _build_connect_properties(
91 version: Literal["3.1.1", "5.0"],
92 *,
93 session_expiry_interval: int,
94 receive_maximum: int | None,
95 maximum_packet_size: int | None,
96 user_properties: Sequence[tuple[str, str]],
97 request_response_information: bool | None,
98 request_problem_information: bool | None,
99) -> ConnectProperties | None:
100 """Validate CONNECT properties once, so every (re)connect sends the same ones.
102 ``None`` means "omit the property", letting the broker apply the spec default.
103 """
104 configured = {
105 "receive_maximum": receive_maximum is not None,
106 "maximum_packet_size": maximum_packet_size is not None,
107 "user_properties": bool(user_properties),
108 "request_response_information": request_response_information is not None,
109 "request_problem_information": request_problem_information is not None,
110 }
111 if version != "5.0":
112 if any(configured.values()):
113 names = ", ".join(name for name, is_set in configured.items() if is_set)
114 msg = f"MQTT 5.0 is required for {names}"
115 raise RuntimeError(msg)
116 return None
117 if not 0 <= session_expiry_interval <= _MAX_SESSION_EXPIRY_INTERVAL:
118 msg = f"session_expiry_interval must be in 0..{_MAX_SESSION_EXPIRY_INTERVAL}"
119 raise ValueError(msg)
120 if receive_maximum is not None and not 1 <= receive_maximum <= _MAX_RECEIVE_MAXIMUM:
121 msg = f"receive_maximum must be in 1..{_MAX_RECEIVE_MAXIMUM}"
122 raise ValueError(msg)
123 if maximum_packet_size is not None and not 1 <= maximum_packet_size <= _MAX_PACKET_SIZE:
124 msg = f"maximum_packet_size must be in 1..{_MAX_PACKET_SIZE}"
125 raise ValueError(msg)
126 return ConnectProperties(
127 session_expiry_interval=session_expiry_interval,
128 receive_maximum=receive_maximum,
129 maximum_packet_size=maximum_packet_size,
130 request_response_information=request_response_information,
131 request_problem_information=request_problem_information,
132 user_properties=_validate_user_properties(user_properties),
133 )
136@dataclass(frozen=True, slots=True, kw_only=True)
137class ConnectionInfo:
138 """Immutable snapshot of a successful CONNECT/CONNACK handshake.
140 Attributes:
141 connection_id: Successful network connection number within this client,
142 starting at 1. A resumed MQTT session still gets a new number.
143 session_present: Whether the broker resumed an existing MQTT session.
144 return_code: Successful CONNACK return code (0).
145 properties: Raw CONNACK properties, without substituted defaults.
146 effective_client_id: Sent client ID, or the broker-assigned ID if empty.
147 effective_keepalive: Server Keep Alive, falling back to CONNECT keepalive.
148 effective_session_expiry_interval: CONNACK session expiry, falling back
149 to CONNECT and then 0. None for MQTT 3.1.1.
150 """
152 connection_id: int
153 session_present: bool
154 return_code: int
155 properties: ConnAckProperties | None
156 effective_client_id: str
157 effective_keepalive: int
158 effective_session_expiry_interval: int | None
160 @classmethod
161 def from_connack(
162 cls,
163 connect_packet: Connect,
164 connack: ConnAck,
165 *,
166 version: Literal["3.1.1", "5.0"],
167 connection_id: int,
168 ) -> Self:
169 """Build a snapshot from a successful CONNECT/CONNACK exchange."""
170 properties = connack.properties
171 client_id = connect_packet.client_id
172 keepalive = connect_packet.keepalive
173 expiry = None
174 if version == "5.0":
175 expiry = 0
176 if connect_packet.properties is not None and connect_packet.properties.session_expiry_interval is not None:
177 expiry = connect_packet.properties.session_expiry_interval
178 if properties is not None:
179 if not client_id and properties.assigned_client_identifier is not None:
180 client_id = properties.assigned_client_identifier
181 if properties.server_keep_alive is not None:
182 keepalive = properties.server_keep_alive
183 if version == "5.0" and properties.session_expiry_interval is not None:
184 expiry = properties.session_expiry_interval
185 return cls(
186 connection_id=connection_id,
187 session_present=connack.session_present,
188 return_code=connack.return_code,
189 properties=properties,
190 effective_client_id=client_id,
191 effective_keepalive=keepalive,
192 effective_session_expiry_interval=expiry,
193 )
196@dataclass(frozen=True, slots=True, kw_only=True)
197class UnsubscribeResult:
198 """The broker's UNSUBACK for the filters sent in one UNSUBSCRIBE.
200 Attributes:
201 topic_filters: Filters sent to the broker, in request order.
202 reason_codes: One code per filter. Empty on MQTT 3.1.1, whose UNSUBACK
203 carries none.
204 properties: Raw UNSUBACK properties.
205 """
207 topic_filters: tuple[str, ...]
208 reason_codes: tuple[int, ...]
209 properties: UnsubAckProperties | None
211 @classmethod
212 def from_unsuback(cls, topic_filters: tuple[str, ...], unsuback: UnsubAck) -> Self:
213 return cls(topic_filters=topic_filters, reason_codes=unsuback.reason_codes, properties=unsuback.properties)
215 @property
216 def failures(self) -> dict[str, int]:
217 """Rejected filters mapped to their reason codes (>= 0x80)."""
218 return {
219 f: code
220 for f, code in zip(self.topic_filters, self.reason_codes, strict=False)
221 if code >= _UNSUBACK_REJECTION_THRESHOLD
222 }
224 @property
225 def reason_string(self) -> str | None:
226 return self.properties.reason_string if self.properties is not None else None
228 @property
229 def user_properties(self) -> tuple[tuple[str, str], ...]:
230 return self.properties.user_properties if self.properties is not None else ()
233@dataclass(frozen=True, slots=True, kw_only=True)
234class ReconnectConfig:
235 """Configuration for automatic reconnection on connection loss.
237 Attributes:
238 enabled: Whether to reconnect automatically. Set to ``False`` to let
239 exceptions propagate immediately on disconnection.
240 initial_delay: Seconds to wait before the first reconnection attempt.
241 max_delay: Upper bound (seconds) for the exponential back-off delay.
242 backoff_factor: Multiplier applied to the delay after each failed attempt.
243 max_attempts: Maximum total number of connection attempts before
244 giving up. ``None`` retries indefinitely.
245 retry_refusal: Decides per refused CONNACK whether to retry it.
246 ``None`` retries only transient refusals
247 (:attr:`MQTTConnectError.is_transient`). Retries count towards
248 *max_attempts*.
249 """
251 enabled: bool = True
252 initial_delay: float = 1.0
253 max_delay: float = 60.0
254 backoff_factor: float = 2.0
255 max_attempts: int | None = 5
256 retry_refusal: Callable[[MQTTConnectError], bool] | None = None
259async def _default_transport_factory(
260 host: str,
261 port: int,
262 tls: ssl.SSLContext | bool | None,
263) -> Transport:
264 if not tls:
265 return await open_tcp(host, port)
266 if tls is True:
267 return await open_tls(host, port)
268 return await open_tls(host, port, tls)
271class MQTTClientV311(Protocol):
272 async def __aenter__(self) -> Self: ...
274 async def __aexit__(self, *exc: object) -> None: ...
276 async def publish(
277 self,
278 topic: str,
279 payload: bytes | str,
280 *,
281 qos: QoS = QoS.AT_MOST_ONCE,
282 retain: bool = False,
283 ) -> None: ...
285 def subscribe(
286 self,
287 *filters: str,
288 qos: QoS = QoS.AT_MOST_ONCE,
289 auto_ack: bool = True,
290 receive_buffer_size: int = 1000,
291 ) -> "Subscription": ...
293 @property
294 def connection_info(self) -> ConnectionInfo: ...
296 async def connect(self) -> None: ...
298 async def disconnect(self) -> None: ...
300 async def ping(self, timeout: float = 10.0) -> float: ...
303class MQTTClientV5(Protocol):
304 """Type-safe view of MQTTClient for MQTT 5.0 connections."""
306 async def __aenter__(self) -> Self: ...
307 async def __aexit__(self, *exc: object) -> None: ...
309 @property
310 def connection_info(self) -> ConnectionInfo: ...
312 async def connect(self) -> None: ...
314 async def disconnect(self) -> None: ...
316 async def publish(
317 self,
318 topic: str,
319 payload: bytes | str,
320 *,
321 qos: QoS = QoS.AT_MOST_ONCE,
322 retain: bool = False,
323 properties: PublishProperties | None = None,
324 ) -> None: ...
326 def subscribe(
327 self,
328 *filters: str,
329 qos: QoS = QoS.AT_MOST_ONCE,
330 auto_ack: bool = True,
331 receive_buffer_size: int = 1000,
332 no_local: bool = False,
333 retain_as_published: bool = False,
334 retain_handling: RetainHandling = RetainHandling.SEND_ON_SUBSCRIBE,
335 subscription_identifier: int | None = None,
336 ) -> "Subscription": ...
338 async def auth(self, method: str, data: bytes | None = None) -> None: ...
340 async def ping(self, timeout: float = 10.0) -> float: ...
342 async def request(
343 self,
344 topic: str,
345 payload: bytes | str,
346 *,
347 qos: QoS = QoS.AT_MOST_ONCE,
348 timeout: float = 30.0,
349 properties: PublishProperties | None = None,
350 ) -> "Message": ...
353class Subscription:
354 """Async context manager for an active topic subscription.
356 Registers filters on enter, unsubscribes on exit. Messages are available
357 via get_message() or async iteration. Survives reconnection transparently —
358 the queue keeps buffering and delivery resumes when the connection restores.
359 """
361 def __init__(
362 self,
363 client: "MQTTClient",
364 filters: list[str],
365 qos: QoS,
366 auto_ack: bool = True,
367 receive_buffer_size: int = 1000,
368 no_local: bool = False,
369 retain_as_published: bool = False,
370 retain_handling: RetainHandling = RetainHandling.SEND_ON_SUBSCRIBE,
371 subscription_identifier: int | None = None,
372 ) -> None:
373 self._client = client
374 self._filters = filters
375 self._qos = qos
376 self._auto_ack = auto_ack
377 self._queue: asyncio.Queue[Message] = asyncio.Queue(receive_buffer_size)
378 self._no_local = no_local
379 self._retain_as_published = retain_as_published
380 self._retain_handling = retain_handling
381 self._subscription_identifier = subscription_identifier
382 self._registered_filters: list[str] = []
383 self._detached = False
385 async def __aenter__(self) -> Self:
386 """Register the subscription filters with the broker.
388 Raises:
389 MQTTDisconnectedError: If the client is not currently connected.
390 """
391 if self._client._protocol is None:
392 msg = "Not connected"
393 raise MQTTDisconnectedError(msg)
394 if self._detached:
395 msg = "A detached subscription cannot be restarted"
396 raise RuntimeError(msg)
397 self._client._subscriptions.append(self)
398 await self._do_subscribe(self._client._protocol)
399 return self
401 async def __aexit__(self, *exc: object) -> None:
402 """Same as :meth:`stop`, discarding its result; skips UNSUBSCRIBE if the body was cancelled."""
403 await self._stop(cancelled=isinstance(exc[1], asyncio.CancelledError))
405 async def _stop(self, *, cancelled: bool) -> UnsubscribeResult | None:
406 if self not in self._client._subscriptions:
407 return None
408 self._client._subscriptions.remove(self)
409 protocol = self._client._protocol
410 if cancelled or not self._registered_filters or protocol is None:
411 return None
412 try:
413 sent = await protocol.unsubscribe(self._registered_filters)
414 except Exception: # noqa: BLE001 - filters are already released locally, so nothing is left to retry
415 log.warning("Unsubscribe of %s failed; stopped locally", self._registered_filters, exc_info=True)
416 return None
417 return UnsubscribeResult.from_unsuback(*sent) if sent is not None else None
419 def _detach_local(self, protocol: MQTTProtocol | None) -> None:
420 self._detached = True
421 if protocol is not None:
422 self._client._detached_filters.update(protocol.detach(self._registered_filters))
423 while not self._queue.empty():
424 self._queue.get_nowait()
426 async def _do_subscribe(self, protocol: MQTTProtocol) -> None:
427 reqs = [
428 SubscriptionRequest(
429 topic_filter=f,
430 qos=self._qos,
431 no_local=self._no_local,
432 retain_as_published=self._retain_as_published,
433 retain_handling=self._retain_handling,
434 )
435 for f in self._filters
436 ]
437 _, queues = await protocol.subscribe(
438 reqs,
439 auto_ack=self._auto_ack,
440 queue=self._queue,
441 subscription_identifier=self._subscription_identifier,
442 )
443 self._registered_filters = list(queues.keys())
445 async def _reconnect(self, protocol: MQTTProtocol) -> None:
446 """Re-subscribe on a fresh protocol after reconnection."""
447 if self._detached:
448 return
449 await self._do_subscribe(protocol)
451 async def start(self) -> None:
452 """Register the subscription filters with the broker.
453 Equivalent to entering the async context manager.
454 Must be paired with a corresponding :meth:`stop` call to send
455 UNSUBSCRIBE and release internal resources.
457 Example::
459 sub = client.subscribe("sensors/#", qos=QoS.AT_LEAST_ONCE)
460 await sub.start()
461 # ... later
462 await sub.stop()
464 Raises:
465 MQTTDisconnectedError: If the client is not currently connected.
466 """
467 await self.__aenter__()
469 async def stop(self) -> UnsubscribeResult | None:
470 """Unsubscribe from all filters and stop message delivery.
472 Equivalent to exiting the async context manager. Sends UNSUBSCRIBE to
473 the broker. Never raises: failures and rejected filters are logged as
474 warnings.
476 Example::
478 await sub.stop()
480 Returns:
481 The broker's UNSUBACK, or ``None`` if none was received.
482 """
483 return await self._stop(cancelled=False)
485 async def detach(self) -> None:
486 """Stop local delivery without sending UNSUBSCRIBE.
488 Use before disconnecting a persistent client to preserve its broker-side
489 filters. New QoS 1/2 messages are left unacknowledged and queued messages
490 are discarded. With ``auto_ack=True``, a queued message may already have
491 been acknowledged before this call; use ``auto_ack=False`` when replay of
492 unprocessed messages matters. Messages already handed to a consumer can
493 still be acknowledged until the client disconnects. Cancel any task
494 already waiting in ``get_message()`` as part of shutdown.
495 Automatic reconnection preserves detachment until an explicit
496 ``client.disconnect()``. A new subscription to the same filter before
497 that disconnect is ignored with a warning.
498 """
499 if self not in self._client._subscriptions:
500 return
501 self._client._subscriptions.remove(self)
502 self._detach_local(self._client._protocol)
504 async def get_message(self) -> Message:
505 """Wait for and return the next message from the subscription queue.
507 Raises:
508 Exception: The terminal error that stopped the client run loop.
509 """
510 if self._detached:
511 msg = "Subscription detached"
512 raise MQTTDisconnectedError(msg)
513 failure_signal = self._client._subscription_failure
514 if failure_signal is None:
515 message = await self._queue.get()
516 else:
517 if failure_signal.done():
518 raise failure_signal.result()
520 message_task = asyncio.create_task(self._queue.get())
521 try:
522 done, _ = await asyncio.wait(
523 (message_task, failure_signal),
524 return_when=asyncio.FIRST_COMPLETED,
525 )
526 if failure_signal in done:
527 raise failure_signal.result()
528 message = message_task.result()
529 finally:
530 if not message_task.done():
531 message_task.cancel()
532 await asyncio.gather(message_task, return_exceptions=True)
534 if self._detached:
535 msg = "Subscription detached"
536 raise MQTTDisconnectedError(msg)
537 await self._notify_capacity_available()
538 return message
540 async def _notify_capacity_available(self) -> None:
541 protocol = self._client._protocol
542 if protocol is not None:
543 await protocol.inbound.drain()
545 def __aiter__(self) -> AsyncIterator[Message]:
546 """Return self as the async iterator."""
547 return self
549 async def __anext__(self) -> Message:
550 """Return the next message, suspending until one is available."""
551 return await self.get_message()
554class MQTTClient:
555 """Asyncio MQTT client with automatic reconnection.
557 Use as an async context manager. subscribe() returns a Subscription that
558 is itself an async context manager.
559 """
561 def __init__(
562 self,
563 host: str,
564 port: int = 1883,
565 *,
566 client_id: str = "",
567 keepalive: int = 60,
568 clean_session: bool = True,
569 username: str | None = None,
570 password: str | None = None,
571 will: Will | None = None,
572 tls: ssl.SSLContext | bool | None = None,
573 reconnect: ReconnectConfig | None = None,
574 on_connection_recovery_failed: Callable[[], Awaitable[None]] | None = None,
575 mqtt_connect_timeout: float = 30.0,
576 transport_factory: TransportFactory | None = None,
577 version: Literal["3.1.1", "5.0"] = "3.1.1",
578 session_expiry_interval: int = 0,
579 receive_maximum: int | None = None,
580 maximum_packet_size: int | None = None,
581 user_properties: Sequence[tuple[str, str]] = (),
582 request_response_information: bool | None = None,
583 request_problem_information: bool | None = None,
584 stripped_prefixes: tuple[str, ...] = _DEFAULT_STRIPPED_PREFIXES,
585 max_pending_requests: int = 1000,
586 session_replay_buffer_size: int = 1000,
587 session_replay_timeout: float = 30.0,
588 ) -> None:
589 """Create an MQTT client.
591 The client must be used as an async context manager to establish the
592 connection::
594 async with MQTTClient("broker.example.com") as client:
595 await client.publish("sensors/temp", "22.5")
597 Prefer :func:`create_client` for version-typed access.
599 Args:
600 host: Broker hostname or IP address.
601 port: TCP port. Defaults to ``1883`` (``8883`` is conventional for TLS).
602 client_id: Client identifier sent in CONNECT. An empty string lets the
603 broker assign one.
604 keepalive: Keepalive interval in seconds. ``0`` disables keepalive.
605 clean_session: Start with a clean session (MQTT 3.1.1) or discard any
606 existing session state on connect.
607 username: Optional username for broker authentication.
608 password: Optional plain-text password for broker authentication.
609 will: Last Will published by the broker if the connection closes
610 unexpectedly.
611 tls: TLS configuration. Pass ``True`` for default TLS, an
612 :class:`ssl.SSLContext` for custom settings, or ``False`` (default)
613 for a plain TCP connection.
614 reconnect: Reconnection policy. Defaults to
615 :class:`ReconnectConfig` with exponential back-off enabled.
616 on_connection_recovery_failed: Async callback invoked once when a
617 connection that was established successfully cannot be restored.
618 Initial connection failures and clean disconnects do not invoke it.
619 mqtt_connect_timeout: Seconds to wait for the broker's CONNACK during
620 the MQTT CONNECT/CONNACK handshake — distinct from the TCP socket
621 connect — before raising :exc:`MQTTTimeoutError`. Must be positive.
622 Defaults to ``30.0``.
623 transport_factory: Override the low-level transport. Useful for testing.
624 version: MQTT protocol version to use. Either ``"3.1.1"`` (default) or
625 ``"5.0"``.
626 session_expiry_interval: MQTT 5.0 session expiry interval in seconds.
627 ``0`` means the session expires on disconnect.
628 receive_maximum: MQTT 5.0 limit (1..65535) on QoS 1/2 messages the
629 broker may send before they are acknowledged. Messages awaiting
630 manual :meth:`Message.ack` count against it. A broker exceeding
631 it is disconnected with reason code ``0x93``. ``None`` omits the
632 property (broker default 65535).
633 maximum_packet_size: MQTT 5.0 limit (1..268435460) on the size in
634 bytes of any packet the broker sends. A broker exceeding it is
635 disconnected with reason code ``0x95``. ``None`` omits the
636 property (no limit).
637 user_properties: MQTT 5.0 ``(name, value)`` pairs sent in CONNECT,
638 in order; names may repeat.
639 request_response_information: MQTT 5.0: ask the broker for Response
640 Information in CONNACK. ``None`` omits the property (broker
641 default ``False``).
642 request_problem_information: MQTT 5.0: set ``False`` to ask the
643 broker to omit Reason Strings and User Properties from packets
644 other than PUBLISH, CONNACK, and DISCONNECT. ``None`` omits the
645 property (broker default ``True``).
646 stripped_prefixes: Group-less subscription prefixes the broker strips
647 before delivery — matched against incoming PUBLISH topics with the
648 prefix removed. Defaults to ``("$queue", "$exclusive")``; add a
649 broker-specific decorator here instead of patching the library.
650 ``$share/<group>/`` is always handled; real namespaces the broker
651 delivers on unchanged (e.g. ``$SYS``) must not be listed.
652 max_pending_requests: Maximum concurrent MQTT 5.0 ``request()`` calls.
653 Additional calls wait until capacity is available.
654 session_replay_buffer_size: Maximum unmatched messages held while a
655 resumed persistent session waits for local subscriptions. ``0``
656 makes the buffer unbounded. Defaults to ``1000``.
657 session_replay_timeout: Seconds a persistent-session message may
658 remain in the replay buffer. Remaining messages are dropped
659 without acknowledgement after the timeout. Defaults to ``30.0``.
661 CONNECT properties are validated here and sent on every connection
662 attempt, including reconnects.
664 Raises:
665 ValueError: If a CONNECT property value is out of range or a User
666 Property string is not a valid MQTT UTF-8 string.
667 TypeError: If *user_properties* holds anything but string pairs.
668 RuntimeError: If an MQTT 5.0-only option is used with MQTT 3.1.1.
669 """
670 if not mqtt_connect_timeout > 0:
671 msg = "mqtt_connect_timeout must be positive"
672 raise ValueError(msg)
673 if session_replay_buffer_size < 0:
674 msg = "session_replay_buffer_size must be non-negative"
675 raise ValueError(msg)
676 if not session_replay_timeout > 0:
677 msg = "session_replay_timeout must be positive"
678 raise ValueError(msg)
679 if will is not None and will.properties is not None and version != "5.0":
680 msg = "will properties require MQTT 5.0"
681 raise RuntimeError(msg)
682 self._connect_properties = _build_connect_properties(
683 version,
684 session_expiry_interval=session_expiry_interval,
685 receive_maximum=receive_maximum,
686 maximum_packet_size=maximum_packet_size,
687 user_properties=user_properties,
688 request_response_information=request_response_information,
689 request_problem_information=request_problem_information,
690 )
691 self._host = host
692 self._port = port
693 self._client_id = client_id
694 self._keepalive = keepalive
695 self._clean_session = clean_session
696 self._username = username
697 self._password = password
698 self._will = will
699 self._tls = tls
700 self._reconnect = reconnect or ReconnectConfig()
701 self._on_connection_recovery_failed = on_connection_recovery_failed
702 self._mqtt_connect_timeout = mqtt_connect_timeout
703 self._transport_factory: TransportFactory = transport_factory or _default_transport_factory
704 self._version: Final = version
705 self._stripped_prefixes = stripped_prefixes
706 self._request_dispatcher = _RequestDispatcher(max_pending_requests)
707 self._session_replay_buffer_size = session_replay_buffer_size
708 self._session_replay_timeout = session_replay_timeout
709 self._connection_info: ConnectionInfo | None = None
710 self._connection_id = 0
711 self._protocol: MQTTProtocol | None = None
712 self._subscriptions: list[Subscription] = []
713 self._detached_filters: dict[str, SubscriptionEntry] = {}
714 self._run_task: asyncio.Task[None] | None = None
715 self._subscription_failure: asyncio.Future[BaseException] | None = None
717 @property
718 def connection_info(self) -> ConnectionInfo:
719 """Current successful handshake.
721 Subscription restoration may still be in progress. Previously returned
722 snapshots remain valid after disconnection. Effective values describe
723 negotiation; they do not change ping scheduling or future CONNECT IDs.
725 Raises:
726 MQTTDisconnectedError: If no successful connection is active,
727 including before connecting and during reconnection.
728 """
729 if self._connection_info is None:
730 msg = "No active connection information"
731 raise MQTTDisconnectedError(msg)
732 return self._connection_info
734 async def __aenter__(self) -> Self:
735 """Connect to the broker and start the background run loop."""
736 await self._connect_with_retry()
737 self._subscription_failure = asyncio.get_running_loop().create_future()
738 self._run_task = asyncio.create_task(self._run_loop())
739 self._run_task.add_done_callback(self._notify_subscription_failure)
740 return self
742 def _notify_subscription_failure(self, run_task: asyncio.Task[None]) -> None:
743 """Wake subscription consumers if the client run loop failed."""
744 self._connection_info = None
745 if run_task.cancelled():
746 return
747 failure = run_task.exception()
748 signal = self._subscription_failure
749 if failure is not None and signal is not None and not signal.done():
750 signal.set_result(failure)
752 async def __aexit__(self, *exc: object) -> None:
753 """Disconnect cleanly and cancel the run loop."""
754 self._connection_info = None
755 async with defer_cancellation():
756 await self._request_dispatcher.cancel_pending()
757 if self._run_task is not None:
758 self._run_task.cancel()
759 await asyncio.gather(self._run_task, return_exceptions=True)
760 self._run_task = None
761 if self._protocol is not None:
762 await self._protocol.disconnect()
763 self._protocol = None
764 self._detached_filters.clear()
766 async def connect(self) -> None:
767 """Connect to the broker and start the background run loop.
769 Equivalent to entering the async context manager.
770 Must be paired with a corresponding :meth:`disconnect` call to send
771 DISCONNECT, close the socket, and stop the background run loop.
773 Example::
775 client = create_client("broker.example.com")
776 await client.connect()
777 # ... use the client
778 await client.disconnect()
780 Raises:
781 MQTTConnectError: If the broker refuses the connection.
782 """
783 await self.__aenter__()
785 async def disconnect(self) -> None:
786 """Disconnect cleanly and stop the background run loop.
788 Equivalent to exiting the async context manager. Sends DISCONNECT,
789 closes the socket, and cancels the internal run loop task. Safe to
790 call even if the connection has already been lost.
791 """
792 await self.__aexit__(None, None, None)
794 async def publish(
795 self,
796 topic: str,
797 payload: bytes | str,
798 *,
799 qos: QoS = QoS.AT_MOST_ONCE,
800 retain: bool = False,
801 properties: PublishProperties | None = None,
802 ) -> None:
803 """Publish a message to *topic*.
805 Args:
806 topic: Topic string. Must not contain wildcards.
807 payload: Message body. ``str`` values are UTF-8 encoded automatically.
808 qos: Delivery guarantee level. Defaults to ``AT_MOST_ONCE``.
809 retain: Ask the broker to retain the message for future subscribers.
810 properties: MQTT 5.0 publish properties. Raises if used with MQTT 3.1.1.
812 Raises:
813 MQTTInvalidTopicError: If *topic* is empty, contains wildcards, or has
814 ``$`` in a non-leading position.
815 MQTTDisconnectedError: If the client is not currently connected.
816 RuntimeError: If *properties* is supplied on an MQTT 3.1.1 connection.
817 MQTTPublishError: If the broker rejects a QoS 1/2 publish. Not raised for QoS 0 or MQTT 3.1.1.
818 MQTTRetainNotAvailableError: If *retain* is set and the broker's CONNACK
819 reported that retained messages are not available. Nothing is sent.
820 """
821 validate_publish(topic)
822 if self._protocol is None:
823 msg = "Not connected"
824 raise MQTTDisconnectedError(msg)
825 if properties is not None and self._version != "5.0":
826 msg = "properties require MQTT 5.0"
827 raise RuntimeError(msg)
828 if isinstance(payload, str):
829 payload = payload.encode()
830 await self._protocol.publish(
831 Publish(
832 topic=topic,
833 payload=payload,
834 qos=qos,
835 retain=retain,
836 dup=False,
837 properties=properties,
838 ),
839 )
841 async def ping(self, timeout: float = 10.0) -> float:
842 """Send a PINGREQ and return the round-trip time in seconds.
844 Args:
845 timeout: Seconds to wait for PINGRESP before raising
846 :exc:`MQTTTimeoutError`.
848 Returns:
849 RTT in seconds.
851 Raises:
852 MQTTDisconnectedError: If the client is not currently connected.
853 MQTTTimeoutError: If no PINGRESP is received within *timeout* seconds.
854 """
855 if self._protocol is None:
856 msg = "Not connected"
857 raise MQTTDisconnectedError(msg)
858 return await self._protocol.ping(timeout=timeout)
860 def subscribe(
861 self,
862 *filters: str,
863 qos: QoS = QoS.AT_MOST_ONCE,
864 auto_ack: bool = True,
865 receive_buffer_size: int = 1000,
866 no_local: bool = False,
867 retain_as_published: bool = False,
868 retain_handling: RetainHandling = RetainHandling.SEND_ON_SUBSCRIBE,
869 subscription_identifier: int | None = None,
870 ) -> Subscription:
871 """Create a :class:`Subscription` for one or more topic filters.
873 The returned object must be used as an async context manager to activate
874 the subscription and unsubscribe on exit::
876 async with client.subscribe("sensors/#", qos=QoS.AT_LEAST_ONCE) as sub:
877 async for msg in sub:
878 print(msg.topic, msg.payload)
880 Args:
881 *filters: One or more MQTT topic filters. Wildcards ``+`` (single level)
882 and ``#`` (multi-level) are supported.
883 qos: Maximum QoS level requested from the broker.
884 auto_ack: Automatically send PUBACK/PUBREC upon receipt. Set to
885 ``False`` to acknowledge manually via :meth:`Message.ack`.
886 receive_buffer_size: Maximum messages buffered per internal queue.
887 When the buffers are full the read loop stops pulling from the
888 socket, so a slow consumer pushes back on the broker through the
889 TCP window instead of growing memory. ``0`` makes the queues
890 unbounded; the default is ``1000``.
891 no_local: Do not receive messages published by this client (MQTT 5.0
892 only).
893 retain_as_published: Preserve the retain flag on forwarded messages
894 (MQTT 5.0 only).
895 retain_handling: Control when the broker sends retained messages for
896 this subscription (MQTT 5.0 only).
897 subscription_identifier: Numeric identifier (1..268435455) sent in the
898 SUBSCRIBE properties (MQTT 5.0 only). The broker echoes it on every
899 PUBLISH this subscription causes: incoming messages are routed to
900 the exact subscription that matched (essential when filters
901 overlap, e.g. a ``$share/...`` subscription plus its plain twin),
902 and the value is readable on ``Message.properties``.
904 Raises:
905 MQTTInvalidTopicError: If any filter is empty, has ``$`` in a non-leading
906 position, or contains a malformed wildcard (e.g. ``sensors#`` or
907 ``a/b#/c``).
908 RuntimeError: If an MQTT 5.0-only subscription option is used on an
909 MQTT 3.1.1 connection.
910 """
911 for f in filters:
912 validate_subscribe_topic(f)
913 uses_v5_option = no_local or retain_as_published or retain_handling is not RetainHandling.SEND_ON_SUBSCRIBE
914 if uses_v5_option and self._version != "5.0":
915 msg = "no_local, retain_as_published, and retain_handling require MQTT 5.0"
916 raise RuntimeError(msg)
917 if subscription_identifier is not None:
918 if self._version != "5.0":
919 msg = "subscription_identifier requires MQTT 5.0"
920 raise RuntimeError(msg)
921 if not 1 <= subscription_identifier <= _MAX_SUBSCRIPTION_IDENTIFIER:
922 msg = "subscription_identifier must be in 1..268435455"
923 raise ValueError(msg)
924 return Subscription(
925 self,
926 list(filters),
927 qos,
928 auto_ack,
929 receive_buffer_size,
930 no_local,
931 retain_as_published,
932 retain_handling,
933 subscription_identifier,
934 )
936 async def request(
937 self,
938 topic: str,
939 payload: bytes | str,
940 *,
941 qos: QoS = QoS.AT_MOST_ONCE,
942 timeout: float = 30.0,
943 properties: PublishProperties | None = None,
944 ) -> Message:
945 """Send a request and wait for exactly one reply (MQTT 5.0 only).
947 Publishes *payload* to *topic* with a ``response_topic`` property, then
948 waits for a message whose ``correlation_data`` matches the request.
949 Other messages on the response topic remain available to regular
950 subscriptions and do not complete this request.
952 Both ``response_topic`` and ``correlation_data`` are taken from
953 *properties* when set; otherwise they are generated automatically
954 (a unique ``_zmqtt/reply/<32 hex chars>`` topic and 16 random bytes
955 respectively).
957 Args:
958 topic: Request topic. Must not contain wildcards.
959 payload: Request body. ``str`` values are UTF-8 encoded automatically.
960 qos: QoS for the outgoing request publish.
961 timeout: Seconds to wait for the reply before raising
962 ``asyncio.TimeoutError``.
963 properties: Publish properties for the request. ``response_topic``
964 selects the reply topic (must not contain wildcards
965 [MQTT-3.3.2-14]). ``correlation_data`` is forwarded as-is to
966 the responder.
968 Returns:
969 The matching response ``Message``.
971 Raises:
972 RuntimeError: If the client is not using MQTT 5.0.
973 MQTTInvalidTopicError: If ``properties.response_topic`` contains wildcards.
974 MQTTDisconnectedError: If the request cannot start because the client
975 is disconnected, or the client is stopped while waiting.
976 ValueError: If the same response topic and correlation data are
977 already used by another active request.
978 asyncio.TimeoutError: If no matching reply arrives within *timeout*
979 seconds.
980 """
981 if self._version != "5.0":
982 msg = "request() requires MQTT 5.0"
983 raise RuntimeError(msg)
985 if properties is not None and properties.response_topic is not None:
986 reply_topic = properties.response_topic
987 validate_response_topic(reply_topic)
988 else:
989 reply_topic = f"_zmqtt/reply/{os.urandom(16).hex()}"
991 if properties is not None and properties.correlation_data is not None:
992 corr = properties.correlation_data
993 else:
994 corr = os.urandom(16)
996 if properties is not None:
997 req_props = dataclasses.replace(
998 properties,
999 response_topic=reply_topic,
1000 correlation_data=corr,
1001 )
1002 else:
1003 req_props = PublishProperties(
1004 response_topic=reply_topic,
1005 correlation_data=corr,
1006 )
1008 pending = await self._request_dispatcher.register(reply_topic, corr)
1009 try:
1010 await self.publish(topic, payload, qos=qos, properties=req_props)
1011 return await wait_for(pending.future, timeout=timeout)
1012 finally:
1013 await pending.close()
1015 async def auth(self, method: str, data: bytes | None = None) -> None:
1016 """Send an AUTH packet for enhanced authentication (MQTT 5.0 only).
1018 Args:
1019 method: Authentication method name negotiated with the broker.
1020 data: Optional authentication data to include in the packet.
1022 Raises:
1023 RuntimeError: If the client is not using MQTT 5.0.
1024 MQTTDisconnectedError: If the client is not currently connected.
1025 """
1026 if self._version != "5.0":
1027 msg = "AUTH requires MQTT 5.0"
1028 raise RuntimeError(msg)
1029 if self._protocol is None:
1030 msg = "Not connected"
1031 raise MQTTDisconnectedError(msg)
1033 props = AuthProperties(authentication_method=method, authentication_data=data)
1034 await self._protocol.send_auth(Auth(reason_code=0x18, properties=props))
1036 async def _connect(self) -> None:
1037 transport = await self._transport_factory(self._host, self._port, self._tls)
1038 connect_props = self._connect_properties
1039 protocol = MQTTProtocol(
1040 transport,
1041 SessionState(),
1042 keepalive=self._keepalive,
1043 connect_timeout=self._mqtt_connect_timeout,
1044 version=self._version,
1045 stripped_prefixes=self._stripped_prefixes,
1046 request_router=self._request_dispatcher,
1047 session_replay_buffer_size=self._session_replay_buffer_size,
1048 session_replay_timeout=self._session_replay_timeout,
1049 receive_maximum=connect_props.receive_maximum if connect_props is not None else None,
1050 maximum_packet_size=connect_props.maximum_packet_size if connect_props is not None else None,
1051 )
1052 connect_packet = Connect(
1053 client_id=self._client_id,
1054 clean_session=self._clean_session,
1055 keepalive=self._keepalive,
1056 username=self._username,
1057 password=self._password.encode() if self._password is not None else None,
1058 will=self._will,
1059 properties=connect_props,
1060 )
1061 try:
1062 connack = await protocol.connect(connect_packet)
1063 except BaseException:
1064 await transport.close()
1065 raise
1066 info = ConnectionInfo.from_connack(
1067 connect_packet,
1068 connack,
1069 version=self._version,
1070 connection_id=self._connection_id + 1,
1071 )
1072 self._protocol = protocol
1073 # Install before starting the read loop: a resumed session can deliver
1074 # PUBLISH immediately, including in the same read as CONNACK.
1075 protocol.restore_detached(self._detached_filters)
1076 self._connection_info = info
1077 self._connection_id = info.connection_id
1078 self._request_dispatcher.bind(protocol)
1080 async def _connect_with_retry(self, *, wait_before_first_attempt: bool = False) -> None:
1081 delay = self._reconnect.initial_delay
1082 if wait_before_first_attempt:
1083 await asyncio.sleep(delay)
1084 delay = min(delay * self._reconnect.backoff_factor, self._reconnect.max_delay)
1086 attempt = 0
1087 while True:
1088 try:
1089 await self._connect()
1090 except (OSError, MQTTTimeoutError, MQTTConnectError) as e: # noqa: PERF203
1091 if isinstance(e, MQTTConnectError) and not self._retries_refusal(e):
1092 raise
1093 attempt += 1
1094 max_a = self._reconnect.max_attempts
1095 if not self._reconnect.enabled or (max_a is not None and attempt >= max_a):
1096 raise
1097 log.warning("Connection failed, retrying in %.1fs", delay, exc_info=True)
1098 await asyncio.sleep(delay)
1099 delay = min(delay * self._reconnect.backoff_factor, self._reconnect.max_delay)
1100 else:
1101 return
1103 def _retries_refusal(self, refusal: MQTTConnectError) -> bool:
1104 retry_refusal = self._reconnect.retry_refusal
1105 if retry_refusal is None:
1106 return refusal.is_transient
1107 return retry_refusal(refusal)
1109 async def _run_loop(self) -> None:
1110 subs_to_restore: list[Subscription] = []
1112 while True:
1113 if self._protocol is None:
1114 msg = "Not connected yet"
1115 raise RuntimeError(msg)
1116 protocol_run_task = asyncio.create_task(self._protocol.run())
1117 try:
1118 # Run the protocol as a sub-task so _read_loop is live while we
1119 # re-subscribe. For the first connection subs_to_restore is empty,
1120 # so this collapses to the original "await protocol.run()" pattern.
1121 await self._protocol.started_event.wait()
1122 if subs_to_restore:
1123 for sub in subs_to_restore:
1124 await sub._reconnect(self._protocol)
1125 subs_to_restore = []
1126 await self._request_dispatcher.restore()
1127 await protocol_run_task
1129 except (MQTTDisconnectedError, MQTTTimeoutError, OSError):
1130 self._connection_info = None
1131 if not self._reconnect.enabled:
1132 await self._notify_connection_recovery_failed()
1133 raise
1134 # Close the dead transport to release the file descriptor.
1135 with contextlib.suppress(Exception):
1136 await self._protocol._transport.close()
1137 else:
1138 return # clean disconnect — protocol.disconnect() was called
1139 finally:
1140 self._connection_info = None
1141 protocol_run_task.cancel()
1142 await asyncio.gather(protocol_run_task, return_exceptions=True)
1144 subs_to_restore = list(self._subscriptions)
1145 log.warning("Connection lost, reconnecting...")
1146 try:
1147 await self._connect_with_retry(wait_before_first_attempt=True)
1148 except (MQTTConnectError, MQTTTimeoutError, OSError):
1149 await self._notify_connection_recovery_failed()
1150 raise
1151 log.info("Successfully reconnected")
1153 async def _notify_connection_recovery_failed(self) -> None:
1154 if self._on_connection_recovery_failed is not None:
1155 await self._on_connection_recovery_failed()
1158# No version= argument: defaults to "3.1.1", so the return type is MQTTClientV311.
1159@overload
1160def create_client(
1161 host: str,
1162 port: int = ...,
1163 *,
1164 client_id: str = ...,
1165 keepalive: int = ...,
1166 clean_session: bool = ...,
1167 username: str | None = ...,
1168 password: str | None = ...,
1169 will: Will | None = ...,
1170 tls: ssl.SSLContext | bool = ...,
1171 reconnect: ReconnectConfig | None = ...,
1172 on_connection_recovery_failed: Callable[[], Awaitable[None]] | None = ...,
1173 mqtt_connect_timeout: float = ...,
1174 transport_factory: TransportFactory | None = ...,
1175 session_expiry_interval: int = ...,
1176 max_pending_requests: int = ...,
1177 session_replay_buffer_size: int = ...,
1178 session_replay_timeout: float = ...,
1179) -> MQTTClientV311: ...
1182@overload
1183def create_client(
1184 host: str,
1185 port: int = ...,
1186 *,
1187 client_id: str = ...,
1188 keepalive: int = ...,
1189 clean_session: bool = ...,
1190 username: str | None = ...,
1191 password: str | None = ...,
1192 will: Will | None = ...,
1193 tls: ssl.SSLContext | bool = ...,
1194 reconnect: ReconnectConfig | None = ...,
1195 on_connection_recovery_failed: Callable[[], Awaitable[None]] | None = ...,
1196 mqtt_connect_timeout: float = ...,
1197 transport_factory: TransportFactory | None = ...,
1198 session_expiry_interval: int = ...,
1199 max_pending_requests: int = ...,
1200 session_replay_buffer_size: int = ...,
1201 session_replay_timeout: float = ...,
1202 version: Literal["3.1.1"],
1203) -> MQTTClientV311: ...
1206@overload
1207def create_client(
1208 host: str,
1209 port: int = ...,
1210 *,
1211 client_id: str = ...,
1212 keepalive: int = ...,
1213 clean_session: bool = ...,
1214 username: str | None = ...,
1215 password: str | None = ...,
1216 will: Will | None = ...,
1217 tls: ssl.SSLContext | bool = ...,
1218 reconnect: ReconnectConfig | None = ...,
1219 on_connection_recovery_failed: Callable[[], Awaitable[None]] | None = ...,
1220 mqtt_connect_timeout: float = ...,
1221 transport_factory: TransportFactory | None = ...,
1222 session_expiry_interval: int = ...,
1223 receive_maximum: int | None = ...,
1224 maximum_packet_size: int | None = ...,
1225 user_properties: Sequence[tuple[str, str]] = ...,
1226 request_response_information: bool | None = ...,
1227 request_problem_information: bool | None = ...,
1228 max_pending_requests: int = ...,
1229 session_replay_buffer_size: int = ...,
1230 session_replay_timeout: float = ...,
1231 version: Literal["5.0"],
1232) -> MQTTClientV5: ...
1235def create_client(
1236 host: str,
1237 port: int = 1883,
1238 *,
1239 client_id: str = "",
1240 keepalive: int = 60,
1241 clean_session: bool = True,
1242 username: str | None = None,
1243 password: str | None = None,
1244 will: Will | None = None,
1245 tls: ssl.SSLContext | bool = False,
1246 reconnect: ReconnectConfig | None = None,
1247 on_connection_recovery_failed: Callable[[], Awaitable[None]] | None = None,
1248 mqtt_connect_timeout: float = 30.0,
1249 transport_factory: TransportFactory | None = None,
1250 session_expiry_interval: int = 0,
1251 receive_maximum: int | None = None,
1252 maximum_packet_size: int | None = None,
1253 user_properties: Sequence[tuple[str, str]] = (),
1254 request_response_information: bool | None = None,
1255 request_problem_information: bool | None = None,
1256 max_pending_requests: int = 1000,
1257 session_replay_buffer_size: int = 1000,
1258 session_replay_timeout: float = 30.0,
1259 version: Literal["3.1.1", "5.0"] = "3.1.1",
1260) -> MQTTClientV311 | MQTTClientV5:
1261 """Create a version-typed MQTT client.
1263 Returns MQTTClientV311 when version="3.1.1", MQTTClientV5 when version="5.0".
1264 The concrete type is always MQTTClient; the return type is a Protocol view.
1265 MQTT 5.0-only CONNECT options are accepted only with ``version="5.0"``;
1266 see :class:`MQTTClient` for all parameters.
1267 """
1268 return MQTTClient(
1269 host,
1270 port,
1271 client_id=client_id,
1272 keepalive=keepalive,
1273 clean_session=clean_session,
1274 username=username,
1275 password=password,
1276 will=will,
1277 tls=tls,
1278 reconnect=reconnect,
1279 on_connection_recovery_failed=on_connection_recovery_failed,
1280 mqtt_connect_timeout=mqtt_connect_timeout,
1281 transport_factory=transport_factory,
1282 version=version,
1283 session_expiry_interval=session_expiry_interval,
1284 receive_maximum=receive_maximum,
1285 maximum_packet_size=maximum_packet_size,
1286 user_properties=user_properties,
1287 request_response_information=request_response_information,
1288 request_problem_information=request_problem_information,
1289 max_pending_requests=max_pending_requests,
1290 session_replay_buffer_size=session_replay_buffer_size,
1291 session_replay_timeout=session_replay_timeout,
1292 )