Port CI, docstrings and validations (#81)

Author: penguinolog

.travis.yml

@@ -3,89 +3,103 @@ language: python
 os: linux
 install:
 - &upgrade_python_toolset pip install --upgrade pip setuptools wheel
-- pip install tox
-- pip install coveralls
-script: []
+- pip install --upgrade pytest pytest-sugar
+- &install_deps pip install -r CI_REQUIREMENTS.txt
+- pip install --upgrade pytest-cov coveralls
+
+_python:
+- &python27
+  name: "Python 2.7"
+  python: 2.7
+- &pypy
+  name: "PyPy"
+  python: pypy
+- &python37
+  name: "Python 3.7"
+  python: 3.7
+  dist: xenial
+  sudo: true
+
+_helpers:
+- &build_package python setup.py bdist_wheel
+
+- &static_analysis
+  stage: Static analysis
+  <<: *python27
+  after_success: skip
+
+- &code_style_check
+  stage: Code style check
+  <<: *python27
+  after_success: skip
+
+script:
+- pip install -e .
+- py.test -vv --cov-config .coveragerc --cov-report= --cov=exec_helpers test
+- coverage report -m --fail-under 87
 after_success:
 - coveralls
 
 jobs:
   fast_finish: true
   include:
   - stage: test
-    name: "Python 2.7"
-    python: 2.7
-    script:
-    - tox -e py27
+    <<: *python27
   - stage: test
-    name: "PyPy"
-    python: pypy
-    script:
-    - tox -e pypy
+    <<: *pypy
 
-  - stage: Static analisys
+  - <<: *static_analysis
     name: "PyLint"
-    python: 2.7
-    services: []
     install:
     - *upgrade_python_toolset
-    - pip install tox
+    - *install_deps
+    - pip install --upgrade "pylint < 2.0"
     script:
-    - tox -e pylint
-    after_success: skip
-  - stage: Static analisys
+    - pylint exec_helpers
+  - <<: *static_analysis
     name: "Bandit"
-    python: 2.7
-    services: []
     install:
     - *upgrade_python_toolset
-    - pip install tox
+    - pip install --upgrade bandit
     script:
-    - tox -e bandit
-    after_success: skip
-  - stage: Static analisys
+    - bandit -r exec_helpers
+  - <<: *static_analysis
+    <<: *python37
     name: "MyPy"
-    python: 3.7
-    dist: xenial
-    sudo: true
-    services: []
     install:
     - *upgrade_python_toolset
-    - pip install tox
+    - *install_deps
+    - pip install --upgrade "mypy >= 0.620"
     script:
-    - tox -e mypy
-    after_success: skip
+    - mypy --strict exec_helpers
 
-  - stage: Code style check
+  - <<: *code_style_check
     name: "PEP8"
-    python: 2.7
     install:
     - *upgrade_python_toolset
-    - pip install tox
+    - pip install --upgrade flake8
     script:
-    - tox -e pep8
-    after_success: skip
-  - stage: Code style check
+    - flake8
+  - <<: *code_style_check
     name: "PEP257"
-    python: 2.7
     install:
     - *upgrade_python_toolset
-    - pip install tox
+    - pip install --upgrade pydocstyle
     script:
-    - tox -e pep257
-    after_success: skip
+    - pydocstyle exec_helpers
 
   - stage: deploy
     # This prevents job from appearing in test plan unless commit is tagged:
     if: tag IS present
-    # Run on pypy to build not cythonized wheel
-    python: pypy
+    <<: *pypy
+    name: Build universal bdist_wheel. Deploy bdist and sdist.
     services: []
     install:
     - *upgrade_python_toolset
     - pip install -r build_requirements.txt
     script:
-    - python setup.py bdist_wheel
+    - *build_package
+    before_deploy: []
     deploy:
     - provider: pypi
       # `skip_cleanup: true` is required to preserve binary wheels, built

build_requirements.txt

@@ -1,4 +1,2 @@
-Cython; platform_python_implementation == "CPython"
 wheel
 -r CI_REQUIREMENTS.txt
--r requirements.txt

exec_helpers/_ssh_client_base.py

@@ -135,6 +135,7 @@ def __call__(  # type: ignore
         :type auth: typing.Optional[ssh_auth.SSHAuth]
         :param verbose: show additional error/warning messages
         :type verbose: bool
+        :return: SSH client instance
         :rtype: SSHClientBase
         """
         if (host, port) in cls.__cache:
@@ -178,7 +179,7 @@ def __call__(  # type: ignore
     def clear_cache(mcs):  # type: (typing.Type[_MemorizedSSH]) -> None
         """Clear cached connections for initialize new instance on next call.
 
-        getrefcount is used to check for usage.
+        getrefcount is used to check for usage, so connections closed on CPYTHON only.
         """
         n_count = 4
         # PY3: cache, ssh, temporary
@@ -224,7 +225,9 @@ def __init__(
         ):  # type: (...) -> None
             """Context manager for call commands with sudo.
 
+            :param ssh: connection instance
             :type ssh: SSHClientBase
+            :param enforce: sudo mode for context manager
             :type enforce: typing.Optional[bool]
             """
             self.__ssh = ssh
@@ -255,7 +258,9 @@ def __init__(
         ):  # type: (...) -> None
             """Context manager for keepalive management.
 
+            :param ssh: connection instance
             :type ssh: SSHClientBase
+            :param enforce: keepalive mode for context manager
             :type enforce: bool
             :param enforce: Keep connection alive after context manager exit
             """
@@ -291,7 +296,7 @@ def __init__(
         auth=None,  # type: typing.Optional[ssh_auth.SSHAuth]
         verbose=True,  # type: bool
     ):  # type: (...) -> None
-        """SSHClient helper.
+        """Main SSH Client helper.
 
         :param host: remote hostname
         :type host: str
@@ -393,7 +398,7 @@ def __str__(self):  # type: () -> str  # pragma: no cover
 
     @property
     def _ssh(self):  # type: () -> paramiko.SSHClient
-        """ssh client object getter for inheritance support only.
+        """Ssh client object getter for inheritance support only.
 
         Attention: ssh client object creation and change
         is allowed only by __init__ and reconnect call.
@@ -534,6 +539,7 @@ def keepalive_mode(self):  # type: () -> bool
     def keepalive_mode(self, mode):  # type: (bool) -> None
         """Persistent keepalive mode change for connection object.
 
+        :param mode: keepalive mode enable/disable
         :type mode: bool
         """
         self.__keepalive_mode = bool(mode)
@@ -556,6 +562,7 @@ def sudo(
 
         :param enforce: Enforce sudo enabled or disabled. By default: None
         :type enforce: typing.Optional[bool]
+        :return: context manager with selected sudo state inside
         :rtype: typing.ContextManager
         """
         return self.__get_sudo(ssh=self, enforce=enforce)
@@ -568,6 +575,7 @@ def keepalive(
 
         :param enforce: Enforce keepalive enabled or disabled.
         :type enforce: bool
+        :return: context manager with selected keepalive state inside
         :rtype: typing.ContextManager
 
         .. Note:: Enter and exit ssh context manager is produced as well.
@@ -600,6 +608,9 @@ def execute_async(
         :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 kwargs: additional parameters for call.
+        :type kwargs: typing.Any
+        :return: Tuple with control interface and file-like objects for STDIN/STDERR/STDOUT
         :rtype: typing.Tuple[
             paramiko.Channel,
             paramiko.ChannelFile,
@@ -669,15 +680,24 @@ def _exec_command(
     ):  # type: (...) -> exec_result.ExecResult
         """Get exit status from channel with timeout.
 
+        :param command: executed command (for logs)
         :type command: str
+        :param interface: interface to control execution
         :type interface: paramiko.channel.Channel
+        :param stdout: source for STDOUT read
         :type stdout: typing.Optional[paramiko.ChannelFile]
+        :param stderr: source for STDERR read
         :type stderr: typing.Optional[paramiko.ChannelFile]
+        :param timeout: timeout before stop execution with TimeoutError
         :type timeout: typing.Union[int, float, None]
+        :param verbose: produce log.info records for STDOUT/STDERR
         :type verbose: bool
         :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 kwargs: additional parameters for call.
+        :type kwargs: typing.Any
+        :return: Execution result
         :rtype: ExecResult
         :raises ExecHelperTimeoutError: Timeout exceeded
 
@@ -784,6 +804,9 @@ def execute_through_host(
         :type timeout: typing.Union[int, float, None]
         :param get_pty: open PTY on target machine
         :type get_pty: bool
+        :param kwargs: additional parameters for call.
+        :type kwargs: typing.Any
+        :return: Execution result
         :rtype: ExecResult
         :raises ExecHelperTimeoutError: Timeout exceeded
 
@@ -859,6 +882,8 @@ def execute_together(
         :type expected: typing.Optional[typing.Iterable[]]
         :param raise_on_err: Raise exception on unexpected return code
         :type raise_on_err: bool
+        :param kwargs: additional parameters for execute_async call.
+        :type kwargs: typing.Any
         :return: dictionary {(hostname, port): result}
         :rtype: typing.Dict[typing.Tuple[str, int], exec_result.ExecResult]
         :raises ParallelCallProcessError: Unexpected any code at lest on one target
@@ -946,16 +971,21 @@ def get_result(remote):  # type: (SSHClientBase) -> exec_result.ExecResult
     def open(self, path, mode='r'):  # type: (str, str) -> paramiko.SFTPFile
         """Open file on remote using SFTP session.
 
+        :param path: filesystem object path
         :type path: str
+        :param mode: open file mode ('t' is not supported)
         :type mode: str
         :return: file.open() stream
+        :rtype: paramiko.SFTPFile
         """
         return self._sftp.open(path, mode)  # pragma: no cover
 
     def exists(self, path):  # type: (str) -> bool
         """Check for file existence using SFTP session.
 
+        :param path: filesystem object path
         :type path: str
+        :return: path is valid (object exists)
         :rtype: bool
         """
         try:
@@ -967,7 +997,9 @@ def exists(self, path):  # type: (str) -> bool
     def stat(self, path):  # type: (str) -> paramiko.sftp_attr.SFTPAttributes
         """Get stat info for path with following symlinks.
 
+        :param path: filesystem object path
         :type path: str
+        :return: stat like information for remote path
         :rtype: paramiko.sftp_attr.SFTPAttributes
         """
         return self._sftp.stat(path)  # pragma: no cover
@@ -991,7 +1023,9 @@ def utime(
     def isfile(self, path):  # type: (str) -> bool
         """Check, that path is file using SFTP session.
 
+        :param path: remote path to validate
         :type path: str
+        :return: path is file
         :rtype: bool
         """
         try:
@@ -1003,7 +1037,9 @@ def isfile(self, path):  # type: (str) -> bool
     def isdir(self, path):  # type: (str) -> bool
         """Check, that path is directory using SFTP session.
 
+        :param path: remote path to validate
         :type path: str
+        :return: path is directory
         :rtype: bool
         """
         try: