Argument

Summary

Package:

CLIAbstraction

Doc-string:

documented

File

Expected

Covered

Uncovered

Coverage

Argument.py

53

53

0

100.0%

Source

pyTooling/CLIAbstraction/Argument.pydocumentedundocumentedignoredexcludednot counted
32"""
33This module implements command line arguments without prefix character(s).
34
35"""
...
49
51__all__ = ["ValueT"]
52
54ValueT = TypeVar("ValueT")
55"""The type of value in a valued argument."""
56
58@export
59@abstractclass
60class CommandLineArgument(metaclass=ExtendedType):
61	"""
62	Base-class for all *Argument* classes.
63
64	An argument instance can be converted via ``AsArgument`` to a single string value or a sequence of string values
65	(tuple) usable e.g. with :class:`subprocess.Popen`. Each argument class implements at least one ``pattern`` parameter
66	to specify how argument are formatted.
67
68	There are multiple derived formats supporting:
69
70	* commands |br|
71	  |rarr| :mod:`~pyTooling.CLIAbstraction.Command`
72	* simple names (flags) |br|
73	  |rarr| :mod:`~pyTooling.CLIAbstraction.Flag`, :mod:`~pyTooling.CLIAbstraction.BooleanFlag`
74	* simple values (vlaued flags) |br|
75	  |rarr| :class:`~pyTooling.CLIAbstraction.Argument.StringArgument`, :class:`~pyTooling.CLIAbstraction.Argument.PathArgument`
76	* names and values |br|
77	  |rarr| :mod:`~pyTooling.CLIAbstraction.ValuedFlag`, :mod:`~pyTooling.CLIAbstraction.OptionalValuedFlag`
78	* key-value pairs |br|
79	  |rarr| :class:`~pyTooling.CLIAbstraction.KeyValueFlag.NamedKeyValuePairsArgument`
80	"""
81
82	_PATTERN: ClassVar[str]  #: Format string to render the argument on the command line.
83
84	def __init_subclass__(cls, *args: Any, pattern: Nullable[str] = None, **kwargs: Any) -> None:
85		"""
86		This method is called when a class is derived.
87
88		:param args:    Any positional arguments.
89		:param pattern: Optional, this pattern is used to format an argument. |br|
90		                Default: ``None``.
91		:param kwargs:  Any keyword argument.
92		"""
		...
95
98	@abstractmethod
99	def AsArgument(self) -> Union[str, Iterable[str]]:  # type: ignore[empty-body]
100		"""
101		Convert this argument instance to a string representation using the matching pattern based on
102		the internal name and value.
103
104		The result isn't escaped: :class:`subprocess.Popen` passes each string to the program as one argument.
105		:meth:`__str__` returns it escaped for a command line.
106
107		:returns:                    Formatted argument.
108		:raises NotImplementedError: This is an abstract method and must be overwritten by a subclass.
109		"""
		...
111
112	def __str__(self) -> str:
113		"""
114		Return this argument as written on a command line, escaped for the current platform.
115
116		:returns: The formatted argument, escaped by ``formatCommandLine``: :func:`shlex.join`, on Windows
117		          ``subprocess.list2cmdline()``.
118		"""
		...
124
125	@staticmethod
126	def _DoubleQuotedLiteral(value: str) -> str:
127		"""
128		Return a string as a Python literal in double quotes, escaped as :func:`repr` escapes it.
129
130		:param value: The string.
131		:returns:     The string's literal.
132		"""
		...
138
139	def __repr__(self) -> str:
140		"""
141		Return this argument as a Python literal, with strings in double quotes.
142
143		:returns: The formatted argument (:meth:`AsArgument`) as a literal; a sequence as a list.
144		"""
		...
152
154@export
155class ExecutableArgument(CommandLineArgument):
156	"""
157	Represents the executable.
158	"""
159
160	_executable: Path  #: Path to the executable this argument represents.
161
162	def __init__(self, executable: Path) -> None:
163		"""
164		Initializes a ExecutableArgument instance.
165
166		:param executable: Path to the executable.
167		:raises TypeError: If parameter 'executable' is not of type :class:`~pathlib.Path`.
168		"""
		...
175
176	@property
177	def Executable(self) -> Path:
178		"""
179		Property to access the path to the wrapped executable (:attr:`_executable`).
180
181		:returns:          Internal path to the executable.
182		:raises TypeError: If an assigned value is not of type :class:`~pathlib.Path`.
183		"""
		...
185
186	@Executable.setter
187	def Executable(self, value: Path) -> None:
		...
194
195	def AsArgument(self) -> Union[str, Iterable[str]]:
196		"""
197		Convert this argument instance to a string representation using the matching pattern based on
198		the internal path to the wrapped executable.
199
200		:returns: Formatted argument.
201		"""
		...
203
205@export
206class DelimiterArgument(CommandLineArgument, pattern="--"):
207	"""
208	Represents a delimiter symbol like ``--``.
209	"""
210
211	def __init_subclass__(cls, *args: Any, pattern: str = "--", **kwargs: Any) -> None:
212		"""
213		This method is called when a class is derived.
214
215		:param args:    Any positional arguments.
216		:param pattern: Optional, this pattern is used to format an argument. |br|
217		                Default: ``"--"``.
218		:param kwargs:  Any keyword argument.
219		"""
		...
222
223	def AsArgument(self) -> Union[str, Iterable[str]]:
224		"""
225		Convert this argument instance to a string representation using the matching pattern.
226
227		:returns: Formatted argument.
228		"""
		...
230
232@export
233@abstractclass
234class NamedArgument(CommandLineArgument, pattern="{0}"):
235	"""
236	Base-class for all command line arguments with a name.
237	"""
238
239	_NAME: ClassVar[str]  #: Name of the argument, inserted into :attr:`_PATTERN`.
240
241	def __init_subclass__(cls, *args: Any, name: Nullable[str] = None, pattern: str = "{0}", **kwargs: Any) -> None:
242		"""
243		This method is called when a class is derived.
244
245		:param args:    Any positional arguments.
246		:param name:    Optional, name of the CLI argument.
247		:param pattern: Optional, this pattern is used to format an argument. |br|
248		                Default: ``"{0}"``.
249		:param kwargs:  Any keyword argument.
250		"""
		...
254
255	@readonly
256	def Name(self) -> str:
257		"""
258		Get the internal name.
259
260		:returns: Internal name.
261		"""
		...
263
264	def AsArgument(self) -> Union[str, Iterable[str]]:
265		"""
266		Convert this argument instance to a string representation using the matching pattern based on
267		the internal name.
268
269		:returns:           Formatted argument.
270		:raises ValueError: If internal name is None.
271		"""
		...
276
278@export
279class ValuedArgument(CommandLineArgument, Generic[ValueT], pattern="{0}"):
280	"""
281	Base-class for all command line arguments with a value.
282	"""
283
284	_value: ValueT  #: Value of the argument, inserted into :attr:`_PATTERN`.
285
286	def __init_subclass__(cls, *args: Any, pattern: str = "{0}", **kwargs: Any) -> None:
287		"""
288		This method is called when a class is derived.
289
290		:param args:    Any positional arguments.
291		:param pattern: Optional, this pattern is used to format an argument. |br|
292		                Default: ``"{0}"``.
293		:param kwargs:  Any keyword argument.
294		"""
		...
297
298	def __init__(self, value: ValueT) -> None:
299		"""
300		Initializes a ValuedArgument instance.
301
302		:param value:       Value to be stored internally.
303		:raises ValueError: If parameter 'value' is None.
304		:raises ValueError: If parameter 'value' is None.
305		"""
		...
310
311	@property
312	def Value(self) -> ValueT:
313		"""
314		Property to access the internal value (:attr:`_value`).
315
316		:returns:           Internal value.
317		:raises ValueError: If ``None`` is assigned.
318		"""
		...
320
321	@Value.setter
322	def Value(self, value: ValueT) -> None:
		...
327
328	def AsArgument(self) -> Union[str, Iterable[str]]:
329		"""
330		Convert this argument instance to a string representation using the matching pattern based on
331		the internal value.
332
333		:returns: Formatted argument.
334		"""
		...
336
338class NamedAndValuedArgument(NamedArgument, ValuedArgument[ValueT], Generic[ValueT], pattern="{0}={1}"):
339	"""
340	Base-class for all command line arguments with a name and a value.
341	"""
342
343	def __init_subclass__(cls, *args: Any, name: Nullable[str] = None, pattern: str = "{0}={1}", **kwargs: Any) -> None:
344		"""
345		This method is called when a class is derived.
346
347		:param args:    Any positional arguments.
348		:param name:    Optional, name of the CLI argument.
349		:param pattern: Optional, this pattern is used to format an argument. |br|
350		                Default: ``"{0}={1}"``.
351		:param kwargs:  Any keyword argument.
352		"""
		...
359
360	def __init__(self, value: ValueT) -> None:
361		"""
362		Initialize the argument with the value rendered into its pattern.
363
364		:param value: Value of the argument.
365		"""
		...
367
368	def AsArgument(self) -> Union[str, Iterable[str]]:
369		"""
370		Convert this argument instance to a string representation using the matching pattern based on
371		the internal name and value.
372
373		:returns:           Formatted argument.
374		:raises ValueError: If internal name is None.
375		"""
		...
380
382@abstractclass
383class NamedTupledArgument(NamedArgument, ValuedArgument[ValueT], Generic[ValueT], pattern="{0}"):
384	"""
385	Class and base-class for all TupleFlag classes, which represents an argument with separate value.
386
387	A tuple argument is a command line argument followed by a separate value. Name and value are passed as two arguments
388	to the executable.
389
390	**Example: **
391
392	* `width 100``
393	"""
394
395	_VALUE_PATTERN: ClassVar[str]  #: Format string to render the argument's value as a second command line element.
396
397	def __init_subclass__(cls, *args: Any, name: Nullable[str] = None, pattern: str = "{0}", valuePattern: str = "{0}", **kwargs: Any) -> None:
398		"""
399		This method is called when a class is derived.
400
401		:param args:         Any positional arguments.
402		:param name:         Optional, name of the CLI argument.
403		:param pattern:      Optional, this pattern is used to format the CLI argument name. |br|
404		                     Default: ``"{0}"``.
405		:param valuePattern: Optional, this pattern is used to format the value. |br|
406		                     Default: ``"{0}"``.
407		:param kwargs:       Any keyword argument.
408		"""
		...
413
414	def __init__(self, value: ValueT) -> None:
415		"""
416		Initialize the argument with the value rendered into its pattern.
417
418		:param value: Value of the argument.
419		"""
		...
421
431	def AsArgument(self) -> Union[str, Iterable[str]]:
432		"""
433		Convert this argument instance to a sequence of string representations using the matching
434		pattern based on the internal name and value.
435
436		:returns:           Formatted argument as tuple of strings.
437		:raises ValueError: If internal name is None.
438		"""
		...
446
448@export
449class StringArgument(ValuedArgument[str], pattern="{0}"):
450	"""
451	Represents a simple string argument.
452
453	A list of strings is available as :class:`~pyTooling.CLIAbstraction.Argument.StringListArgument`.
454	"""
455
456	def __init_subclass__(cls, *args: Any, pattern: str = "{0}", **kwargs: Any) -> None:
457		"""
458		This method is called when a class is derived.
459
460		:param args:    Any positional arguments.
461		:param pattern: Optional, this pattern is used to format an argument. |br|
462		                Default: ``"{0}"``.
463		:param kwargs:  Any keyword argument.
464		"""
		...
467
469@export
470class StringListArgument(ValuedArgument[str]):
471	"""
472	Represents a list of string argument (:class:`~pyTooling.CLIAbstraction.Argument.StringArgument`)."""
473
474	def __init__(self, values: Iterable[str]) -> None:
475		"""
476		Initializes a StringListArgument instance.
477
478		:param values:     An iterable of str instances.
479		:raises TypeError: If iterable parameter 'values' contains elements not of type string.
480		"""
		...
489
490	@property
491	def Value(self) -> list[str]:
492		"""
493		Property to access the internal list of str objects (:attr:`_values`).
494
495		.. note:: On assignment, the list object is not replaced, but cleared and then reused by adding the given elements
496		   of the iterable.
497
498		:returns:          Reference to the internal list of str objects.
499		:raises TypeError: If an assigned iterable contains elements which are not of type string.
500		"""
		...
502
503	@Value.setter
504	def Value(self, value: Iterable[str]) -> None:
		...
512
513	def AsArgument(self) -> Union[str, Iterable[str]]:
514		"""
515		Convert this argument instance to a string representation using the matching pattern based on
516		the internal value.
517
518		:returns: Sequence of formatted arguments.
519		"""
		...
521
524@export
525class PathArgument(CommandLineArgument):
526	"""
527	Represents a single path argument.
528
529	A list of paths is available as :class:`~pyTooling.CLIAbstraction.Argument.PathListArgument`.
530	"""
532	_path: Path  #: Path this argument represents.
533
534	def __init__(self, path: Path) -> None:
535		"""
536		Initializes a PathArgument instance.
537
538		:param path:       Path to a filesystem object.
539		:raises TypeError: If parameter 'path' is not of type :class:`~pathlib.Path`.
540		"""
		...
546
547	@property
548	def Value(self) -> Path:
549		"""
550		Property to access the internal path object (:attr:`_path`).
551
552		:returns:          Internal path object.
553		:raises TypeError: If an assigned value is not of type :class:`~pathlib.Path`.
554		"""
		...
556
557	@Value.setter
558	def Value(self, value: Path) -> None:
		...
565
566	def AsArgument(self) -> Union[str, Iterable[str]]:
567		"""
568		Convert this argument instance to a string representation using the matching pattern based on
569		the internal value.
570
571		:returns: Formatted argument.
572		"""
		...
574
576@export
577class PathListArgument(CommandLineArgument):
578	"""
579	Represents a list of path arguments  (:class:`~pyTooling.CLIAbstraction.Argument.PathArgument`).
580	"""
582	_paths: list[Path]  #: Paths this argument represents.
583
584	def __init__(self, paths: Iterable[Path]) -> None:
585		"""
586		Initializes a PathListArgument instance.
587
588		:param paths:      An iterable os Path instances.
589		:raises TypeError: If iterable parameter 'paths' contains elements not of type :class:`~pathlib.Path`.
590		"""
		...
599
600	@property
601	def Value(self) -> list[Path]:
602		"""
603		Property to access the internal list of path objects (:attr:`_paths`).
604
605		.. note:: On assignment, the list object is not replaced, but cleared and then reused by adding the given elements
606		   of the iterable.
607
608		:returns:          Reference to the internal list of path objects.
609		:raises TypeError: If an assigned iterable contains elements which are not of type :class:`~pathlib.Path`.
610		"""
		...
612
613	@Value.setter
614	def Value(self, value: Iterable[Path]) -> None:
		...
622
623	def AsArgument(self) -> Union[str, Iterable[str]]:
624		"""
625		Convert this argument instance to a string representation using the matching pattern based on
626		the internal value.
627
628		:returns: Sequence of formatted arguments.
629		"""
		...