Coverage for faststream/_internal/application.py: 90%

113 statements  

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

1import logging 

2from abc import abstractmethod 

3from collections.abc import AsyncGenerator, Callable, Sequence 

4from contextlib import AbstractAsyncContextManager, asynccontextmanager, nullcontext 

5from typing import TYPE_CHECKING, Any, Optional, TypeVar 

6 

7from typing_extensions import ParamSpec, Self, deprecated 

8 

9from faststream._internal.di import FastDependsConfig 

10from faststream._internal.logger import logger 

11from faststream._internal.utils import apply_types 

12from faststream._internal.utils.functions import to_async 

13from faststream.exceptions import SetupError 

14from faststream.specification import AsyncAPI 

15 

16if TYPE_CHECKING: 

17 from types import TracebackType 

18 

19 from faststream._internal.basic_types import ( 

20 AnyCallable, 

21 AsyncFunc, 

22 Lifespan, 

23 LoggerProto, 

24 SettingField, 

25 ) 

26 from faststream._internal.broker import BrokerUsecase 

27 from faststream._internal.context import ContextRepo 

28 from faststream.specification.base import SpecificationFactory 

29 

30 

31catch_startup_validation_error: Callable[[], AbstractAsyncContextManager[Any, Any]] 

32 

33try: 

34 from pydantic import ValidationError as PValidation 

35 

36 from faststream.exceptions import StartupValidationError 

37 

38 @asynccontextmanager 

39 async def catch_startup_validation_error() -> AsyncGenerator[None, None]: 

40 try: 

41 yield 

42 except PValidation as e: 

43 missed_fields = [] 

44 invalid_fields = [] 

45 for x in e.errors(): 

46 location = str(x["loc"][0]) 

47 if x["type"] == "missing": 

48 missed_fields.append(location) 

49 else: 

50 invalid_fields.append(location) 

51 

52 raise StartupValidationError( 

53 missed_fields=missed_fields, 

54 invalid_fields=invalid_fields, 

55 ) from e 

56 

57except ImportError: # pragma: no cover 

58 catch_startup_validation_error = nullcontext 

59 

60 

61P_HookParams = ParamSpec("P_HookParams") 

62T_HookReturn = TypeVar("T_HookReturn") 

63 

64 

65class StartAbleApplication: 

66 __slots__ = ( 

67 "brokers", 

68 "config", 

69 "schema", 

70 ) 

71 

72 def __init__( 

73 self, 

74 *brokers: "BrokerUsecase[Any, Any, Any]", 

75 specification: Optional["SpecificationFactory"] = None, 

76 config: Optional["FastDependsConfig"] = None, 

77 ) -> None: 

78 self._init_setupable_( 

79 *brokers, 

80 config=config, 

81 specification=specification, 

82 ) 

83 

84 @property 

85 def context(self) -> "ContextRepo": 

86 return self.config.context 

87 

88 def _init_setupable_( # ruff: ignore[bad-dunder-method-name] 

89 self, 

90 *brokers: "BrokerUsecase[Any, Any, Any]", 

91 specification: Optional["SpecificationFactory"] = None, 

92 config: Optional["FastDependsConfig"] = None, 

93 ) -> None: 

94 self.config = config or FastDependsConfig() 

95 self.config.context.set_global("app", self) 

96 self.brokers: list[BrokerUsecase[Any, Any, Any]] = [] 

97 

98 self.schema: SpecificationFactory = specification or AsyncAPI() 

99 

100 for br in brokers: 

101 self.add_broker(br) 

102 

103 async def _start_broker(self) -> None: 

104 assert self.brokers, "You should setup a broker" 

105 for b in self.brokers: 

106 await b.start() 

107 

108 @property 

109 def broker(self) -> Optional["BrokerUsecase[Any, Any, Any]"]: 

110 return self.brokers[0] if self.brokers else None 

111 

112 @deprecated( 

113 "This method is deprecated and will be removed in 0.8.0 Use `add_broker` instead." 

114 ) 

115 def set_broker(self, broker: "BrokerUsecase[Any, Any, Any]") -> None: 

116 """Set already existed App object broker. 

117 

118 Useful then you create/init broker in `on_startup` hook. 

119 """ 

120 self.add_broker(broker) 

121 

122 def add_broker(self, broker: "BrokerUsecase[Any, Any, Any]") -> None: 

123 if broker in self.brokers: 123 ↛ 124line 123 didn't jump to line 124 because the condition on line 123 was never true

124 msg = f"Broker {broker} is already added" 

125 raise SetupError(msg) 

126 

127 self.brokers.append(broker) 

128 self.schema.add_broker(broker) 

129 broker._update_fd_config(self.config) 

130 

131 

132class Application(StartAbleApplication): 

133 """Unslotted on purpose: an application object is the user's own. 

134 

135 One exists per process, so slots would save nothing, and user code and our own 

136 CLI tests assign to it (`app.run` is patched in `tests/cli/test_logs.py`). 

137 """ 

138 

139 def __init__( 

140 self, 

141 *brokers: "BrokerUsecase[Any, Any, Any]", 

142 config: Optional["FastDependsConfig"] = None, 

143 logger: Optional["LoggerProto"] = logger, 

144 lifespan: Optional["Lifespan"] = None, 

145 on_startup: Sequence["AnyCallable"] = (), 

146 after_startup: Sequence["AnyCallable"] = (), 

147 on_shutdown: Sequence["AnyCallable"] = (), 

148 after_shutdown: Sequence["AnyCallable"] = (), 

149 specification: Optional["SpecificationFactory"] = None, 

150 ) -> None: 

151 self.logger = logger 

152 

153 super().__init__(*brokers, config=config, specification=specification) 

154 

155 self._on_startup_calling: list[AsyncFunc] = [ 

156 apply_types( 

157 to_async(x), 

158 serializer_cls=self.config._serializer, 

159 context__=self.context, 

160 ) 

161 for x in on_startup 

162 ] 

163 self._after_startup_calling: list[AsyncFunc] = [ 

164 apply_types( 

165 to_async(x), 

166 serializer_cls=self.config._serializer, 

167 context__=self.context, 

168 ) 

169 for x in after_startup 

170 ] 

171 self._on_shutdown_calling: list[AsyncFunc] = [ 

172 apply_types( 

173 to_async(x), 

174 serializer_cls=self.config._serializer, 

175 context__=self.context, 

176 ) 

177 for x in on_shutdown 

178 ] 

179 self._after_shutdown_calling: list[AsyncFunc] = [ 

180 apply_types( 

181 to_async(x), 

182 serializer_cls=self.config._serializer, 

183 context__=self.context, 

184 ) 

185 for x in after_shutdown 

186 ] 

187 

188 if lifespan: 

189 self.lifespan_context = apply_types( 

190 func=lifespan, 

191 serializer_cls=self.config._serializer, 

192 cast_result=False, 

193 context__=self.context, 

194 ) 

195 else: 

196 self.lifespan_context = lambda *_, **__: nullcontext() 

197 

198 async def __aenter__(self) -> Self: 

199 await self.start() 

200 return self 

201 

202 async def __aexit__( 

203 self, 

204 exc_type: type[BaseException] | None = None, 

205 exc_val: BaseException | None = None, 

206 exc_tb: Optional["TracebackType"] = None, 

207 ) -> None: 

208 await self.stop() 

209 

210 @abstractmethod 

211 def exit(self) -> None: 

212 """Stop application manually.""" 

213 ... 

214 

215 @abstractmethod 

216 async def run( 

217 self, 

218 log_level: int, 

219 run_extra_options: dict[str, "SettingField"] | None = None, 

220 ) -> None: ... 

221 

222 # Startup 

223 

224 async def _startup( 

225 self, 

226 log_level: int = logging.INFO, 

227 run_extra_options: dict[str, "SettingField"] | None = None, 

228 ) -> None: 

229 """Private method calls `start` with logging.""" 

230 async with self._startup_logging(log_level=log_level): 

231 await self.start(**(run_extra_options or {})) 

232 

233 self.running = True 

234 

235 async def start( 

236 self, 

237 **run_extra_options: "SettingField", 

238 ) -> None: 

239 """Executes startup hooks and start broker.""" 

240 async with self._start_hooks_context(**run_extra_options): 

241 await self._start_broker() 

242 

243 @asynccontextmanager 

244 async def _start_hooks_context( 

245 self, 

246 **run_extra_options: "SettingField", 

247 ) -> AsyncGenerator[None, None]: 

248 async with catch_startup_validation_error(): 

249 for func in self._on_startup_calling: 

250 await func(**run_extra_options) 

251 

252 yield # ruff: ignore[fallible-context-manager] 

253 

254 for func in self._after_startup_calling: 

255 await func() 

256 

257 @asynccontextmanager 

258 async def _startup_logging( 

259 self, 

260 log_level: int = logging.INFO, 

261 ) -> AsyncGenerator[None, None]: 

262 """Separated startup logging.""" 

263 self._log( 

264 log_level, 

265 "FastStream app starting...", 

266 ) 

267 

268 yield # ruff: ignore[fallible-context-manager] 

269 

270 self._log( 

271 log_level, 

272 "FastStream app started successfully! To exit, press CTRL+C", 

273 ) 

274 

275 # Shutdown 

276 

277 async def _shutdown(self, log_level: int = logging.INFO) -> None: 

278 """Private method calls `stop` with logging.""" 

279 async with self._shutdown_logging(log_level=log_level): 

280 await self.stop() 

281 

282 self.running = False 

283 

284 async def stop(self) -> None: 

285 """Executes shutdown hooks and stop broker.""" 

286 async with self._shutdown_hooks_context(): 

287 for broker in self.brokers: 

288 await broker.stop() 

289 

290 @asynccontextmanager 

291 async def _shutdown_hooks_context(self) -> AsyncGenerator[None, None]: 

292 for func in self._on_shutdown_calling: 

293 await func() 

294 

295 yield # ruff: ignore[fallible-context-manager] 

296 

297 for func in self._after_shutdown_calling: 

298 await func() 

299 

300 @asynccontextmanager 

301 async def _shutdown_logging( 

302 self, 

303 log_level: int = logging.INFO, 

304 ) -> AsyncGenerator[None, None]: 

305 """Separated startup logging.""" 

306 self._log(log_level, "FastStream app shutting down...") 

307 

308 yield # ruff: ignore[fallible-context-manager] 

309 

310 self._log(log_level, "FastStream app shut down gracefully.") 

311 

312 # Service methods 

313 

314 def _log(self, level: int, message: str) -> None: 

315 if self.logger is not None: 

316 self.logger.log(level, message) 

317 

318 # Hooks 

319 

320 def on_startup( 

321 self, 

322 func: Callable[P_HookParams, T_HookReturn], 

323 ) -> Callable[P_HookParams, T_HookReturn]: 

324 """Add hook running BEFORE broker connected. 

325 

326 This hook also takes an extra CLI options as a kwargs. 

327 """ 

328 self._on_startup_calling.append( 

329 apply_types( 

330 to_async(func), 

331 serializer_cls=self.config._serializer, 

332 context__=self.context, 

333 ), 

334 ) 

335 return func 

336 

337 def on_shutdown( 

338 self, 

339 func: Callable[P_HookParams, T_HookReturn], 

340 ) -> Callable[P_HookParams, T_HookReturn]: 

341 """Add hook running BEFORE broker disconnected.""" 

342 self._on_shutdown_calling.append( 

343 apply_types( 

344 to_async(func), 

345 serializer_cls=self.config._serializer, 

346 context__=self.context, 

347 ), 

348 ) 

349 return func 

350 

351 def after_startup( 

352 self, 

353 func: Callable[P_HookParams, T_HookReturn], 

354 ) -> Callable[P_HookParams, T_HookReturn]: 

355 """Add hook running AFTER broker connected.""" 

356 self._after_startup_calling.append( 

357 apply_types( 

358 to_async(func), 

359 serializer_cls=self.config._serializer, 

360 context__=self.context, 

361 ), 

362 ) 

363 return func 

364 

365 def after_shutdown( 

366 self, 

367 func: Callable[P_HookParams, T_HookReturn], 

368 ) -> Callable[P_HookParams, T_HookReturn]: 

369 """Add hook running AFTER broker disconnected.""" 

370 self._after_shutdown_calling.append( 

371 apply_types( 

372 to_async(func), 

373 serializer_cls=self.config._serializer, 

374 context__=self.context, 

375 ), 

376 ) 

377 return func