Coverage for src / gitversioned / compat.py: 100%

1""" 

2Compatibility abstractions for optional dependencies. 

3 

4This module centralizes fallback logic for safely importing optional dependencies 

5like ``psutil``, ``opentelemetry``, and TOML parsers. It provides standardized 

6access points for these modules, avoiding scattered ``try-except`` blocks across 

7the codebase. Maintainers should import optional dependencies from this module 

8rather than attempting direct imports elsewhere. 

9""" 

10 

11from __future__ import annotations 

12 

13import types 

14from typing import Annotated 

15 

16__all__ = ["opentelemetry_trace", "psutil", "tomllib"] 

17 

18try: 

19 import tomllib as _tomllib 

20except ImportError: 

21 try: 

22 import tomli as _tomllib # type: ignore[import-not-found, no-redef] 

23 except ImportError: 

24 _tomllib = None # type: ignore[assignment] 

25 

26try: 

27 from opentelemetry import ( 

28 trace as _opentelemetry_trace, # type: ignore[import-not-found] 

29 ) 

30except ImportError: 

31 _opentelemetry_trace = None # type: ignore[assignment] 

32 

33try: 

34 import psutil as _psutil 

35except ImportError: 

36 _psutil = None # type: ignore[assignment] 

37 

38opentelemetry_trace: Annotated[ 

39 types.ModuleType | None, 

40 "Enables distributed tracing integration. Used for tracing execution paths " 

41 "when OpenTelemetry is present. Provides the ``opentelemetry.trace`` module " 

42 "or ``None``.", 

43] = _opentelemetry_trace 

44 

45psutil: Annotated[ 

46 types.ModuleType | None, 

47 "Enables retrieval of detailed system and process information. Used to monitor " 

48 "system context. Provides the ``psutil`` module or ``None``.", 

49] = _psutil 

50 

51tomllib: Annotated[ 

52 types.ModuleType | None, 

53 "Enables TOML file parsing. Used for reading configuration files like " 

54 "``pyproject.toml``. Provides the standard library ``tomllib``, the " 

55 "third-party ``tomli``, or ``None``.", 

56] = _tomllib