Coverage for pyTooling/Attributes/ArgParse/Argument.py: 100%

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 2007-2016 Patrick Lehmann - Dresden, Germany # 

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""" 

33Attributes describing positional command line arguments. 

34 

35A positional argument has no option name: it is recognized by its position, and its value is converted to the type the 

36attribute declares before the handler method is called: 

37 

38* :class:`~pyTooling.Attributes.ArgParse.Argument.StringArgument` 

39* :class:`~pyTooling.Attributes.ArgParse.Argument.IntegerArgument` 

40* :class:`~pyTooling.Attributes.ArgParse.Argument.FloatArgument` 

41* :class:`~pyTooling.Attributes.ArgParse.Argument.PathArgument` 

42* :class:`~pyTooling.Attributes.ArgParse.Argument.ListArgument` and its typed variants 

43 (:class:`~pyTooling.Attributes.ArgParse.Argument.StringListArgument`, 

44 :class:`~pyTooling.Attributes.ArgParse.Argument.IntegerListArgument`, 

45 :class:`~pyTooling.Attributes.ArgParse.Argument.FloatListArgument`, 

46 :class:`~pyTooling.Attributes.ArgParse.Argument.PathListArgument`) 

47""" 

48from pathlib import Path 

49 

50 

51from pyTooling.Decorators import export 

52from pyTooling.Attributes.ArgParse import CommandLineArgument 

53 

54 

55@export 

56class DelimiterArgument(CommandLineArgument): 

57 """ 

58 Represents a delimiter symbol like ``--``. 

59 """ 

60 

61 

62@export 

63class NamedArgument(CommandLineArgument): 

64 """ 

65 Base-class for all command line arguments with a name. 

66 """ 

67 

68 

69@export 

70class ValuedArgument(CommandLineArgument): 

71 """ 

72 Base-class for all command line arguments with a value. 

73 """ 

74 

75 

76@export 

77class NamedAndValuedArgument(NamedArgument, ValuedArgument): 

78 """ 

79 Base-class for all command line arguments with a name and a value. 

80 """ 

81 

82 

83@export 

84class NamedTupledArgument(NamedArgument, ValuedArgument): 

85 """ 

86 Class and base-class for all TupleFlag classes, which represents an argument with separate value. 

87 

88 A tuple argument is a command line argument followed by a separate value. Name and value are passed as two arguments 

89 to the executable. 

90 

91 **Example:** 

92 

93 * ``width 100`` 

94 """ 

95 

96 

97@export 

98class PositionalArgument(ValuedArgument): 

99 """ 

100 Represents a simple string argument containing any information encoded in a string. 

101 

102 TODO 

103 

104 A list of strings is available as :class:`~pyTooling.Attributes.ArgParse.Argument.StringListArgument`. 

105 """ 

106 

107 def __init__(self, dest: str, metaName: str, type: type = str, optional: bool = False, help: str = "") -> None: 

108 """ 

109 Initializes a positional argument. 

110 

111 .. admonition:: ArgParse parameterization 

112 

113 :meth:`~argparse.ArgumentParser.add_argument` is called without positional parameters, and with these named 

114 parameters: 

115 

116 * ``dest=dest`` 

117 * ``metavar=metaName`` 

118 * ``type=type`` 

119 * ``help=help`` 

120 * ``nargs="?"`` - only if ``optional`` is ``True`` 

121 

122 :param dest: Name the parsed value is stored under in the :class:`~argparse.Namespace`, and the name the 

123 handler method reads it by. 

124 :param metaName: Name shown for the value in the usage line and the help page (argparse's ``metavar``). 

125 :param type: Optional, callable converting the argument's string to the target type. Default: :class:`str`. 

126 :param optional: Optional, if ``True``, the argument may be omitted (``nargs="?"``). Default: ``False``. 

127 :param help: Optional, help text shown for this argument in the help page. Default: ``""``. 

128 """ 

129 args: list[str] = [] 

130 kwargs = { 

131 "dest": dest, 

132 "metavar": metaName, 

133 "type": type, 

134 "help": help 

135 } 

136 if optional: 

137 kwargs["nargs"] = "?" 

138 

139 super().__init__(*args, **kwargs) 

140 

141 

142@export 

143class StringArgument(PositionalArgument): 

144 """ 

145 Represents a simple string argument. 

146 

147 A list of strings is available as :class:`~pyTooling.Attributes.ArgParse.Argument.StringListArgument`. 

148 """ 

149 

150 def __init__(self, dest: str, metaName: str, optional: bool = False, help: str = "") -> None: 

151 """ 

152 Initializes a positional string argument. 

153 

154 Parameterizes :meth:`~argparse.ArgumentParser.add_argument` like 

155 :class:`~pyTooling.Attributes.ArgParse.Argument.PositionalArgument` does, with ``type`` set to :class:`str`. 

156 

157 :param dest: Name the parsed value is stored under in the :class:`~argparse.Namespace`, and the name the 

158 handler method reads it by. 

159 :param metaName: Name shown for the value in the usage line and the help page (argparse's ``metavar``). 

160 :param optional: Optional, if ``True``, the argument may be omitted (``nargs="?"``). Default: ``False``. 

161 :param help: Optional, help text shown for this argument in the help page. Default: ``""``. 

162 """ 

163 super().__init__(dest, metaName, str, optional, help) 

164 

165 

166@export 

167class IntegerArgument(PositionalArgument): 

168 """ 

169 Represents an integer argument. 

170 

171 A list of integer numbers is available as :class:`~pyTooling.Attributes.ArgParse.Argument.IntegerListArgument`. 

172 """ 

173 

174 def __init__(self, dest: str, metaName: str, optional: bool = False, help: str = "") -> None: 

175 """ 

176 Initializes a positional integer argument. 

177 

178 Parameterizes :meth:`~argparse.ArgumentParser.add_argument` like 

179 :class:`~pyTooling.Attributes.ArgParse.Argument.PositionalArgument` does, with ``type`` set to :class:`int`. 

180 

181 :param dest: Name the parsed value is stored under in the :class:`~argparse.Namespace`, and the name the 

182 handler method reads it by. 

183 :param metaName: Name shown for the value in the usage line and the help page (argparse's ``metavar``). 

184 :param optional: Optional, if ``True``, the argument may be omitted (``nargs="?"``). Default: ``False``. 

185 :param help: Optional, help text shown for this argument in the help page. Default: ``""``. 

186 """ 

187 super().__init__(dest, metaName, int, optional, help) 

188 

189 

190@export 

191class FloatArgument(PositionalArgument): 

192 """ 

193 Represents a floating point number argument. 

194 

195 A list of floating point numbers is available as :class:`~pyTooling.Attributes.ArgParse.Argument.FloatListArgument`. 

196 """ 

197 

198 def __init__(self, dest: str, metaName: str, optional: bool = False, help: str = "") -> None: 

199 """ 

200 Initializes a positional floating point number argument. 

201 

202 Parameterizes :meth:`~argparse.ArgumentParser.add_argument` like 

203 :class:`~pyTooling.Attributes.ArgParse.Argument.PositionalArgument` does, with ``type`` set to :class:`float`. 

204 

205 :param dest: Name the parsed value is stored under in the :class:`~argparse.Namespace`, and the name the 

206 handler method reads it by. 

207 :param metaName: Name shown for the value in the usage line and the help page (argparse's ``metavar``). 

208 :param optional: Optional, if ``True``, the argument may be omitted (``nargs="?"``). Default: ``False``. 

209 :param help: Optional, help text shown for this argument in the help page. Default: ``""``. 

210 """ 

211 super().__init__(dest, metaName, float, optional, help) 

212 

213 

214# TODO: Add option to class if path should be checked for existence 

215@export 

216class PathArgument(PositionalArgument): 

217 """ 

218 Represents a single path argument. 

219 

220 A list of paths is available as :class:`~pyTooling.Attributes.ArgParse.Argument.PathListArgument`. 

221 """ 

222 

223 def __init__(self, dest: str, metaName: str, optional: bool = False, help: str = "") -> None: 

224 """ 

225 Initializes a positional path argument. 

226 

227 Parameterizes :meth:`~argparse.ArgumentParser.add_argument` like 

228 :class:`~pyTooling.Attributes.ArgParse.Argument.PositionalArgument` does, with ``type`` set to 

229 :class:`~pathlib.Path`. 

230 

231 :param dest: Name the parsed value is stored under in the :class:`~argparse.Namespace`, and the name the 

232 handler method reads it by. 

233 :param metaName: Name shown for the value in the usage line and the help page (argparse's ``metavar``). 

234 :param optional: Optional, if ``True``, the argument may be omitted (``nargs="?"``). Default: ``False``. 

235 :param help: Optional, help text shown for this argument in the help page. Default: ``""``. 

236 """ 

237 super().__init__(dest, metaName, Path, optional, help) 

238 

239 

240@export 

241class ListArgument(ValuedArgument): 

242 """ 

243 Represents a list of values (:class:`~pyTooling.Attributes.ArgParse.Argument.StringArgument`). 

244 """ 

245 

246 def __init__(self, dest: str, metaName: str, type: type = str, optional: bool = False, help: str = "") -> None: 

247 """ 

248 Initializes a positional argument accepting a list of values. 

249 

250 .. admonition:: ArgParse parameterization 

251 

252 :meth:`~argparse.ArgumentParser.add_argument` is called without positional parameters, and with these named 

253 parameters: 

254 

255 * ``dest=dest`` 

256 * ``metavar=metaName`` 

257 * ``nargs="*"`` if ``optional`` is ``True``, otherwise ``"+"`` 

258 * ``type=type`` 

259 * ``help=help`` 

260 

261 :param dest: Name the parsed value is stored under in the :class:`~argparse.Namespace`, and the name the 

262 handler method reads it by. 

263 :param metaName: Name shown for the value in the usage line and the help page (argparse's ``metavar``). 

264 :param type: Optional, callable converting each value's string to the target type. Default: :class:`str`. 

265 :param optional: Optional, if ``True``, an empty list is accepted (``nargs="*"``); otherwise at least one value is 

266 required (``nargs="+"``). Default: ``False``. 

267 :param help: Optional, help text shown for this argument in the help page. Default: ``""``. 

268 """ 

269 args: list[str] = [] 

270 kwargs = { 

271 "dest": dest, 

272 "metavar": metaName, 

273 "nargs": "*" if optional else "+", 

274 "type": type, 

275 "help": help 

276 } 

277 super().__init__(*args, **kwargs) 

278 

279 

280@export 

281class StringListArgument(ListArgument): 

282 """ 

283 Represents a list of string arguments (:class:`~pyTooling.Attributes.ArgParse.Argument.StringArgument`). 

284 """ 

285 

286 def __init__(self, dest: str, metaName: str, optional: bool = False, help: str = "") -> None: 

287 """ 

288 Initializes a positional argument accepting a list of string values. 

289 

290 Parameterizes :meth:`~argparse.ArgumentParser.add_argument` like 

291 :class:`~pyTooling.Attributes.ArgParse.Argument.ListArgument` does, with ``type`` set to :class:`str`. 

292 

293 :param dest: Name the parsed value is stored under in the :class:`~argparse.Namespace`, and the name the 

294 handler method reads it by. 

295 :param metaName: Name shown for the value in the usage line and the help page (argparse's ``metavar``). 

296 :param optional: Optional, if ``True``, an empty list is accepted (``nargs="*"``); otherwise at least one value is 

297 required (``nargs="+"``). Default: ``False``. 

298 :param help: Optional, help text shown for this argument in the help page. Default: ``""``. 

299 """ 

300 super().__init__(dest, metaName, str, optional, help) 

301 

302 

303@export 

304class IntegerListArgument(ListArgument): 

305 """ 

306 Represents a list of integer number arguments (:class:`~pyTooling.Attributes.ArgParse.Argument.IntegerArgument`). 

307 """ 

308 

309 def __init__(self, dest: str, metaName: str, optional: bool = False, help: str = "") -> None: 

310 """ 

311 Initializes a positional argument accepting a list of integer numbers. 

312 

313 Parameterizes :meth:`~argparse.ArgumentParser.add_argument` like 

314 :class:`~pyTooling.Attributes.ArgParse.Argument.ListArgument` does, with ``type`` set to :class:`int`. 

315 

316 :param dest: Name the parsed value is stored under in the :class:`~argparse.Namespace`, and the name the 

317 handler method reads it by. 

318 :param metaName: Name shown for the value in the usage line and the help page (argparse's ``metavar``). 

319 :param optional: Optional, if ``True``, an empty list is accepted (``nargs="*"``); otherwise at least one value is 

320 required (``nargs="+"``). Default: ``False``. 

321 :param help: Optional, help text shown for this argument in the help page. Default: ``""``. 

322 """ 

323 super().__init__(dest, metaName, int, optional, help) 

324 

325 

326@export 

327class FloatListArgument(ListArgument): 

328 """ 

329 Represents a list of floating point number arguments (:class:`~pyTooling.Attributes.ArgParse.Argument.FloatArgument`). 

330 """ 

331 

332 def __init__(self, dest: str, metaName: str, optional: bool = False, help: str = "") -> None: 

333 """ 

334 Initializes a positional argument accepting a list of floating point numbers. 

335 

336 Parameterizes :meth:`~argparse.ArgumentParser.add_argument` like 

337 :class:`~pyTooling.Attributes.ArgParse.Argument.ListArgument` does, with ``type`` set to :class:`float`. 

338 

339 :param dest: Name the parsed value is stored under in the :class:`~argparse.Namespace`, and the name the 

340 handler method reads it by. 

341 :param metaName: Name shown for the value in the usage line and the help page (argparse's ``metavar``). 

342 :param optional: Optional, if ``True``, an empty list is accepted (``nargs="*"``); otherwise at least one value is 

343 required (``nargs="+"``). Default: ``False``. 

344 :param help: Optional, help text shown for this argument in the help page. Default: ``""``. 

345 """ 

346 super().__init__(dest, metaName, float, optional, help) 

347 

348 

349@export 

350class PathListArgument(ListArgument): 

351 """ 

352 Represents a list of path arguments (:class:`~pyTooling.Attributes.ArgParse.Argument.PathArgument`). 

353 """ 

354 

355 def __init__(self, dest: str, metaName: str, optional: bool = False, help: str = "") -> None: 

356 """ 

357 Initializes a positional argument accepting a list of path arguments. 

358 

359 Parameterizes :meth:`~argparse.ArgumentParser.add_argument` like 

360 :class:`~pyTooling.Attributes.ArgParse.Argument.ListArgument` does, with ``type`` set to 

361 :class:`~pathlib.Path`. 

362 

363 :param dest: Name the parsed value is stored under in the :class:`~argparse.Namespace`, and the name the 

364 handler method reads it by. 

365 :param metaName: Name shown for the value in the usage line and the help page (argparse's ``metavar``). 

366 :param optional: Optional, if ``True``, an empty list is accepted (``nargs="*"``); otherwise at least one value is 

367 required (``nargs="+"``). Default: ``False``. 

368 :param help: Optional, help text shown for this argument in the help page. Default: ``""``. 

369 """ 

370 super().__init__(dest, metaName, Path, optional, help)