Coverage for faststream/redis/schemas/stream_sub.py: 98%
54 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
1import warnings
2from copy import deepcopy
3from typing import Any, Generic, Literal, overload
5from typing_extensions import Self, TypeVar
7from faststream._internal.proto import NameRequired
8from faststream.exceptions import SetupError
9from faststream.redis._compat import REDIS_V710, _REDIS_VERSION
11# Carries `batch` in the type, so `subscriber(stream=StreamSub(..., batch=True))`
12# resolves to the batch subscriber instead of a Union of both.
13BatchT_co = TypeVar("BatchT_co", bound=bool, default=bool, covariant=True)
14BatchT = TypeVar("BatchT", bound=bool, default=bool)
17class StreamSub(NameRequired, Generic[BatchT_co]):
18 """A class to represent a Redis Stream subscriber.
20 Args:
21 batch:
22 Whether to consume messages in batches or not.
23 max_records:
24 Number of messages to consume as one batch.
25 consumer:
26 The consumer unique name
28 https://redis.io/docs/latest/develop/tools/insight/tutorials/insight-stream-consumer/#run-the-consumer
29 group:
30 The name of consumer group
31 last_id:
32 An Entry ID, which uses to pick up from where it left off after it is restarted.
33 maxlen:
34 Redis Stream maxlen publish option. Remove eldest message if maxlen exceeded.
36 https://redis.io/docs/latest/develop/data-types/streams/#capped-streams
37 name:
38 The original Redis Stream name.
39 no_ack:
40 If True, to enable the XREADGROUP NOACK subcommand.
42 https://redis.io/docs/latest/commands/xreadgroup/#differences-between-xread-and-xreadgroup
43 polling_interval:
44 Polling interval in milliseconds.
45 min_idle_time:
46 Minimum idle time in milliseconds for a message to be eligible for claiming via XAUTOCLAIM.
47 Messages that have been pending (unacknowledged) for at least this duration can be
48 reclaimed by this consumer. Only applicable when using consumer groups.
50 https://redis.io/docs/latest/commands/xautoclaim/
51 declare:
52 Whether to create the stream when creating a consumer group.
53 claim_min_idle_time:
54 Redis 8.4+ `XREADGROUP CLAIM` option (milliseconds). When set, each read
55 also claims messages of the same group that have been pending for at least
56 this duration, so a single subscriber consumes new messages and recovers
57 abandoned ones in one command. Claimed entries arrive first; per-entry
58 metadata is exposed via the `idle_times` / `delivery_counts` keys of the
59 raw message. Requires redis-py 7.1.0+ and Redis server 8.4+ (older servers
60 reject the CLAIM option). Mutually exclusive with `min_idle_time` and
61 `no_ack`.
63 https://redis.io/docs/latest/commands/xreadgroup/#the-claim-option
64 """
66 __slots__ = (
67 "batch",
68 "claim_min_idle_time",
69 "consumer",
70 "declare",
71 "group",
72 "last_id",
73 "max_records",
74 "maxlen",
75 "min_idle_time",
76 "no_ack",
77 "polling_interval",
78 )
80 @overload
81 def __init__(
82 self: "StreamSub[Literal[False]]",
83 stream: str,
84 polling_interval: int | None = None,
85 group: str | None = None,
86 consumer: str | None = None,
87 batch: Literal[False] = False,
88 no_ack: bool = False,
89 last_id: str | None = None,
90 maxlen: int | None = None,
91 max_records: int | None = None,
92 min_idle_time: int | None = None,
93 declare: bool = True,
94 claim_min_idle_time: int | None = None,
95 ) -> None: ...
97 @overload
98 def __init__(
99 self: "StreamSub[Literal[True]]",
100 stream: str,
101 polling_interval: int | None = None,
102 group: str | None = None,
103 consumer: str | None = None,
104 batch: Literal[True] = ...,
105 no_ack: bool = False,
106 last_id: str | None = None,
107 maxlen: int | None = None,
108 max_records: int | None = None,
109 min_idle_time: int | None = None,
110 declare: bool = True,
111 claim_min_idle_time: int | None = None,
112 ) -> None: ...
114 @overload
115 def __init__(
116 self: "StreamSub[bool]",
117 stream: str,
118 polling_interval: int | None = None,
119 group: str | None = None,
120 consumer: str | None = None,
121 batch: bool = ...,
122 no_ack: bool = False,
123 last_id: str | None = None,
124 maxlen: int | None = None,
125 max_records: int | None = None,
126 min_idle_time: int | None = None,
127 declare: bool = True,
128 claim_min_idle_time: int | None = None,
129 ) -> None: ...
131 def __init__(
132 self,
133 stream: str,
134 polling_interval: int | None = None,
135 group: str | None = None,
136 consumer: str | None = None,
137 batch: bool = False,
138 no_ack: bool = False,
139 last_id: str | None = None,
140 maxlen: int | None = None,
141 max_records: int | None = None,
142 min_idle_time: int | None = None,
143 declare: bool = True,
144 claim_min_idle_time: int | None = None,
145 ) -> None:
146 if (group and not consumer) or (not group and consumer):
147 msg = "You should specify `group` and `consumer` both"
148 raise SetupError(msg)
150 if not declare and not group:
151 warnings.warn(
152 message="`declare` has no effect without consumer group",
153 category=RuntimeWarning,
154 stacklevel=1,
155 )
157 if last_id is None:
158 last_id = ">" if group and consumer else "$"
160 if group and consumer and last_id != ">":
161 if polling_interval: 161 ↛ 162line 161 didn't jump to line 162 because the condition on line 161 was never true
162 warnings.warn(
163 message="`polling_interval` is not supported by consumer group with last_id other than `>`",
164 category=RuntimeWarning,
165 stacklevel=1,
166 )
168 if no_ack:
169 warnings.warn(
170 message="`no_ack` is not supported by consumer group with last_id other than `>`",
171 category=RuntimeWarning,
172 stacklevel=1,
173 )
175 if claim_min_idle_time is not None:
176 if not REDIS_V710:
177 msg = (
178 "`claim_min_idle_time` requires redis-py 7.1.0 or newer "
179 f"(installed: {_REDIS_VERSION})"
180 )
181 raise SetupError(msg)
183 if min_idle_time is not None:
184 msg = (
185 "`claim_min_idle_time` (XREADGROUP CLAIM) and `min_idle_time` "
186 "(XAUTOCLAIM) are mutually exclusive"
187 )
188 raise SetupError(msg)
190 if no_ack:
191 msg = (
192 "`claim_min_idle_time` with `no_ack` causes infinite "
193 "redelivery: claimed entries stay in the PEL and are "
194 "never acknowledged"
195 )
196 raise SetupError(msg)
198 if not group:
199 msg = "`claim_min_idle_time` requires `group` and `consumer`"
200 raise SetupError(msg)
202 if last_id != ">":
203 msg = (
204 "`claim_min_idle_time` requires last_id `>`: Redis ignores "
205 "the CLAIM option for any other id"
206 )
207 raise SetupError(msg)
209 super().__init__(stream)
211 self.group = group
212 self.consumer = consumer
213 self.declare = declare
214 self.polling_interval = polling_interval or 100
215 self.batch = batch
216 self.no_ack = no_ack
217 self.last_id = last_id
218 self.maxlen = maxlen
219 self.max_records = max_records
220 self.min_idle_time = min_idle_time
221 self.claim_min_idle_time = claim_min_idle_time
223 @overload
224 @classmethod
225 def validate(
226 cls, value: "str | StreamSub[BatchT]", **kwargs: Any
227 ) -> "StreamSub[BatchT]": ...
229 @overload
230 @classmethod
231 def validate(cls, value: None, **kwargs: Any) -> None: ...
233 @classmethod
234 def validate(
235 cls, value: "str | StreamSub[Any] | None", **kwargs: Any
236 ) -> "StreamSub[Any] | None":
237 # `Self` would resolve to the non-batch parametrization of the first `__init__`
238 if isinstance(value, str):
239 return cls(value, **kwargs)
240 return value
242 def add_prefix(self, prefix: str) -> Self:
243 new_stream = deepcopy(self)
244 new_stream.name = f"{prefix}{new_stream.name}"
245 return new_stream