BooleanFlag

Summary

Package:

CLIAbstraction

Doc-string:

documented

File

Expected

Covered

Uncovered

Coverage

BooleanFlag.py

12

12

0

100.0%

Source

pyTooling/CLIAbstraction/BooleanFlag.pydocumentedundocumentedignoredexcludednot counted
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"""
...
49
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	_FALSE_PATTERN: 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		"""
		...
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		"""
		...
96
97	def AsArgument(self) -> Union[str, Iterable[str]]:
98		"""Convert this argument instance to a string representation 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		"""
		...
109
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		"""
		...
138
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		"""
		...
167
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		"""
		...