Coverage for pyTooling/Common/__init_

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

2# _____ _ _ ____ #

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

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

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

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

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

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

9# Authors: #

10# Patrick Lehmann #

11# #

12# License: #

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

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.

34.. hint::

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.12.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__issue_tracker__ = "https://GitHub.com/pyTooling/pyTooling/issues"

52from collections import deque

53from importlib.resources import files

54from numbers import Number

55from os import chdir

56from pathlib import Path

57from types import ModuleType, TracebackType

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

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

62from pyTooling.Decorators import export

65@export

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

67 """

68 Assemble the fully qualified name of a type.

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

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

72 """

73 try:

74 module = obj.__module__ # for class or function

75 except AttributeError:

76 module = obj.__class__.__module__

78 try:

79 name = obj.__qualname__ # for class or function

80 except AttributeError:

81 name = obj.__class__.__qualname__

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

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

85 return name

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

90@export

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

92 """

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

95 :param module: The resource package.

96 :param filename: The filename.

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

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

99 """

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

101 resourcePath: Path = files(module) / filename

102 if not resourcePath.exists():

103 from pyTooling.Exceptions import ToolingException

104

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

106 from FileNotFoundError(str(resourcePath))

107

108 return resourcePath

109

110

111@export

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

113 """

114 Read a text file resource from resource package.

115

116 :param module: The resource package.

117 :param filename: The filename.

118 :returns: File content.

119 """

120 # TODO: check if resource exists.

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

122

123

124@export

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

126 """

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

128

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

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

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

132 """

133 for mroClass in scope.mro():

134 for memberName in mroClass.__dict__:

135 member = getattr(mroClass, memberName)

136 if isinstance(member, Type):

137 if cls is member:

138 return True

139

140 return False

141

142

143@export

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

145 """

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

147

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

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

150

151 .. admonition:: Background Information

152

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

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

155

156 .. seealso::

157

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

159

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

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

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

163 """

164 from sys import getsizeof as sys_getsizeof

165

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

167

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

169 """

170 Nested function for recursion.

171

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

173 :returns: Size of a subobject in bytes.

174 """

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

176 objectID = id(obj)

177 if objectID in visitedIDs:

178 return 0

179 else:

180 visitedIDs.add(objectID)

181

182 # Get objects raw size

183 size: int = sys_getsizeof(obj)

184

185 # Skip elementary types

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

187 pass

188 # Handle iterables

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

190 for item in obj:

191 size += recurse(item)

192 # Handle mappings

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

194 items = getattr(obj, 'items')

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

196 if hasattr(items, "__self__"):

197 itemView = items()

198 else:

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

200 for key, value in itemView:

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

202

203 # Accumulate members from __dict__

204 if hasattr(obj, '__dict__'):

205 v = vars(obj)

206 size += recurse(v)

207

208 # Accumulate members from __slots__

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

210 for slot in obj.__slots__:

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

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

213

214 return size

215

216 return recurse(obj)

217

218

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

220 """

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

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

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

224

225 :param instance:

226 :param func:

227 :param methodName:

228 :return:

229 """

230 if methodName is None:

231 methodName = func.__name__

232

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

234 setattr(instance, methodName, boundMethod)

235

236 return boundMethod

237

238

239@export

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

241 """

242 Returns the number of elements in an iterable.

243

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

245

246 :param iterator: Iterable to consume and count.

247 :return: Number of elements in the iterable.

248 """

249 return len(list(iterator))

250

251

252_Element = TypeVar("Element")

253

254

255@export

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

257 """

258 Returns the first element from an indexable.

259

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

261 :return: First element.

262 """

263 return indexable[0]

264

265

266@export

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

268 """

269 Returns the last element from an indexable.

270

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

272 :return: Last element.

273 """

274 return indexable[-1]

275

276

277@export

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

279 """

280 Returns the first item from an iterable.

281

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

283 :return: First item.

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

285 """

286 i = iter(iterable)

287 try:

288 return next(i)

289 except StopIteration:

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

291

292

293@export

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

295 """

296 Returns the last item from an iterable.

297

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

299 :return: Last item.

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

301 """

302 i = iter(iterable)

303 try:

304 element = next(i)

305 except StopIteration:

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

307

308 for element in i:

309 pass

310 return element

311

312

313_DictKey = TypeVar("_DictKey")

314_DictKey1 = TypeVar("_DictKey1")

315_DictKey2 = TypeVar("_DictKey2")

316_DictKey3 = TypeVar("_DictKey3")

317_DictValue1 = TypeVar("_DictValue1")

318_DictValue2 = TypeVar("_DictValue2")

319_DictValue3 = TypeVar("_DictValue3")

320

321

322@export

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

324 """

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

326

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

328 :returns: The first key.

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

330 """

331 if len(d) == 0:

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

333

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

335

336

337@export

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

339 """

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

341

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

343 :returns: The first value.

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

345 """

346 if len(d) == 0:

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

348

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

350

351

352@export

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

354 """

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

356

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

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

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

360 """

361 if len(d) == 0:

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

363

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

365

366

367@export

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

369 """

370 Merge multiple dictionaries into a single new dictionary.

371

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

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

374

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

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

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

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

379

380 .. seealso::

381

382 `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>`__

383 """

384 if len(dicts) == 0:

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

386

387 if filter is None:

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

389 else:

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

391

392

393@export

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

395 """

396 Iterate multiple dictionaries simultaneously.

397

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

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

400 given dictionaries.

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

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

403

404 .. seealso::

405

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

407

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

409 """

410 if len(dicts) == 0:

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

412

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

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

415

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

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

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

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

420

421 return gen(dicts)

422

423

424@export

425class ChangeDirectory:

426 """

427 A context manager for changing a directory.

428 """

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

430 _newWorkingDirectory: Path #: New working directory.

431

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

433 """

434 Initializes the context manager for changing directories.

435

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

437 """

438 self._newWorkingDirectory = directory

439

440 def __enter__(self) -> Path:

441 """

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

443

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

445 """

446 self._oldWorkingDirectory = Path.cwd()

447 chdir(self._newWorkingDirectory)

448

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

450 return self._newWorkingDirectory.resolve()

451 else:

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

453

454 def __exit__(

455 self,

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

457 exc_val: Nullable[BaseException] = None,

458 exc_tb: Nullable[TracebackType] = None

459 ) -> Nullable[bool]:

460 """

461 Exit the context and revert any working directory changes.

462

463 :param exc_type: Exception type

464 :param exc_val: Exception instance

465 :param exc_tb: Exception's traceback.

466 :returns: ``None``

467 """

468 chdir(self._oldWorkingDirectory)

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

165 statements