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 _context: Context 

140 

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

142 

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

144 

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

146 

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

148 

149 

150class FilteringBoundLogger(BindableLogger, Protocol): 

151 """ 

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

153 

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

155 

156 .. versionadded:: 20.2.0 

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

158 .. versionadded:: 22.2.0 

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

160 .. versionchanged:: 22.3.0 

161 String interpolation is only attempted if positional arguments are 

162 passed. 

163 """ 

164 

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

166 """ 

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

168 

169 .. versionadded:: 22.1.0 

170 """ 

171 

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

173 """ 

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

175 

176 .. versionadded:: 22.1.0 

177 """ 

178 

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

180 """ 

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

182 

183 .. versionadded:: 22.1.0 

184 """ 

185 

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

187 """ 

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

189 

190 .. versionadded:: 22.1.0 

191 """ 

192 

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

194 """ 

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

196 

197 .. versionadded:: 25.1.0 

198 """ 

199 

200 def get_effective_level(self) -> int: 

201 """ 

202 Return the effective level of the logger. 

203 

204 .. versionadded:: 25.1.0 

205 """ 

206 

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

208 """ 

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

210 """ 

211 

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

213 """ 

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

215 

216 ..versionadded:: 22.2.0 

217 """ 

218 

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

220 """ 

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

222 """ 

223 

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

225 """ 

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

227 

228 ..versionadded:: 22.2.0 

229 """ 

230 

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

232 """ 

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

234 """ 

235 

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

237 """ 

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

239 

240 ..versionadded:: 22.2.0 

241 """ 

242 

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

244 """ 

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

246 """ 

247 

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

249 """ 

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

251 

252 ..versionadded:: 22.2.0 

253 """ 

254 

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

256 """ 

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

258 """ 

259 

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

261 """ 

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

263 

264 ..versionadded:: 22.2.0 

265 """ 

266 

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

268 """ 

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

270 """ 

271 

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

273 """ 

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

275 """ 

276 

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

278 """ 

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

280 

281 ..versionadded:: 22.2.0 

282 """ 

283 

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

285 """ 

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

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

288 """ 

289 

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

291 """ 

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

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

294 

295 ..versionadded:: 22.2.0 

296 """ 

297 

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

299 """ 

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

301 """ 

302 

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

304 """ 

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

306 

307 ..versionadded:: 22.2.0 

308 """ 

309 

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

311 """ 

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

313 """ 

314 

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

316 """ 

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

318 """ 

319 

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

321 """ 

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

323 """ 

324 

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

326 """ 

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

328 """