__init__.py

Summary

Lines:

201 of 256 covered (78.5%)

Branches:

62 of 84 taken (73.8%), 10 lines partially

Coverage:

77.4%

Directory:

CLIAbstraction

Missed lines:

127, 134-135, 174, 183, 284-286, 293, 344-346, 361-363, 439-442, 523-526, 542-543, 554-563, 578, 581, 588-589, 630-643, 656, 672, 703-708, 718, 728, 738

Source

pyTooling/CLIAbstraction/__init__.pycoveredpartialuncoveredexcludednot executable

# ==================================================================================================================== #
#             _____           _ _               ____ _     ___    _    _         _                  _   _              #
#  _ __  _   |_   _|__   ___ | (_)_ __   __ _  / ___| |   |_ _|  / \  | |__  ___| |_ _ __ __ _  ___| |_(_) ___  _ __   #
# | '_ \| | | || |/ _ \ / _ \| | | '_ \ / _` || |   | |    | |  / _ \ | '_ \/ __| __| '__/ _` |/ __| __| |/ _ \| '_ \  #
# | |_) | |_| || | (_) | (_) | | | | | | (_| || |___| |___ | | / ___ \| |_) \__ \ |_| | | (_| | (__| |_| | (_) | | | | #
# | .__/ \__, ||_|\___/ \___/|_|_|_| |_|\__, (_)____|_____|___/_/   \_\_.__/|___/\__|_|  \__,_|\___|\__|_|\___/|_| |_| #
# |_|    |___/                          |___/                                                                          #
# ==================================================================================================================== #
# Authors:                                                                                                             #
#   Patrick Lehmann                                                                                                    #
#                                                                                                                      #
# License:                                                                                                             #
# ==================================================================================================================== #
# Copyright 2017-2026 Patrick Lehmann - Bötzingen, Germany                                                             #
# Copyright 2014-2016 Technische Universität Dresden - Germany, Chair of VLSI-Design, Diagnostics and Architecture     #
#                                                                                                                      #
# Licensed under the Apache License, Version 2.0 (the "License");                                                      #
# you may not use this file except in compliance with the License.                                                     #
# You may obtain a copy of the License at                                                                              #
#                                                                                                                      #
#   http://www.apache.org/licenses/LICENSE-2.0                                                                         #
#                                                                                                                      #
# Unless required by applicable law or agreed to in writing, software                                                  #
# distributed under the License is distributed on an "AS IS" BASIS,                                                    #
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.                                             #
# See the License for the specific language governing permissions and                                                  #
# limitations under the License.                                                                                       #
#                                                                                                                      #
# SPDX-License-Identifier: Apache-2.0                                                                                  #
# ==================================================================================================================== #
#
"""
Basic abstraction layer for executables.

.. seealso::

   :mod:`pyTooling.Attributes.ArgParse`
      |rarr| The other direction: describing the command line a program accepts.
   :mod:`pyTooling.TerminalUI`
      |rarr| Writing the program's own messages to the terminal.
   :mod:`pyTooling.Platform`
      |rarr| Deciding which executable name and path style the current platform uses.
"""
from __future__ import annotations

# __keywords__ =  ["abstract", "executable", "cli", "cli arguments"]

from os         import environ as os_environ
from pathlib    import Path
from platform   import system
from shutil     import which as shutil_which
from subprocess import Popen as Subprocess_Popen, PIPE as Subprocess_Pipe, STDOUT as Subprocess_StdOut, TimeoutExpired
from typing     import Optional as Nullable, ClassVar, Iterator, Generator, Any, Mapping, Iterable

from pyTooling.Decorators                import export, readonly
from pyTooling.MetaClasses               import ExtendedType
from pyTooling.Exceptions                import ToolingException, PlatformNotSupportedError
from pyTooling.Common                    import getFullyQualifiedName, getTypeName
from pyTooling.Attributes                import Attribute
from pyTooling.CLIAbstraction.Argument   import CommandLineArgument, formatCommandLine, NamedAndValuedArgument, \
                                                ValuedArgument, PathArgument, PathListArgument, NamedTupledArgument
from pyTooling.CLIAbstraction.ValuedFlag import ValuedFlag
from pyTooling.Platform                  import Platform


_Path = Path
"""
Alias of :class:`~pathlib.Path` for annotations in a class with a property named ``Path``, which the class body binds.
"""


@export
class CLIAbstractionError(ToolingException):
	"""Base-exception of all exceptions raised by :mod:`pyTooling.CLIAbstraction`."""


@export
class DryRunError(CLIAbstractionError):
	"""This exception is raised if an executable is launched while in dry-run mode."""


@export
class CLIArgument(Attribute):
	"""An attribute to annotate nested classes as an CLI argument."""


@export
class Environment(metaclass=ExtendedType, slots=True):
	"""
	A class describing the environment of an executable.

	.. topic:: Content of the environment

	   * Environment variables
	"""
	_variables: dict[str, str]  #: Dictionary of active environment variables.

	# TODO: derive environment from existing environment object.
	def __init__(
		self, *,
		environment:  Nullable[Environment] = None,
		newVariables: Nullable[Mapping[str, str]] = None,
		addVariables: Nullable[Mapping[str, str]] = None,
		delVariables: Nullable[Iterable[str]] = None
	) -> None:
		"""
		Initializes an environment class managing.

		.. topic:: Algorithm

			 1. Create a new dictionary of environment variables (name-value pairs) from either:

			    * an existing :class:`Environment` instance.
			    * current executable's environment by reading environment variables from :func:`os.environ`.
			    * a dictionary of name-value pairs.

			 2. Remove variables from environment.
			 3. Add new or update existing variables.

		:param environment:  Optional, existing Environment instance to derive a new environment.
		:param newVariables: Optional, dictionary of new environment variables. |br|
		                     If ``None``, read current environment variables from :func:`os.environ`.
		:param addVariables: Optional, dictionary of variables to be added or modified in the environment.
		:param delVariables: Optional, list of variable names to be removed from the environment.
		"""
		if environment is not None:
			newVariables = environment._variables
		elif newVariables is None:
			newVariables = os_environ

		self._variables = dict(newVariables)

		if delVariables is not None:
			for variableName in delVariables:
				del self._variables[variableName]

		if addVariables is not None:
			self._variables.update(addVariables)

	def __len__(self) -> len:
		"""
		Returns the number of set environment variables.

		:returns: Number of environment variables.
		"""
		return len(self._variables)

	def __contains__(self, name: str) -> bool:
		"""
		Checks if the variable is set in the environment.

		:param name: The variable name to check.
		:returns:    ``True``, if the variable is set in the environment.
		"""
		return name in self._variables

	def __getitem__(self, name: str) -> str:
		"""
		Access an environment variable in the environment by name.

		:param name:      Name of the environment variable.
		:returns:         The environment variable's value.
		:raises KeyError: If Variable name is not set in the environment.
		"""
		return self._variables[name]

	def __setitem__(self, name: str, value: str) -> None:
		"""
		Add or set an environment variable in the environment by name.

		:param name:  Name of the environment variable.
		:param value: Value of the environment variable to be set.
		"""
		self._variables[name] = value

	def __delitem__(self, name: str) -> None:
		"""
		Remove an environment variable from the environment by name.

		:param name:      The name of the environment variable to remove.
		:raises KeyError: If name doesn't exist in the environment.
		"""
		del self._variables[name]


@export
class Program(metaclass=ExtendedType, slots=True):
	"""
	Represent a simple command line interface (CLI) executable (program or script).

	CLI options are collected in a ``__cliOptions__`` dictionary.
	"""

	_platform:         str                                                   #: Current platform the executable runs on (Linux, Windows, ...)
	_EXECUTABLE_NAMES: ClassVar[dict[str, str]]                              #: Dictionary of platform specific executable names.
	_executablePath:   _Path                                                 #: The path to the executable (binary, script, ...).
	_dryRun:           bool                                                  #: True, if program shall run in *dry-run mode*.
	_dryRunMessages:   list[str]                                             #: Actions skipped in *dry-run mode*.
	__cliOptions__:    ClassVar[dict[type[CommandLineArgument], int]]        #: List of all possible CLI options.
	__cliParameters__: dict[type[CommandLineArgument], CommandLineArgument]  #: List of all CLI parameters.

	def __init_subclass__(cls, *args: Any, **kwargs: Any) -> None:
		"""
		Whenever a subclass is derived from :class:``Program``, all nested classes declared within ``Program`` and which are
		marked with attribute ``CLIArgument`` are collected and then listed in the ``__cliOptions__`` dictionary.

		:param args:   Any positional arguments.
		:param kwargs: Any keyword arguments.
		"""
		super().__init_subclass__(*args, **kwargs)

		# register all available CLI options (nested classes marked with attribute 'CLIArgument')
		options: dict[type[CommandLineArgument], int] = {
			option: order
			for order, option in enumerate(CLIArgument.GetClasses(scope=cls))
		}
		cls.__cliOptions__ = options

	def __init__(
		self,
		executablePath: Nullable[Path] = None,
		binaryDirectoryPath: Nullable[Path] = None,
		dryRun: bool = False
	) -> None:
		"""
		Initializes a program instance.

		.. todo:: Document algorithm

		:param executablePath:       Optional, path to the executable.
		:param binaryDirectoryPath:  Optional, path to the executable's directory.
		:param dryRun:               Optional, ``True``, when the program should run in dryrun mode.
		:raises TypeError:           If parameter 'executablePath' is not of type :class:`~pathlib.Path`.
		:raises CLIAbstractionError: If the executable doesn't exist at the given path.
		"""
		self._platform =       system()
		self._dryRun =         dryRun
		self._dryRunMessages = []

		if executablePath is not None:
			if isinstance(executablePath, Path):
				if not executablePath.exists():
					if dryRun:
						self.LogDryRun(f"File check for '{executablePath}' failed. [SKIPPING]")
					else:
						raise CLIAbstractionError(f"Program '{executablePath}' not found.") from FileNotFoundError(executablePath)
			else:
				ex = TypeError("Parameter 'executablePath' is not of type 'Path'.")
				ex.add_note(f"Got type '{getFullyQualifiedName(executablePath)}'.")
				raise ex
		elif binaryDirectoryPath is not None:
			if isinstance(binaryDirectoryPath, Path):
				if not binaryDirectoryPath.exists():
					if dryRun:
						self.LogDryRun(f"Directory check for '{binaryDirectoryPath}' failed. [SKIPPING]")
					else:
						raise CLIAbstractionError(f"Binary directory '{binaryDirectoryPath}' not found.") from FileNotFoundError(binaryDirectoryPath)

				try:
					executablePath = binaryDirectoryPath / self.__class__._EXECUTABLE_NAMES[self._platform]
				except KeyError:
					raise CLIAbstractionError(f"Program is not supported on platform '{self._platform}'.") from PlatformNotSupportedError(self._platform)

				if not executablePath.exists():
					if dryRun:
						self.LogDryRun(f"File check for '{executablePath}' failed. [SKIPPING]")
					else:
						raise CLIAbstractionError(f"Program '{executablePath}' not found.") from FileNotFoundError(executablePath)
			else:
				ex = TypeError("Parameter 'binaryDirectoryPath' is not of type 'Path'.")
				ex.add_note(f"Got type '{getFullyQualifiedName(binaryDirectoryPath)}'.")
				raise ex
		else:
			try:
				executablePath = Path(self._EXECUTABLE_NAMES[self._platform])
			except KeyError:
				raise CLIAbstractionError(f"Program is not supported on platform '{self._platform}'.") from PlatformNotSupportedError(self._platform)

			resolvedExecutable = shutil_which(str(executablePath))
			if dryRun:
				if resolvedExecutable is None:
					self.LogDryRun(f"Search for '{executablePath}' in PATH failed. [SKIPPING]")
				else:
					fullExecutablePath = Path(resolvedExecutable)
					if not fullExecutablePath.exists():
						self.LogDryRun(f"File check for '{fullExecutablePath}' failed. [SKIPPING]")
			else:
				if resolvedExecutable is None:
					raise CLIAbstractionError("Program could not be found in PATH.") from FileNotFoundError(executablePath)

				fullExecutablePath = Path(resolvedExecutable)
				if not fullExecutablePath.exists():
					raise CLIAbstractionError(f"Program '{fullExecutablePath}' not found.") from FileNotFoundError(fullExecutablePath)

			if resolvedExecutable is not None:
				executablePath = Path(resolvedExecutable)

			# TODO: log found executable in PATH
			# TODO: check if found executable has execute permissions
			# raise ValueError(f"Neither parameter 'executablePath' nor 'binaryDirectoryPath' was set.")

		self._executablePath = executablePath
		self.__cliParameters__ = {}

	@readonly
	def DryRunMessages(self) -> list[str]:
		"""
		Read-only property to access the actions skipped in *dry-run mode* (:attr:`_dryRunMessages`).

		:returns: The messages :meth:`LogDryRun` recorded, in the order the actions were skipped.
		"""
		return self._dryRunMessages

	def LogDryRun(self, message: str) -> None:
		"""
		Record an action that was skipped, because the program runs in *dry-run mode*.

		The message is appended to :attr:`DryRunMessages`. A derived class may override this method to write it, e.g.
		to a terminal.

		:param message: Description of the skipped action.
		"""
		self._dryRunMessages.append(message)

	@staticmethod
	def _NeedsParameterInitialization(key: type) -> bool:
		"""
		Check if an argument class needs a value when it is set.

		:param key: Class of the command line argument.
		:returns:   ``True``, if the argument carries a value.
		"""
		return issubclass(key, (ValuedFlag, ValuedArgument, NamedAndValuedArgument, NamedTupledArgument, PathArgument, PathListArgument))

	def __getitem__(self, key: type[CommandLineArgument]) -> CommandLineArgument:
		"""
		Access to a CLI parameter by CLI option, which is already used.

		:param key:        Class of the command line argument to read.
		:returns:          The command line argument object registered for that class.
		:raises TypeError: If the key is not a subclass of :class:`~pyTooling.CLIAbstraction.Argument.CommandLineArgument`.
		"""
		if not issubclass(key, CommandLineArgument):
			ex = TypeError(f"Key '{key}' is not a subclass of 'CommandLineArgument'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(key)}'.")
			raise ex

		# TODO: is nested check
		return self.__cliParameters__[key]

	def __setitem__(self, key: type[CommandLineArgument], value: CommandLineArgument) -> None:
		"""
		Set a command line argument of this program by its argument class.

		:param key:        Class of the command line argument to set.
		:param value:      Value of that argument; ignored for arguments needing no value.
		:raises TypeError: If the key is not a subclass of :class:`~pyTooling.CLIAbstraction.Argument.CommandLineArgument`.
		:raises KeyError:  If the argument isn't allowed on this program, or was set before.
		"""
		if not issubclass(key, CommandLineArgument):
			ex = TypeError(f"Key '{key}' is not a subclass of 'CommandLineArgument'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(key)}'.")
			raise ex
		elif key not in self.__cliOptions__:
			raise KeyError(f"Option '{key}' is not allowed on executable '{getTypeName(self)}'")
		elif key in self.__cliParameters__:
			raise KeyError(f"Option '{key}' is already set to a value.")

		if self._NeedsParameterInitialization(key):
			self.__cliParameters__[key] = key(value)
		else:
			self.__cliParameters__[key] = key()

	def _CopyParameters(self, tool: Program) -> None:
		"""
		Copy every command line argument set on this program to another program instance.

		A method deriving a program variant calls it on the new instance, then sets the arguments it is given explicitly.

		:param tool:        The program instance receiving the arguments.
		:raises ValueError: If parameter 'tool' is None.
		:raises TypeError:  If parameter 'tool' is not of type :class:`Program`.
		:raises KeyError:   If an argument isn't allowed on 'tool', or is set there already.
		"""
		if tool is None:
			raise ValueError("Parameter 'tool' is None.")
		elif not isinstance(tool, Program):
			ex = TypeError("Parameter 'tool' is not of type 'Program'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(tool)}'.")
			raise ex

		for key, argument in self.__cliParameters__.items():
			if self._NeedsParameterInitialization(key):
				tool[key] = argument.Value
			else:
				tool[key] = True

	@readonly
	def Path(self) -> Path:
		"""
		Read-only property to access the program's path (:attr:`_executablePath`).

		:returns: The program's path. For a program searched in ``PATH``, the path it was found at.
		"""
		return self._executablePath

	def ToArgumentList(self) -> list[str]:
		"""
		Convert a program and used CLI options to a list of CLI argument strings in correct order, unescaped.

		The list can be passed directly to :func:`subprocess.run` or :class:`subprocess.Popen` (without ``shell=True``):
		each string reaches the program as one argument, so nothing needs escaping or quoting.

		:returns:          List of CLI arguments
		:raises TypeError: If an argument is neither a string nor a sequence of strings. |br|
		                   An argument's :meth:`~pyTooling.CLIAbstraction.Argument.CommandLineArgument.AsArgument` has to
		                   return a string, a tuple or a list.
		"""
		result: list[str] = []

		result.append(str(self._executablePath))

		def predicate(item: tuple[type[CommandLineArgument], int]) -> int:
			"""
			Nested function used as sort key.

			:param item: Pair of an argument class and its argument object.
			:returns:    The position the argument class was registered at, so the command line keeps the declared order.
			"""
			return self.__cliOptions__[item[0]]

		for key, value in sorted(self.__cliParameters__.items(), key=predicate):
			param = value.AsArgument()
			if isinstance(param, str):
				result.append(param)
			elif isinstance(param, (tuple, list)):
				result += param
			else:
				ex = TypeError(f"Argument '{key.__name__}' was rendered to neither a string nor a sequence of strings.")
				ex.add_note(f"Got type '{getFullyQualifiedName(param)}'.")
				ex.add_note("'AsArgument()' has to return a 'str', a 'tuple' or a 'list'.")
				raise ex

		return result

	def __repr__(self) -> str:
		"""
		Return the argument list as a Python literal, with strings in double quotes.

		Example: :pycode:`["/usr/bin/git", "--version"]`

		:returns: :meth:`ToArgumentList`'s result as a literal.
		"""
		literal = CommandLineArgument._DoubleQuotedLiteral
		return "[" + ", ".join([literal(item) for item in self.ToArgumentList()]) + "]"  # WORKAROUND: Python <3.12
		# return f"[{", ".join([literal(item) for item in self.ToArgumentList()])}]"

	def __str__(self) -> str:
		"""
		Return the command line, escaped for the current platform.

		Example: :pycode:`/usr/bin/git commit -m 'Bumped dependencies.'`

		:returns: The argument list joined by ``formatCommandLine``: :func:`shlex.join`, on Windows
		          ``subprocess.list2cmdline()``.
		"""
		return formatCommandLine(self.ToArgumentList())


@export
class Executable(Program):  # (ILogable):
	"""Represent a CLI executable derived from :class:`Program`, that adds an abstraction of :class:`subprocess.Popen`."""

	_BOUNDARY:         ClassVar[str] = "====== BOUNDARY pyTooling.CLIAbstraction BOUNDARY ======"  #: Marker line printed between the program's own output and the executable's output.

	_workingDirectory: Nullable[Path]              #: Path to the working directory
	_environment:      Nullable[Environment]       #: Environment to use when executing.
	_process:          Nullable[Subprocess_Popen[str]]  #: Reference to the running process.
	_exitCode:         Nullable[int]               #: The child's process exit code.
	_killed:           Nullable[bool]              #: True, if the child-process got killed (e.g. by a timeout).
	_iterator:         Nullable[Iterator[str]]     #: Iterator for reading STDOUT.

	def __init__(
		self,
		executablePath:      Nullable[Path] = None,
		binaryDirectoryPath: Nullable[Path] = None,
		workingDirectory:    Nullable[Path] = None,
		environment:         Nullable[Environment] = None,
		dryRun:              bool = False
	) -> None:
		"""
		Initializes an executable instance.

		:param executablePath:      Optional, path to the executable.
		:param binaryDirectoryPath: Optional, path to the executable's directory.
		:param workingDirectory:    Optional, path to the working directory.
		:param environment:         Optional, environment that should be setup when launching the executable.
		:param dryRun:              Optional, ``True``, when the program should run in dryrun mode.
		"""
		super().__init__(executablePath, binaryDirectoryPath, dryRun)

		self._workingDirectory = None
		self._environment = environment
		self._process =  None
		self._exitCode = None
		self._killed =   None
		self._iterator = None

	def StartProcess(self, environment: Nullable[Environment] = None) -> None:
		"""
		Start the executable as a child-process.

		:param environment:          Optional, environment that should be setup when launching the executable. |br|
		                             If ``None``, the :attr:`_environment` is used.
		:raises CLIAbstractionError: When an :exc:`OSError` occurs while launching the child-process.
		"""
		if self._dryRun:
			self.LogDryRun(f"Start process: {self}")
			return

		if environment is not None:
			envVariables = environment._variables
		elif self._environment is not None:
			envVariables = self._environment._variables
		else:
			envVariables = None

		# FIXME: verbose log start process
		# FIXME: debug log - parameter list
		try:
			self._process = Subprocess_Popen(
				self.ToArgumentList(),
				stdin=Subprocess_Pipe,
				stdout=Subprocess_Pipe,
				stderr=Subprocess_StdOut,
				cwd=self._workingDirectory,
				env=envVariables,
				universal_newlines=True,
				bufsize=256
			)

		except OSError as ex:
			raise CLIAbstractionError(f"Error while launching a process for '{self._executablePath}'.") from ex

	def Send(self, line: str, end: str = "\n") -> None:
		"""
		Send a string to STDIN of the running child-process.

		:param line:                 Line to send.
		:param end:                  Optional, line end character.
		:raises CLIAbstractionError: If the child-process was not started, or has no standard input.
		:raises CLIAbstractionError: When any error occurs while sending data to the child-process.
		"""
		if self._process is None or self._process.stdin is None:
			raise CLIAbstractionError(
				f"The child-process '{self._executablePath}' was not started, or has no standard input."
			)

		try:
			self._process.stdin.write(line + end)
			self._process.stdin.flush()
		except Exception as ex:
			raise CLIAbstractionError(f"Error while sending data to the child-process '{self._executablePath}'.") from ex

	# This is TCL specific ...
	# def SendBoundary(self):
	# 	self.Send("puts \"{0}\"".format(self._pyIPCMI_BOUNDARY))

	def GetLineReader(self) -> Generator[str, None, None]:
		"""
		Return a line-reader for STDOUT.

		:returns:                    A generator object to read from STDOUT line-by-line.
		:raises DryRunError:         In case dryrun mode is active.
		:raises CLIAbstractionError: When any error occurs while reading outputs from the child-process.
		"""
		if self._dryRun:
			raise DryRunError(f"Can't read from the child-process '{self._executablePath}' in dry-run mode.")

		if self._process is None or self._process.stdout is None:
			raise CLIAbstractionError(
				f"The child-process '{self._executablePath}' was not started, or has no standard output."
			)

		try:
			for line in iter(self._process.stdout.readline, ""):     # FIXME: can it be improved?
				yield line[:-1]
		except Exception as ex:
			raise CLIAbstractionError(f"Error while reading from the child-process '{self._executablePath}'.") from ex
		# finally:
			# self._process.terminate()

	def Wait(self, timeout: Nullable[float] = None, kill: bool = False) -> Nullable[int]:
		"""
		Wait on the child-process with an optional timeout.

		When the timeout period exceeds, the child-process can be forcefully terminated.

		:param timeout:              Optional, timeout in seconds. |br|
		                             Default: infinitely wait on the child-process.
		:param kill:                 Optional, if ``True``, terminate (kill) the child-process if it didn't terminate by
		                             itself within the timeout period.
		:returns:                    ``None`` when the child-process is still running, otherwise the exit code.
		:raises CLIAbstractionError: When the child-process is not started yet.

		.. topic:: Usecases

		   :pycode:`executable.Wait()`
		     Infinitely wait on the child-process. When the child-process terminates by itself, the exit code is returned.

		     This is a blocking call.

		   :pycode:`executable.Wait(timeout=5.4)`
		     Wait for a specified time on the child-process' termination. If it terminated by itself within the specified
		     timeout period, the exit code is returned; otherwise ``None``.

		     Thus :pycode:`.Wait(timeout=0.0)` returning ``None`` indicates a running process.

		   :pycode:`executable.Wait(timeout=20.0, kill=True)`
		     Wait for a specified time on the child-process' termination. If it terminated by itself within the specified
		     timeout period, the exit code is returned; otherwise the child-process gets killed and it's exit code is returned.

 		   :pycode:`executable.Wait(timeout=0.0, kill=True)`
 		     Kill immediately.

		.. seealso::

		   :meth:`Terminate` - Terminate the child-process.
		"""
		if self._process is None:
			raise CLIAbstractionError("Process not yet started.")

		try:
			self._exitCode = self._process.wait(timeout=timeout)
		except TimeoutExpired:
			# when timed out, the process isn't terminated/killed automatically
			if kill:
				self._killed = True
				self._process.terminate()
				# After killing, wait to clean up the "zombie" process
				self._exitCode = self._process.wait()

		return self._exitCode

	def Terminate(self) -> Nullable[int]:
		"""
		Terminate the child-process.

		:returns:                    The child-process' exit code.
		:raises CLIAbstractionError: When the child-process is not started yet.

		.. seealso::

		   :meth:`Wait` - Wait on the child-process with an optional timeout.
		"""
		return self.Wait(timeout=0.0, kill=True)

	@readonly
	def ExitCode(self) -> int:
		"""
		Read-only property accessing the child-process' exit code.

		:returns: Child-process' exit code or ``None`` if it's still running.

		.. seealso::

		   :meth:`Wait`
		      |rarr| Wait on the child-process with an optional timeout.
		   :meth:`Terminate`
		      |rarr| Terminate the child-process.
		"""
		return self._exitCode

	# This is TCL specific
	# def ReadUntilBoundary(self, indent=0):
	# 	__indent = "  " * indent
	# 	if self._iterator is None:
	# 		self._iterator = iter(self.GetReader())
	#
	# 	for line in self._iterator:
	# 		print(__indent + line)
	# 		if self._pyIPCMI_BOUNDARY in line:
	# 			break
	# 	self.LogDebug("Quartus II is ready")


@export
class OutputFilteredExecutable(Executable):
	"""Represent a CLI executable derived from :class:`Executable`, whose outputs are filtered."""
	_hasOutput:   bool  #: ``True``, if the executable wrote any output.
	_hasWarnings: bool  #: ``True``, if the output filter classified a line as a warning.
	_hasErrors:   bool  #: ``True``, if the output filter classified a line as an error.
	_hasFatals:   bool  #: ``True``, if the output filter classified a line as a fatal error.

	def __init__(self, platform: Platform, dryrun: bool, executablePath: Path) -> None: #, environment=None, logger=None) -> None:
		"""
		Initialize an executable whose output is filtered, with all filter results cleared.

		:param platform:       Platform the executable is called on.
		:param dryrun:         If ``True``, the executable is not started, only the command line is assembled.
		:param executablePath: Path to the executable.
		"""
		super().__init__(platform, dryrun, executablePath)  #, environment=environment, logger=logger)

		self._hasOutput =   False
		self._hasWarnings = False
		self._hasErrors =   False
		self._hasFatals =   False

	@readonly
	def HasWarnings(self) -> bool:
		# TODO: update doc-string
		"""
		Check if warnings were found while processing the output stream.

		:returns: ``True``, if at least one warning was found.
		"""
		return self._hasWarnings

	@readonly
	def HasErrors(self) -> bool:
		# TODO: update doc-string
		"""
		Check if errors were found while processing the output stream.

		:returns: ``True``, if at least one error was found.
		"""
		return self._hasErrors

	@readonly
	def HasFatals(self) -> bool:
		# TODO: update doc-string
		"""
		Check if fatal errors were found while processing the output stream.

		:returns: ``True``, if at least one fatal error was found.
		"""
		return self._hasErrors