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.

38.. seealso::

40 :mod:`pyTooling.Decorators`

41 |rarr| Decorators used throughout the package.

42 :mod:`pyTooling.MetaClasses`

43 |rarr| The meta-class implementing slots, singletons and abstract classes.

44"""

45__author__ = "Patrick Lehmann"

46__email__ = "Paebbels@gmail.com"

47__copyright__ = "2017-2026, Patrick Lehmann"

48__license__ = "Apache License, Version 2.0"

49__version__ = "9.1.0"

50__keywords__ = [

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

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

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

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

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

56]

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

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

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

61from collections import deque

62from importlib.resources import files

63from numbers import Number

64from os import chdir

65from pathlib import Path

66from types import ModuleType, TracebackType

67from typing import TypeVar, Callable, Generator, Hashable

68from typing import Any, Union, Mapping, Iterable, Optional as Nullable

70from pyTooling.Decorators import export

73@export

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

75 """

76 Assemble the fully qualified name of a type.

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

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

80 """

81 try:

82 module = obj.__module__ # for class or function

83 except AttributeError:

84 module = obj.__class__.__module__

86 try:

87 name = obj.__qualname__ # for class or function

88 except AttributeError:

89 name = obj.__class__.__qualname__

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

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

93 return name

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

98@export

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

100 """

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

102

103 :param module: The resource package.

104 :param filename: The filename.

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

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

107 """

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

109 resourcePath: Path = files(module) / filename

110 if not resourcePath.exists():

111 from pyTooling.Exceptions import ToolingException

112

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

114 from FileNotFoundError(str(resourcePath))

115

116 return resourcePath

117

118

119@export

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

121 """

122 Read a text file resource from resource package.

123

124 :param module: The resource package.

125 :param filename: The filename.

126 :returns: File content.

127 """

128 # TODO: check if resource exists.

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

130

131

132@export

133def isnestedclass(cls: type, scope: type) -> bool:

134 """

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

136

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

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

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

140 """

141 for mroClass in scope.mro():

142 for memberName in mroClass.__dict__:

143 member = getattr(mroClass, memberName)

144 if isinstance(member, type):

145 if cls is member:

146 return True

147

148 return False

149

150

151@export

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

153 """

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

155

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

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

158

159 .. admonition:: Background Information

160

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

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

163

164 .. seealso::

165

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

167

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

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

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

171 """

172 from sys import getsizeof as sys_getsizeof

173

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

175

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

177 """

178 Nested function for recursion.

179

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

181 :returns: Size of a subobject in bytes.

182 """

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

184 objectID = id(obj)

185 if objectID in visitedIDs:

186 return 0

187 else:

188 visitedIDs.add(objectID)

189

190 # Get objects raw size

191 size: int = sys_getsizeof(obj)

192

193 # Skip elementary types

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

195 pass

196 # Handle iterables

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

198 for item in obj:

199 size += recurse(item)

200 # Handle mappings

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

202 items = getattr(obj, 'items')

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

204 if hasattr(items, "__self__"): 204 ↛ 207line 204 didn't jump to line 207 because the condition on line 204 was always true

205 itemView = items()

206 else:

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

208 for key, value in itemView:

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

210

211 # Accumulate members from __dict__

212 if hasattr(obj, '__dict__'):

213 v = vars(obj)

214 size += recurse(v)

215

216 # Accumulate members from __slots__

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

218 for slot in obj.__slots__:

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

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

221

222 return size

223

224 return recurse(obj)

225

226

227def bind(instance: Any, func: Callable[..., Any], methodName: Nullable[str] = None) -> None:

228 """

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

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

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

232

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

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

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

236 :returns: The bound method.

237 """

238 if methodName is None:

239 methodName = func.__name__

240

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

242 setattr(instance, methodName, boundMethod)

243

244 return boundMethod

245

246

247@export

248def count(iterator: Iterable[Any]) -> int:

249 """

250 Returns the number of elements in an iterable.

251

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

253

254 :param iterator: Iterable to consume and count.

255 :returns: Number of elements in the iterable.

256 """

257 return len(list(iterator))

258

259

260_Element = TypeVar("Element")

261

262

263@export

264def firstElement(indexable: Union[list[_Element], tuple[_Element, ...]]) -> _Element:

265 """

266 Returns the first element from an indexable.

267

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

269 :returns: First element.

270 """

271 return indexable[0]

272

273

274@export

275def lastElement(indexable: Union[list[_Element], tuple[_Element, ...]]) -> _Element:

276 """

277 Returns the last element from an indexable.

278

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

280 :returns: Last element.

281 """

282 return indexable[-1]

283

284

285@export

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

287 """

288 Returns the first item from an iterable.

289

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

291 :returns: First item.

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

293 """

294 i = iter(iterable)

295 try:

296 return next(i)

297 except StopIteration:

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

299

300

301@export

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

303 """

304 Returns the last item from an iterable.

305

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

307 :returns: Last item.

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

309 """

310 i = iter(iterable)

311 try:

312 element = next(i)

313 except StopIteration:

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

315

316 for element in i:

317 pass

318 return element

319

320

321_DictKey = TypeVar("_DictKey")

322_DictKey1 = TypeVar("_DictKey1")

323_DictKey2 = TypeVar("_DictKey2")

324_DictKey3 = TypeVar("_DictKey3")

325_DictValue1 = TypeVar("_DictValue1")

326_DictValue2 = TypeVar("_DictValue2")

327_DictValue3 = TypeVar("_DictValue3")

328

329

330@export

331def firstKey(d: dict[_DictKey1, _DictValue1]) -> _DictKey1:

332 """

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

334

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

336 :returns: The first key.

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

338 """

339 if len(d) == 0:

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

341

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

343

344

345@export

346def firstValue(d: dict[_DictKey1, _DictValue1]) -> _DictValue1:

347 """

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

349

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

351 :returns: The first value.

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

353 """

354 if len(d) == 0:

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

356

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

358

359

360@export

361def firstPair(d: dict[_DictKey1, _DictValue1]) -> tuple[_DictKey1, _DictValue1]:

362 """

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

364

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

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

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

368 """

369 if len(d) == 0:

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

371

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

373

374

375@export

376def mergedicts(

377 *dicts: dict[Hashable, Any],

378 filter: Nullable[Callable[[Hashable, Any], bool]] = None

379) -> dict[Hashable, Any]:

380 """

381 Merge multiple dictionaries into a single new dictionary.

382

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

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

385

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

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

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

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

390

391 .. seealso::

392

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

394 """

395 if len(dicts) == 0:

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

397

398 if filter is None:

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

400 else:

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

402

403

404@export

405def zipdicts(*dicts: dict[Hashable, Any]) -> Generator[tuple[Any, ...], None, None]:

406 """

407 Iterate multiple dictionaries simultaneously.

408

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

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

411 given dictionaries.

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

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

414

415 .. seealso::

416

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

418

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

420 """

421 if len(dicts) == 0:

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

423

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

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

426

427 def gen(ds: tuple[dict[Hashable, Any], ...]) -> Generator[tuple[Any, ...], None, None]:

428 """

429 Nested generator function, so the length check runs when :func:`zipdicts` is called, not on first iteration.

430

431 :param ds: The dictionaries to zip.

432 :returns: A generator yielding a tuple of the key and one value per dictionary.

433 """

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

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

436

437 return gen(dicts)

438

439

440@export

441class ChangeDirectory:

442 """

443 A context manager for changing a directory.

444 """

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

446 _newWorkingDirectory: Path #: New working directory.

447

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

449 """

450 Initializes the context manager for changing directories.

451

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

453 """

454 self._newWorkingDirectory = directory

455

456 def __enter__(self) -> Path:

457 """

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

459

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

461 """

462 self._oldWorkingDirectory = Path.cwd()

463 chdir(self._newWorkingDirectory)

464

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

466 return self._newWorkingDirectory.resolve()

467 else:

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

469

470 def __exit__(

471 self,

472 exc_type: Nullable[type[BaseException]] = None,

473 exc_val: Nullable[BaseException] = None,

474 exc_tb: Nullable[TracebackType] = None

475 ) -> Nullable[bool]:

476 """

477 Exit the context and revert any working directory changes.

478

479 :param exc_type: Exception type

480 :param exc_val: Exception instance

481 :param exc_tb: Exception's traceback.

482 :returns: ``None``

483 """

484 chdir(self._oldWorkingDirectory)

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

165 statements