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

1"""High-level MQTT client — public API layer.""" 

2 

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 

12 

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 

38 

39__all__ = ( 

40 "ConnectionInfo", 

41 "MQTTClient", 

42 "MQTTClientV5", 

43 "MQTTClientV311", 

44 "ReconnectConfig", 

45 "Subscription", 

46 "Transport", 

47 "UnsubscribeResult", 

48 "create_client", 

49) 

50 

51TransportFactory = Callable[[str, int, ssl.SSLContext | bool | None], Awaitable[Transport]] 

52 

53# MQTT 5.0 §3.8.2.1.2: a subscription identifier is a variable-byte integer. 

54_MAX_SUBSCRIPTION_IDENTIFIER = 268_435_455 

55 

56_UNSUBACK_REJECTION_THRESHOLD: Final = 0x80 

57 

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 

66 

67log = logging.getLogger(__name__) 

68 

69 

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) 

88 

89 

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. 

101 

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 ) 

134 

135 

136@dataclass(frozen=True, slots=True, kw_only=True) 

137class ConnectionInfo: 

138 """Immutable snapshot of a successful CONNECT/CONNACK handshake. 

139 

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 """ 

151 

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 

159 

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 ) 

194 

195 

196@dataclass(frozen=True, slots=True, kw_only=True) 

197class UnsubscribeResult: 

198 """The broker's UNSUBACK for the filters sent in one UNSUBSCRIBE. 

199 

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 """ 

206 

207 topic_filters: tuple[str, ...] 

208 reason_codes: tuple[int, ...] 

209 properties: UnsubAckProperties | None 

210 

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) 

214 

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 } 

223 

224 @property 

225 def reason_string(self) -> str | None: 

226 return self.properties.reason_string if self.properties is not None else None 

227 

228 @property 

229 def user_properties(self) -> tuple[tuple[str, str], ...]: 

230 return self.properties.user_properties if self.properties is not None else () 

231 

232 

233@dataclass(frozen=True, slots=True, kw_only=True) 

234class ReconnectConfig: 

235 """Configuration for automatic reconnection on connection loss. 

236 

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 """ 

250 

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 

257 

258 

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) 

269 

270 

271class MQTTClientV311(Protocol): 

272 async def __aenter__(self) -> Self: ... 

273 

274 async def __aexit__(self, *exc: object) -> None: ... 

275 

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: ... 

284 

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": ... 

292 

293 @property 

294 def connection_info(self) -> ConnectionInfo: ... 

295 

296 async def connect(self) -> None: ... 

297 

298 async def disconnect(self) -> None: ... 

299 

300 async def ping(self, timeout: float = 10.0) -> float: ... 

301 

302 

303class MQTTClientV5(Protocol): 

304 """Type-safe view of MQTTClient for MQTT 5.0 connections.""" 

305 

306 async def __aenter__(self) -> Self: ... 

307 async def __aexit__(self, *exc: object) -> None: ... 

308 

309 @property 

310 def connection_info(self) -> ConnectionInfo: ... 

311 

312 async def connect(self) -> None: ... 

313 

314 async def disconnect(self) -> None: ... 

315 

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: ... 

325 

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": ... 

337 

338 async def auth(self, method: str, data: bytes | None = None) -> None: ... 

339 

340 async def ping(self, timeout: float = 10.0) -> float: ... 

341 

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": ... 

351 

352 

353class Subscription: 

354 """Async context manager for an active topic subscription. 

355 

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 """ 

360 

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 

384 

385 async def __aenter__(self) -> Self: 

386 """Register the subscription filters with the broker. 

387 

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 

400 

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)) 

404 

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 

418 

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() 

425 

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()) 

444 

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) 

450 

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. 

456 

457 Example:: 

458 

459 sub = client.subscribe("sensors/#", qos=QoS.AT_LEAST_ONCE) 

460 await sub.start() 

461 # ... later 

462 await sub.stop() 

463 

464 Raises: 

465 MQTTDisconnectedError: If the client is not currently connected. 

466 """ 

467 await self.__aenter__() 

468 

469 async def stop(self) -> UnsubscribeResult | None: 

470 """Unsubscribe from all filters and stop message delivery. 

471 

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. 

475 

476 Example:: 

477 

478 await sub.stop() 

479 

480 Returns: 

481 The broker's UNSUBACK, or ``None`` if none was received. 

482 """ 

483 return await self._stop(cancelled=False) 

484 

485 async def detach(self) -> None: 

486 """Stop local delivery without sending UNSUBSCRIBE. 

487 

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) 

503 

504 async def get_message(self) -> Message: 

505 """Wait for and return the next message from the subscription queue. 

506 

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() 

519 

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) 

533 

534 if self._detached: 

535 msg = "Subscription detached" 

536 raise MQTTDisconnectedError(msg) 

537 await self._notify_capacity_available() 

538 return message 

539 

540 async def _notify_capacity_available(self) -> None: 

541 protocol = self._client._protocol 

542 if protocol is not None: 

543 await protocol.inbound.drain() 

544 

545 def __aiter__(self) -> AsyncIterator[Message]: 

546 """Return self as the async iterator.""" 

547 return self 

548 

549 async def __anext__(self) -> Message: 

550 """Return the next message, suspending until one is available.""" 

551 return await self.get_message() 

552 

553 

554class MQTTClient: 

555 """Asyncio MQTT client with automatic reconnection. 

556 

557 Use as an async context manager. subscribe() returns a Subscription that 

558 is itself an async context manager. 

559 """ 

560 

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. 

590 

591 The client must be used as an async context manager to establish the 

592 connection:: 

593 

594 async with MQTTClient("broker.example.com") as client: 

595 await client.publish("sensors/temp", "22.5") 

596 

597 Prefer :func:`create_client` for version-typed access. 

598 

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``. 

660 

661 CONNECT properties are validated here and sent on every connection 

662 attempt, including reconnects. 

663 

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 

716 

717 @property 

718 def connection_info(self) -> ConnectionInfo: 

719 """Current successful handshake. 

720 

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. 

724 

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 

733 

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 

741 

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) 

751 

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() 

765 

766 async def connect(self) -> None: 

767 """Connect to the broker and start the background run loop. 

768 

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. 

772 

773 Example:: 

774 

775 client = create_client("broker.example.com") 

776 await client.connect() 

777 # ... use the client 

778 await client.disconnect() 

779 

780 Raises: 

781 MQTTConnectError: If the broker refuses the connection. 

782 """ 

783 await self.__aenter__() 

784 

785 async def disconnect(self) -> None: 

786 """Disconnect cleanly and stop the background run loop. 

787 

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) 

793 

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*. 

804 

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. 

811 

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 ) 

840 

841 async def ping(self, timeout: float = 10.0) -> float: 

842 """Send a PINGREQ and return the round-trip time in seconds. 

843 

844 Args: 

845 timeout: Seconds to wait for PINGRESP before raising 

846 :exc:`MQTTTimeoutError`. 

847 

848 Returns: 

849 RTT in seconds. 

850 

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) 

859 

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. 

872 

873 The returned object must be used as an async context manager to activate 

874 the subscription and unsubscribe on exit:: 

875 

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) 

879 

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``. 

903 

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 ) 

935 

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). 

946 

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. 

951 

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). 

956 

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. 

967 

968 Returns: 

969 The matching response ``Message``. 

970 

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) 

984 

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()}" 

990 

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) 

995 

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 ) 

1007 

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() 

1014 

1015 async def auth(self, method: str, data: bytes | None = None) -> None: 

1016 """Send an AUTH packet for enhanced authentication (MQTT 5.0 only). 

1017 

1018 Args: 

1019 method: Authentication method name negotiated with the broker. 

1020 data: Optional authentication data to include in the packet. 

1021 

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) 

1032 

1033 props = AuthProperties(authentication_method=method, authentication_data=data) 

1034 await self._protocol.send_auth(Auth(reason_code=0x18, properties=props)) 

1035 

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) 

1079 

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) 

1085 

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 

1102 

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) 

1108 

1109 async def _run_loop(self) -> None: 

1110 subs_to_restore: list[Subscription] = [] 

1111 

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 

1128 

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) 

1143 

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") 

1152 

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() 

1156 

1157 

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: ... 

1180 

1181 

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: ... 

1204 

1205 

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: ... 

1233 

1234 

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. 

1262 

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 )