Skip to content

Commit 83488d9

Browse files
marian-codemarian-code
committed
added type aliases documentation, enhancements in typing
1 parent 38f0f24 commit 83488d9

File tree

10 files changed

+94
-56
lines changed

10 files changed

+94
-56
lines changed

‎docs/source/api.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,4 +49,9 @@ ssh_utilities.exceptions
4949
ssh_utilities.constants
5050
-----------------------
5151
.. automodule:: ssh_utilities.constants
52+
:members:
53+
54+
ssh_utilities.typeshed
55+
----------------------
56+
.. automodule:: ssh_utilities.typeshed
5257
:members:

‎ssh_utilities/abc/_builtins.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ def open(self, filename: "_SPATH", mode: str = "r",
3535
3636
Parameters
3737
----------
38-
filename: _SPATH
38+
filename: :const:`ssh_utilities.typeshed._SPATH`
3939
path to file to be opened
4040
mode: str
4141
select mode to open file. Same as python open modes

‎ssh_utilities/abc/_connection.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@ def _path2str(path: Optional["_SPATH"]) -> str:
101101
102102
Parameters
103103
----------
104-
path: "_SPATH"
104+
path: :const:`ssh_utilities.typeshed._SPATH`
105105
path to convert to string, if string is passed,
106106
then just returns it
107107

‎ssh_utilities/abc/_os.py‎

Lines changed: 34 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
from typing import TYPE_CHECKING, Generic, FrozenSet, TypeVar
55

66
if TYPE_CHECKING:
7-
from ..typeshed import _SPATH
7+
from ..typeshed import _SPATH, _ONERROR
88

99
__all__ = ["OsPathABC", "OsABC"]
1010

@@ -36,7 +36,7 @@ def realpath(self, path: "_SPATH") -> str:
3636
3737
Parameters
3838
----------
39-
path : _SPATH
39+
path : :const:`ssh_utilities.typeshed._SPATH`
4040
path to resolve
4141
4242
Returns
@@ -59,7 +59,7 @@ def isfile(self, path: "_SPATH") -> _Os1:
5959
6060
Parameters
6161
----------
62-
path: "_SPATH"
62+
path: :const:`ssh_utilities.typeshed._SPATH`
6363
path to check
6464
6565
Raises
@@ -75,7 +75,7 @@ def isdir(self, path: "_SPATH") -> _Os1:
7575
7676
Parameters
7777
----------
78-
path: "_SPATH"
78+
path: :const:`ssh_utilities.typeshed._SPATH`
7979
path to check
8080
8181
Raises
@@ -94,7 +94,7 @@ def makedirs(self, path: "_SPATH", mode: int = 511, exist_ok: bool = True,
9494
9595
Parameters
9696
----------
97-
path: "_SPATH"
97+
path: :const:`ssh_utilities.typeshed._SPATH`
9898
path to directory which should be created
9999
mode: int
100100
create directory with mode, default is 511
@@ -126,7 +126,7 @@ def mkdir(self, path: "_SPATH", mode: int = 511, quiet: bool = True):
126126
127127
Parameters
128128
----------
129-
path: "_SPATH"
129+
path: :const:`ssh_utilities.typeshed._SPATH`
130130
path to directory which should be created
131131
mode: int
132132
create directory with mode, default is 511
@@ -150,7 +150,7 @@ def listdir(self, path: "_SPATH") -> _Os2:
150150
151151
Parameters
152152
----------
153-
path: "_SPATH"
153+
path: :const:`ssh_utilities.typeshed._SPATH`
154154
directory path
155155
156156
Returns
@@ -176,7 +176,7 @@ def stat(self, path: "_SPATH", *, dir_fd=None,
176176
177177
Parameters
178178
----------
179-
path: _SPATH
179+
path: :const:`ssh_utilities.typeshed._SPATH`
180180
path to file whose stats are desired
181181
dir_fd: Any
182182
not implemented
@@ -201,7 +201,7 @@ def lstat(self, path: "_SPATH", *, dir_fd=None) -> _Os3:
201201
202202
Parameters
203203
----------
204-
path: _SPATH
204+
path: :const:`ssh_utilities.typeshed._SPATH`
205205
path to file whose stats are desired
206206
dir_fd: Any
207207
not implemented in remote version
@@ -262,6 +262,29 @@ def path(self, path: _Os5):
262262
raise NotImplementedError
263263

264264
def walk(self, top: "_SPATH", topdown: bool = True,
265-
onerror=None, followlinks: bool = False) -> _Os6:
266-
"""Recursive directory listing."""
265+
onerror: "_ONERROR" = None, followlinks: bool = False) -> _Os6:
266+
"""Recursive directory listing.
267+
268+
Parameters
269+
----------
270+
top : :const:`ssh_utilities.typeshed._SPATH`
271+
directory to start from
272+
topdown : bool, optional
273+
if true or not specified, the triple for a directory is generated
274+
before the triples for any of its subdirectories (directories are
275+
generated top-down). This enables you to modify the subdirectories
276+
list in place befor iteration continues. If topdown is False, the
277+
triple for a directory is generated after the triples for all of
278+
its subdirectories, by default True
279+
onerror : :const:`ssh_utilities.typeshed._ONERROR`, optional
280+
Callable acception one argument of type exception which decides
281+
how to handle that exception, by default None
282+
followlinks : bool, optional
283+
follow symbolic links if true, by default False
284+
285+
Returns
286+
-------
287+
:const:`ssh_utilities.typeshed._WALK`
288+
iterator of 3 tuples containing current dir, subdirs and files
289+
"""
267290
raise NotImplementedError

‎ssh_utilities/abc/_pathlib.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ def Path(self, path: "_SPATH") -> _Pathlib1:
3232
3333
Parameters
3434
----------
35-
path: _SPATH
35+
path: :const:`ssh_utilities.typeshed._SPATH`
3636
provide initial path
3737
3838
Returns

‎ssh_utilities/abc/_shutil.py‎

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,9 @@ def copy_files(self, files: List[str], remote_path: "_SPATH",
2727
----------
2828
files: List[str]
2929
list of files to upload/download
30-
remote_path: "_SPATH"
30+
remote_path: :const:`ssh_utilities.typeshed._SPATH`
3131
path to remote directory with files
32-
local_path: "_SPATH"
32+
local_path: :const:`ssh_utilities.typeshed._SPATH`
3333
path to local directory with files
3434
direction: str
3535
get for download and put for upload
@@ -48,15 +48,15 @@ def copyfile(self, src: "_SPATH", dst: "_SPATH", *,
4848
4949
Parameters
5050
----------
51-
src: "_SPATH"
51+
src: :const:`ssh_utilities.typeshed._SPATH`
5252
path to the file
53-
dst: "_SPATH"
53+
dst: :const:`ssh_utilities.typeshed._SPATH`
5454
path to copy into
55-
direction: str
55+
direction: :const:`ssh_utilities.typeshed._DIRECTION`
5656
'get' for download and 'put' for upload
5757
follow_symlinks: bool
5858
resolve symlinks when looking for file, by default True
59-
callback: Callable[[float, float], Any]
59+
callback: :const:`ssh_utilities.typeshed._CALLBACK`
6060
callback function that recives two arguments: amount done and total
6161
amount to be copied
6262
quiet: bool
@@ -81,15 +81,15 @@ def copy(self, src: "_SPATH", dst: "_SPATH", *, direction: "_DIRECTION",
8181
8282
Parameters
8383
----------
84-
src: "_SPATH"
84+
src: :const:`ssh_utilities.typeshed._SPATH`
8585
path to the file
86-
dst: "_SPATH"
86+
dst: :const:`ssh_utilities.typeshed._SPATH`
8787
path to copy into
88-
direction: str
88+
direction: :const:`ssh_utilities.typeshed._DIRECTION`
8989
'get' for download and 'put' for upload
9090
follow_symlinks: bool
9191
resolve symlinks when looking for file, by default True
92-
callback: Callable[[float, float], Any]
92+
callback: :const:`ssh_utilities.typeshed._CALLBACK`
9393
callback function that recives two arguments: amount done and total
9494
amount to be copied
9595
quiet: bool
@@ -125,16 +125,16 @@ def download_tree(self, remote_path: "_SPATH", local_path: "_SPATH",
125125
126126
Parameters
127127
----------
128-
remote_path: "_SPATH"
128+
remote_path: :const:`ssh_utilities.typeshed._SPATH`
129129
path to directory which should be downloaded
130-
local_path: "_SPATH"
130+
local_path: :const:`ssh_utilities.typeshed._SPATH`
131131
directory to copy to, must be full path!
132132
remove_after: bool
133133
remove remote copy after directory is uploaded
134-
include: _GLOBPAT
134+
include: :const:`ssh_utilities.typeshed._GLOBPAT`
135135
glob pattern of files to include in copy, can be used
136136
simultaneously with exclude, default is None = no filtering
137-
exclude: _GLOBPAT
137+
exclude: :const:`ssh_utilities.typeshed._GLOBPAT`
138138
glob pattern of files to exclude in copy, can be used
139139
simultaneously with include, default is None = no filtering
140140
quiet: Literal[True, False, "stats", "progress"]
@@ -164,16 +164,16 @@ def upload_tree(self, local_path: "_SPATH", remote_path: "_SPATH",
164164
165165
Parameters
166166
----------
167-
local_path: "_SPATH"
167+
local_path: :const:`ssh_utilities.typeshed._SPATH`
168168
path to directory which should be uploaded
169-
remote_path: "_SPATH"
169+
remote_path: :const:`ssh_utilities.typeshed._SPATH`
170170
directory to copy to, must be full path!
171171
remove_after: bool
172172
remove local copy after directory is uploaded
173-
include: _GLOBPAT
173+
include: :const:`ssh_utilities.typeshed._GLOBPAT`
174174
glob pattern of files to include in copy, can be used
175175
simultaneously with exclude, default is None = no filtering
176-
exclude: _GLOBPAT
176+
exclude: :const:`ssh_utilities.typeshed._GLOBPAT`
177177
glob pattern of files to exclude in copy, can be used
178178
simultaneously with include, default is None = no filtering
179179
quiet: Literal[True, False, "stats", "progress"]
@@ -200,7 +200,7 @@ def rmtree(self, path: "_SPATH", ignore_errors: bool = False,
200200
201201
Parameters
202202
----------
203-
path: "_SPATH"
203+
path: :const:`ssh_utilities.typeshed._SPATH`
204204
directory to be recursively removed
205205
ignore_errors: bool
206206
if True only log warnings do not raise exception

‎ssh_utilities/abc/_subprocess.py‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -33,14 +33,14 @@ def run(self, args: "_CMD", *, suppress_out: bool, # NOSONAR
3333
cwd: "_SPATH" = None, timeout: Optional[float] = None,
3434
check: bool = False, encoding: Optional[str] = None,
3535
errors: Optional[str] = None, text: Optional[bool] = None,
36-
env: Optional["_ENV"] = None,
36+
env: "_ENV" = None,
3737
universal_newlines: bool = False
3838
) -> _Subprocess1:
3939
"""Excecute command on remote, has simillar API to subprocess run.
4040
4141
Parameters
4242
----------
43-
args : _CMD
43+
args : :const:`ssh_utilities.typeshed._CMD`
4444
string, Path-like object or a list of strings. If it is a list it
4545
will be joined to string with whitespace delimiter.
4646
suppress_out : bool
@@ -53,7 +53,7 @@ def run(self, args: "_CMD", *, suppress_out: bool, # NOSONAR
5353
number greater than 1 (>1) uses that specific buffer size. This
5454
applies ti underlying paramiko client as well as `stdin`, `stdout`
5555
and `stderr` PIPES, by default -1
56-
executable : _SPATH, optional
56+
executable : :const:`ssh_utilities.typeshed._SPATH`, optional
5757
[description], by default None
5858
input : Optional[str], optional
5959
[description], by default None
@@ -91,7 +91,7 @@ def run(self, args: "_CMD", *, suppress_out: bool, # NOSONAR
9191
behaviour of `subprocess` module is not selected by
9292
`locale.getpreferredencoding(False)` but is always set to `utf-8`.
9393
By default None
94-
env : Optional[_ENV], optional
94+
env : :const:`ssh_utilities.typeshed._ENV`, optional
9595
optinal environment variables that will be merged into the existing
9696
environment. This is different to `subprocess` behaviour which
9797
creates new environment with only specified variables,
@@ -130,8 +130,6 @@ def run(self, args: "_CMD", *, suppress_out: bool, # NOSONAR
130130
if `stdin`, `stdout` or `stderr` arguments are of wrong type
131131
TypeError
132132
if `args` argument is of wrong type
133-
exception
134-
[description]
135133
CalledProcessError
136134
if check is true and command exited with non-zero status
137135
TimeoutExpired

‎ssh_utilities/local/_subprocess.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ def run(args: "_CMD", *, suppress_out: bool, # NOSONAR
4040
cwd: "_SPATH" = None, timeout: Optional[float] = None,
4141
check: bool = False, encoding: Optional[str] = None,
4242
errors: Optional[str] = None, text: Optional[bool] = None,
43-
env: Optional["_ENV"] = None, universal_newlines: bool = False
43+
env: "_ENV" = None, universal_newlines: bool = False
4444
) -> subprocess.CompletedProcess:
4545

4646
if capture_output:

‎ssh_utilities/remote/_subprocess.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ def run(self, args: "_CMD", *, suppress_out: bool, # NOSONAR
4646
cwd: "_SPATH" = None, timeout: Optional[float] = None,
4747
check: bool = False, encoding: Optional[str] = None,
4848
errors: Optional[str] = None, text: Optional[bool] = None,
49-
env: Optional["_ENV"] = None, universal_newlines: bool = False
49+
env: "_ENV" = None, universal_newlines: bool = False
5050
) -> CompletedProcess:
5151

5252
command: str

‎ssh_utilities/typeshed.py‎

Lines changed: 27 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -13,20 +13,32 @@
1313

1414
AnyPath = Union[str, bytes, PathLike[str], PathLike[bytes]]
1515

16-
_FILE = Union[None, int, IO[Any]]
17-
_TXT = Union[bytes, str]
18-
# Python 3.6 does't support _CMD being a single PathLike.
19-
# See: https://bugs.python.org/issue31961
20-
_CMD = Union[_TXT, Sequence[AnyPath]]
21-
_ENV = Union[Mapping[bytes, _TXT], Mapping[str, _TXT]]
22-
23-
_GLOBPAT = Optional[str]
24-
_SPATH = Union[str, Path, SSHPath]
25-
_DIRECTION = Literal["get", "put"]
26-
_CALLBACK = Optional[Callable[[float, float], Any]]
27-
_WALK = Iterator[Tuple[str, List[str], List[str]]]
28-
_EXCTYPE = Union[Type[Exception], Tuple[Type[Exception], ...]]
29-
16+
#: opened file object or int file descriptor
17+
_FILE = Union[None, int, IO[Any]]
18+
#: string or bytes variable
19+
_TXT = Union[bytes, str]
20+
# Python 3.6 does't support _CMD being a single PathLike.
21+
# See: https://bugs.python.org/issue31961
22+
#: command to exectute for subprocess run, can be str, bytes or sefuence of
23+
#: these
24+
_CMD = Union[_TXT, Sequence["AnyPath"]]
25+
#: mapping of environment varibles names
26+
_ENV = Optional[Union[Mapping[bytes, _TXT], Mapping[str, _TXT]]]
27+
#: srting glob pattern
28+
_GLOBPAT = Optional[str]
29+
#: accepted path types by ssh_utilities - str, Path or SSHPath
30+
_SPATH = Union[str, "Path", "SSHPath"]
31+
#: aliac for file send direction - put or get
32+
_DIRECTION = Literal["get", "put"]
33+
#: copy callback function - callable that accepts two floats first reperesents
34+
#: done part and second total amount
35+
_CALLBACK = Optional[Callable[[float, float], Any]]
36+
#: walk iterator yield typle exactly same as os.walk
37+
_WALK = Iterator[Tuple[str, List[str], List[str]]]
38+
#: alias for exception of tuple of exceptions
39+
_EXCTYPE = Union[Type[Exception], Tuple[Type[Exception], ...]]
40+
#: callble that accept one argument which is of exception type
41+
_ONERROR = Optional[Callable[[Exception], Any]]
3042

3143
__all__ = ["_FILE", "_CMD", "_ENV", "_GLOBPAT", "_SPATH", "_DIRECTION",
32-
"_CALLBACK", "_WALK", "_EXCTYPE"]
44+
"_CALLBACK", "_WALK", "_EXCTYPE", "_ONERROR"]

0 commit comments

Comments
 (0)