Backport updates

Update docs: expected is not optional

(cherry picked from commit 31c6a01)
(cherry picked from commit df8a438)
(cherry picked from commit f4908a5)

On subprocess kill write exit code to result to prevent changes (#120)

* fix missed docstring

(cherry picked from commit fb0ef72)

Add timestamp of command start to execute_async for future processing

(cherry picked from commit b3dc162)

More info in result: start timestamp (#124)

(cherry picked from commit 8b7a8e7)

Always set timestamp on kill, provide spent time in str()

(cherry picked from commit 06f1650)

Author: penguinolog

README.rst

@@ -37,15 +37,15 @@ Pros:
 * Open Source: https://github.com/python-useful-helpers/exec-helpers
 * PyPI packaged: https://pypi.python.org/pypi/exec-helpers
 * Self-documented code: docstrings with types in comments
-* Tested: see bages on top
+* Tested: see badges on top
 * Support multiple Python versions:
 
 ::
 
     Python 2.7
     PyPy
 
-.. note:: Update to version 2.0+ for usage with python 3.4+. This version is for legacy python and no new features are planned.
+.. note:: Pythons: For Python 3.4 use versions 2.x.x, python 3.5+ use versions 3.x.x, python 3.6+ use versions 4+
 
 This package includes:
 
@@ -96,7 +96,7 @@ Creation from scratch:
     )
 
 Key is a main connection key (always tried first) and keys are alternate keys.
-Key filename is afilename or list of filenames with keys, which should be loaded.
+Key filename is a filename or list of filenames with keys, which should be loaded.
 Passphrase is an alternate password for keys, if it differs from main password.
 If main key now correct for username - alternate keys tried, if correct key found - it became main.
 If no working key - password is used and None is set as main key.
@@ -217,7 +217,7 @@ Possible to call commands in parallel on multiple hosts if it's not produce huge
         remotes,  # type: typing.Iterable[SSHClient]
         command,  # type: str
         timeout=1 * 60 * 60,  # type: type: typing.Union[int, float, None]
-        expected=None,  # type: typing.Optional[typing.Iterable[int]]
+        expected=(0,),  # type: typing.Iterable[typing.Union[int, ExitCodes]]
         raise_on_err=True  # type: bool
     )
     results  # type: typing.Dict[typing.Tuple[str, int], exec_result.ExecResult]

appveyor.yml

@@ -21,19 +21,11 @@ environment:
       PYTHON_ARCH: "64"
 
     - PYTHON: "C:\\Python35"
-      PYTHON_VERSION: "3.5.x" # currently 3.5.1
+      PYTHON_VERSION: "3.5.x"
       PYTHON_ARCH: "32"
 
     - PYTHON: "C:\\Python35-x64"
-      PYTHON_VERSION: "3.5.x" # currently 3.5.1
-      PYTHON_ARCH: "64"
-
-    - PYTHON: "C:\\Python36"
-      PYTHON_VERSION: "3.6.x" # currently 3.6.0
-      PYTHON_ARCH: "32"
-
-    - PYTHON: "C:\\Python36-x64"
-      PYTHON_VERSION: "3.6.x" # currently 3.6.0
+      PYTHON_VERSION: "3.5.x"
       PYTHON_ARCH: "64"
 
 install:

doc/source/ExecResult.rst

@@ -10,7 +10,7 @@ API: ExecResult
 
     Command execution result.
 
-    .. py:method:: __init__(cmd, stdin=None, stdout=None, stderr=None, exit_code=ExitCodes.EX_INVALID)
+    .. py:method:: __init__(cmd, stdin=None, stdout=None, stderr=None, exit_code=0xDEADBEEF, *, started=None)
 
         :param cmd: command
         :type cmd: ``str``
@@ -22,6 +22,8 @@ API: ExecResult
         :type stderr: ``typing.Optional[typing.Iterable[bytes]]``
         :param exit_code: Exit code. If integer - try to convert to BASH enum.
         :type exit_code: typing.Union[int, ExitCodes]
+        :param started: Timestamp of command start
+        :type started: typing.Optional[datetime.datetime]
 
     .. py:attribute:: stdout_lock
 
@@ -42,6 +44,14 @@ API: ExecResult
         ``typing.Optional(datetime.datetime)``
         Timestamp
 
+    .. py:method:: set_timestamp()
+
+        Set timestamp if empty.
+
+        This will block future object changes.
+
+        .. versionadded:: 2.11.0
+
     .. py:attribute:: cmd
 
         ``str``
@@ -98,6 +108,13 @@ API: ExecResult
 
         :rtype: typing.Union[int, ExitCodes]
 
+    .. py:attribute:: started
+
+        ``datetime.datetime``
+        Timestamp of command start.
+
+        .. versionadded:: 2.11.0
+
     .. py:attribute:: stdout_json
 
         JSON from stdout.

doc/source/SSHClient.rst

@@ -175,7 +175,7 @@ API: SSHClient and SSHAuth.
 
         .. versionadded:: 1.9.7
 
-    .. py:method:: check_call(command, verbose=False, timeout=1*60*60, error_info=None, expected=None, raise_on_err=True, **kwargs)
+    .. py:method:: check_call(command, verbose=False, timeout=1*60*60, error_info=None, expected=(0,), raise_on_err=True, **kwargs)
 
         Execute command and check for return code.
 
@@ -188,14 +188,16 @@ API: SSHClient and SSHAuth.
         :param error_info: Text for error details, if fail happens
         :type error_info: ``typing.Optional[str]``
         :param expected: expected return codes (0 by default)
-        :type expected: ``typing.Optional[typing.Iterable[int]]``
+        :type expected: typing.Iterable[typing.Union[int, ExitCodes]]
         :param raise_on_err: Raise exception on unexpected return code
         :type raise_on_err: ``bool``
         :rtype: ExecResult
         :raises ExecHelperTimeoutError: Timeout exceeded
         :raises CalledProcessError: Unexpected exit code
 
         .. versionchanged:: 1.2.0 default timeout 1 hour
+        .. versionchanged:: 1.10.0 Exception class can be substituted
+        .. versionchanged:: 1.11.0 Expected is not optional, defaults os dependent
 
     .. py:method:: check_stderr(command, verbose=False, timeout=1*60*60, error_info=None, raise_on_err=True, **kwargs)
 
@@ -240,8 +242,9 @@ API: SSHClient and SSHAuth.
         :raises ExecHelperTimeoutError: Timeout exceeded
 
         .. versionchanged:: 1.2.0 default timeout 1 hour
+        .. versionchanged:: 1.10.0 Exception class can be substituted
 
-    .. py:classmethod:: execute_together(remotes, command, timeout=1*60*60, expected=None, raise_on_err=True, **kwargs)
+    .. py:classmethod:: execute_together(remotes, command, timeout=1*60*60, expected=(0,), raise_on_err=True, **kwargs)
 
         Execute command on multiple remotes in async mode.
 
@@ -252,7 +255,7 @@ API: SSHClient and SSHAuth.
         :param timeout: Timeout for command execution.
         :type timeout: ``typing.Union[int, float, None]``
         :param expected: expected return codes (0 by default)
-        :type expected: ``typing.Optional[typing.Iterable[]]``
+        :type expected: typing.Iterable[typing.Union[int, ExitCodes]]
         :param raise_on_err: Raise exception on unexpected return code
         :type raise_on_err: ``bool``
         :return: dictionary {(hostname, port): result}
@@ -261,6 +264,8 @@ API: SSHClient and SSHAuth.
         :raises ParallelCallExceptions: At lest one exception raised during execution (including timeout)
 
         .. versionchanged:: 1.2.0 default timeout 1 hour
+        .. versionchanged:: 1.10.0 Exception class can be substituted
+        .. versionchanged:: 1.11.0 Expected is not optional, defaults os dependent
 
     .. py:method:: open(path, mode='r')
 
@@ -425,3 +430,9 @@ API: SSHClient and SSHAuth.
     .. py:attribute:: stdout
 
         ``typing.Optional[paramiko.ChannelFile]``
+
+    .. py:attribute:: started
+
+        ``datetime.datetime``
+
+        .. versionadded:: 2.11.0

doc/source/Subprocess.rst

@@ -98,7 +98,7 @@ API: Subprocess
         .. note:: stdin channel is closed after the input processing
         .. versionadded:: 1.9.7
 
-    .. py:method:: check_call(command, verbose=False, timeout=1*60*60, error_info=None, expected=None, raise_on_err=True, **kwargs)
+    .. py:method:: check_call(command, verbose=False, timeout=1*60*60, error_info=None, expected=(0,), raise_on_err=True, **kwargs)
 
         Execute command and check for return code.
 
@@ -111,7 +111,7 @@ API: Subprocess
         :param error_info: Text for error details, if fail happens
         :type error_info: ``typing.Optional[str]``
         :param expected: expected return codes (0 by default)
-        :type expected: ``typing.Optional[typing.Iterable[int]]``
+        :type expected: typing.Iterable[typing.Union[int, ExitCodes]]
         :param raise_on_err: Raise exception on unexpected return code
         :type raise_on_err: ``bool``
         :rtype: ExecResult
@@ -120,6 +120,8 @@ API: Subprocess
 
         .. versionchanged:: 1.1.0 make method
         .. versionchanged:: 1.2.0 default timeout 1 hour
+        .. versionchanged:: 1.10.0 Exception class can be substituted
+        .. versionchanged:: 1.11.0 Expected is not optional, defaults os dependent
 
     .. py:method:: check_stderr(command, verbose=False, timeout=1*60*60, error_info=None, raise_on_err=True, **kwargs)
 
@@ -143,6 +145,7 @@ API: Subprocess
 
         .. versionchanged:: 1.1.0 make method
         .. versionchanged:: 1.2.0 default timeout 1 hour
+        .. versionchanged:: 1.10.0 Exception class can be substituted
 
 
 .. py:class:: SubprocessExecuteAsyncResult
@@ -164,3 +167,9 @@ API: Subprocess
     .. py:attribute:: stdout
 
         ``typing.Optional[typing.IO]``
+
+    .. py:attribute:: started
+
+        ``datetime.datetime``
+
+        .. versionadded:: 2.11.0

doc/source/exceptions.rst

@@ -18,21 +18,11 @@ API: exceptions
 
     Base class for process call errors.
 
-.. py:exception:: ExecHelperTimeoutError(ExecCalledProcessError)
+class ExecHelperTimeoutProcessError(ExecCalledProcessError):
+    
+    Timeout based errors.
 
-    Execution timeout.
-
-    .. versionchanged:: 1.3.0 provide full result and timeout inside.
-    .. versionchanged:: 1.3.0 subclass ExecCalledProcessError
-
-    .. py:method:: __init__(self, result, timeout)
-
-        Exception for error on process calls.
-
-        :param result: execution result
-        :type result: exec_result.ExecResult
-        :param timeout: timeout for command
-        :type timeout: typing.Union[int, float]
+    .. versionadded:: 2.11.0
 
     .. py:attribute:: timeout
 
@@ -54,18 +44,54 @@ API: exceptions
         ``typing.Text``
         stdout string or brief string
 
+
+.. py:exception:: ExecHelperNoKillError(ExecHelperTimeoutProcessError)
+    
+    Impossible to kill process.
+
+    .. versionadded:: 2.11.0
+
+    .. py:method:: __init__(self, result, timeout)
+        
+        Exception for error on process calls.
+
+        :param result: execution result
+        :type result: ExecResult
+        :param timeout: timeout for command
+        :type timeout: typing.Union[int, float]
+
+
+.. py:exception:: ExecHelperTimeoutError(ExecHelperTimeoutProcessError)
+
+    Execution timeout.
+
+    .. versionchanged:: 1.3.0 provide full result and timeout inside.
+    .. versionchanged:: 1.3.0 subclass ExecCalledProcessError
+
+    .. py:method:: __init__(self, result, timeout)
+
+        Exception for error on process calls.
+
+        :param result: execution result
+        :type result: ExecResult
+        :param timeout: timeout for command
+        :type timeout: typing.Union[int, float]
+
+
 .. py:exception:: CalledProcessError(ExecCalledProcessError)
 
     Exception for error on process calls.
 
     .. versionchanged:: 1.1.1 - provide full result
 
-    .. py:method:: __init__(result, expected=None)
+    .. py:method:: __init__(result, expected=(0,))
 
         :param result: execution result
         :type result: ExecResult
-        :param returncode: return code
-        :type returncode: typing.Union[int, ExitCodes]
+        :param expected: expected return codes
+        :type expected: typing.Iterable[typing.Union[int, ExitCodes]]
+
+        .. versionchanged:: 2.11.0 Expected is not optional, defaults os dependent
 
     .. py:attribute:: result
 
@@ -104,7 +130,7 @@ API: exceptions
 
     Exception during parallel execution.
 
-    .. py:method:: __init__(command, errors, results, expected=None, )
+    .. py:method:: __init__(command, errors, results, expected=(0,), )
 
         :param command: command
         :type command: ``str``
@@ -113,9 +139,10 @@ API: exceptions
         :param results: all results
         :type results: typing.Dict[typing.Tuple[str, int], ExecResult]
         :param expected: expected return codes
-        :type expected: typing.Optional[typing.List[typing.List[typing.Union[int, ExitCodes]]]
+        :type expected: typing.Iterable[typing.Union[int, ExitCodes]]
 
         .. versionchanged:: 1.0 - fixed inheritance
+        .. versionchanged:: 2.11.0 Expected is not optional, defaults os dependent
 
     .. py:attribute:: cmd
 
@@ -144,7 +171,7 @@ API: exceptions
 
     Exception raised during parallel call as result of exceptions.
 
-    .. py:method:: __init__(command, exceptions, errors, results, expected=None, )
+    .. py:method:: __init__(command, exceptions, errors, results, expected=(0,), )
 
         :param command: command
         :type command: ``str``
@@ -155,9 +182,10 @@ API: exceptions
         :param results: all results
         :type results: typing.Dict[typing.Tuple[str, int], ExecResult]
         :param expected: expected return codes
-        :type expected: typing.Optional[typing.List[typing.List[typing.Union[int, ExitCodes]]]
+        :type expected: typing.Iterable[typing.Union[int, ExitCodes]]
 
         .. versionchanged:: 1.0 - fixed inheritance
+        .. versionchanged:: 2.11.0 Expected is not optional, defaults os dependent
 
     .. py:attribute:: cmd
 

exec_helpers/__init__.py

@@ -16,8 +16,6 @@
 
 from __future__ import absolute_import
 
-import typing
-
 import pkg_resources
 
 from .proc_enums import ExitCodes
@@ -55,7 +53,7 @@
     "SubprocessExecuteAsyncResult",
     "ExitCodes",
     "ExecResult",
-)  # type: typing.Tuple[str, ...]
+)
 
 try:  # pragma: no cover
     __version__ = pkg_resources.get_distribution(__name__).version