Coverage for src / taipanstack / bridges / _imports.py: 100%

1""" 

2Lazy optional import helpers for Taipan Bridges. 

3 

4Provides a centralised mechanism to handle optional dependencies 

5that may or may not be installed at runtime. 

6""" 

7 

8import importlib 

9import types 

10 

11from taipanstack.core.result import Err, Ok, Result 

12 

13 

14def require_dependency( 

15 module_name: str, 

16 *, 

17 pip_extra: str = "", 

18) -> Result[types.ModuleType, ImportError]: 

19 """Attempt to import *module_name* and return a ``Result``. 

20 

21 Args: 

22 module_name: Dotted module path (e.g. ``"httpx"``). 

23 pip_extra: Optional pip extra name for the error message. 

24 

25 Returns: 

26 ``Ok(module)`` if available, ``Err(ImportError)`` otherwise. 

27 

28 Example: 

29 >>> require_dependency("httpx", pip_extra="bridges-http") 

30 Ok(<module 'httpx' ...>) 

31 

32 """ 

33 try: 

34 mod = importlib.import_module(module_name) # nosem 

35 return Ok(mod) 

36 except ImportError: 

37 install_hint = ( 

38 f"pip install taipanstack[{pip_extra}]" 

39 if pip_extra 

40 else f"pip install {module_name}" 

41 ) 

42 return Err( 

43 ImportError( 

44 f"'{module_name}' is required but not installed. " 

45 f"Install with: {install_hint}" 

46 ) 

47 ) 

48 

49 

50def get_attr_or_err( 

51 module: types.ModuleType, 

52 name: str, 

53) -> Result[object, AttributeError]: 

54 """Safely access an attribute from a module. 

55 

56 Args: 

57 module: The imported module. 

58 name: Attribute name to retrieve. 

59 

60 Returns: 

61 ``Ok(attr)`` if found, ``Err(AttributeError)`` otherwise. 

62 

63 """ 

64 try: 

65 return Ok(getattr(module, name)) 

66 except AttributeError as exc: 

67 return Err(exc)