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 collections.abc import Callable, Mapping, MutableMapping 

20from types import TracebackType 

21from typing import ( 

22 Any, 

23 Protocol, 

24 TextIO, 

25 TypeAlias, 

26 runtime_checkable, 

27) 

28 

29 

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

31 from typing import Self 

32else: 

33 from typing_extensions import Self 

34 

35 

36WrappedLogger: TypeAlias = Any 

37""" 

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

39the output of the log entries. 

40 

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

42 

43.. versionadded:: 20.2.0 

44""" 

45 

46 

47Context: TypeAlias = dict[Any, Any] 

48""" 

49A dict-like context carrier. 

50 

51.. versionadded:: 20.2.0 

52""" 

53 

54 

55EventDict: TypeAlias = MutableMapping[str, Any] 

56""" 

57An event dictionary as it is passed into processors. 

58 

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

60copy itself. 

61 

62.. versionadded:: 20.2.0 

63""" 

64 

65ProcessorReturnValue: TypeAlias = ( 

66 Mapping[str, Any] | str | bytes | bytearray | tuple[Any, ...] 

67) 

68""" 

69A value returned by a processor. 

70""" 

71 

72Processor: TypeAlias = Callable[ 

73 [WrappedLogger, str, EventDict], ProcessorReturnValue 

74] 

75""" 

76A callable that is part of the processor chain. 

77 

78See :doc:`processors`. 

79 

80.. versionadded:: 20.2.0 

81""" 

82 

83ExcInfo: TypeAlias = tuple[ 

84 type[BaseException], BaseException, TracebackType | None 

85] 

86""" 

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

88 

89.. versionadded:: 20.2.0 

90""" 

91 

92 

93ExceptionRenderer: TypeAlias = Callable[[TextIO, ExcInfo], None] 

94""" 

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

96 

97Used by `structlog.dev.ConsoleRenderer`. 

98 

99.. versionadded:: 21.2.0 

100""" 

101 

102 

103@runtime_checkable 

104class ExceptionTransformer(Protocol): 

105 """ 

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

107 datastructure. 

108 

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

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

111 

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

113 `structlog.processors.ExceptionPrettyPrinter`. 

114 

115 Args: 

116 exc_info: Is the exception tuple to format 

117 

118 Returns: 

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

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

121 

122 .. versionadded:: 22.1.0 

123 """ 

124 

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

126 

127 

128@runtime_checkable 

129class BindableLogger(Protocol): 

130 """ 

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

132 by *structlog*. 

133 

134 .. versionadded:: 20.2.0 

135 """ 

136 

137 @property 

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

139 

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

141 

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

143 

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

145 

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

147 

148 

149class FilteringBoundLogger(BindableLogger, Protocol): 

150 """ 

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

152 

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

154 

155 .. versionadded:: 20.2.0 

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

157 .. versionadded:: 22.2.0 

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

159 .. versionchanged:: 22.3.0 

160 String interpolation is only attempted if positional arguments are 

161 passed. 

162 .. versionadded:: 25.5.0 

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

164 only argument is a mapping. 

165 

166 """ 

167 

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

169 """ 

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

171 

172 .. versionadded:: 22.1.0 

173 """ 

174 

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

176 """ 

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

178 

179 .. versionadded:: 22.1.0 

180 """ 

181 

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

183 """ 

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

185 

186 .. versionadded:: 22.1.0 

187 """ 

188 

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

190 """ 

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

192 

193 .. versionadded:: 22.1.0 

194 """ 

195 

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

197 """ 

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

199 

200 .. versionadded:: 25.1.0 

201 """ 

202 

203 def get_effective_level(self) -> int: 

204 """ 

205 Return the effective level of the logger. 

206 

207 .. versionadded:: 25.1.0 

208 """ 

209 

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

211 """ 

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

213 """ 

214 

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

216 """ 

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

218 

219 ..versionadded:: 22.2.0 

220 """ 

221 

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

223 """ 

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

225 """ 

226 

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

228 """ 

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

230 

231 ..versionadded:: 22.2.0 

232 """ 

233 

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

235 """ 

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

237 """ 

238 

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

240 """ 

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

242 

243 ..versionadded:: 22.2.0 

244 """ 

245 

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

247 """ 

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

249 """ 

250 

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

252 """ 

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

254 

255 ..versionadded:: 22.2.0 

256 """ 

257 

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

259 """ 

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

261 """ 

262 

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

264 """ 

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

266 

267 ..versionadded:: 22.2.0 

268 """ 

269 

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

271 """ 

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

273 """ 

274 

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

276 """ 

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

278 """ 

279 

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

281 """ 

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

283 

284 ..versionadded:: 22.2.0 

285 """ 

286 

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

288 """ 

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

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

291 """ 

292 

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

294 """ 

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

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

297 

298 ..versionadded:: 22.2.0 

299 """ 

300 

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

302 """ 

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

304 """ 

305 

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

307 """ 

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

309 

310 ..versionadded:: 22.2.0 

311 """ 

312 

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

314 """ 

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

316 """ 

317 

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

319 """ 

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

321 """ 

322 

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

324 """ 

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

326 """ 

327 

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

329 """ 

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

331 """