Coverage for pyTooling/Attributes/ArgParse/ValuedFlag.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 options carrying a value, like ``--count=25``. 

34""" 

35from typing import Optional as Nullable 

36 

37from pyTooling.Decorators import export 

38from pyTooling.Attributes.ArgParse.Argument import NamedAndValuedArgument 

39 

40 

41@export 

42class ValuedFlag(NamedAndValuedArgument): 

43 """ 

44 Defines a switch argument like ``--count=25``. 

45 

46 Some of the named parameters passed to :meth:`~argparse.ArgumentParser.add_argument` are predefined (or 

47 overwritten), so the value following the switch is passed to the registered handler method. 

48 """ 

49 

50 def __init__(self, short: Nullable[str] = None, long: Nullable[str] = None, dest: Nullable[str] = None, metaName: Nullable[str] = None, optional: bool = False, help: Nullable[str] = None) -> None: 

51 """ 

52 Initializes a flag argument taking a value. 

53 

54 .. admonition:: ArgParse parameterization 

55 

56 :meth:`~argparse.ArgumentParser.add_argument` is called with the option strings from ``short`` and ``long`` 

57 as positional parameters, and with these named parameters: 

58 

59 * ``dest=dest`` 

60 * ``metavar=metaName`` 

61 * ``default=None`` 

62 * ``help=help`` 

63 * ``required=not optional`` 

64 

65 No ``action`` is set, so argparse's default ``"store"`` applies and the handler method receives the value. 

66 

67 :param short: Optional, short option name including the dash, e.g. ``"-o"``. Default: ``None``. 

68 :param long: Optional, long option name including the dashes, e.g. ``"--output"``. Default: ``None``. 

69 :param dest: Optional, name the value is stored under in the :class:`~argparse.Namespace`. Default: ``None``. 

70 :param metaName: Optional, name shown for the value in the help page (``metavar``). Default: ``None``. 

71 :param optional: Optional, if ``True``, the value may be omitted. Default: ``False``. 

72 :param help: Optional, help text shown for this argument. Default: ``None``. 

73 """ 

74 args = [] 

75 if short is not None: 

76 args.append(short) 

77 if long is not None: 

78 args.append(long) 

79 

80 kwargs = { 

81 "dest": dest, 

82 "metavar": metaName, 

83 "default": None, 

84 "help": help, 

85 "required": not optional 

86 } 

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

88 

89 

90@export 

91class ShortValuedFlag(ValuedFlag): 

92 """Defines a switch argument with a value in short form like ``-c=25``.""" 

93 

94 def __init__(self, short: Nullable[str] = None, dest: Nullable[str] = None, metaName: Nullable[str] = None, optional: bool = False, help: Nullable[str] = None) -> None: 

95 """ 

96 Initialize a switch argument with a value in its short form. 

97 

98 :param short: Optional, short form of the option, including its dash, e.g. :pycode:`short="-v"`. 

99 :param dest: Optional, name of the parameter the parsed value is passed to the handler method as. 

100 :param metaName: Optional, name of the value in the help page. 

101 :param optional: Optional, if ``True``, the option may be omitted. 

102 :param help: Optional, help text of the option, displayed in the help page. 

103 """ 

104 super().__init__(short, None, dest, metaName, optional, help) 

105 

106 

107@export 

108class LongValuedFlag(ValuedFlag): 

109 """Defines a switch argument with a value in long form like ``--count=25``.""" 

110 

111 def __init__(self, long: Nullable[str] = None, dest: Nullable[str] = None, metaName: Nullable[str] = None, optional: bool = False, help: Nullable[str] = None) -> None: 

112 """ 

113 Initialize a switch argument with a value in its long form. 

114 

115 :param long: Optional, long form of the option, including its dashes, e.g. :pycode:`long="--verbose"`. 

116 :param dest: Optional, name of the parameter the parsed value is passed to the handler method as. 

117 :param metaName: Optional, name of the value in the help page. 

118 :param optional: Optional, if ``True``, the option may be omitted. 

119 :param help: Optional, help text of the option, displayed in the help page. 

120 """ 

121 super().__init__(None, long, dest, metaName, optional, help)