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

1import warnings 

2from copy import deepcopy 

3from typing import Any, Generic, Literal, overload 

4 

5from typing_extensions import Self, TypeVar 

6 

7from faststream._internal.proto import NameRequired 

8from faststream.exceptions import SetupError 

9from faststream.redis._compat import REDIS_V710, _REDIS_VERSION 

10 

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) 

15 

16 

17class StreamSub(NameRequired, Generic[BatchT_co]): 

18 """A class to represent a Redis Stream subscriber. 

19 

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 

27 

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. 

35 

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. 

41 

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. 

49 

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`. 

62 

63 https://redis.io/docs/latest/commands/xreadgroup/#the-claim-option 

64 """ 

65 

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 ) 

79 

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: ... 

96 

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: ... 

113 

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: ... 

130 

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) 

149 

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 ) 

156 

157 if last_id is None: 

158 last_id = ">" if group and consumer else "$" 

159 

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 ) 

167 

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 ) 

174 

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) 

182 

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) 

189 

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) 

197 

198 if not group: 

199 msg = "`claim_min_idle_time` requires `group` and `consumer`" 

200 raise SetupError(msg) 

201 

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) 

208 

209 super().__init__(stream) 

210 

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 

222 

223 @overload 

224 @classmethod 

225 def validate( 

226 cls, value: "str | StreamSub[BatchT]", **kwargs: Any 

227 ) -> "StreamSub[BatchT]": ... 

228 

229 @overload 

230 @classmethod 

231 def validate(cls, value: None, **kwargs: Any) -> None: ... 

232 

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 

241 

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