Coverage for pyTooling/Common/__init__.py: 91%

1# ==================================================================================================================== # 

2# _____ _ _ ____ # 

3# _ __ _ |_ _|__ ___ | (_)_ __ __ _ / ___|___ _ __ ___ _ __ ___ ___ _ __ # 

4# | '_ \| | | || |/ _ \ / _ \| | | '_ \ / _` || | / _ \| '_ ` _ \| '_ ` _ \ / _ \| '_ \ # 

5# | |_) | |_| || | (_) | (_) | | | | | | (_| || |__| (_) | | | | | | | | | | | (_) | | | | # 

6# | .__/ \__, ||_|\___/ \___/|_|_|_| |_|\__, (_)____\___/|_| |_| |_|_| |_| |_|\___/|_| |_| # 

7# |_| |___/ |___/ # 

8# ==================================================================================================================== # 

9# Authors: # 

10# Patrick Lehmann # 

11# # 

12# License: # 

13# ==================================================================================================================== # 

14# Copyright 2017-2026 Patrick Lehmann - Bötzingen, Germany # 

15# # 

16# Licensed under the Apache License, Version 2.0 (the "License"); # 

17# you may not use this file except in compliance with the License. # 

18# You may obtain a copy of the License at # 

19# # 

20# http://www.apache.org/licenses/LICENSE-2.0 # 

21# # 

22# Unless required by applicable law or agreed to in writing, software # 

23# distributed under the License is distributed on an "AS IS" BASIS, # 

24# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 

25# See the License for the specific language governing permissions and # 

26# limitations under the License. # 

27# # 

28# SPDX-License-Identifier: Apache-2.0 # 

29# ==================================================================================================================== # 

30# 

31""" 

32Common types, helper functions and classes. 

33 

34.. hint:: 

35 

36 See :ref:`high-level help <COMMON>` for explanations and usage examples. 

37""" 

38__author__ = "Patrick Lehmann" 

39__email__ = "Paebbels@gmail.com" 

40__copyright__ = "2017-2026, Patrick Lehmann" 

41__license__ = "Apache License, Version 2.0" 

42__version__ = "8.19.0" 

43__keywords__ = [ 

44 "abstract", "argparse", "attributes", "bfs", "cli", "console", "data structure", "decorators", "dfs", 

45 "double linked list", "exceptions", "file system statistics", "generators", "generic library", "generic path", 

46 "geometry", "graph", "installation", "iterators", "licensing", "linked list", "message logging", "meta-classes", 

47 "overloading", "override", "packaging", "path", "platform", "setuptools", "shapes", "shell", "singleton", "slots", 

48 "terminal", "text user interface", "stopwatch", "tree", "TUI", "url", "versioning", "volumes", "warning", "wheel" 

49] 

50__project_url__ = "https://github.com/pyTooling/pyTooling" 

51__documentation_url__ = "https://pyTooling.github.io/pyTooling" 

52__issue_tracker_url__ = "https://GitHub.com/pyTooling/pyTooling/issues" 

53 

54from collections import deque 

55from importlib.resources import files 

56from numbers import Number 

57from os import chdir 

58from pathlib import Path 

59from types import ModuleType, TracebackType 

60from typing import Type, TypeVar, Callable, Generator, Hashable, List 

61from typing import Any, Dict, Tuple, Union, Mapping, Set, Iterable, Optional as Nullable 

62 

63 

64from pyTooling.Decorators import export 

65 

66 

67@export 

68def getFullyQualifiedName(obj: Any) -> str: 

69 """ 

70 Assemble the fully qualified name of a type. 

71 

72 :param obj: The object for with the fully qualified type is to be assembled. 

73 :returns: The fully qualified name of obj's type. 

74 """ 

75 try: 

76 module = obj.__module__ # for class or function 

77 except AttributeError: 

78 module = obj.__class__.__module__ 

79 

80 try: 

81 name = obj.__qualname__ # for class or function 

82 except AttributeError: 

83 name = obj.__class__.__qualname__ 

84 

85 # If obj is a method of builtin class, then module will be None 

86 if module == "builtins" or module is None: 

87 return name 

88 

89 return f"{module}.{name}" 

90 

91 

92@export 

93def getResourceFile(module: Union[str, ModuleType], filename: str) -> Path: 

94 """ 

95 Compute the path to a file within a resource package. 

96 

97 :param module: The resource package. 

98 :param filename: The filename. 

99 :returns: Path to the resource's file. 

100 :raises ToolingException: If resource file doesn't exist. 

101 """ 

102 # TODO: files() has wrong TypeHint Traversible vs. Path 

103 resourcePath: Path = files(module) / filename 

104 if not resourcePath.exists(): 

105 from pyTooling.Exceptions import ToolingException 

106 

107 raise ToolingException(f"Resource file '{filename}' not found in resource '{module}'.") \ 

108 from FileNotFoundError(str(resourcePath)) 

109 

110 return resourcePath 

111 

112 

113@export 

114def readResourceFile(module: Union[str, ModuleType], filename: str) -> str: 

115 """ 

116 Read a text file resource from resource package. 

117 

118 :param module: The resource package. 

119 :param filename: The filename. 

120 :returns: File content. 

121 """ 

122 # TODO: check if resource exists. 

123 return files(module).joinpath(filename).read_text() 

124 

125 

126@export 

127def isnestedclass(cls: Type, scope: Type) -> bool: 

128 """ 

129 Returns true, if the given class ``cls`` is a member on an outer class ``scope``. 

130 

131 :param cls: Class to check, if it's a nested class. 

132 :param scope: Outer class which is the outer scope of ``cls``. 

133 :returns: ``True``, if ``cls`` is a nested class within ``scope``. 

134 """ 

135 for mroClass in scope.mro(): 

136 for memberName in mroClass.__dict__: 

137 member = getattr(mroClass, memberName) 

138 if isinstance(member, Type): 

139 if cls is member: 

140 return True 

141 

142 return False 

143 

144 

145@export 

146def getsizeof(obj: Any) -> int: 

147 """ 

148 Recursively calculate the "true" size of an object including complex members like ``__dict__``. 

149 

150 :param obj: Object to calculate the size of. 

151 :returns: True size of an object in bytes. 

152 

153 .. admonition:: Background Information 

154 

155 The function :func:`sys.getsizeof` only returns the raw size of a Python object and doesn't account for the 

156 overhead of e.g. ``_dict__`` to store dynamically allocated object members. 

157 

158 .. seealso:: 

159 

160 The code is based on code snippets and ideas from: 

161 

162 * `Compute Memory Footprint of an Object and its Contents <https://code.activestate.com/recipes/577504/>`__ (MIT Lizense) 

163 * `How do I determine the size of an object in Python? <https://stackoverflow.com/a/30316760/3719459>`__ (CC BY-SA 4.0) 

164 * `Python __slots__, slots, and object layout <https://github.com/mCodingLLC/VideosSampleCode/tree/master/videos/080_python_slots>`__ (MIT Lizense) 

165 """ 

166 from sys import getsizeof as sys_getsizeof 

167 

168 visitedIDs = set() #: A set to track visited objects, so memory consumption isn't counted multiple times. 

169 

170 def recurse(obj: Any) -> int: 

171 """ 

172 Nested function for recursion. 

173 

174 :param obj: Subobject to calculate the size of. 

175 :returns: Size of a subobject in bytes. 

176 """ 

177 # If already visited, return 0 bytes, so no additional bytes are accumulated 

178 objectID = id(obj) 

179 if objectID in visitedIDs: 

180 return 0 

181 else: 

182 visitedIDs.add(objectID) 

183 

184 # Get objects raw size 

185 size: int = sys_getsizeof(obj) 

186 

187 # Skip elementary types 

188 if isinstance(obj, (str, bytes, bytearray, range, Number)): 

189 pass 

190 # Handle iterables 

191 elif isinstance(obj, (tuple, list, Set, deque)): # TODO: What about builtin "set", "frozenset" and "dict"? 

192 for item in obj: 

193 size += recurse(item) 

194 # Handle mappings 

195 elif isinstance(obj, Mapping) or hasattr(obj, 'items'): 

196 items = getattr(obj, 'items') 

197 # Check if obj.items is a bound method. 

198 if hasattr(items, "__self__"): 

199 itemView = items() 

200 else: 

201 itemView = {} # bind(obj, items) 

202 for key, value in itemView: 

203 size += recurse(key) + recurse(value) 

204 

205 # Accumulate members from __dict__ 

206 if hasattr(obj, '__dict__'): 

207 v = vars(obj) 

208 size += recurse(v) 

209 

210 # Accumulate members from __slots__ 

211 if hasattr(obj, '__slots__') and obj.__slots__ is not None: 

212 for slot in obj.__slots__: 

213 if hasattr(obj, slot): 213 ↛ 212line 213 didn't jump to line 212 because the condition on line 213 was always true

214 size += recurse(getattr(obj, slot)) 

215 

216 return size 

217 

218 return recurse(obj) 

219 

220 

221def bind(instance, func, methodName: Nullable[str] = None): 

222 """ 

223 Bind the function *func* to *instance*, with either provided name *as_name* 

224 or the existing name of *func*. The provided *func* should accept the 

225 instance as the first argument, i.e. "self". 

226 

227 :param instance: Object to bind the function to. 

228 :param func: Function to bind. Its first parameter is the instance (``self``). 

229 :param methodName: Optional name to bind the function as. If ``None``, the function's own name is used. 

230 :returns: The bound method. 

231 """ 

232 if methodName is None: 

233 methodName = func.__name__ 

234 

235 boundMethod = func.__get__(instance, instance.__class__) 

236 setattr(instance, methodName, boundMethod) 

237 

238 return boundMethod 

239 

240 

241@export 

242def count(iterator: Iterable) -> int: 

243 """ 

244 Returns the number of elements in an iterable. 

245 

246 .. attention:: After counting the iterable's elements, the iterable is consumed. 

247 

248 :param iterator: Iterable to consume and count. 

249 :returns: Number of elements in the iterable. 

250 """ 

251 return len(list(iterator)) 

252 

253 

254_Element = TypeVar("Element") 

255 

256 

257@export 

258def firstElement(indexable: Union[List[_Element], Tuple[_Element, ...]]) -> _Element: 

259 """ 

260 Returns the first element from an indexable. 

261 

262 :param indexable: Indexable to get the first element from. 

263 :returns: First element. 

264 """ 

265 return indexable[0] 

266 

267 

268@export 

269def lastElement(indexable: Union[List[_Element], Tuple[_Element, ...]]) -> _Element: 

270 """ 

271 Returns the last element from an indexable. 

272 

273 :param indexable: Indexable to get the last element from. 

274 :returns: Last element. 

275 """ 

276 return indexable[-1] 

277 

278 

279@export 

280def firstItem(iterable: Iterable[_Element]) -> _Element: 

281 """ 

282 Returns the first item from an iterable. 

283 

284 :param iterable: Iterable to get the first item from. 

285 :returns: First item. 

286 :raises ValueError: If parameter 'iterable' contains no items. 

287 """ 

288 i = iter(iterable) 

289 try: 

290 return next(i) 

291 except StopIteration: 

292 raise ValueError(f"Iterable contains no items.") 

293 

294 

295@export 

296def lastItem(iterable: Iterable[_Element]) -> _Element: 

297 """ 

298 Returns the last item from an iterable. 

299 

300 :param iterable: Iterable to get the last item from. 

301 :returns: Last item. 

302 :raises ValueError: If parameter 'iterable' contains no items. 

303 """ 

304 i = iter(iterable) 

305 try: 

306 element = next(i) 

307 except StopIteration: 

308 raise ValueError(f"Iterable contains no items.") 

309 

310 for element in i: 

311 pass 

312 return element 

313 

314 

315_DictKey = TypeVar("_DictKey") 

316_DictKey1 = TypeVar("_DictKey1") 

317_DictKey2 = TypeVar("_DictKey2") 

318_DictKey3 = TypeVar("_DictKey3") 

319_DictValue1 = TypeVar("_DictValue1") 

320_DictValue2 = TypeVar("_DictValue2") 

321_DictValue3 = TypeVar("_DictValue3") 

322 

323 

324@export 

325def firstKey(d: Dict[_DictKey1, _DictValue1]) -> _DictKey1: 

326 """ 

327 Retrieves the first key from a dictionary's keys. 

328 

329 :param d: Dictionary to get the first key from. 

330 :returns: The first key. 

331 :raises ValueError: If parameter 'd' is an empty dictionary. 

332 """ 

333 if len(d) == 0: 

334 raise ValueError(f"Dictionary is empty.") 

335 

336 return next(iter(d.keys())) 

337 

338 

339@export 

340def firstValue(d: Dict[_DictKey1, _DictValue1]) -> _DictValue1: 

341 """ 

342 Retrieves the first value from a dictionary's values. 

343 

344 :param d: Dictionary to get the first value from. 

345 :returns: The first value. 

346 :raises ValueError: If parameter 'd' is an empty dictionary. 

347 """ 

348 if len(d) == 0: 

349 raise ValueError(f"Dictionary is empty.") 

350 

351 return next(iter(d.values())) 

352 

353 

354@export 

355def firstPair(d: Dict[_DictKey1, _DictValue1]) -> Tuple[_DictKey1, _DictValue1]: 

356 """ 

357 Retrieves the first key-value-pair from a dictionary. 

358 

359 :param d: Dictionary to get the first key-value-pair from. 

360 :returns: The first key-value-pair as tuple. 

361 :raises ValueError: If parameter 'd' is an empty dictionary. 

362 """ 

363 if len(d) == 0: 

364 raise ValueError(f"Dictionary is empty.") 

365 

366 return next(iter(d.items())) 

367 

368 

369@export 

370def mergedicts(*dicts: Dict, filter: Nullable[Callable[[Hashable, Any], bool]] = None) -> Dict: 

371 """ 

372 Merge multiple dictionaries into a single new dictionary. 

373 

374 If parameter ``filter`` isn't ``None``, then this function is applied to every element during the merge operation. If 

375 it returns true, the dictionary element will be present in the resulting dictionary. 

376 

377 :param dicts: Tuple of dictionaries to merge as positional parameters. 

378 :param filter: Optional filter function to apply to each dictionary element when merging. 

379 :returns: A new dictionary containing the merge result. 

380 :raises ValueError: If 'mergedicts' got called without any dictionaries parameters. 

381 

382 .. seealso:: 

383 

384 `How do I merge two dictionaries in a single expression in Python? <https://stackoverflow.com/questions/38987/how-do-i-merge-two-dictionaries-in-a-single-expression-in-python>`__ 

385 """ 

386 if len(dicts) == 0: 

387 raise ValueError(f"Called 'mergedicts' without any dictionary parameter.") 

388 

389 if filter is None: 

390 return {k: v for d in dicts for k, v in d.items()} 

391 else: 

392 return {k: v for d in dicts for k, v in d.items() if filter(k, v)} 

393 

394 

395@export 

396def zipdicts(*dicts: Dict) -> Generator[Tuple, None, None]: 

397 """ 

398 Iterate multiple dictionaries simultaneously. 

399 

400 :param dicts: Tuple of dictionaries to iterate as positional parameters. 

401 :returns: A generator returning a tuple containing the key and values of each dictionary in the order of 

402 given dictionaries. 

403 :raises ValueError: If 'zipdicts' got called without any dictionary parameters. 

404 :raises ValueError: If not all dictionaries have the same length. 

405 

406 .. seealso:: 

407 

408 The code is based on code snippets and ideas from: 

409 

410 * `zipping together Python dicts <https://github.com/mCodingLLC/VideosSampleCode/tree/master/videos/101_zip_dict>`__ (MIT Lizense) 

411 """ 

412 if len(dicts) == 0: 

413 raise ValueError(f"Called 'zipdicts' without any dictionary parameter.") 

414 

415 if any(len(d) != len(dicts[0]) for d in dicts): 

416 raise ValueError(f"All given dictionaries must have the same length.") 

417 

418 def gen(ds: Tuple[Dict, ...]) -> Generator[Tuple, None, None]: 

419 for key, item0 in ds[0].items(): 

420 # WORKAROUND: using redundant parenthesis for Python 3.7 and pypy-3.10 

421 yield key, item0, *(d[key] for d in ds[1:]) 

422 

423 return gen(dicts) 

424 

425 

426@export 

427class ChangeDirectory: 

428 """ 

429 A context manager for changing a directory. 

430 """ 

431 _oldWorkingDirectory: Path #: Working directory before directory change. 

432 _newWorkingDirectory: Path #: New working directory. 

433 

434 def __init__(self, directory: Path) -> None: 

435 """ 

436 Initializes the context manager for changing directories. 

437 

438 :param directory: The new working directory to change into. 

439 """ 

440 self._newWorkingDirectory = directory 

441 

442 def __enter__(self) -> Path: 

443 """ 

444 Enter the context and change the working directory to the parameter given in the class initializer. 

445 

446 :returns: The relative path between old and new working directories. 

447 """ 

448 self._oldWorkingDirectory = Path.cwd() 

449 chdir(self._newWorkingDirectory) 

450 

451 if self._newWorkingDirectory.is_absolute(): 451 ↛ 452line 451 didn't jump to line 452 because the condition on line 451 was never true

452 return self._newWorkingDirectory.resolve() 

453 else: 

454 return (self._oldWorkingDirectory / self._newWorkingDirectory).resolve() 

455 

456 def __exit__( 

457 self, 

458 exc_type: Nullable[Type[BaseException]] = None, 

459 exc_val: Nullable[BaseException] = None, 

460 exc_tb: Nullable[TracebackType] = None 

461 ) -> Nullable[bool]: 

462 """ 

463 Exit the context and revert any working directory changes. 

464 

465 :param exc_type: Exception type 

466 :param exc_val: Exception instance 

467 :param exc_tb: Exception's traceback. 

468 :returns: ``None`` 

469 """ 

470 chdir(self._oldWorkingDirectory)