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

@@ -39,7 +39,7 @@ 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:
 
 ::
@@ -49,7 +49,7 @@ Pros:
     Python 3.7
     PyPy3 3.5+
 
-.. note:: For Python 2.7 and PyPy please use versions 1.x.x. For python 3.5+ use versions 3.0+
+.. note:: Pythons: For Python 2.7 and PyPy use versions 1.x.x, python 3.5+ use versions 3.x.x, python 3.6+ use versions 4+
 
 This package includes:
 
@@ -100,7 +100,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.
@@ -226,9 +226,11 @@ 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
         # Keyword only:
+        stdin=None,  # type: typing.Union[bytes, str, bytearray, None]
+        log_mask_re=None,  # type: typing.Optional[str]
         exception_class=ParallelCallProcessError  # typing.Type[ParallelCallProcessError]
     )
     results  # type: typing.Dict[typing.Tuple[str, int], exec_result.ExecResult]
@@ -248,6 +250,8 @@ For execute through SSH host can be used `execute_through_host` method:
         timeout=1 * 60 * 60,  # type: type: typing.Union[int, float, None]
         verbose=False,  # type: bool
         # Keyword only:
+        stdin=None,  # type: typing.Union[bytes, str, bytearray, None]
+        log_mask_re=None,  # type: typing.Optional[str]
         get_pty=False,  # type: bool
         width=80,  # type: int
         height=24  # type: int

appveyor.yml

@@ -5,19 +5,11 @@ environment:
 
   matrix:
     - 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

@@ -182,7 +182,7 @@ API: SSHClient and SSHAuth.
 
         .. versionadded:: 2.9.4
 
-    .. py:method:: check_call(command, verbose=False, timeout=1*60*60, error_info=None, expected=None, raise_on_err=True, *, exception_class=CalledProcessError, **kwargs)
+    .. py:method:: check_call(command, verbose=False, timeout=1*60*60, error_info=None, expected=(0,), raise_on_err=True, *, exception_class=CalledProcessError, **kwargs)
 
         Execute command and check for return code.
 
@@ -195,7 +195,7 @@ 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``
         :param exception_class: Exception class for errors. Subclass of CalledProcessError is mandatory.
@@ -206,8 +206,9 @@ API: SSHClient and SSHAuth.
 
         .. versionchanged:: 1.2.0 default timeout 1 hour
         .. versionchanged:: 3.2.0 Exception class can be substituted
+        .. versionchanged:: 2.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, *, expected=None, exception_class=CalledProcessError, **kwargs)
+    .. py:method:: check_stderr(command, verbose=False, timeout=1*60*60, error_info=None, raise_on_err=True, *, expected=(0,), exception_class=CalledProcessError, **kwargs)
 
         Execute command expecting return code 0 and empty STDERR.
 
@@ -222,7 +223,7 @@ API: SSHClient and SSHAuth.
         :param raise_on_err: Raise exception on unexpected return code
         :type raise_on_err: ``bool``
         :param expected: expected return codes (0 by default)
-        :type expected: typing.Optional[typing.Iterable[typing.Union[int, ExitCodes]]]
+        :type expected: typing.Iterable[typing.Union[int, ExitCodes]]
         :param exception_class: Exception class for errors. Subclass of CalledProcessError is mandatory.
         :type exception_class: typing.Type[CalledProcessError]
         :rtype: ExecResult
@@ -232,7 +233,7 @@ API: SSHClient and SSHAuth.
         .. versionchanged:: 1.2.0 default timeout 1 hour
         .. versionchanged:: 3.2.0 Exception class can be substituted
 
-    .. py:method:: execute_through_host(hostname, command, auth=None, target_port=22, verbose=False, timeout=1*60*60, *, get_pty=False, width=80, height=24, **kwargs)
+    .. py:method:: execute_through_host(hostname, command, auth=None, target_port=22, verbose=False, timeout=1*60*60, *, stdin=None, log_mask_re="", get_pty=False, width=80, height=24, **kwargs)
 
         Execute command on remote host through currently connected host.
 
@@ -248,6 +249,11 @@ API: SSHClient and SSHAuth.
         :type verbose: ``bool``
         :param timeout: Timeout for command execution.
         :type timeout: ``typing.Union[int, float, None]``
+        :param stdin: pass STDIN text to the process
+        :type stdin: typing.Union[bytes, str, bytearray, None]
+        :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]
         :param get_pty: open PTY on target machine
         :type get_pty: ``bool``
         :param width: PTY width
@@ -260,8 +266,9 @@ API: SSHClient and SSHAuth.
         .. versionchanged:: 1.2.0 default timeout 1 hour
         .. versionchanged:: 3.2.0 Expose pty options as optional keyword-only arguments
         .. versionchanged:: 3.2.0 Exception class can be substituted
+        .. versionchanged:: 2.11.0 Expose stdin and log_mask_re as optional keyword-only arguments
 
-    .. py:classmethod:: execute_together(remotes, command, timeout=1*60*60, expected=None, raise_on_err=True, *, exception_class=ParallelCallProcessError, **kwargs)
+    .. py:classmethod:: execute_together(remotes, command, timeout=1*60*60, expected=(0,), raise_on_err=True, *, stdin=None, log_mask_re="", exception_class=ParallelCallProcessError, **kwargs)
 
         Execute command on multiple remotes in async mode.
 
@@ -272,9 +279,14 @@ 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``
+        :param stdin: pass STDIN text to the process
+        :type stdin: typing.Union[bytes, str, bytearray, None]
+        :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]
         :param exception_class: Exception to raise on error. Mandatory subclass of ParallelCallProcessError
         :type exception_class: typing.Type[ParallelCallProcessError]
         :return: dictionary {(hostname, port): result}
@@ -284,6 +296,8 @@ API: SSHClient and SSHAuth.
 
         .. versionchanged:: 1.2.0 default timeout 1 hour
         .. versionchanged:: 3.2.0 Exception class can be substituted
+        .. versionchanged:: 2.11.0 Expected is not optional, defaults os dependent
+        .. versionchanged:: 2.11.0 Expose stdin and log_mask_re as optional keyword-only arguments
 
     .. py:method:: open(path, mode='r')
 
@@ -448,3 +462,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

@@ -106,7 +106,7 @@ API: Subprocess
         .. note:: stdin channel is closed after the input processing
         .. versionadded:: 2.9.4
 
-    .. py:method:: check_call(command, verbose=False, timeout=1*60*60, error_info=None, expected=None, raise_on_err=True, *, exception_class=CalledProcessError, **kwargs)
+    .. py:method:: check_call(command, verbose=False, timeout=1*60*60, error_info=None, expected=(0,), raise_on_err=True, *, exception_class=CalledProcessError, **kwargs)
 
         Execute command and check for return code.
 
@@ -119,7 +119,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``
         :param exception_class: Exception class for errors. Subclass of CalledProcessError is mandatory.
@@ -131,8 +131,9 @@ API: Subprocess
         .. versionchanged:: 1.1.0 make method
         .. versionchanged:: 1.2.0 default timeout 1 hour
         .. versionchanged:: 2.9.3 Exception class can be substituted
+        .. versionchanged:: 2.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, *, expected=None, exception_class=CalledProcessError, **kwargs)
+    .. py:method:: check_stderr(command, verbose=False, timeout=1*60*60, error_info=None, raise_on_err=True, *, expected=(0,), exception_class=CalledProcessError, **kwargs)
 
         Execute command expecting return code 0 and empty STDERR.
 
@@ -147,7 +148,7 @@ API: Subprocess
         :param raise_on_err: Raise exception on unexpected return code
         :type raise_on_err: ``bool``
         :param expected: expected return codes (0 by default)
-        :type expected: typing.Optional[typing.Iterable[typing.Union[int, ExitCodes]]]
+        :type expected: typing.Iterable[typing.Union[int, ExitCodes]]
         :param exception_class: Exception class for errors. Subclass of CalledProcessError is mandatory.
         :type exception_class: typing.Type[CalledProcessError]
         :rtype: ExecResult
@@ -157,6 +158,7 @@ API: Subprocess
         .. versionchanged:: 1.1.0 make method
         .. versionchanged:: 1.2.0 default timeout 1 hour
         .. versionchanged:: 2.9.3 Exception class can be substituted
+        .. versionchanged:: 2.11.0 Expected is not optional, defaults os dependent
 
 
 .. py:class:: SubprocessExecuteAsyncResult
@@ -178,3 +180,9 @@ API: Subprocess
     .. py:attribute:: stdout
 
         ``typing.Optional[typing.IO]``
+
+    .. py:attribute:: started
+
+        ``datetime.datetime``
+
+        .. versionadded:: 2.11.0