Coverage for pyTooling/CLIAbstraction/OptionalValuedFlag.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""" 

33 

34Command line arguments with an optional value, like ``--width`` or ``--width=100``. 

35 

36The argument renders one of two patterns: the one with a value when a value was assigned, and the one without a value 

37otherwise - which is why an optional-valued flag carries two format strings instead of one. 

38""" 

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

40 

41from pyTooling.Decorators import export 

42from pyTooling.MetaClasses import abstractclass 

43from pyTooling.CLIAbstraction.Argument import NamedAndValuedArgument 

44 

45 

46@export 

47@abstractclass 

48class OptionalValuedFlag(NamedAndValuedArgument[str], pattern="{0"): 

49 """ 

50 Class and base-class for all OptionalValuedFlag classes, which represents a flag argument with data. 

51 

52 An optional valued flag is a flag name followed by a value. The default delimiter sign is equal (``=``). Name and 

53 value are passed as one argument to the executable even if the delimiter sign is a whitespace character. If the value 

54 is None, no delimiter sign and value is passed. 

55 

56 Example: ``width=100`` 

57 """ 

58 _PATTERN_WITH_VALUE: ClassVar[str] #: Format string used when the flag has a value; :attr:`_PATTERN` is used without one. 

59 

60 def __init_subclass__(cls, *args: Any, pattern: str = "{0}", patternWithValue: str = "{0}={1}", **kwargs: Any) -> None: 

61 """ 

62 This method is called when a class is derived. 

63 

64 :param args: Any positional arguments. 

65 :param pattern: Optional, this pattern is used to format an argument without a value. |br| 

66 Default: ``"{0}"``. 

67 :param patternWithValue: Optional, this pattern is used to format an argument with a value. |br| 

68 Default: ``"{0}={1}"``. 

69 :param kwargs: Any keyword argument. 

70 """ 

71 kwargs["pattern"] = pattern 

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

73 cls._PATTERN_WITH_VALUE = patternWithValue 

74 

75 def __init__(self, value: Nullable[str] = None) -> None: 

76 """ 

77 Initialize the flag, optionally with a value. 

78 

79 :param value: Optional, value of the flag, or ``None`` to render the flag without a value. 

80 """ 

81 self._value = value 

82 

83 @property 

84 def Value(self) -> Nullable[str]: 

85 """ 

86 Property to access the internal value (:attr:`_value`). 

87 

88 :returns: Internal value, or ``None`` if the flag is used without a value. 

89 """ 

90 return self._value 

91 

92 @Value.setter 

93 def Value(self, value: Nullable[str]) -> None: 

94 self._value = value 

95 

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

97 """ 

98 Convert this argument instance to a string representation using the matching pattern based on 

99 the internal name and optional 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("Internal value '_NAME' is None.") 

106 

107 pattern = self._PATTERN if self._value is None else self._PATTERN_WITH_VALUE 

108 return pattern.format(self._NAME, self._value) 

109 

110 

111@export 

112@abstractclass 

113class ShortOptionalValuedFlag(OptionalValuedFlag, pattern="-{0}", patternWithValue="-{0}={1}"): 

114 """ 

115 Represents a :py:class:`OptionalValuedFlag` with a single dash. 

116 

117 Example: ``-optimizer=on`` 

118 """ 

119 def __init_subclass__(cls, *args: Any, pattern: str = "-{0}", patternWithValue: str = "-{0}={1}", **kwargs: Any) -> None: 

120 """ 

121 This method is called when a class is derived. 

122 

123 :param args: Any positional arguments. 

124 :param pattern: Optional, this pattern is used to format an argument without a value. |br| 

125 Default: ``"-{0}"``. 

126 :param patternWithValue: Optional, this pattern is used to format an argument with a value. |br| 

127 Default: ``"-{0}={1}"``. 

128 :param kwargs: Any keyword argument. 

129 """ 

130 kwargs["pattern"] = pattern 

131 kwargs["patternWithValue"] = patternWithValue 

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

133 

134 

135@export 

136@abstractclass 

137class LongOptionalValuedFlag(OptionalValuedFlag, pattern="--{0}", patternWithValue="--{0}={1}"): 

138 """ 

139 Represents a :py:class:`OptionalValuedFlag` with a double dash. 

140 

141 Example: ``--optimizer=on`` 

142 """ 

143 def __init_subclass__(cls, *args: Any, pattern: str = "--{0}", patternWithValue: str = "--{0}={1}", **kwargs: Any) -> None: 

144 """ 

145 This method is called when a class is derived. 

146 

147 :param args: Any positional arguments. 

148 :param pattern: Optional, this pattern is used to format an argument without a value. |br| 

149 Default: ``"--{0}"``. 

150 :param patternWithValue: Optional, this pattern is used to format an argument with a value. |br| 

151 Default: ``"--{0}={1}"``. 

152 :param kwargs: Any keyword argument. 

153 """ 

154 kwargs["pattern"] = pattern 

155 kwargs["patternWithValue"] = patternWithValue 

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

157 

158 

159@export 

160@abstractclass 

161class WindowsOptionalValuedFlag(OptionalValuedFlag, pattern="/{0}", patternWithValue="/{0}:{1}"): 

162 """ 

163 Represents a :py:class:`OptionalValuedFlag` with a single slash. 

164 

165 Example: ``/optimizer:on`` 

166 """ 

167 def __init_subclass__(cls, *args: Any, pattern: str = "/{0}", patternWithValue: str = "/{0}:{1}", **kwargs: Any) -> None: 

168 """ 

169 This method is called when a class is derived. 

170 

171 :param args: Any positional arguments. 

172 :param pattern: Optional, this pattern is used to format an argument without a value. |br| 

173 Default: ``"/{0}"``. 

174 :param patternWithValue: Optional, this pattern is used to format an argument with a value. |br| 

175 Default: ``"/{0}:{1}"``. 

176 :param kwargs: Any keyword argument. 

177 """ 

178 kwargs["pattern"] = pattern 

179 kwargs["patternWithValue"] = patternWithValue 

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