Coverage for faststream/kafka/publisher/usecase.py: 97%
65 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 Callable, Iterable, Mapping
2from typing import TYPE_CHECKING, Any, Literal, Union, cast, overload
4from typing_extensions import override
6from faststream._internal.endpoint.publisher import PublisherUsecase
7from faststream._internal.kafka import KafkaCallAssertions
8from faststream._internal.types import P_HandlerParams, T_HandlerReturn
9from faststream.kafka.call_wrapper import KafkaHandlerCallWrapper
10from faststream.kafka.response import KafkaPublishCommand
11from faststream.response.publish_type import PublishType
13if TYPE_CHECKING:
14 import asyncio
16 from aiokafka.structs import RecordMetadata
18 from faststream._internal.basic_types import SendableMessage
19 from faststream._internal.endpoint.publisher import PublisherSpecification
20 from faststream._internal.types import PublisherMiddleware
21 from faststream.kafka.message import KafkaMessage
22 from faststream.kafka.types import KafkaSendableMessage
23 from faststream.response.response import PublishCommand
25 from .config import KafkaPublisherConfig
26 from .producer import AioKafkaFastProducer
29class LogicPublisher(KafkaCallAssertions, PublisherUsecase):
30 """A class to publish messages to a Kafka topic."""
32 __slots__ = (
33 "_topic",
34 "headers",
35 "partition",
36 "reply_to",
37 )
39 _call_wrapper_class = KafkaHandlerCallWrapper
40 _read_field = KafkaHandlerCallWrapper._read_field
42 def __init__(
43 self,
44 config: "KafkaPublisherConfig",
45 specification: "PublisherSpecification[Any, Any]",
46 ) -> None:
47 super().__init__(config, specification)
49 self._topic = config.topic
50 self.partition = config.partition
51 self.reply_to = config.reply_to
52 self.headers = dict(config.headers or {})
54 @override
55 def __call__(
56 self,
57 func: Callable[P_HandlerParams, T_HandlerReturn],
58 ) -> "KafkaHandlerCallWrapper[P_HandlerParams, T_HandlerReturn]":
59 # The base builds the wrapper from `_call_wrapper_class`; this only narrows the name
60 return cast(
61 "KafkaHandlerCallWrapper[P_HandlerParams, T_HandlerReturn]",
62 super().__call__(func),
63 )
65 @property
66 def topic(self) -> str:
67 return f"{self._outer_config.prefix}{self._topic}"
69 @override
70 async def request(
71 self,
72 message: "SendableMessage",
73 topic: str = "",
74 *,
75 key: bytes | Any | None = None,
76 partition: int | None = None,
77 timestamp_ms: int | None = None,
78 headers: Mapping[str, str | bytes | None] | None = None,
79 correlation_id: str | None = None,
80 timeout: float = 0.5,
81 ) -> "KafkaMessage":
82 """Send a request message to Kafka topic.
84 Args:
85 message: Message body to send.
86 topic: Topic where the message will be published.
87 key: A key to associate with the message. Can be used to
88 determine which partition to send the message to. If partition
89 is `None` (and producer's partitioner config is left as default),
90 then messages with the same key will be delivered to the same
91 partition (but if key is `None`, partition is chosen randomly).
92 Must be type `bytes`, or be serializable to bytes via configured
93 `key_serializer`.
94 partition: Specify a partition. If not set, the partition will be
95 selected using the configured `partitioner`.
96 timestamp_ms: Epoch milliseconds (from Jan 1 1970 UTC) to use as
97 the message timestamp. Defaults to current time.
98 headers: Message headers to store metainformation.
99 correlation_id: Manual message **correlation_id** setter.
100 **correlation_id** is a useful option to trace messages.
101 timeout: Timeout to send RPC request.
103 Returns:
104 KafkaMessage: The response message.
105 """
106 cmd = KafkaPublishCommand(
107 message,
108 topic=topic or self.topic,
109 key=key,
110 partition=partition if partition is not None else self.partition,
111 headers=self.headers | dict(headers or {}),
112 correlation_id=correlation_id or self._outer_config.id_generator(),
113 timestamp_ms=timestamp_ms,
114 timeout=timeout,
115 _publish_type=PublishType.REQUEST,
116 )
118 msg: KafkaMessage = await self._basic_request(
119 cmd,
120 producer=self._outer_config.producer,
121 )
122 return msg
124 async def flush(self) -> None:
125 producer = cast("AioKafkaFastProducer", self._outer_config.producer)
126 await producer.flush()
129class DefaultPublisher(LogicPublisher):
130 __slots__ = ()
132 def __init__(
133 self,
134 config: "KafkaPublisherConfig",
135 specification: "PublisherSpecification[Any, Any]",
136 ) -> None:
137 super().__init__(config, specification)
139 self.key = config.key
141 @overload
142 async def publish(
143 self,
144 message: "SendableMessage",
145 topic: str = "",
146 *,
147 key: bytes | Any | None = None,
148 partition: int | None = None,
149 timestamp_ms: int | None = None,
150 headers: Mapping[str, str | bytes | None] | None = None,
151 correlation_id: str | None = None,
152 reply_to: str = "",
153 no_confirm: Literal[False] = False,
154 ) -> "RecordMetadata": ...
156 @overload
157 async def publish(
158 self,
159 message: "SendableMessage",
160 topic: str = "",
161 *,
162 key: bytes | Any | None = None,
163 partition: int | None = None,
164 timestamp_ms: int | None = None,
165 headers: Mapping[str, str | bytes | None] | None = None,
166 correlation_id: str | None = None,
167 reply_to: str = "",
168 no_confirm: Literal[True] = ...,
169 ) -> "asyncio.Future[RecordMetadata]": ...
171 @overload
172 async def publish(
173 self,
174 message: "SendableMessage",
175 topic: str = "",
176 *,
177 key: bytes | Any | None = None,
178 partition: int | None = None,
179 timestamp_ms: int | None = None,
180 headers: Mapping[str, str | bytes | None] | None = None,
181 correlation_id: str | None = None,
182 reply_to: str = "",
183 no_confirm: bool = False,
184 ) -> Union["asyncio.Future[RecordMetadata]", "RecordMetadata"]: ...
186 @override
187 async def publish(
188 self,
189 message: "SendableMessage",
190 topic: str = "",
191 *,
192 key: bytes | Any | None = None,
193 partition: int | None = None,
194 timestamp_ms: int | None = None,
195 headers: Mapping[str, str | bytes | None] | None = None,
196 correlation_id: str | None = None,
197 reply_to: str = "",
198 no_confirm: bool = False,
199 ) -> Union["asyncio.Future[RecordMetadata]", "RecordMetadata"]:
200 """Publishes a message to Kafka.
202 Args:
203 message:
204 Message body to send.
205 topic:
206 Topic where the message will be published.
207 key:
208 A key to associate with the message. Can be used to
209 determine which partition to send the message to. If partition
210 is `None` (and producer's partitioner config is left as default),
211 then messages with the same key will be delivered to the same
212 partition (but if key is `None`, partition is chosen randomly).
213 Must be type `bytes`, or be serializable to bytes via configured
214 `key_serializer`
215 partition:
216 Specify a partition. If not set, the partition will be
217 selected using the configured `partitioner`
218 timestamp_ms:
219 Epoch milliseconds (from Jan 1 1970 UTC) to use as
220 the message timestamp. Defaults to current time.
221 headers:
222 Message headers to store metainformation.
223 correlation_id:
224 Manual message **correlation_id** setter.
225 **correlation_id** is a useful option to trace messages.
226 reply_to:
227 Reply message topic name to send response.
228 no_confirm:
229 Do not wait for Kafka publish confirmation.
231 Returns:
232 `asyncio.Future[RecordMetadata]` if no_confirm = True.
233 `RecordMetadata` if no_confirm = False.
234 """
235 cmd = KafkaPublishCommand(
236 message,
237 topic=topic or self.topic,
238 key=key or self.key,
239 partition=partition if partition is not None else self.partition,
240 reply_to=reply_to or self.reply_to,
241 headers=self.headers | dict(headers or {}),
242 correlation_id=correlation_id or self._outer_config.id_generator(),
243 timestamp_ms=timestamp_ms,
244 no_confirm=no_confirm,
245 _publish_type=PublishType.PUBLISH,
246 )
247 return await self._basic_publish(
248 cmd,
249 producer=self._outer_config.producer,
250 _extra_middlewares=(),
251 )
253 @override
254 async def _publish(
255 self,
256 cmd: Union["PublishCommand", "KafkaPublishCommand"],
257 *,
258 _extra_middlewares: Iterable["PublisherMiddleware"],
259 ) -> None:
260 """This method should be called in subscriber flow only."""
261 cmd = KafkaPublishCommand.from_cmd(cmd)
263 cmd.destination = self.topic
264 cmd.add_headers(self.headers, override=False)
265 cmd.reply_to = cmd.reply_to or self.reply_to
267 cmd.partition = cmd.partition if cmd.partition is not None else self.partition
268 cmd.key = cmd.key or self.key
270 await self._basic_publish(
271 cmd,
272 producer=self._outer_config.producer,
273 _extra_middlewares=_extra_middlewares,
274 )
276 @override
277 async def request(
278 self,
279 message: "SendableMessage",
280 topic: str = "",
281 *,
282 key: bytes | Any | None = None,
283 partition: int | None = None,
284 timestamp_ms: int | None = None,
285 headers: Mapping[str, str | bytes | None] | None = None,
286 correlation_id: str | None = None,
287 timeout: float = 0.5,
288 ) -> "KafkaMessage":
289 """Send a request message and wait for a response.
291 Args:
292 message: Message body to send.
293 topic: Topic where the message will be published.
294 key: A key to associate with the message. Can be used to
295 determine which partition to send the message to. If partition
296 is `None` (and producer's partitioner config is left as default),
297 then messages with the same key will be delivered to the same
298 partition (but if key is `None`, partition is chosen randomly).
299 Must be type `bytes`, or be serializable to bytes via configured
300 `key_serializer`.
301 partition: Specify a partition. If not set, the partition will be
302 selected using the configured `partitioner`.
303 timestamp_ms: Epoch milliseconds (from Jan 1 1970 UTC) to use as
304 the message timestamp. Defaults to current time.
305 headers: Message headers to store metainformation.
306 correlation_id: Manual message **correlation_id** setter.
307 **correlation_id** is a useful option to trace messages.
308 timeout: Timeout to send RPC request.
310 Returns:
311 The response message.
312 """
313 return await super().request(
314 message,
315 topic=topic,
316 key=key or self.key,
317 partition=partition,
318 timestamp_ms=timestamp_ms,
319 headers=headers,
320 correlation_id=correlation_id,
321 timeout=timeout,
322 )
325class BatchPublisher(LogicPublisher):
326 __slots__ = ()
328 def __init__(
329 self,
330 config: "KafkaPublisherConfig",
331 specification: "PublisherSpecification[Any, Any]",
332 ) -> None:
333 super().__init__(config, specification)
334 self.key = config.key
336 @overload
337 async def publish(
338 self,
339 *messages: "KafkaSendableMessage",
340 topic: str = "",
341 key: bytes | Any | None = None,
342 partition: int | None = None,
343 timestamp_ms: int | None = None,
344 headers: Mapping[str, str | bytes | None] | None = None,
345 reply_to: str = "",
346 correlation_id: str | None = None,
347 no_confirm: Literal[False] = False,
348 ) -> "RecordMetadata": ...
350 @overload
351 async def publish(
352 self,
353 *messages: "KafkaSendableMessage",
354 topic: str = "",
355 key: bytes | Any | None = None,
356 partition: int | None = None,
357 timestamp_ms: int | None = None,
358 headers: Mapping[str, str | bytes | None] | None = None,
359 reply_to: str = "",
360 correlation_id: str | None = None,
361 no_confirm: Literal[True] = ...,
362 ) -> "asyncio.Future[RecordMetadata]": ...
364 @overload
365 async def publish(
366 self,
367 *messages: "KafkaSendableMessage",
368 topic: str = "",
369 key: bytes | Any | None = None,
370 partition: int | None = None,
371 timestamp_ms: int | None = None,
372 headers: Mapping[str, str | bytes | None] | None = None,
373 reply_to: str = "",
374 correlation_id: str | None = None,
375 no_confirm: bool = False,
376 ) -> Union["asyncio.Future[RecordMetadata]", "RecordMetadata"]: ...
378 @override
379 async def publish(
380 self,
381 *messages: "KafkaSendableMessage",
382 topic: str = "",
383 key: bytes | Any | None = None,
384 partition: int | None = None,
385 timestamp_ms: int | None = None,
386 headers: Mapping[str, str | bytes | None] | None = None,
387 reply_to: str = "",
388 correlation_id: str | None = None,
389 no_confirm: bool = False,
390 ) -> Union["asyncio.Future[RecordMetadata]", "RecordMetadata"]:
391 """Publish a message batch as a single request to broker.
393 Args:
394 *messages:
395 Messages bodies to send.
396 topic:
397 Topic where the message will be published.
398 key:
399 A single key to associate with every message in this batch. If a
400 partition is not specified and the producer uses the default
401 partitioner, messages with the same key will be routed to the
402 same partition. Must be bytes or serializable to bytes via the
403 configured key serializer. If omitted, falls back to the
404 publisher's default key (if configured).
405 partition:
406 Specify a partition. If not set, the partition will be
407 selected using the configured `partitioner`
408 timestamp_ms:
409 Epoch milliseconds (from Jan 1 1970 UTC) to use as
410 the message timestamp. Defaults to current time.
411 headers:
412 Message headers to store metainformation.
413 reply_to:
414 Reply message topic name to send response.
415 correlation_id:
416 Manual message **correlation_id** setter.
417 **correlation_id** is a useful option to trace messages.
418 no_confirm:
419 Do not wait for Kafka publish confirmation.
421 Returns:
422 `asyncio.Future[RecordMetadata]` if no_confirm = True.
423 `RecordMetadata` if no_confirm = False.
424 """
425 cmd = KafkaPublishCommand(
426 *messages,
427 key=key or self.key,
428 topic=topic or self.topic,
429 partition=partition if partition is not None else self.partition,
430 reply_to=reply_to or self.reply_to,
431 headers=self.headers | dict(headers or {}),
432 correlation_id=correlation_id or self._outer_config.id_generator(),
433 timestamp_ms=timestamp_ms,
434 no_confirm=no_confirm,
435 _publish_type=PublishType.PUBLISH,
436 )
438 return await self._basic_publish_batch(
439 cmd,
440 producer=self._outer_config.producer,
441 _extra_middlewares=(),
442 )
444 @override
445 async def _publish(
446 self,
447 cmd: Union["PublishCommand", "KafkaPublishCommand"],
448 *,
449 _extra_middlewares: Iterable["PublisherMiddleware"],
450 ) -> None:
451 """This method should be called in subscriber flow only."""
452 cmd = KafkaPublishCommand.from_cmd(cmd, batch=True)
454 if not cmd.batch_bodies:
455 # Match the non-batch publisher: an empty result is one empty message,
456 # not a batch of zero, which no broker can express (see issue #3056).
457 cmd.batch_bodies = (b"",)
459 cmd.destination = self.topic
460 cmd.add_headers(self.headers, override=False)
461 cmd.reply_to = cmd.reply_to or self.reply_to
463 cmd.partition = cmd.partition if cmd.partition is not None else self.partition
464 cmd.key = cmd.key or self.key
466 await self._basic_publish_batch(
467 cmd,
468 producer=self._outer_config.producer,
469 _extra_middlewares=_extra_middlewares,
470 )