Skip to content

Commit 814d435

Browse files
penguinologpenguinolog
authored
Add type stubs and py.typed. Fix #40 Fix #41 (#42)
* Add type stubs and py.typed. Fix #40 Fix #41 * Signatures verified and updated * stubs without cyclic imports (no stubs for simple code) * py.typed added
1 parent 261e703 commit 814d435

18 files changed

+609
-119
lines changed

‎doc/source/ExecResult.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ API: ExecResult
4040

4141
.. py:attribute:: stdin
4242
43-
``str``
43+
``typing.Text``
4444
Stdin input as string.
4545

4646
.. py:attribute:: stdout
@@ -65,22 +65,22 @@ API: ExecResult
6565

6666
.. py:attribute:: stdout_str
6767
68-
``str``
68+
``typing.Text``
6969
Stdout output as string.
7070

7171
.. py:attribute:: stderr_str
7272
73-
``str``
73+
``typing.Text``
7474
Stderr output as string.
7575

7676
.. py:attribute:: stdout_brief
7777
78-
``str``
78+
``typing.Text``
7979
Brief stdout output (mostly for exceptions).
8080

8181
.. py:attribute:: stderr_brief
8282
83-
``str``
83+
``typing.Text``
8484
Brief stderr output (mostly for exceptions).
8585

8686
.. py:attribute:: exit_code

‎doc/source/SSHClient.rst‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -106,13 +106,15 @@ API: SSHClient and SSHAuth.
106106

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

110111
.. py:method:: keepalive(enforce=None)
111112
112113
Context manager getter for keepalive operation.
113114

114115
:param enforce: Enforce keepalive enabled or disabled. By default: True
115116
:type enforce: ``typing.bool``
117+
:rtype: ``typing.ContextManager``
116118

117119
.. Note:: Enter and exit ssh context manager is produced as well.
118120
.. versionadded:: 1.2.1
@@ -124,7 +126,7 @@ API: SSHClient and SSHAuth.
124126
:param command: Command for execution
125127
:type command: ``str``
126128
:param stdin: pass STDIN text to the process
127-
:type stdin: ``typing.Union[six.text_type, six.binary_type, bytearray, None]``
129+
:type stdin: ``typing.Union[typing.AnyStr, bytearray, None]``
128130
:param open_stdout: open STDOUT stream for read
129131
:type open_stdout: bool
130132
:param open_stderr: open STDERR stream for read
@@ -149,7 +151,7 @@ API: SSHClient and SSHAuth.
149151
:param verbose: Produce log.info records for command call and output
150152
:type verbose: ``bool``
151153
:param timeout: Timeout for command execution.
152-
:type timeout: ``typing.Optional[int]``
154+
:type timeout: ``typing.Union[int, None]``
153155
:rtype: ExecResult
154156
:raises ExecHelperTimeoutError: Timeout exceeded
155157

@@ -164,7 +166,7 @@ API: SSHClient and SSHAuth.
164166
:param verbose: Produce log.info records for command call and output
165167
:type verbose: ``bool``
166168
:param timeout: Timeout for command execution.
167-
:type timeout: ``typing.Optional[int]``
169+
:type timeout: ``typing.Union[int, None]``
168170
:param error_info: Text for error details, if fail happens
169171
:type error_info: ``typing.Optional[str]``
170172
:param expected: expected return codes (0 by default)
@@ -186,7 +188,7 @@ API: SSHClient and SSHAuth.
186188
:param verbose: Produce log.info records for command call and output
187189
:type verbose: ``bool``
188190
:param timeout: Timeout for command execution.
189-
:type timeout: ``typing.Optional[int]``
191+
:type timeout: ``typing.Union[int, None]``
190192
:param error_info: Text for error details, if fail happens
191193
:type error_info: ``typing.Optional[str]``
192194
:param raise_on_err: Raise exception on unexpected return code
@@ -213,7 +215,7 @@ API: SSHClient and SSHAuth.
213215
:param verbose: Produce log.info records for command call and output
214216
:type verbose: ``bool``
215217
:param timeout: Timeout for command execution.
216-
:type timeout: ``typing.Optional[int]``
218+
:type timeout: ``typing.Union[int, None]``
217219
:param get_pty: open PTY on target machine
218220
:type get_pty: ``bool``
219221
:rtype: ExecResult
@@ -230,7 +232,7 @@ API: SSHClient and SSHAuth.
230232
:param command: Command for execution
231233
:type command: ``str``
232234
:param timeout: Timeout for command execution.
233-
:type timeout: ``typing.Optional[int]``
235+
:type timeout: ``typing.Union[int, None]``
234236
:param expected: expected return codes (0 by default)
235237
:type expected: ``typing.Optional[typing.Iterable[]]``
236238
:param raise_on_err: Raise exception on unexpected return code
@@ -271,6 +273,7 @@ API: SSHClient and SSHAuth.
271273
:type path: str
272274
:param times: (atime, mtime)
273275
:type times: typing.Optional[typing.Tuple[int, int]]
276+
:rtype: None
274277

275278
.. versionadded:: 1.0.0
276279

@@ -347,7 +350,7 @@ API: SSHClient and SSHAuth.
347350

348351
.. py:attribute:: username
349352
350-
``str``
353+
``typing.Optional[str]``
351354

352355
.. py:attribute:: public_key
353356

‎doc/source/Subprocess.rst‎

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -46,16 +46,16 @@ API: Subprocess
4646
:param command: Command for execution
4747
:type command: str
4848
:param stdin: pass STDIN text to the process
49-
:type stdin: typing.Union[six.text_type, six.binary_type, bytearray, None]
49+
:type stdin: ``typing.Union[typing.AnyStr, bytearray, None]``
5050
:param open_stdout: open STDOUT stream for read
51-
:type open_stdout: bool
51+
:type open_stdout: ``bool``
5252
:param open_stderr: open STDERR stream for read
53-
:type open_stderr: bool
53+
:type open_stderr: ``bool``
5454
:param verbose: produce verbose log record on command call
55-
:type verbose: bool
55+
:type verbose: ``bool``
5656
:param log_mask_re: regex lookup rule to mask command for logger.
5757
all MATCHED groups will be replaced by '<*masked*>'
58-
:type log_mask_re: typing.Optional[str]
58+
:type log_mask_re: ``typing.Optional[str]``
5959
:rtype: ``typing.Tuple[subprocess.Popen, None, typing.Optional[typing.IO], typing.Optional[typing.IO], ]``
6060

6161
.. versionadded:: 1.2.0
@@ -66,12 +66,10 @@ API: Subprocess
6666

6767
:param command: Command for execution
6868
:type command: ``str``
69-
:param stdin: STDIN passed to execution
70-
:type stdin: ``typing.Union[six.text_type, six.binary_type, None]``
7169
:param verbose: Produce log.info records for command call and output
7270
:type verbose: ``bool``
7371
:param timeout: Timeout for command execution.
74-
:type timeout: ``typing.Optional[int]``
72+
:type timeout: ``typing.Union[int, None]``
7573
:rtype: ExecResult
7674
:raises ExecHelperTimeoutError: Timeout exceeded
7775

@@ -90,7 +88,7 @@ API: Subprocess
9088
:param verbose: Produce log.info records for command call and output
9189
:type verbose: ``bool``
9290
:param timeout: Timeout for command execution.
93-
:type timeout: ``typing.Optional[int]``
91+
:type timeout: ``typing.Union[int, None]``
9492
:param error_info: Text for error details, if fail happens
9593
:type error_info: ``typing.Optional[str]``
9694
:param expected: expected return codes (0 by default)
@@ -113,7 +111,7 @@ API: Subprocess
113111
:param verbose: Produce log.info records for command call and output
114112
:type verbose: ``bool``
115113
:param timeout: Timeout for command execution.
116-
:type timeout: ``typing.Optional[int]``
114+
:type timeout: ``typing.Union[int, None]``
117115
:param error_info: Text for error details, if fail happens
118116
:type error_info: ``typing.Optional[str]``
119117
:param raise_on_err: Raise exception on unexpected return code

‎exec_helpers/_api.py‎

Lines changed: 13 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -25,18 +25,13 @@
2525
import logging
2626
import re
2727
import threading
28-
import typing
29-
30-
import six # noqa # pylint: disable=unused-import
28+
import typing # noqa # pylint: disable=unused-import
3129

3230
from exec_helpers import constants
3331
from exec_helpers import exceptions
3432
from exec_helpers import exec_result # noqa # pylint: disable=unused-import
3533
from exec_helpers import proc_enums
3634

37-
_type_exit_codes = typing.Union[int, proc_enums.ExitCodes]
38-
_type_expected = typing.Optional[typing.Iterable[_type_exit_codes]]
39-
4035

4136
class ExecHelper(object):
4237
"""ExecHelper global API."""
@@ -136,19 +131,19 @@ def mask(text, rules): # type: (str, str) -> str
136131
def execute_async(
137132
self,
138133
command, # type: str
139-
stdin=None, # type: typing.Union[six.text_type, six.binary_type, bytearray, None]
134+
stdin=None, # type: typing.Union[typing.AnyStr, bytearray, None]
140135
open_stdout=True, # type: bool
141136
open_stderr=True, # type: bool
142137
verbose=False, # type: bool
143138
log_mask_re=None, # type: typing.Optional[str]
144139
**kwargs
145-
):
140+
): # type: (...) -> typing.Tuple[typing.Any, typing.Any, typing.Any, typing.Any,]
146141
"""Execute command in async mode and return remote interface with IO objects.
147142
148143
:param command: Command for execution
149144
:type command: str
150145
:param stdin: pass STDIN text to the process
151-
:type stdin: typing.Union[six.text_type, six.binary_type, bytearray, None]
146+
:type stdin: typing.Union[typing.AnyStr, bytearray, None]
152147
:param open_stdout: open STDOUT stream for read
153148
:type open_stdout: bool
154149
:param open_stderr: open STDERR stream for read
@@ -176,7 +171,7 @@ def _exec_command(
176171
interface, # type: typing.Any
177172
stdout, # type: typing.Any
178173
stderr, # type: typing.Any
179-
timeout, # type: int
174+
timeout, # type: typing.Union[int, None]
180175
verbose=False, # type: bool
181176
log_mask_re=None, # type: typing.Optional[str]
182177
**kwargs
@@ -209,7 +204,7 @@ def execute(
209204
self,
210205
command, # type: str
211206
verbose=False, # type: bool
212-
timeout=constants.DEFAULT_TIMEOUT, # type: typing.Optional[int]
207+
timeout=constants.DEFAULT_TIMEOUT, # type: typing.Union[int, None]
213208
**kwargs
214209
): # type: (...) -> exec_result.ExecResult
215210
"""Execute command and wait for return code.
@@ -221,7 +216,7 @@ def execute(
221216
:param verbose: Produce log.info records for command call and output
222217
:type verbose: bool
223218
:param timeout: Timeout for command execution.
224-
:type timeout: typing.Optional[int]
219+
:type timeout: typing.Union[int, None]
225220
:rtype: ExecResult
226221
:raises ExecHelperTimeoutError: Timeout exceeded
227222
@@ -259,9 +254,9 @@ def check_call(
259254
self,
260255
command, # type: str
261256
verbose=False, # type: bool
262-
timeout=constants.DEFAULT_TIMEOUT, # type: typing.Optional[int]
257+
timeout=constants.DEFAULT_TIMEOUT, # type: typing.Union[int, None]
263258
error_info=None, # type: typing.Optional[str]
264-
expected=None, # type: _type_expected
259+
expected=None, # type: typing.Optional[typing.Iterable[typing.Union[int, proc_enums.ExitCodes]]]
265260
raise_on_err=True, # type: bool
266261
**kwargs
267262
): # type: (...) -> exec_result.ExecResult
@@ -274,11 +269,11 @@ def check_call(
274269
:param verbose: Produce log.info records for command call and output
275270
:type verbose: bool
276271
:param timeout: Timeout for command execution.
277-
:type timeout: typing.Optional[int]
272+
:type timeout: typing.Union[int, None]
278273
:param error_info: Text for error details, if fail happens
279274
:type error_info: typing.Optional[str]
280275
:param expected: expected return codes (0 by default)
281-
:type expected: typing.Optional[typing.Iterable[int]]
276+
:type expected: typing.Optional[typing.Iterable[typing.Union[int, proc_enums.ExitCodes]]]
282277
:param raise_on_err: Raise exception on unexpected return code
283278
:type raise_on_err: bool
284279
:rtype: ExecResult
@@ -309,7 +304,7 @@ def check_stderr(
309304
self,
310305
command, # type: str
311306
verbose=False, # type: bool
312-
timeout=constants.DEFAULT_TIMEOUT, # type: typing.Optional[int]
307+
timeout=constants.DEFAULT_TIMEOUT, # type: typing.Union[int, None]
313308
error_info=None, # type: typing.Optional[str]
314309
raise_on_err=True, # type: bool
315310
**kwargs
@@ -323,7 +318,7 @@ def check_stderr(
323318
:param verbose: Produce log.info records for command call and output
324319
:type verbose: bool
325320
:param timeout: Timeout for command execution.
326-
:type timeout: typing.Optional[int]
321+
:type timeout: typing.Union[int, None]
327322
:param error_info: Text for error details, if fail happens
328323
:type error_info: typing.Optional[str]
329324
:param raise_on_err: Raise exception on unexpected return code

‎exec_helpers/_api.pyi‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
import logging
2+
import threading
3+
import typing
4+
5+
from exec_helpers import exec_result, proc_enums
6+
7+
class ExecHelper:
8+
log_mask_re: typing.Optional[str] = ...
9+
10+
def __init__(self, logger: logging.Logger, log_mask_re: typing.Optional[str]=...) -> None: ...
11+
12+
@property
13+
def logger(self) -> logging.Logger: ...
14+
15+
@property
16+
def lock(self) -> threading.RLock: ...
17+
18+
def __enter__(self): ...
19+
20+
def __exit__(self, exc_type: typing.Any, exc_val: typing.Any, exc_tb: typing.Any) -> None: ...
21+
22+
def _mask_command(self, cmd: str, log_mask_re: typing.Optional[str]=...) -> str: ...
23+
24+
def execute_async(
25+
self,
26+
command: str,
27+
stdin: typing.Union[typing.AnyStr, bytearray, None]=...,
28+
open_stdout: bool=...,
29+
open_stderr: bool=...,
30+
verbose: bool=...,
31+
log_mask_re: typing.Optional[str]=...,
32+
**kwargs
33+
) -> typing.Tuple[typing.Any, typing.Any, typing.Any, typing.Any,]: ...
34+
35+
def _exec_command(
36+
self,
37+
command: str,
38+
interface: typing.Any,
39+
stdout: typing.Any,
40+
stderr: typing.Any,
41+
timeout: typing.Union[int, None],
42+
verbose: bool=...,
43+
log_mask_re: typing.Optional[str]=...,
44+
**kwargs
45+
) -> exec_result.ExecResult: ...
46+
47+
def execute(
48+
self,
49+
command: str,
50+
verbose: bool=...,
51+
timeout: typing.Union[int, None]=...,
52+
**kwargs
53+
) -> exec_result.ExecResult: ...
54+
55+
def check_call(
56+
self,
57+
command: str,
58+
verbose: bool=...,
59+
timeout: typing.Union[int, None]=...,
60+
error_info: typing.Optional[str]=...,
61+
expected: typing.Optional[typing.Iterable[typing.Union[int, proc_enums.ExitCodes]]]=...,
62+
raise_on_err: bool=...,
63+
**kwargs
64+
) -> exec_result.ExecResult: ...
65+
66+
def check_stderr(
67+
self,
68+
command: str,
69+
verbose: bool=...,
70+
timeout: typing.Union[int, None]=...,
71+
error_info: typing.Optional[str]=...,
72+
raise_on_err: bool=...,
73+
**kwargs
74+
) -> exec_result.ExecResult: ...

0 commit comments

Comments
 (0)