Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/structlog/typing.py: 97%

1# SPDX-License-Identifier: MIT OR Apache-2.0 

2# This file is dual licensed under the terms of the Apache License, Version 

3# 2.0, and the MIT License. See the LICENSE file in the root of this 

4# repository for complete details. 

5 

6""" 

7Type information used throughout *structlog*. 

8 

9For now, they are considered provisional. Especially `BindableLogger` will 

10probably change to something more elegant. 

11 

12.. versionadded:: 22.2.0 

13""" 

14 

15from __future__ import annotations 

16 

17import sys 

18 

19from types import TracebackType 

20from typing import ( 

21 Any, 

22 Callable, 

23 Dict, 

24 Mapping, 

25 MutableMapping, 

26 Optional, 

27 Protocol, 

28 TextIO, 

29 Tuple, 

30 Type, 

31 Union, 

32 runtime_checkable, 

33) 

34 

35 

36if sys.version_info >= (3, 11): 

37 from typing import Self 

38else: 

39 from typing_extensions import Self 

40 

41 

42WrappedLogger = Any 

43""" 

44A logger that is wrapped by a bound logger and is ultimately responsible for 

45the output of the log entries. 

46 

47*structlog* makes *no* assumptions about it. 

48 

49.. versionadded:: 20.2.0 

50""" 

51 

52 

53Context = Union[Dict[str, Any], Dict[Any, Any]] 

54""" 

55A dict-like context carrier. 

56 

57.. versionadded:: 20.2.0 

58""" 

59 

60 

61EventDict = MutableMapping[str, Any] 

62""" 

63An event dictionary as it is passed into processors. 

64 

65It's created by copying the configured `Context` but doesn't need to support 

66copy itself. 

67 

68.. versionadded:: 20.2.0 

69""" 

70 

71ProcessorReturnValue = Union[ 

72 Mapping[str, Any], str, bytes, bytearray, Tuple[Any, ...] 

73] 

74""" 

75A value returned by a processor. 

76""" 

77 

78Processor = Callable[[WrappedLogger, str, EventDict], ProcessorReturnValue] 

79""" 

80A callable that is part of the processor chain. 

81 

82See :doc:`processors`. 

83 

84.. versionadded:: 20.2.0 

85""" 

86 

87ExcInfo = Tuple[Type[BaseException], BaseException, Optional[TracebackType]] 

88""" 

89An exception info tuple as returned by `sys.exc_info`. 

90 

91.. versionadded:: 20.2.0 

92""" 

93 

94 

95ExceptionRenderer = Callable[[TextIO, ExcInfo], None] 

96""" 

97A callable that pretty-prints an `ExcInfo` into a file-like object. 

98 

99Used by `structlog.dev.ConsoleRenderer`. 

100 

101.. versionadded:: 21.2.0 

102""" 

103 

104 

105@runtime_checkable 

106class ExceptionTransformer(Protocol): 

107 """ 

108 **Protocol:** A callable that transforms an `ExcInfo` into another 

109 datastructure. 

110 

111 The result should be something that your renderer can work with, e.g., a 

112 ``str`` or a JSON-serializable ``dict``. 

113 

114 Used by `structlog.processors.format_exc_info()` and 

115 `structlog.processors.ExceptionPrettyPrinter`. 

116 

117 Args: 

118 exc_info: Is the exception tuple to format 

119 

120 Returns: 

121 Anything that can be rendered by the last processor in your chain, for 

122 example, a string or a JSON-serializable structure. 

123 

124 .. versionadded:: 22.1.0 

125 """ 

126 

127 def __call__(self, exc_info: ExcInfo) -> Any: ... 

128 

129 

130@runtime_checkable 

131class BindableLogger(Protocol): 

132 """ 

133 **Protocol**: Methods shared among all bound loggers and that are relied on 

134 by *structlog*. 

135 

136 .. versionadded:: 20.2.0 

137 """ 

138 

139 @property 

140 def _context(self) -> Context: ... 

141 

142 def bind(self, **new_values: Any) -> Self: ... 

143 

144 def unbind(self, *keys: str) -> Self: ... 

145 

146 def try_unbind(self, *keys: str) -> Self: ... 

147 

148 def new(self, **new_values: Any) -> Self: ... 

149 

150 

151class FilteringBoundLogger(BindableLogger, Protocol): 

152 """ 

153 **Protocol**: A `BindableLogger` that filters by a level. 

154 

155 The only way to instantiate one is using `make_filtering_bound_logger`. 

156 

157 .. versionadded:: 20.2.0 

158 .. versionadded:: 22.2.0 String interpolation using positional arguments. 

159 .. versionadded:: 22.2.0 

160 Async variants ``alog()``, ``adebug()``, ``ainfo()``, and so forth. 

161 .. versionchanged:: 22.3.0 

162 String interpolation is only attempted if positional arguments are 

163 passed. 

164 .. versionadded:: 25.5.0 

165 String interpolation using dictionary-based arguments if the first and 

166 only argument is a mapping. 

167 

168 """ 

169 

170 def bind(self, **new_values: Any) -> FilteringBoundLogger: 

171 """ 

172 Return a new logger with *new_values* added to the existing ones. 

173 

174 .. versionadded:: 22.1.0 

175 """ 

176 

177 def unbind(self, *keys: str) -> FilteringBoundLogger: 

178 """ 

179 Return a new logger with *keys* removed from the context. 

180 

181 .. versionadded:: 22.1.0 

182 """ 

183 

184 def try_unbind(self, *keys: str) -> FilteringBoundLogger: 

185 """ 

186 Like :meth:`unbind`, but best effort: missing keys are ignored. 

187 

188 .. versionadded:: 22.1.0 

189 """ 

190 

191 def new(self, **new_values: Any) -> FilteringBoundLogger: 

192 """ 

193 Clear context and binds *initial_values* using `bind`. 

194 

195 .. versionadded:: 22.1.0 

196 """ 

197 

198 def is_enabled_for(self, level: int) -> bool: 

199 """ 

200 Check whether the logger is enabled for *level*. 

201 

202 .. versionadded:: 25.1.0 

203 """ 

204 

205 def get_effective_level(self) -> int: 

206 """ 

207 Return the effective level of the logger. 

208 

209 .. versionadded:: 25.1.0 

210 """ 

211 

212 def debug(self, event: str, *args: Any, **kw: Any) -> Any: 

213 """ 

214 Log ``event % args`` with **kw** at **debug** level. 

215 """ 

216 

217 async def adebug(self, event: str, *args: Any, **kw: Any) -> Any: 

218 """ 

219 Log ``event % args`` with **kw** at **debug** level. 

220 

221 ..versionadded:: 22.2.0 

222 """ 

223 

224 def info(self, event: str, *args: Any, **kw: Any) -> Any: 

225 """ 

226 Log ``event % args`` with **kw** at **info** level. 

227 """ 

228 

229 async def ainfo(self, event: str, *args: Any, **kw: Any) -> Any: 

230 """ 

231 Log ``event % args`` with **kw** at **info** level. 

232 

233 ..versionadded:: 22.2.0 

234 """ 

235 

236 def warning(self, event: str, *args: Any, **kw: Any) -> Any: 

237 """ 

238 Log ``event % args`` with **kw** at **warn** level. 

239 """ 

240 

241 async def awarning(self, event: str, *args: Any, **kw: Any) -> Any: 

242 """ 

243 Log ``event % args`` with **kw** at **warn** level. 

244 

245 ..versionadded:: 22.2.0 

246 """ 

247 

248 def warn(self, event: str, *args: Any, **kw: Any) -> Any: 

249 """ 

250 Log ``event % args`` with **kw** at **warn** level. 

251 """ 

252 

253 async def awarn(self, event: str, *args: Any, **kw: Any) -> Any: 

254 """ 

255 Log ``event % args`` with **kw** at **warn** level. 

256 

257 ..versionadded:: 22.2.0 

258 """ 

259 

260 def error(self, event: str, *args: Any, **kw: Any) -> Any: 

261 """ 

262 Log ``event % args`` with **kw** at **error** level. 

263 """ 

264 

265 async def aerror(self, event: str, *args: Any, **kw: Any) -> Any: 

266 """ 

267 Log ``event % args`` with **kw** at **error** level. 

268 

269 ..versionadded:: 22.2.0 

270 """ 

271 

272 def err(self, event: str, *args: Any, **kw: Any) -> Any: 

273 """ 

274 Log ``event % args`` with **kw** at **error** level. 

275 """ 

276 

277 def fatal(self, event: str, *args: Any, **kw: Any) -> Any: 

278 """ 

279 Log ``event % args`` with **kw** at **critical** level. 

280 """ 

281 

282 async def afatal(self, event: str, *args: Any, **kw: Any) -> Any: 

283 """ 

284 Log ``event % args`` with **kw** at **critical** level. 

285 

286 ..versionadded:: 22.2.0 

287 """ 

288 

289 def exception(self, event: str, *args: Any, **kw: Any) -> Any: 

290 """ 

291 Log ``event % args`` with **kw** at **error** level and ensure that 

292 ``exc_info`` is set in the event dictionary. 

293 """ 

294 

295 async def aexception(self, event: str, *args: Any, **kw: Any) -> Any: 

296 """ 

297 Log ``event % args`` with **kw** at **error** level and ensure that 

298 ``exc_info`` is set in the event dictionary. 

299 

300 ..versionadded:: 22.2.0 

301 """ 

302 

303 def critical(self, event: str, *args: Any, **kw: Any) -> Any: 

304 """ 

305 Log ``event % args`` with **kw** at **critical** level. 

306 """ 

307 

308 async def acritical(self, event: str, *args: Any, **kw: Any) -> Any: 

309 """ 

310 Log ``event % args`` with **kw** at **critical** level. 

311 

312 ..versionadded:: 22.2.0 

313 """ 

314 

315 def msg(self, event: str, *args: Any, **kw: Any) -> Any: 

316 """ 

317 Log ``event % args`` with **kw** at **info** level. 

318 """ 

319 

320 async def amsg(self, event: str, *args: Any, **kw: Any) -> Any: 

321 """ 

322 Log ``event % args`` with **kw** at **info** level. 

323 """ 

324 

325 def log(self, level: int, event: str, *args: Any, **kw: Any) -> Any: 

326 """ 

327 Log ``event % args`` with **kw** at *level*. 

328 """ 

329 

330 async def alog(self, level: int, event: str, *args: Any, **kw: Any) -> Any: 

331 """ 

332 Log ``event % args`` with **kw** at *level*. 

333 """