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# Exports #### 

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

39 

40 

41__all__: list[str] = ["strtobool", "STR_TO_BOOL_MAP"] 

42 

43 

44# ---------------------------------------------------------------------------- # 

45# Constants #### 

46# ---------------------------------------------------------------------------- # 

47 

48 

49STR_TO_BOOL_MAP: dict[str, bool] = { 

50 "y": True, 

51 "yes": True, 

52 "t": True, 

53 "true": True, 

54 "on": True, 

55 "1": True, 

56 "n": False, 

57 "no": False, 

58 "f": False, 

59 "false": False, 

60 "off": False, 

61 "0": False, 

62} 

63""" 

64Summary: 

65 Map of string values to their corresponding boolean values. 

66""" 

67 

68 

69# ---------------------------------------------------------------------------- # 

70# # 

71# Functions #### 

72# # 

73# ---------------------------------------------------------------------------- # 

74 

75 

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

77 """ 

78 !!! note "Summary" 

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

80 

81 ???+ abstract "Details" 

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

83 

84 Params: 

85 value (str): 

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

87 

88 Raises: 

89 ValueError: 

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

91 

92 Returns: 

93 (bool): 

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

95 

96 ???+ example "Examples" 

97 

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

99 from toolbox_python.bools import strtobool 

100 ``` 

101 

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

103 >>> print(strtobool("true")) 

104 >>> print(strtobool("t")) 

105 >>> print(strtobool("1")) 

106 ``` 

107 <div class="result" markdown> 

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

109 True 

110 True 

111 True 

112 ``` 

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

114 </div> 

115 

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

117 >>> print(strtobool("false")) 

118 >>> print(strtobool("f")) 

119 >>> print(strtobool("0")) 

120 ``` 

121 <div class="result" markdown> 

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

123 False 

124 False 

125 False 

126 ``` 

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

128 </div> 

129 

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

131 >>> print(strtobool(5)) 

132 ``` 

133 <div class="result" markdown> 

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

135 ValueError: Invalid bool value: '5'. 

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

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

138 ``` 

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

140 </div> 

141 

142 ??? question "References" 

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

144 """ 

145 try: 

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

147 except KeyError as exc: 

148 raise ValueError( 

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

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

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

152 ) from exc