Skip to content

Add type stubs and py.typed. Fix #40 Fix #41 #42

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
May 18, 2018
Merged

Add type stubs and py.typed. Fix #40 Fix #41 #42

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
09ea00b
Add type stubs and py.typed. Fix #40 Fix #41
penguinolog May 18, 2018
c4acdf1
Fix typing for package_data
penguinolog May 18, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions doc/source/ExecResult.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ API: ExecResult

.. py:attribute:: stdin

``str``
``typing.Text``
Stdin input as string.

.. py:attribute:: stdout
Expand All @@ -65,22 +65,22 @@ API: ExecResult

.. py:attribute:: stdout_str

``str``
``typing.Text``
Stdout output as string.

.. py:attribute:: stderr_str

``str``
``typing.Text``
Stderr output as string.

.. py:attribute:: stdout_brief

``str``
``typing.Text``
Brief stdout output (mostly for exceptions).

.. py:attribute:: stderr_brief

``str``
``typing.Text``
Brief stderr output (mostly for exceptions).

.. py:attribute:: exit_code
Expand Down
17 changes: 10 additions & 7 deletions doc/source/SSHClient.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,13 +106,15 @@ API: SSHClient and SSHAuth.

:param enforce: Enforce sudo enabled or disabled. By default: None
:type enforce: ``typing.Optional[bool]``
:rtype: ``typing.ContextManager``

.. py:method:: keepalive(enforce=None)

Context manager getter for keepalive operation.

:param enforce: Enforce keepalive enabled or disabled. By default: True
:type enforce: ``typing.bool``
:rtype: ``typing.ContextManager``

.. Note:: Enter and exit ssh context manager is produced as well.
.. versionadded:: 1.2.1
Expand All @@ -124,7 +126,7 @@ API: SSHClient and SSHAuth.
:param command: Command for execution
:type command: ``str``
:param stdin: pass STDIN text to the process
:type stdin: ``typing.Union[six.text_type, six.binary_type, bytearray, None]``
:type stdin: ``typing.Union[typing.AnyStr, bytearray, None]``
:param open_stdout: open STDOUT stream for read
:type open_stdout: bool
:param open_stderr: open STDERR stream for read
Expand All @@ -149,7 +151,7 @@ API: SSHClient and SSHAuth.
:param verbose: Produce log.info records for command call and output
:type verbose: ``bool``
:param timeout: Timeout for command execution.
:type timeout: ``typing.Optional[int]``
:type timeout: ``typing.Union[int, None]``
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why? I remember previously you replaced Union[x, None] with Optional

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

None is not default here, and Optional for cases, when None is default. (Anyway Optional[T] === Union[None, T])

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see

:rtype: ExecResult
:raises ExecHelperTimeoutError: Timeout exceeded

Expand All @@ -164,7 +166,7 @@ API: SSHClient and SSHAuth.
:param verbose: Produce log.info records for command call and output
:type verbose: ``bool``
:param timeout: Timeout for command execution.
:type timeout: ``typing.Optional[int]``
:type timeout: ``typing.Union[int, None]``
:param error_info: Text for error details, if fail happens
:type error_info: ``typing.Optional[str]``
:param expected: expected return codes (0 by default)
Expand All @@ -186,7 +188,7 @@ API: SSHClient and SSHAuth.
:param verbose: Produce log.info records for command call and output
:type verbose: ``bool``
:param timeout: Timeout for command execution.
:type timeout: ``typing.Optional[int]``
:type timeout: ``typing.Union[int, None]``
:param error_info: Text for error details, if fail happens
:type error_info: ``typing.Optional[str]``
:param raise_on_err: Raise exception on unexpected return code
Expand All @@ -213,7 +215,7 @@ API: SSHClient and SSHAuth.
:param verbose: Produce log.info records for command call and output
:type verbose: ``bool``
:param timeout: Timeout for command execution.
:type timeout: ``typing.Optional[int]``
:type timeout: ``typing.Union[int, None]``
:param get_pty: open PTY on target machine
:type get_pty: ``bool``
:rtype: ExecResult
Expand All @@ -230,7 +232,7 @@ API: SSHClient and SSHAuth.
:param command: Command for execution
:type command: ``str``
:param timeout: Timeout for command execution.
:type timeout: ``typing.Optional[int]``
:type timeout: ``typing.Union[int, None]``
:param expected: expected return codes (0 by default)
:type expected: ``typing.Optional[typing.Iterable[]]``
:param raise_on_err: Raise exception on unexpected return code
Expand Down Expand Up @@ -271,6 +273,7 @@ API: SSHClient and SSHAuth.
:type path: str
:param times: (atime, mtime)
:type times: typing.Optional[typing.Tuple[int, int]]
:rtype: None

.. versionadded:: 1.0.0

Expand Down Expand Up @@ -347,7 +350,7 @@ API: SSHClient and SSHAuth.

.. py:attribute:: username

``str``
``typing.Optional[str]``

.. py:attribute:: public_key

Expand Down
18 changes: 8 additions & 10 deletions doc/source/Subprocess.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,16 +46,16 @@ API: Subprocess
:param command: Command for execution
:type command: str
:param stdin: pass STDIN text to the process
:type stdin: typing.Union[six.text_type, six.binary_type, bytearray, None]
:type stdin: ``typing.Union[typing.AnyStr, bytearray, None]``
:param open_stdout: open STDOUT stream for read
:type open_stdout: bool
:type open_stdout: ``bool``
:param open_stderr: open STDERR stream for read
:type open_stderr: bool
:type open_stderr: ``bool``
:param verbose: produce verbose log record on command call
:type verbose: bool
: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]
:type log_mask_re: ``typing.Optional[str]``
:rtype: ``typing.Tuple[subprocess.Popen, None, typing.Optional[typing.IO], typing.Optional[typing.IO], ]``

.. versionadded:: 1.2.0
Expand All @@ -66,12 +66,10 @@ API: Subprocess

:param command: Command for execution
:type command: ``str``
:param stdin: STDIN passed to execution
:type stdin: ``typing.Union[six.text_type, six.binary_type, None]``
:param verbose: Produce log.info records for command call and output
:type verbose: ``bool``
:param timeout: Timeout for command execution.
:type timeout: ``typing.Optional[int]``
:type timeout: ``typing.Union[int, None]``
:rtype: ExecResult
:raises ExecHelperTimeoutError: Timeout exceeded

Expand All @@ -90,7 +88,7 @@ API: Subprocess
:param verbose: Produce log.info records for command call and output
:type verbose: ``bool``
:param timeout: Timeout for command execution.
:type timeout: ``typing.Optional[int]``
:type timeout: ``typing.Union[int, None]``
:param error_info: Text for error details, if fail happens
:type error_info: ``typing.Optional[str]``
:param expected: expected return codes (0 by default)
Expand All @@ -113,7 +111,7 @@ API: Subprocess
:param verbose: Produce log.info records for command call and output
:type verbose: ``bool``
:param timeout: Timeout for command execution.
:type timeout: ``typing.Optional[int]``
:type timeout: ``typing.Union[int, None]``
:param error_info: Text for error details, if fail happens
:type error_info: ``typing.Optional[str]``
:param raise_on_err: Raise exception on unexpected return code
Expand Down
31 changes: 13 additions & 18 deletions exec_helpers/_api.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,18 +25,13 @@
import logging
import re
import threading
import typing

import six # noqa # pylint: disable=unused-import
import typing # noqa # pylint: disable=unused-import

from exec_helpers import constants
from exec_helpers import exceptions
from exec_helpers import exec_result # noqa # pylint: disable=unused-import
from exec_helpers import proc_enums

_type_exit_codes = typing.Union[int, proc_enums.ExitCodes]
_type_expected = typing.Optional[typing.Iterable[_type_exit_codes]]


class ExecHelper(object):
"""ExecHelper global API."""
Expand Down Expand Up @@ -136,19 +131,19 @@ def mask(text, rules): # type: (str, str) -> str
def execute_async(
self,
command, # type: str
stdin=None, # type: typing.Union[six.text_type, six.binary_type, bytearray, None]
stdin=None, # type: typing.Union[typing.AnyStr, bytearray, None]
open_stdout=True, # type: bool
open_stderr=True, # type: bool
verbose=False, # type: bool
log_mask_re=None, # type: typing.Optional[str]
**kwargs
):
): # type: (...) -> typing.Tuple[typing.Any, typing.Any, typing.Any, typing.Any,]
"""Execute command in async mode and return remote interface with IO objects.

:param command: Command for execution
:type command: str
:param stdin: pass STDIN text to the process
:type stdin: typing.Union[six.text_type, six.binary_type, bytearray, None]
:type stdin: typing.Union[typing.AnyStr, bytearray, None]
:param open_stdout: open STDOUT stream for read
:type open_stdout: bool
:param open_stderr: open STDERR stream for read
Expand Down Expand Up @@ -176,7 +171,7 @@ def _exec_command(
interface, # type: typing.Any
stdout, # type: typing.Any
stderr, # type: typing.Any
timeout, # type: int
timeout, # type: typing.Union[int, None]
verbose=False, # type: bool
log_mask_re=None, # type: typing.Optional[str]
**kwargs
Expand Down Expand Up @@ -209,7 +204,7 @@ def execute(
self,
command, # type: str
verbose=False, # type: bool
timeout=constants.DEFAULT_TIMEOUT, # type: typing.Optional[int]
timeout=constants.DEFAULT_TIMEOUT, # type: typing.Union[int, None]
**kwargs
): # type: (...) -> exec_result.ExecResult
"""Execute command and wait for return code.
Expand All @@ -221,7 +216,7 @@ def execute(
:param verbose: Produce log.info records for command call and output
:type verbose: bool
:param timeout: Timeout for command execution.
:type timeout: typing.Optional[int]
:type timeout: typing.Union[int, None]
:rtype: ExecResult
:raises ExecHelperTimeoutError: Timeout exceeded

Expand Down Expand Up @@ -259,9 +254,9 @@ def check_call(
self,
command, # type: str
verbose=False, # type: bool
timeout=constants.DEFAULT_TIMEOUT, # type: typing.Optional[int]
timeout=constants.DEFAULT_TIMEOUT, # type: typing.Union[int, None]
error_info=None, # type: typing.Optional[str]
expected=None, # type: _type_expected
expected=None, # type: typing.Optional[typing.Iterable[typing.Union[int, proc_enums.ExitCodes]]]
raise_on_err=True, # type: bool
**kwargs
): # type: (...) -> exec_result.ExecResult
Expand All @@ -274,11 +269,11 @@ def check_call(
:param verbose: Produce log.info records for command call and output
:type verbose: bool
:param timeout: Timeout for command execution.
:type timeout: typing.Optional[int]
:type timeout: typing.Union[int, None]
: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.Optional[typing.Iterable[typing.Union[int, proc_enums.ExitCodes]]]
:param raise_on_err: Raise exception on unexpected return code
:type raise_on_err: bool
:rtype: ExecResult
Expand Down Expand Up @@ -309,7 +304,7 @@ def check_stderr(
self,
command, # type: str
verbose=False, # type: bool
timeout=constants.DEFAULT_TIMEOUT, # type: typing.Optional[int]
timeout=constants.DEFAULT_TIMEOUT, # type: typing.Union[int, None]
error_info=None, # type: typing.Optional[str]
raise_on_err=True, # type: bool
**kwargs
Expand All @@ -323,7 +318,7 @@ def check_stderr(
:param verbose: Produce log.info records for command call and output
:type verbose: bool
:param timeout: Timeout for command execution.
:type timeout: typing.Optional[int]
:type timeout: typing.Union[int, None]
:param error_info: Text for error details, if fail happens
:type error_info: typing.Optional[str]
:param raise_on_err: Raise exception on unexpected return code
Expand Down
74 changes: 74 additions & 0 deletions exec_helpers/_api.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
import logging
import threading
import typing

from exec_helpers import exec_result, proc_enums

class ExecHelper:
log_mask_re: typing.Optional[str] = ...

def __init__(self, logger: logging.Logger, log_mask_re: typing.Optional[str]=...) -> None: ...

@property
def logger(self) -> logging.Logger: ...

@property
def lock(self) -> threading.RLock: ...

def __enter__(self): ...

def __exit__(self, exc_type: typing.Any, exc_val: typing.Any, exc_tb: typing.Any) -> None: ...

def _mask_command(self, cmd: str, log_mask_re: typing.Optional[str]=...) -> str: ...

def execute_async(
self,
command: str,
stdin: typing.Union[typing.AnyStr, bytearray, None]=...,
open_stdout: bool=...,
open_stderr: bool=...,
verbose: bool=...,
log_mask_re: typing.Optional[str]=...,
**kwargs
) -> typing.Tuple[typing.Any, typing.Any, typing.Any, typing.Any,]: ...

def _exec_command(
self,
command: str,
interface: typing.Any,
stdout: typing.Any,
stderr: typing.Any,
timeout: typing.Union[int, None],
verbose: bool=...,
log_mask_re: typing.Optional[str]=...,
**kwargs
) -> exec_result.ExecResult: ...

def execute(
self,
command: str,
verbose: bool=...,
timeout: typing.Union[int, None]=...,
**kwargs
) -> exec_result.ExecResult: ...

def check_call(
self,
command: str,
verbose: bool=...,
timeout: typing.Union[int, None]=...,
error_info: typing.Optional[str]=...,
expected: typing.Optional[typing.Iterable[typing.Union[int, proc_enums.ExitCodes]]]=...,
raise_on_err: bool=...,
**kwargs
) -> exec_result.ExecResult: ...

def check_stderr(
self,
command: str,
verbose: bool=...,
timeout: typing.Union[int, None]=...,
error_info: typing.Optional[str]=...,
raise_on_err: bool=...,
**kwargs
) -> exec_result.ExecResult: ...
Loading