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# ## Local First Party Imports ---- 

45from toolbox_python.collection_types import str_list 

46 

47 

48# ---------------------------------------------------------------------------- # 

49# Exports #### 

50# ---------------------------------------------------------------------------- # 

51 

52 

53__all__: str_list = ["get_full_class_name"] 

54 

55 

56# ---------------------------------------------------------------------------- # 

57# # 

58# Functions #### 

59# # 

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

61 

62 

63# ---------------------------------------------------------------------------- # 

64# Name of classes #### 

65# ---------------------------------------------------------------------------- # 

66 

67 

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

69 """ 

70 !!! note "Summary" 

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

72 

73 ???+ abstract "Details" 

74 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. 

75 

76 Params: 

77 obj (Any): 

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

79 

80 Returns: 

81 (str): 

82 The full name of the class of the object. 

83 

84 ???+ example "Examples" 

85 

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

87 >>> from toolbox_python.classes import get_full_class_name 

88 ``` 

89 

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

91 >>> print(get_full_class_name(str)) 

92 ``` 

93 <div class="result" markdown> 

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

95 str 

96 ``` 

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

98 </div> 

99 

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

101 >>> from random import Random 

102 >>> print(get_full_class_name(Random)) 

103 ``` 

104 <div class="result" markdown> 

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

106 random.Random 

107 ``` 

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

109 </div> 

110 

111 ??? success "Credit" 

112 Full credit goes to:<br> 

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

114 """ 

115 module: str = obj.__class__.__module__ 

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

117 return obj.__class__.__name__ 

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