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
« 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
7from typing_extensions import ParamSpec, Self, deprecated
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
16if TYPE_CHECKING:
17 from types import TracebackType
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
31catch_startup_validation_error: Callable[[], AbstractAsyncContextManager[Any, Any]]
33try:
34 from pydantic import ValidationError as PValidation
36 from faststream.exceptions import StartupValidationError
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)
52 raise StartupValidationError(
53 missed_fields=missed_fields,
54 invalid_fields=invalid_fields,
55 ) from e
57except ImportError: # pragma: no cover
58 catch_startup_validation_error = nullcontext
61P_HookParams = ParamSpec("P_HookParams")
62T_HookReturn = TypeVar("T_HookReturn")
65class StartAbleApplication:
66 __slots__ = (
67 "brokers",
68 "config",
69 "schema",
70 )
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 )
84 @property
85 def context(self) -> "ContextRepo":
86 return self.config.context
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]] = []
98 self.schema: SpecificationFactory = specification or AsyncAPI()
100 for br in brokers:
101 self.add_broker(br)
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()
108 @property
109 def broker(self) -> Optional["BrokerUsecase[Any, Any, Any]"]:
110 return self.brokers[0] if self.brokers else None
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.
118 Useful then you create/init broker in `on_startup` hook.
119 """
120 self.add_broker(broker)
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)
127 self.brokers.append(broker)
128 self.schema.add_broker(broker)
129 broker._update_fd_config(self.config)
132class Application(StartAbleApplication):
133 """Unslotted on purpose: an application object is the user's own.
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 """
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
153 super().__init__(*brokers, config=config, specification=specification)
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 ]
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()
198 async def __aenter__(self) -> Self:
199 await self.start()
200 return self
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()
210 @abstractmethod
211 def exit(self) -> None:
212 """Stop application manually."""
213 ...
215 @abstractmethod
216 async def run(
217 self,
218 log_level: int,
219 run_extra_options: dict[str, "SettingField"] | None = None,
220 ) -> None: ...
222 # Startup
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 {}))
233 self.running = True
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()
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)
252 yield # ruff: ignore[fallible-context-manager]
254 for func in self._after_startup_calling:
255 await func()
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 )
268 yield # ruff: ignore[fallible-context-manager]
270 self._log(
271 log_level,
272 "FastStream app started successfully! To exit, press CTRL+C",
273 )
275 # Shutdown
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()
282 self.running = False
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()
290 @asynccontextmanager
291 async def _shutdown_hooks_context(self) -> AsyncGenerator[None, None]:
292 for func in self._on_shutdown_calling:
293 await func()
295 yield # ruff: ignore[fallible-context-manager]
297 for func in self._after_shutdown_calling:
298 await func()
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...")
308 yield # ruff: ignore[fallible-context-manager]
310 self._log(log_level, "FastStream app shut down gracefully.")
312 # Service methods
314 def _log(self, level: int, message: str) -> None:
315 if self.logger is not None:
316 self.logger.log(level, message)
318 # Hooks
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.
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
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
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
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