Coverage for pyTooling/CLIAbstraction/BooleanFlag.py: 96%

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

2# _____ _ _ ____ _ ___ _ _ _ _ _ # 

3# _ __ _ |_ _|__ ___ | (_)_ __ __ _ / ___| | |_ _| / \ | |__ ___| |_ _ __ __ _ ___| |_(_) ___ _ __ # 

4# | '_ \| | | || |/ _ \ / _ \| | | '_ \ / _` || | | | | | / _ \ | '_ \/ __| __| '__/ _` |/ __| __| |/ _ \| '_ \ # 

5# | |_) | |_| || | (_) | (_) | | | | | | (_| || |___| |___ | | / ___ \| |_) \__ \ |_| | | (_| | (__| |_| | (_) | | | | # 

6# | .__/ \__, ||_|\___/ \___/|_|_|_| |_|\__, (_)____|_____|___/_/ \_\_.__/|___/\__|_| \__,_|\___|\__|_|\___/|_| |_| # 

7# |_| |___/ |___/ # 

8# ==================================================================================================================== # 

9# Authors: # 

10# Patrick Lehmann # 

11# # 

12# License: # 

13# ==================================================================================================================== # 

14# Copyright 2017-2026 Patrick Lehmann - Bötzingen, Germany # 

15# Copyright 2014-2016 Technische Universität Dresden - Germany, Chair of VLSI-Design, Diagnostics and Architecture # 

16# # 

17# Licensed under the Apache License, Version 2.0 (the "License"); # 

18# you may not use this file except in compliance with the License. # 

19# You may obtain a copy of the License at # 

20# # 

21# http://www.apache.org/licenses/LICENSE-2.0 # 

22# # 

23# Unless required by applicable law or agreed to in writing, software # 

24# distributed under the License is distributed on an "AS IS" BASIS, # 

25# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 

26# See the License for the specific language governing permissions and # 

27# limitations under the License. # 

28# # 

29# SPDX-License-Identifier: Apache-2.0 # 

30# ==================================================================================================================== # 

31# 

32""" 

33Boolean flags are arguments with a name and different pattern for a positive (``True``) and negative (``False``) value. 

34 

35.. seealso:: 

36 

37 :mod:`~pyTooling.CLIAbstraction.Flag` 

38 |rarr| For simple flags. 

39 :mod:`~pyTooling.CLIAbstraction.ValuedFlag` 

40 |rarr| For flags with a value. 

41 :class:`~pyTooling.CLIAbstraction.OptionalValuedFlag.OptionalValuedFlag` 

42 |rarr| For flags that have an optional value. 

43""" 

44from typing import ClassVar, Union, Iterable, Any, Optional as Nullable 

45 

46from pyTooling.Decorators import export 

47from pyTooling.MetaClasses import abstractclass 

48from pyTooling.CLIAbstraction.Argument import NamedArgument, ValuedArgument 

49 

50 

51@export 

52@abstractclass 

53class BooleanFlag(NamedArgument, ValuedArgument[bool]): 

54 """ 

55 Class and base-class for all BooleanFlag classes, which represents a flag argument with different pattern for an 

56 enabled/positive (``True``) or disabled/negative (``False``) state. 

57 

58 When deriving a subclass from an abstract BooleanFlag class, the parameters ``pattern`` and ``falsePattern`` are 

59 expected. 

60 

61 **Example:** 

62 

63 * True: ``with-checks`` 

64 * False: ``without-checks`` 

65 """ 

66 

67 _falsePattern: ClassVar[str] #: Format string used when the flag's value is ``False``; :attr:`_pattern` is used for ``True``. 

68 

69 def __init_subclass__(cls, *args: Any, name: Nullable[str] = None, pattern: str = "with-{0}", falsePattern: str = "without-{0}", **kwargs: Any) -> None: 

70 """ 

71 This method is called when a class is derived. 

72 

73 :param args: Any positional arguments. 

74 :param name: Optional, name of the flag, inserted into the patterns. 

75 :param pattern: Optional, this pattern is used to format an argument when the value is ``True``. |br| 

76 Default: ``"with-{0}"``. 

77 :param falsePattern: Optional, this pattern is used to format an argument when the value is ``False``. |br| 

78 Default: ``"without-{0}"``. 

79 :param kwargs: Any keyword argument. 

80 """ 

81 kwargs["name"] = name 

82 kwargs["pattern"] = pattern 

83 super().__init_subclass__(*args, **kwargs) 

84 del kwargs["name"] 

85 del kwargs["pattern"] 

86 ValuedArgument.__init_subclass__(*args, **kwargs) 

87 

88 cls._falsePattern = falsePattern 

89 

90 def __init__(self, value: bool) -> None: 

91 """Initializes a BooleanFlag instance. 

92 

93 :param value: ``True`` adds the flag, ``False`` its negation. 

94 """ 

95 ValuedArgument.__init__(self, value) 

96 

97 def AsArgument(self) -> Union[str, Iterable[str]]: 

98 """Convert this argument instance to a string representation with proper escaping using the matching pattern based 

99 on the internal name and value. 

100 

101 :returns: Formatted argument. 

102 :raises ValueError: If internal name is None. 

103 """ 

104 if self._name is None: 104 ↛ 105line 104 didn't jump to line 105 because the condition on line 104 was never true

105 raise ValueError(f"Internal value '_name' is None.") 

106 

107 pattern = self._pattern if self._value is True else self._falsePattern 

108 return pattern.format(self._name) 

109 

110 

111@export 

112@abstractclass 

113class ShortBooleanFlag(BooleanFlag, pattern="-with-{0}", falsePattern="-without-{0}"): 

114 """Represents a :py:class:`BooleanFlag` with a single dash. 

115 

116 **Example:** 

117 

118 * True: ``-with-checks`` 

119 * False: ``-without-checks`` 

120 """ 

121 

122 def __init_subclass__(cls, *args: Any, name: Nullable[str] = None, pattern: str = "-with-{0}", falsePattern: str = "-without-{0}", **kwargs: Any) -> None: 

123 """ 

124 This method is called when a class is derived. 

125 

126 :param args: Any positional arguments. 

127 :param name: Optional, name of the flag, inserted into the patterns. 

128 :param pattern: Optional, this pattern is used to format an argument when the value is ``True``. |br| 

129 Default: ``"-with-{0}"``. 

130 :param falsePattern: Optional, this pattern is used to format an argument when the value is ``False``. |br| 

131 Default: ``"-without-{0}"``. 

132 :param kwargs: Any keyword argument. 

133 """ 

134 kwargs["name"] = name 

135 kwargs["pattern"] = pattern 

136 kwargs["falsePattern"] = falsePattern 

137 super().__init_subclass__(*args, **kwargs) 

138 

139 

140@export 

141@abstractclass 

142class LongBooleanFlag(BooleanFlag, pattern="--with-{0}", falsePattern="--without-{0}"): 

143 """Represents a :py:class:`BooleanFlag` with a double dash. 

144 

145 **Example:** 

146 

147 * True: ``--with-checks`` 

148 * False: ``--without-checks`` 

149 """ 

150 

151 def __init_subclass__(cls, *args: Any, name: Nullable[str] = None, pattern: str = "--with-{0}", falsePattern: str = "--without-{0}", **kwargs: Any) -> None: 

152 """ 

153 This method is called when a class is derived. 

154 

155 :param args: Any positional arguments. 

156 :param name: Optional, name of the flag, inserted into the patterns. 

157 :param pattern: Optional, this pattern is used to format an argument when the value is ``True``. |br| 

158 Default: ``"--with-{0}"``. 

159 :param falsePattern: Optional, this pattern is used to format an argument when the value is ``False``. |br| 

160 Default: ``"--without-{0}"``. 

161 :param kwargs: Any keyword argument. 

162 """ 

163 kwargs["name"] = name 

164 kwargs["pattern"] = pattern 

165 kwargs["falsePattern"] = falsePattern 

166 super().__init_subclass__(*args, **kwargs) 

167 

168 

169@export 

170@abstractclass 

171class WindowsBooleanFlag(BooleanFlag, pattern="/with-{0}", falsePattern="/without-{0}"): 

172 """Represents a :py:class:`BooleanFlag` with a slash. 

173 

174 **Example:** 

175 

176 * True: ``/with-checks`` 

177 * False: ``/without-checks`` 

178 """ 

179 

180 def __init_subclass__(cls, *args: Any, name: Nullable[str] = None, pattern: str = "/with-{0}", falsePattern: str = "/without-{0}", **kwargs: Any) -> None: 

181 """ 

182 This method is called when a class is derived. 

183 

184 :param args: Any positional arguments. 

185 :param name: Optional, name of the flag, inserted into the patterns. 

186 :param pattern: Optional, this pattern is used to format an argument when the value is ``True``. |br| 

187 Default: ``"/with-{0}"``. 

188 :param falsePattern: Optional, this pattern is used to format an argument when the value is ``False``. |br| 

189 Default: ``"/without-{0}"``. 

190 :param kwargs: Any keyword argument. 

191 """ 

192 kwargs["name"] = name 

193 kwargs["pattern"] = pattern 

194 kwargs["falsePattern"] = falsePattern 

195 super().__init_subclass__(*args, **kwargs)