Skip to content

Commit 6ad4b39

Browse files
marian-codemarian-code
committed
overhauled README
1 parent 735ebcc commit 6ad4b39

File tree

1 file changed

+129
-64
lines changed

1 file changed

+129
-64
lines changed

‎README.rst‎

Lines changed: 129 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
Paramiko wrapper
2-
================
1+
ssh-utilities
2+
=============
33

44
:Test Status:
55

@@ -39,49 +39,118 @@ Paramiko wrapper
3939
.. image:: https://img.shields.io/pypi/l/ssh-utilities
4040
:alt: PyPI - License
4141

42+
.. |yes| unicode:: U+2705
43+
.. |no| unicode:: U+274C
44+
.. _builtins: https://docs.python.org/3/library/builtins.html
45+
.. _os: https://docs.python.org/3/library/os.html
46+
.. _os.path: https://docs.python.org/3/library/os.path.html
47+
.. _subprocess: https://docs.python.org/3/library/subprocess.html
48+
.. _shutil: https://docs.python.org/3/library/shutil.html
49+
.. _pathlib: https://docs.python.org/3/library/pathlib.html
4250

43-
Simple paramiko wrapper that aims to facilitate easy remote file operations
44-
and command execution. The API vaguely follows python libraries:
45-
`os <https://docs.python.org/3/library/os.html>`_,
46-
`os.path <https://docs.python.org/3/library/os.path.html>`_,
47-
`subprocess <https://docs.python.org/3/library/subprocess.html>`_,
48-
`shutil <https://docs.python.org/3/library/shutil.html>`_,
49-
`pathlib <https://docs.python.org/3/library/pathlib.html>`_. Has also
50-
local variant that mimics the remote API on local machine. The connection is
51-
resilient to interruptions and thread safe. Everything is well documented by
52-
dostrings and typed.
53-
54-
This module should be ideally platform agnostic, but only connections from
55-
Windows and Linux(Debian, Ubuntu) to Linux(Debian, Ubuntu) have been tested
56-
so any other combinations are officially unsupported but should work.
51+
.. contents:: Table of contents
52+
:local:
53+
:depth: 2
5754

58-
Installation
55+
Introduction
5956
------------
6057

61-
.. code-block:: bash
62-
63-
pip install ssh_utilities
64-
65-
Or if you want to install directly from source:
66-
67-
.. code-block:: bash
58+
Simple paramiko wrapper that aims to facilitate easy remote file operations
59+
and command execution. The API vaguely follows python libraries: `builtins`_,
60+
`os`_, `os.path`_, `subprocess`_, `shutil`_, `pathlib`_,
6861

69-
git clone https://github.com/marian-code/ssh-utilities.git
70-
cd ssh_utilities
71-
pip install -e .
7262

73-
Use ``-e`` only to install in editable mode
63+
This is not intended to be a full fledged python ssh client. Instead it focuses
64+
on smaller set of features which it trie to make as user-friendly as possible.
7465

75-
If you encounter some import errors try installing from requirements.txt file:
76-
``pip install requirements.txt``
66+
This module should be ideally platform agnostic, but only connections from
67+
Windows and Linux(Debian, Ubuntu) to Linux(Debian, Ubuntu) have been tested
68+
so any other combinations are officially unsupported but should work.
7769

78-
Warning
79-
-------
70+
Design goals and features
71+
-------------------------
72+
73+
- support python > 3.6
74+
- everything is typed for easy code understanding and superior type hints and
75+
autocompletion
76+
- everything is properly documented
77+
- API is as consistent as possible with python modules and functions we are
78+
trying to reimplement
79+
- connection can be made thread safe
80+
- try to be as platform agnostic as possible
81+
- accept both stings and Path objects in all methods that require some path as
82+
an input
83+
- strong emphasis on usage of ssh key based authentication
84+
85+
List of inner classes and implemented methods
86+
---------------------------------------------
87+
88+
ssh_utilities have three main connection classes:
89+
- ``SSHConnection``
90+
- ``LocalConnection``
91+
- ``MultiConnection``
92+
93+
Their inner classes with their methods are listed in the table below which
94+
summarizes the API. based on table you can do for instance:
95+
96+
.. code-block:: python
97+
98+
>>> # this is OK
99+
>>> SSHConnection.os.isfile(<somepath>)
100+
>>> # this is not OK as it is marked in table as not implemented
101+
>>> MultiConnection.os.path.realpath(<somepath>)
102+
>>> # this is also not permitted as methods not mentioned in table are not
103+
>>> # implemented in any class
104+
>>> SSHConnection.os.getpid()
105+
106+
+---------------+---------------+-----------------+------------------+-----------------+
107+
| module | method | SSHConnection | LocalConnection | MultiConnection |
108+
+===============+===============+=================+==================+=================+
109+
| `builtins`_ | open | |yes| | |yes| | |yes| |
110+
+---------------+---------------+-----------------+------------------+-----------------+
111+
| `os`_ | isfile | |yes| | |yes| | |yes| |
112+
| +---------------+-----------------+------------------+-----------------+
113+
| | isdir | |yes| | |yes| | |yes| |
114+
| +---------------+-----------------+------------------+-----------------+
115+
| | makedirs | |yes| | |yes| | |yes| |
116+
| +---------------+-----------------+------------------+-----------------+
117+
| | mkdir | |yes| | |yes| | |yes| |
118+
| +---------------+-----------------+------------------+-----------------+
119+
| | listdir | |yes| | |yes| | |yes| |
120+
| +---------------+-----------------+------------------+-----------------+
121+
| | chdir | |yes| | |yes| | |yes| |
122+
| +---------------+-----------------+------------------+-----------------+
123+
| | stat | |yes| | |yes| | |yes| |
124+
| +---------------+-----------------+------------------+-----------------+
125+
| | lstat | |yes| | |yes| | |yes| |
126+
| +---------------+-----------------+------------------+-----------------+
127+
| | name | |yes| | |yes| | |yes| |
128+
| +---------------+-----------------+------------------+-----------------+
129+
| | walk | |yes| | |yes| | |yes| |
130+
| +---------------+-----------------+------------------+-----------------+
131+
| | path | |yes| | |yes| | |no| |
132+
+---------------+---------------+-----------------+------------------+-----------------+
133+
| `os.path`_ | realpath | |yes| | |yes| | |no| |
134+
+---------------+---------------+-----------------+------------------+-----------------+
135+
| `pathlib`_ | Path | |yes| | |yes| | |yes| |
136+
+---------------+---------------+-----------------+------------------+-----------------+
137+
| `shutil`_ | copy | |yes| | |yes| | |yes| |
138+
| +---------------+-----------------+------------------+-----------------+
139+
| | copy2 | |yes| | |yes| | |yes| |
140+
| +---------------+-----------------+------------------+-----------------+
141+
| | copyfile | |yes| | |yes| | |yes| |
142+
| +---------------+-----------------+------------------+-----------------+
143+
| | rmtree | |yes| | |yes| | |yes| |
144+
| +---------------+-----------------+------------------+-----------------+
145+
| | copy_files | |yes| | |yes| | |yes| |
146+
| +---------------+-----------------+------------------+-----------------+
147+
| | upload_tree | |yes| | |yes| | |yes| |
148+
| +---------------+-----------------+------------------+-----------------+
149+
| | download_tree | |yes| | |yes| | |yes| |
150+
+---------------+---------------+-----------------+------------------+-----------------+
151+
| `subprocess`_ | run | |yes| | |yes| | |yes| |
152+
+---------------+---------------+-----------------+------------------+-----------------+
80153

81-
There has been a recent mayor change in modules API betweeen versions 0.4.2
82-
and 0.5.0. Most methods of the connection classes have been moved a level
83-
deeper. See `migration from 0.4.x to 0.5.x <https://ssh-utilities.readthedocs.io/en/latest/migration.html>`_
84-
for details how to port to newer version
85154

86155
API and documentation
87156
---------------------
@@ -90,44 +159,21 @@ It is recommended that you have configured **rsa** keys with config file accordi
90159
to `openssh standard <https://www.ssh.com/ssh/config/>`_. For easy quickstart guide
91160
you can look at: https://www.cyberciti.biz/faq/create-ssh-config-file-on-linux-unix/
92161

93-
API exposes three main connection classes one path manipulation class, python
162+
API exposes four main connection classes one path manipulation class, python
94163
module replacement classes, utility functions and constants:
95164

96165
.. code-block:: python
97166
98-
from ssh_utilities import SSHConnection, Connection, LocalConnection
167+
from ssh_utilities import SSHConnection, Connection, LocalConnection, MultiConnection
99168
from ssh_utilities import SSHPath
100169
from ssh_utilities import Builtins, Os, Pathlib, Shutil, Subprocess
101170
from ssh_utilities import config_parser
102171
from ssh_utilities import PIPE, STDOUT, DEVNULL, GET, PUT
103172
104173
``Connection`` is the a factory class that initializes ``SSHConnection`` or
105-
``LocalConnection`` classes based on input parameters.
106-
107-
``SSHConnection`` is the remote connection class with API partly following that
108-
of python `os <https://docs.python.org/3/library/os.html>`_,
109-
`os.path library <https://docs.python.org/3/library/os.path.html>`_,
110-
`shutil library <https://docs.python.org/3/library/shutil.html>`_ and
111-
`subprocess library <https://docs.python.org/3/library/subprocess.html>`_
112-
`pathlib <https://docs.python.org/3/library/pathlib.html>`_
113-
114-
``LocalConnection`` is included only for convenience purposes so same API as for
115-
``SSHConnection`` can be used for interacting with local machine
116-
117-
``SSHPath`` is an object for remote path manipulation with same API as python:
118-
`pathlib library <https://docs.python.org/3/library/pathlib.html>`_
119-
120-
The ``SSHConnection`` and ``LocalConnection`` objects are both devided to few
121-
inner classes which correspond to python modules. For ``SSHConnection``
122-
these are:
123-
124-
* ``SSHConnection.builtins``
125-
* ``SSHConnection.os``
126-
* ``SSHConnection.pathlib``
127-
* ``SSHConnection.subprocess``
128-
* ``SSHConnection.shutil``
129-
130-
same applies to ``LocalConnection``
174+
``LocalConnection`` classes based on input parameters. ``MultiConnection`` is
175+
a container for convenient management of pool of connections.
176+
``SSHPath`` is an object for remote path manipulation.
131177

132178
All API documentation can be found at readthedocs:
133179
https://ssh-utilities.readthedocs.io/en/latest/
@@ -247,6 +293,25 @@ information is in the docs.
247293
>>> mc.<some_attribute>
248294
>>> ...
249295
296+
Installation
297+
------------
298+
299+
.. code-block:: bash
300+
301+
pip install ssh_utilities
302+
303+
Or if you want to install directly from source:
304+
305+
.. code-block:: bash
306+
307+
git clone https://github.com/marian-code/ssh-utilities.git
308+
cd ssh_utilities
309+
pip install -e .
310+
311+
Use ``-e`` only to install in editable mode
312+
313+
If you encounter some import errors try installing from requirements.txt file:
314+
``pip install -r requirements.txt``
250315

251316
Contributing
252317
------------

0 commit comments

Comments
 (0)