Coverage for faststream/mqtt/broker/registrator.py: 87%

19 statements  

« prev     ^ index     » next       coverage.py v7.17.3, created at 2026-11-17 21:20 +0000

1from collections.abc import Sequence 

2from typing import TYPE_CHECKING, Any, Literal, Optional, cast 

3 

4from typing_extensions import overload, override 

5from zmqtt import QoS 

6 

7from faststream._internal.broker.registrator import Registrator 

8from faststream._internal.constants import EMPTY 

9from faststream.middlewares import AckPolicy 

10from faststream.mqtt.broker.config import MQTTBrokerConfig 

11from faststream.mqtt.publisher.factory import create_publisher 

12from faststream.mqtt.subscriber.factory import create_subscriber 

13 

14if TYPE_CHECKING: 

15 import zmqtt # ruff: ignore[unused-import] 

16 from fast_depends.dependencies import Dependant 

17 

18 from faststream._internal.parser import CodecProto 

19 from faststream._internal.types import ( 

20 BrokerMiddleware, 

21 CustomCallable, 

22 ) 

23 from faststream.mqtt.publisher.usecase import MQTTPublisher 

24 from faststream.mqtt.subscriber.usecase import ( 

25 MQTTConcurrentSubscriber, 

26 MQTTDefaultSubscriber, 

27 ) 

28 

29 

30class MQTTRegistrator(Registrator["zmqtt.Message", MQTTBrokerConfig]): 

31 """Includable to MQTTBroker router.""" 

32 

33 @overload # type: ignore[override] 

34 def subscriber( 

35 self, 

36 topic: str, 

37 *, 

38 qos: QoS = QoS.AT_MOST_ONCE, 

39 shared: str | None = None, 

40 # broker arguments 

41 ack_policy: AckPolicy = EMPTY, 

42 no_reply: bool = False, 

43 dependencies: Sequence["Dependant"] = (), 

44 parser: Optional["CustomCallable"] = None, 

45 decoder: Optional["CustomCallable"] = None, 

46 codec: Optional["CodecProto"] = None, 

47 max_workers: Literal[1] = 1, 

48 persistent: bool = True, 

49 # AsyncAPI information 

50 title: str | None = None, 

51 description: str | None = None, 

52 include_in_schema: bool = True, 

53 ) -> "MQTTDefaultSubscriber": ... 

54 

55 @overload 

56 def subscriber( 

57 self, 

58 topic: str, 

59 *, 

60 qos: QoS = QoS.AT_MOST_ONCE, 

61 shared: str | None = None, 

62 # broker arguments 

63 ack_policy: AckPolicy = EMPTY, 

64 no_reply: bool = False, 

65 dependencies: Sequence["Dependant"] = (), 

66 parser: Optional["CustomCallable"] = None, 

67 decoder: Optional["CustomCallable"] = None, 

68 codec: Optional["CodecProto"] = None, 

69 max_workers: int = ..., 

70 persistent: bool = True, 

71 # AsyncAPI information 

72 title: str | None = None, 

73 description: str | None = None, 

74 include_in_schema: bool = True, 

75 ) -> "MQTTConcurrentSubscriber": ... 

76 

77 @override 

78 def subscriber( 

79 self, 

80 topic: str, 

81 *, 

82 qos: QoS = QoS.AT_MOST_ONCE, 

83 shared: str | None = None, 

84 # broker arguments 

85 ack_policy: AckPolicy = EMPTY, 

86 no_reply: bool = False, 

87 dependencies: Sequence["Dependant"] = (), 

88 parser: Optional["CustomCallable"] = None, 

89 decoder: Optional["CustomCallable"] = None, 

90 codec: Optional["CodecProto"] = None, 

91 max_workers: int = 1, 

92 persistent: bool = True, 

93 # AsyncAPI information 

94 title: str | None = None, 

95 description: str | None = None, 

96 include_in_schema: bool = True, 

97 ) -> "MQTTDefaultSubscriber | MQTTConcurrentSubscriber": 

98 """Subscribe a handler to an MQTT topic. 

99 

100 Args: 

101 topic: MQTT topic filter. Wildcards ``+`` (single level) and 

102 ``#`` (multi-level) are supported. 

103 qos: QoS level for the subscription (0, 1, or 2). 

104 shared: Optional shared subscription group name. When set, 

105 subscribes as ``$share/<group>/<topic>``. 

106 ack_policy: Acknowledgement policy for message processing. 

107 no_reply: Whether to disable FastStream RPC / reply-to responses. 

108 dependencies: Dependencies list to apply to the subscriber. 

109 parser: Custom parser to map raw messages to FastStream ones. 

110 decoder: Function to decode FastStream message bytes to Python objects. 

111 codec: Custom codec object. 

112 max_workers: Number of workers to process messages concurrently. 

113 persistent: Whether to retain the subscriber across broker restarts. 

114 title: AsyncAPI subscriber object title. 

115 description: AsyncAPI subscriber object description. 

116 include_in_schema: Whether to include operation in AsyncAPI schema. 

117 """ 

118 subscriber = create_subscriber( 

119 topic=topic, 

120 qos=qos, 

121 shared=shared, 

122 ack_policy=ack_policy, 

123 no_reply=no_reply, 

124 config=cast("MQTTBrokerConfig", self.config), 

125 max_workers=max_workers, 

126 title_=title, 

127 description_=description, 

128 include_in_schema=include_in_schema, 

129 ) 

130 

131 super().subscriber(subscriber, persistent=persistent) 

132 

133 return subscriber.add_call( 

134 parser_=parser or self._parser, 

135 decoder_=decoder or self._decoder, 

136 codec_=codec, 

137 dependencies_=dependencies, 

138 ) 

139 

140 @override 

141 def publisher( # type: ignore[override] 

142 self, 

143 topic: str, 

144 *, 

145 qos: QoS = QoS.AT_MOST_ONCE, 

146 retain: bool = False, 

147 headers: dict[str, str] | None = None, 

148 persistent: bool = True, 

149 # AsyncAPI information 

150 title: str | None = None, 

151 description: str | None = None, 

152 schema: Any | None = None, 

153 include_in_schema: bool = True, 

154 ) -> "MQTTPublisher": 

155 """Create a persistent publisher object for the given MQTT topic. 

156 

157 Args: 

158 topic: MQTT topic to publish to. Must not contain wildcards. 

159 qos: QoS level for published messages (0, 1, or 2). 

160 retain: Whether the broker should retain the last message. 

161 headers: Default headers to include in every published message. 

162 persistent: Whether to retain the publisher across broker restarts. 

163 title: AsyncAPI publisher object title. 

164 description: AsyncAPI publisher object description. 

165 schema: AsyncAPI publishing message type. 

166 include_in_schema: Whether to include operation in AsyncAPI schema. 

167 """ 

168 publisher = create_publisher( 

169 topic=topic, 

170 qos=qos, 

171 retain=retain, 

172 headers=headers, 

173 broker_config=cast("MQTTBrokerConfig", self.config), 

174 title_=title, 

175 description_=description, 

176 schema_=schema, 

177 include_in_schema=include_in_schema, 

178 ) 

179 super().publisher(publisher, persistent=persistent) 

180 return publisher 

181 

182 @override 

183 def include_router( 

184 self, 

185 router: "MQTTRegistrator", # type: ignore[override] 

186 *, 

187 prefix: str = "", 

188 dependencies: Sequence["Dependant"] = (), 

189 middlewares: Sequence["BrokerMiddleware[Any, Any]"] = (), 

190 include_in_schema: bool | None = None, 

191 ) -> None: 

192 if not isinstance(router, MQTTRegistrator): 192 ↛ 193line 192 didn't jump to line 193 because the condition on line 192 was never true

193 msg = ( 

194 f"Router must be an instance of MQTTRegistrator, " 

195 f"got {type(router).__name__} instead." 

196 ) 

197 raise TypeError(msg) 

198 

199 super().include_router( 

200 router, 

201 prefix=prefix, 

202 dependencies=dependencies, 

203 middlewares=middlewares, 

204 include_in_schema=include_in_schema, 

205 ) 

206 

207 for m in router.config.broker_middlewares: 

208 router.config._validate_middleware(m)