Coverage for src / zmqtt / errors.py: 100%

39 statements  

« prev     ^ index     » next       coverage.py v7.13.4, created at 2026-11-12 08:49 +0000

1from zmqtt._internal.packets.properties import ConnAckProperties 

2 

3 

4class MQTTError(Exception): 

5 """Base class for all zmqtt exceptions.""" 

6 

7 

8# CONNACK codes for a refusal the broker may lift on its own, such as while it 

9# boots or sheds load. MQTT 3.1.1 codes are below 0x80 and MQTT 5 codes are 

10# 0x80 and above, so one set covers both versions. 0x9C (Use another server) 

11# and 0x9D (Server moved) are left out: MQTT 5 section 4.11 says to switch 

12# server rather than retry the same one. 

13_TRANSIENT_CONNACK_CODES = frozenset( 

14 { 

15 0x03, # MQTT 3.1.1: Server unavailable 

16 0x88, # MQTT 5: Server unavailable 

17 0x89, # MQTT 5: Server busy 

18 0x97, # MQTT 5: Quota exceeded 

19 0x9F, # MQTT 5: Connection rate exceeded 

20 }, 

21) 

22 

23 

24class MQTTConnectError(MQTTError): 

25 """CONNACK returned a non-zero return code.""" 

26 

27 def __init__(self, return_code: int, *, properties: ConnAckProperties | None = None) -> None: 

28 self.return_code = return_code 

29 self.properties = properties 

30 self.reason_string = properties.reason_string if properties is not None else None 

31 self.user_properties = properties.user_properties if properties is not None else () 

32 self.server_reference = properties.server_reference if properties is not None else None 

33 super().__init__(f"Connection refused: return code {return_code}") 

34 

35 @property 

36 def is_transient(self) -> bool: 

37 """Whether the broker may accept a later attempt without a config change. 

38 

39 True for "server unavailable", "server busy", "quota exceeded" and 

40 "connection rate exceeded"; false for refusals such as bad credentials. 

41 """ 

42 return self.return_code in _TRANSIENT_CONNACK_CODES 

43 

44 

45class MQTTProtocolError(MQTTError): 

46 """Unexpected or malformed packet received.""" 

47 

48 

49class MQTTQoSExceededError(MQTTError): 

50 """A PUBLISH requested a QoS higher than the server's advertised Maximum QoS. 

51 

52 Raised locally, before the packet is sent — the server would otherwise 

53 have to reject or drop it (MQTT 5.0 §3.2.2.3.4). 

54 """ 

55 

56 def __init__(self, requested: int, maximum: int) -> None: 

57 self.requested_qos = requested 

58 self.maximum_qos = maximum 

59 super().__init__(f"Requested QoS {requested} exceeds the server's Maximum QoS {maximum}") 

60 

61 

62class MQTTRetainNotAvailableError(MQTTError): 

63 """A retained PUBLISH was requested but the server does not support retained messages. 

64 

65 Raised locally, before the packet is sent, when CONNACK set Retain Available 

66 to 0 (MQTT 5.0 §3.2.2.3.5). The connection stays open. 

67 """ 

68 

69 def __init__(self) -> None: 

70 super().__init__("The server does not support retained messages (Retain Available is 0)") 

71 

72 

73class MQTTDisconnectedError(MQTTError): 

74 """Connection lost unexpectedly.""" 

75 

76 

77class MQTTTimeoutError(MQTTError): 

78 """An MQTT operation did not complete within the allotted time.""" 

79 

80 

81class MQTTSubscribeError(MQTTError): 

82 """The broker rejected one or more filters in a SUBSCRIBE (SUBACK >= 0x80). 

83 

84 Most commonly an authorization denial: without this error the subscription 

85 looks successful and silently never receives anything. 

86 """ 

87 

88 def __init__(self, failures: dict[str, int]) -> None: 

89 self.failures = failures 

90 rendered = ", ".join(f"{f!r} (0x{code:02X})" for f, code in failures.items()) 

91 super().__init__(f"Broker rejected subscription: {rendered}") 

92 

93 

94class MQTTPublishError(MQTTError): 

95 """The broker rejected a QoS 1/2 publish. 

96 

97 *reason_name* is the spec's name for *reason_code* (``None`` for a code 

98 zmqtt does not recognize). *reason_string* is the broker's optional Reason 

99 String property. 

100 """ 

101 

102 def __init__( 

103 self, 

104 reason_code: int, 

105 reason_name: str | None, 

106 reason_string: str | None, 

107 ) -> None: 

108 self.reason_code = reason_code 

109 self.reason_name = reason_name 

110 self.reason_string = reason_string 

111 named = f"0x{reason_code:02X} {reason_name}" if reason_name else f"0x{reason_code:02X}" 

112 detail = f": {reason_string}" if reason_string else "" 

113 super().__init__(f"Broker rejected publish ({named}){detail}") 

114 

115 

116class MQTTInvalidTopicError(MQTTError): 

117 """Topic string or topic filter failed MQTT validation."""