Allow direct call of helpers: shortcut to execute

Author: penguinolog

README.rst

@@ -167,6 +167,15 @@ This methods are almost the same for `SSHCleint` and `Subprocess`, except specif
         exception_class=CalledProcessError,  # typing.Type[CalledProcessError]
     )
 
+.. code-block:: python
+
+    result = helper(  # Lazy way: instances are callable and uses `execute`.
+        command,  # type: str
+        verbose=False,  # type: bool
+        timeout=1 * 60 * 60,  # type: typing.Union[int, float, None]
+        **kwargs
+    )
+
 If no STDOUT or STDERR required, it is possible to disable this FIFO pipes via `**kwargs` with flags `open_stdout=False` and `open_stderr=False`.
 
 The next command level uses lower level and kwargs are forwarded, so expected exit codes are forwarded from `check_stderr`.

doc/source/SSHClient.rst

@@ -167,6 +167,21 @@ API: SSHClient and SSHAuth.
 
         .. versionchanged:: 1.2.0 default timeout 1 hour
 
+    .. py:method:: __call__(command, verbose=False, timeout=1*60*60, **kwargs)
+
+        Execute command and wait for return code.
+
+        :param command: Command for execution
+        :type command: ``str``
+        :param verbose: Produce log.info records for command call and output
+        :type verbose: ``bool``
+        :param timeout: Timeout for command execution.
+        :type timeout: ``typing.Union[int, float, None]``
+        :rtype: ExecResult
+        :raises ExecHelperTimeoutError: Timeout exceeded
+
+        .. versionadded:: 3.3.0
+
     .. py:method:: check_call(command, verbose=False, timeout=1*60*60, error_info=None, expected=None, raise_on_err=True, *, exception_class=CalledProcessError, **kwargs)
 
         Execute command and check for return code.

doc/source/Subprocess.rst

@@ -90,6 +90,22 @@ API: Subprocess
         .. versionchanged:: 1.2.0 default timeout 1 hour
         .. versionchanged:: 1.2.0 stdin data
 
+    .. py:method:: __call__(command, verbose=False, timeout=1*60*60, **kwargs)
+
+        Execute command and wait for return code.
+
+        :param command: Command for execution
+        :type command: ``str``
+        :param verbose: Produce log.info records for command call and output
+        :type verbose: ``bool``
+        :param timeout: Timeout for command execution.
+        :type timeout: ``typing.Union[int, float, None]``
+        :rtype: ExecResult
+        :raises ExecHelperTimeoutError: Timeout exceeded
+
+        .. note:: stdin channel is closed after the input processing
+        .. versionadded:: 3.3.0
+
     .. py:method:: check_call(command, verbose=False, timeout=1*60*60, error_info=None, expected=None, raise_on_err=True, *, exception_class=CalledProcessError, **kwargs)
 
         Execute command and check for return code.

exec_helpers/__init__.py

@@ -53,9 +53,9 @@
     "async_api",
 )
 
-try:
+try:  # pragma: no cover
     __version__ = pkg_resources.get_distribution(__name__).version
-except pkg_resources.DistributionNotFound:
+except pkg_resources.DistributionNotFound:  # pragma: no cover
     # package is not installed, try to get from SCM
     try:
         # noinspection PyPackageRequirements,PyUnresolvedReferences

exec_helpers/api.py

@@ -250,6 +250,31 @@ def execute(
         self.logger.log(level=logging.INFO if verbose else logging.DEBUG, msg=message)  # type: ignore
         return result
 
+    def __call__(
+        self,
+        command: str,
+        verbose: bool = False,
+        timeout: typing.Union[int, float, None] = constants.DEFAULT_TIMEOUT,
+        **kwargs: typing.Any
+    ) -> exec_result.ExecResult:
+        """Execute command and wait for return code.
+
+        :param command: Command for execution
+        :type command: str
+        :param verbose: Produce log.info records for command call and output
+        :type verbose: bool
+        :param timeout: Timeout for command execution.
+        :type timeout: typing.Union[int, float, None]
+        :param kwargs: additional parameters for call.
+        :type kwargs: typing.Any
+        :return: Execution result
+        :rtype: ExecResult
+        :raises ExecHelperTimeoutError: Timeout exceeded
+
+        .. versionadded:: 3.3.0
+        """
+        return self.execute(command=command, verbose=verbose, timeout=timeout, **kwargs)
+
     def check_call(
         self,
         command: str,

exec_helpers/async_api/api.py

@@ -171,6 +171,31 @@ async def execute(  # type: ignore
         self.logger.log(level=logging.INFO if verbose else logging.DEBUG, msg=message)  # type: ignore
         return result
 
+    async def __call__(  # type: ignore
+        self,
+        command: str,
+        verbose: bool = False,
+        timeout: typing.Union[int, float, None] = constants.DEFAULT_TIMEOUT,
+        **kwargs: typing.Any
+    ) -> exec_result.ExecResult:
+        """Execute command and wait for return code.
+
+        :param command: Command for execution
+        :type command: str
+        :param verbose: Produce log.info records for command call and output
+        :type verbose: bool
+        :param timeout: Timeout for command execution.
+        :type timeout: typing.Union[int, float, None]
+        :param kwargs: additional parameters for call.
+        :type kwargs: typing.Any
+        :return: Execution result
+        :rtype: ExecResult
+        :raises ExecHelperTimeoutError: Timeout exceeded
+
+        .. versionadded:: 3.3.0
+        """
+        return await self.execute(command=command, verbose=verbose, timeout=timeout, **kwargs)
+
     async def check_call(  # type: ignore
         self,
         command: str,

test/async_api/test_subprocess.py

@@ -343,3 +343,13 @@ async def test_008_check_stderr_no_raise(execute, exec_result, logger) -> None:
         )
         == exec_result
     )
+
+
+async def test_009_call(create_subprocess_shell, logger, exec_result, run_parameters) -> None:
+    runner = exec_helpers.async_api.Subprocess()
+    res = await runner(command, stdin=run_parameters["stdin"])
+    assert isinstance(res, exec_helpers.async_api.ExecResult)
+    assert res == exec_result
+    assert logger.mock_calls[-1] == mock.call.log(
+        level=logging.DEBUG, msg="Command {result.cmd!r} exit code: {result.exit_code!s}".format(result=res)
+    )

test/test_ssh_client_execute.py

@@ -506,3 +506,24 @@ def test_010_execute_together_expected(ssh, ssh2, execute_async, exec_result, ru
         )
     )
     assert results == {(host, port): exec_result, (host2, port): exec_result}
+
+
+def test_011_call(ssh, ssh_transport_channel, exec_result, run_parameters) -> None:
+    kwargs = {}
+    if "get_pty" in run_parameters:
+        kwargs["get_pty"] = run_parameters["get_pty"]
+    if "width" in run_parameters:
+        kwargs["width"] = run_parameters["width"]
+    if "height" in run_parameters:
+        kwargs["height"] = run_parameters["height"]
+
+    res = ssh(
+        command,
+        stdin=run_parameters["stdin"],
+        open_stdout=run_parameters["open_stdout"],
+        open_stderr=run_parameters["open_stderr"],
+        **kwargs
+    )
+    assert isinstance(res, exec_helpers.ExecResult)
+    assert res == exec_result
+    ssh_transport_channel.assert_has_calls((mock.call.status_event.is_set(),))

test/test_subprocess.py

@@ -317,3 +317,16 @@ def test_008_check_stderr_no_raise(execute, exec_result, logger) -> None:
         runner.check_stderr(command, stdin=exec_result.stdin, expected=[exec_result.exit_code], raise_on_err=False)
         == exec_result
     )
+
+
+def test_009_call(popen, logger, exec_result, run_parameters) -> None:
+    runner = exec_helpers.Subprocess()
+    res = runner(
+        command,
+        stdin=run_parameters["stdin"],
+        open_stdout=run_parameters["open_stdout"],
+        open_stderr=run_parameters["open_stderr"],
+    )
+    assert isinstance(res, exec_helpers.ExecResult)
+    assert res == exec_result
+    popen().wait.assert_called_once_with(timeout=default_timeout)