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

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

2# # 

3# Title : Bools # 

4# Purpose : Manipulate and enhance booleans. # 

5# # 

6# ============================================================================ # 

7 

8 

9# ---------------------------------------------------------------------------- # 

10# # 

11# Overview #### 

12# # 

13# ---------------------------------------------------------------------------- # 

14 

15 

16# ---------------------------------------------------------------------------- # 

17# Description #### 

18# ---------------------------------------------------------------------------- # 

19 

20 

21""" 

22!!! note "Summary" 

23 The `bools` module is used how to manipulate and enhance Python booleans. 

24!!! abstract "Details" 

25 Primarily, this module is used to store the `strtobool()` function, which used to be found in the `distutils.util` module, until it was deprecated. As mentioned in [PEP632](https://peps.python.org/pep-0632/#migration-advice), we should re-implement this function in our own code. And that's what we've done here. 

26""" 

27 

28 

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

30# # 

31# Setup #### 

32# # 

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

34 

35 

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

37# Imports #### 

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

39 

40 

41# ## Local First Party Imports ---- 

42from toolbox_python.collection_types import str_list 

43 

44 

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

46# Exports #### 

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

48 

49 

50__all__: str_list = ["strtobool", "STR_TO_BOOL_MAP"] 

51 

52 

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

54# Constants #### 

55# ---------------------------------------------------------------------------- # 

56 

57 

58STR_TO_BOOL_MAP: dict[str, bool] = { 

59 "y": True, 

60 "yes": True, 

61 "t": True, 

62 "true": True, 

63 "on": True, 

64 "1": True, 

65 "n": False, 

66 "no": False, 

67 "f": False, 

68 "false": False, 

69 "off": False, 

70 "0": False, 

71} 

72""" 

73Summary: 

74 Map of string values to their corresponding boolean values. 

75""" 

76 

77 

78# ---------------------------------------------------------------------------- # 

79# # 

80# Functions #### 

81# # 

82# ---------------------------------------------------------------------------- # 

83 

84 

85def strtobool(value: str) -> bool: 

86 """ 

87 !!! note "Summary" 

88 Convert a `#!py str` value in to a `#!py bool` value. 

89 

90 ???+ abstract "Details" 

91 This process is necessary because the `d`istutils` module was completely deprecated in Python 3.12. 

92 

93 Params: 

94 value (str): 

95 The string value to convert. Valid input options are defined in [`STR_TO_BOOL_MAP`][toolbox_python.bools.STR_TO_BOOL_MAP] 

96 

97 Raises: 

98 ValueError: 

99 If the value parse'ed in to `value` is not a valid value to be able to convert to a `#!py bool` value. 

100 

101 Returns: 

102 (bool): 

103 A `#!py True` or `#!py False` value, having successfully converted `value`. 

104 

105 ???+ example "Examples" 

106 

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

108 from toolbox_python.bools import strtobool 

109 ``` 

110 

111 ```{.py .python linenums="1" title="Example 1: `true` conversions"} 

112 >>> print(strtobool("true")) 

113 >>> print(strtobool("t")) 

114 >>> print(strtobool("1")) 

115 ``` 

116 <div class="result" markdown> 

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

118 True 

119 True 

120 True 

121 ``` 

122 !!! success "Conclusion: Successful conversion." 

123 </div> 

124 

125 ```{.py .python linenums="1" title="Example 2: `false` conversions"} 

126 >>> print(strtobool("false")) 

127 >>> print(strtobool("f")) 

128 >>> print(strtobool("0")) 

129 ``` 

130 <div class="result" markdown> 

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

132 False 

133 False 

134 False 

135 ``` 

136 !!! success "Conclusion: Successful conversion." 

137 </div> 

138 

139 ```{.py .python linenums="1" title="Example 3: invalid value"} 

140 >>> print(strtobool(5)) 

141 ``` 

142 <div class="result" markdown> 

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

144 ValueError: Invalid bool value: '5'. 

145 For `True`, must be one of: ['y', 'yes', 't', 'true', 'on', '1'] 

146 For `False`, must be one of: ['n', 'no', 'f', 'false', 'off', '0'] 

147 ``` 

148 !!! failure "Conclusion: Invalid type." 

149 </div> 

150 

151 ??? question "References" 

152 - [PEP632](https://peps.python.org/pep-0632/#migration-advice) 

153 """ 

154 try: 

155 return STR_TO_BOOL_MAP[str(value).lower()] 

156 except KeyError as exc: 

157 raise ValueError( 

158 f"Invalid bool value: '{value}'.\n" 

159 f"For `True`, must be one of: {[key for key, val in STR_TO_BOOL_MAP.items() if val]}\n" 

160 f"For `False`, must be one of: {[key for key, val in STR_TO_BOOL_MAP.items() if not val]}" 

161 ) from exc