API port from master & bump to 1.4.0 (#87)

* API port from master & bump to 1.4.0

* `ExecuteAsyncResult` NamedTuple
* Non-blocking execute
* CI optimizations: static part before tests
* Partial code-style port for easier backports later

Author: penguinolog

.travis.yml

@@ -43,11 +43,6 @@ after_success:
 jobs:
   fast_finish: true
   include:
-  - stage: test
-    <<: *python27
-  - stage: test
-    <<: *pypy
-
   - <<: *static_analysis
     name: "PyLint"
     install:
@@ -88,6 +83,11 @@ jobs:
     script:
     - pydocstyle exec_helpers
 
+  - stage: test
+    <<: *python27
+  - stage: test
+    <<: *pypy
+
   - stage: deploy
     # This prevents job from appearing in test plan unless commit is tagged:
     if: tag IS present

doc/source/SSHClient.rst

@@ -138,11 +138,12 @@ API: SSHClient and SSHAuth.
         :param log_mask_re: regex lookup rule to mask command for logger.
                             all MATCHED groups will be replaced by '<*masked*>'
         :type log_mask_re: typing.Optional[str]
-        :rtype: ``typing.Tuple[paramiko.Channel, paramiko.ChannelFile, typing.Optional[paramiko.ChannelFile], typing.Optional[paramiko.ChannelFile]]``
+        :rtype: SshExecuteAsyncResult
 
         .. versionchanged:: 1.2.0 open_stdout and open_stderr flags
         .. versionchanged:: 1.2.0 stdin data
         .. versionchanged:: 1.2.0 get_pty moved to `**kwargs`
+        .. versionchanged:: 1.4.0 Use typed NamedTuple as result
 
     .. py:method:: execute(command, verbose=False, timeout=1*60*60, **kwargs)
 
@@ -388,3 +389,24 @@ API: SSHClient and SSHAuth.
         :param log: Log on generic connection failure
         :type log: ``bool``
         :raises paramiko.AuthenticationException: Authentication failed.
+
+
+.. py:class:: SshExecuteAsyncResult
+
+    Typed NamedTuple
+
+    .. py:attribute:: interface
+
+        ``paramiko.Channel``
+
+    .. py:attribute:: stdin
+
+        ``paramiko.ChannelFile``
+
+    .. py:attribute:: stderr
+
+        ``typing.Optional[paramiko.ChannelFile]``
+
+    .. py:attribute:: stdout
+
+        ``typing.Optional[paramiko.ChannelFile]``

doc/source/Subprocess.rst

@@ -56,9 +56,11 @@ API: Subprocess
         :param log_mask_re: regex lookup rule to mask command for logger.
                             all MATCHED groups will be replaced by '<*masked*>'
         :type log_mask_re: ``typing.Optional[str]``
-        :rtype: ``typing.Tuple[subprocess.Popen, None, typing.Optional[typing.IO], typing.Optional[typing.IO], ]``
+        :rtype: SubprocessExecuteAsyncResult
+        :raises OSError: impossible to process STDIN
 
         .. versionadded:: 1.2.0
+        .. versionchanged:: 1.4.0 Use typed NamedTuple as result
 
     .. py:method:: execute(command, verbose=False, timeout=1*60*60, **kwargs)
 
@@ -124,3 +126,24 @@ API: Subprocess
 
         .. versionchanged:: 1.1.0 make method
         .. versionchanged:: 1.2.0 default timeout 1 hour
+
+
+.. py:class:: SubprocessExecuteAsyncResult
+
+    Typed NamedTuple
+
+    .. py:attribute:: interface
+
+        ``subprocess.Popen``
+
+    .. py:attribute:: stdin
+
+        ``typing.Optional[typing.IO]``
+
+    .. py:attribute:: stderr
+
+        ``typing.Optional[typing.IO]``
+
+    .. py:attribute:: stdout
+
+        ``typing.Optional[typing.IO]``

exec_helpers/__init__.py

@@ -24,40 +24,41 @@
     CalledProcessError,
     ParallelCallProcessError,
     ParallelCallExceptions,
-    ExecHelperTimeoutError
+    ExecHelperTimeoutError,
 )
 
 from .exec_result import ExecResult
 from .api import ExecHelper
 from .ssh_auth import SSHAuth
+from ._ssh_client_base import SshExecuteAsyncResult
 from .ssh_client import SSHClient
-from .subprocess_runner import Subprocess  # nosec  # Expected
+from .subprocess_runner import Subprocess, SubprocessExecuteAsyncResult  # nosec  # Expected
 
 __all__ = (
-    'ExecHelperError',
-    'ExecCalledProcessError',
-    'CalledProcessError',
-    'ParallelCallExceptions',
-    'ParallelCallProcessError',
-    'ExecHelperTimeoutError',
-    'ExecHelper',
-    'SSHClient',
-    'SSHAuth',
-    'Subprocess',
-    'ExitCodes',
-    'ExecResult',
+    "ExecHelperError",
+    "ExecCalledProcessError",
+    "CalledProcessError",
+    "ParallelCallExceptions",
+    "ParallelCallProcessError",
+    "ExecHelperTimeoutError",
+    "ExecHelper",
+    "SSHClient",
+    "SshExecuteAsyncResult",
+    "SSHAuth",
+    "Subprocess",
+    "SubprocessExecuteAsyncResult",
+    "ExitCodes",
+    "ExecResult",
 )
 
-__version__ = '1.3.8'
+__version__ = "1.4.0"
 __author__ = "Alexey Stepanov"
-__author_email__ = 'penguinolog@gmail.com'
+__author_email__ = "penguinolog@gmail.com"
 __maintainers__ = {
-    'Alexey Stepanov': 'penguinolog@gmail.com',
-    'Antonio Esposito': 'esposito.cloud@gmail.com',
-    'Dennis Dmitriev': 'dis-xcom@gmail.com',
+    "Alexey Stepanov": "penguinolog@gmail.com",
+    "Antonio Esposito": "esposito.cloud@gmail.com",
+    "Dennis Dmitriev": "dis-xcom@gmail.com",
 }
-__url__ = 'https://github.com/python-useful-helpers/exec-helpers'
-__description__ = (
-    "Execution helpers for simplified usage of subprocess and ssh."
-)
+__url__ = "https://github.com/python-useful-helpers/exec-helpers"
+__description__ = "Execution helpers for simplified usage of subprocess and ssh."
 __license__ = "Apache License, Version 2.0"

exec_helpers/_log_templates.py

@@ -24,8 +24,8 @@
 
 CMD_WAIT_ERROR = (
     "Wait for {result.cmd!r} during {timeout!s}s: no return code!\n"
-    '\tSTDOUT:\n'
-    '{result.stdout_brief}\n'
-    '\tSTDERR"\n'
-    '{result.stderr_brief}'
+    "\tSTDOUT:\n"
+    "{result.stdout_brief}\n"
+    "\tSTDERR:\n"
+    "{result.stderr_brief}"
 )