Coverage for src/toolbox_python/classes.py: 100%

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

2# # 

3# Title : Classes # 

4# Purpose : Contain functions which can be run on classes to extract # 

5# general information. # 

6# # 

7# ============================================================================ # 

8 

9 

10# ---------------------------------------------------------------------------- # 

11# # 

12# Overview #### 

13# # 

14# ---------------------------------------------------------------------------- # 

15 

16 

17# ---------------------------------------------------------------------------- # 

18# Description #### 

19# ---------------------------------------------------------------------------- # 

20 

21 

22""" 

23!!! note "Summary" 

24 The `classes` module is designed for functions to be executed _on_ classes; not _within_ classes. 

25 For any methods/functions that should be added _to_ classes, you should consider re-designing the original class, or sub-classing it to make further alterations. 

26""" 

27 

28 

29# ---------------------------------------------------------------------------- # 

30# # 

31# Setup #### 

32# # 

33# ---------------------------------------------------------------------------- # 

34 

35 

36# ---------------------------------------------------------------------------- # 

37# Imports #### 

38# ---------------------------------------------------------------------------- # 

39 

40 

41# ## Python StdLib Imports ---- 

42from typing import Any 

43 

44 

45# ---------------------------------------------------------------------------- # 

46# Exports #### 

47# ---------------------------------------------------------------------------- # 

48 

49 

50__all__: list[str] = ["get_full_class_name"] 

51 

52 

53# ---------------------------------------------------------------------------- # 

54# # 

55# Functions #### 

56# # 

57# ---------------------------------------------------------------------------- # 

58 

59 

60# ---------------------------------------------------------------------------- # 

61# Name of classes #### 

62# ---------------------------------------------------------------------------- # 

63 

64 

65def get_full_class_name(obj: Any) -> str: 

66 """ 

67 !!! note "Summary" 

68 This function is designed to extract the full name of a class, including the name of the module from which it was loaded. 

69 

70 ???+ abstract "Details" 

71 Note, this is designed to retrieve the underlying _class name_ of an object, not the _instance name_ of an object. This is useful for debugging purposes, or for logging. 

72 

73 Params: 

74 obj (Any): 

75 The object for which you want to retrieve the full name. 

76 

77 Returns: 

78 (str): 

79 The full name of the class of the object. 

80 

81 ???+ example "Examples" 

82 

83 ```{.py .python linenums="1" title="Set up"} 

84 >>> from toolbox_python.classes import get_full_class_name 

85 ``` 

86 

87 ```{.py .python linenums="1" title="Example 1: Check the name of a standard class"} 

88 >>> print(get_full_class_name(str)) 

89 ``` 

90 <div class="result" markdown> 

91 ```{.sh .shell title="Terminal"} 

92 str 

93 ``` 

94 !!! success "Conclusion: Successful class name extraction." 

95 </div> 

96 

97 ```{.py .python linenums="1" title="Example 2: Check the name of an imported class"} 

98 >>> from random import Random 

99 >>> print(get_full_class_name(Random)) 

100 ``` 

101 <div class="result" markdown> 

102 ```{.sh .shell title="Terminal"} 

103 random.Random 

104 ``` 

105 !!! success "Conclusion: Successful class name extraction." 

106 </div> 

107 

108 ??? success "Credit" 

109 Full credit goes to:<br> 

110 https://stackoverflow.com/questions/18176602/how-to-get-the-name-of-an-exception-that-was-caught-in-python#answer-58045927 

111 """ 

112 module: str = obj.__class__.__module__ 

113 if module is None or module == str.__class__.__module__: 

114 return obj.__class__.__name__ 

115 return module + "." + obj.__class__.__name__