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
« 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
4from typing_extensions import overload, override
5from zmqtt import QoS
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
14if TYPE_CHECKING:
15 import zmqtt # ruff: ignore[unused-import]
16 from fast_depends.dependencies import Dependant
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 )
30class MQTTRegistrator(Registrator["zmqtt.Message", MQTTBrokerConfig]):
31 """Includable to MQTTBroker router."""
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": ...
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": ...
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.
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 )
131 super().subscriber(subscriber, persistent=persistent)
133 return subscriber.add_call(
134 parser_=parser or self._parser,
135 decoder_=decoder or self._decoder,
136 codec_=codec,
137 dependencies_=dependencies,
138 )
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.
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
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)
199 super().include_router(
200 router,
201 prefix=prefix,
202 dependencies=dependencies,
203 middlewares=middlewares,
204 include_in_schema=include_in_schema,
205 )
207 for m in router.config.broker_middlewares:
208 router.config._validate_middleware(m)