From 21b443c29265247e855dc10fcd42b75a5c9f87fc Mon Sep 17 00:00:00 2001 From: Ganesh B Nalawade Date: Mon, 27 Jul 2020 19:32:37 +0530 Subject: [PATCH 1/9] Add initial user guide --- docs/guide/user_guide/index.rst | 13 +++ .../user_guide/intro_getting_started.rst | 99 +++++++++++++++++++ 2 files changed, 112 insertions(+) create mode 100644 docs/guide/user_guide/index.rst create mode 100644 docs/guide/user_guide/intro_getting_started.rst diff --git a/docs/guide/user_guide/index.rst b/docs/guide/user_guide/index.rst new file mode 100644 index 000000000..5899527f0 --- /dev/null +++ b/docs/guide/user_guide/index.rst @@ -0,0 +1,13 @@ +########## +User Guide +########## + +Welcome to the ansible-pylibssh User Guide! + +This guide covers how to work with ansible-pylibssh. + +.. toctree:: + :maxdepth: 2 + + ../installation_guide/index + intro_getting_started diff --git a/docs/guide/user_guide/intro_getting_started.rst b/docs/guide/user_guide/intro_getting_started.rst new file mode 100644 index 000000000..648335ec9 --- /dev/null +++ b/docs/guide/user_guide/intro_getting_started.rst @@ -0,0 +1,99 @@ +.. _intro_getting_started: + +*************** +Getting Started +*************** + +Now that you have read the :ref:`installation guide` and installed ansible-pylibssh on a your system. + +.. contents:: + :local: + +Checking libssh version +======================= + +.. code-block:: python + + from pylibsshext._libssh_version import LIBSSH_VERSION + + print(LIBSSH_VERSION) + +Creating a SSH session +====================== + +.. code-block:: python + + from pylibsshext.session import Session + from pylibsshext.errors import LibsshSessionException + + ssh = Session() + + +Connecting with remote SSH server +================================= + +.. code-block:: python + + HOST = "CHANGEME" + USER = "CHANGEME" + PASSWORD = "CHANGEME" + TIMEOUT = 30 + PORT = 22 + try: + ssh.connect( + host=HOST, + user=USER, + password=PASSWORD, + timeout=TIMEOUT, + port=PORT, + ) + except LibsshSessionException as ex: + print(str(ex)) + + print(ssh.is_connected) + +Passing a command and reading response +====================================== + +.. code-block:: python + + chan = ssh.new_channel() + print("stdout:\n%s\n stderr:\n%s\n returncode:\n%s\n" % (resp.stdout, resp.stderr, resp.returncode)) + chan.close() + +Opening a remote shell passing command and receiving response +============================================================= +.. code-block:: python + + chan_shell = ssh.invoke_shell() + chan_shell.sendall("ls") + data = chan_shell.read_bulk_response(timeout=2, retry=10) + chan_shell.close() + print(data) + +Fetch file from remote host +=========================== +.. code-block:: python + + remote_file = '/etc/hosts' + local_file = '/tmp/hosts' + sftp = SFTP(ssh) + sftp.get(remote_file, local_file) + sftp.close() + +Copy file from remote host +=========================== +.. code-block:: python + + remote_file = '/etc/hosts' + local_file = '/tmp/hosts' + sftp = SFTP(ssh) + sftp.put(remote_file, local_file) + sftp.close() + +Closing SSH session +=================== + +.. code-block:: python + + ssh.close() From a4258f2ad9fdc2ba99aff6b1e816109ed65a4ea2 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Wed, 29 Jul 2020 00:40:23 +0200 Subject: [PATCH 2/9] Fix RST and Sphinx syntax --- docs/guide/user_guide/index.rst | 2 +- docs/index.rst | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/guide/user_guide/index.rst b/docs/guide/user_guide/index.rst index 5899527f0..adf9a8ebf 100644 --- a/docs/guide/user_guide/index.rst +++ b/docs/guide/user_guide/index.rst @@ -9,5 +9,5 @@ This guide covers how to work with ansible-pylibssh. .. toctree:: :maxdepth: 2 - ../installation_guide/index + ../installation_guide/index intro_getting_started diff --git a/docs/index.rst b/docs/index.rst index 5a61085f1..1dbd97bae 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,6 +16,8 @@ Welcome to |project|'s documentation! :maxdepth: 2 :caption: Contents: + guide/user_guide/index.rst + .. toctree:: :caption: What's new From 45fcf2c538d2b81604f08c299dfcb7fb5da35e1a Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Mon, 3 Aug 2020 17:46:24 +0200 Subject: [PATCH 3/9] Use `|project|` substitution in guides --- docs/guide/user_guide/index.rst | 4 ++-- docs/guide/user_guide/intro_getting_started.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guide/user_guide/index.rst b/docs/guide/user_guide/index.rst index adf9a8ebf..1b31979ad 100644 --- a/docs/guide/user_guide/index.rst +++ b/docs/guide/user_guide/index.rst @@ -2,9 +2,9 @@ User Guide ########## -Welcome to the ansible-pylibssh User Guide! +Welcome to the |project| User Guide! -This guide covers how to work with ansible-pylibssh. +This guide covers how to work with |project|. .. toctree:: :maxdepth: 2 diff --git a/docs/guide/user_guide/intro_getting_started.rst b/docs/guide/user_guide/intro_getting_started.rst index 648335ec9..4841dda6e 100644 --- a/docs/guide/user_guide/intro_getting_started.rst +++ b/docs/guide/user_guide/intro_getting_started.rst @@ -4,7 +4,7 @@ Getting Started *************** -Now that you have read the :ref:`installation guide` and installed ansible-pylibssh on a your system. +Now that you have read the :ref:`installation guide` and installed |project| on a your system. .. contents:: :local: From bf9f16dc535f6764f67be2036ad218ab36d08b50 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Mon, 3 Aug 2020 17:58:06 +0200 Subject: [PATCH 4/9] Extract user guide to the top level --- docs/guide/user_guide/index.rst | 13 ------------- docs/index.rst | 2 +- .../intro_getting_started.rst => user_guide.rst} | 8 ++++++++ 3 files changed, 9 insertions(+), 14 deletions(-) delete mode 100644 docs/guide/user_guide/index.rst rename docs/{guide/user_guide/intro_getting_started.rst => user_guide.rst} (94%) diff --git a/docs/guide/user_guide/index.rst b/docs/guide/user_guide/index.rst deleted file mode 100644 index 1b31979ad..000000000 --- a/docs/guide/user_guide/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -########## -User Guide -########## - -Welcome to the |project| User Guide! - -This guide covers how to work with |project|. - -.. toctree:: - :maxdepth: 2 - - ../installation_guide/index - intro_getting_started diff --git a/docs/index.rst b/docs/index.rst index 1dbd97bae..38c5fd337 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,7 +16,7 @@ Welcome to |project|'s documentation! :maxdepth: 2 :caption: Contents: - guide/user_guide/index.rst + user_guide .. toctree:: :caption: What's new diff --git a/docs/guide/user_guide/intro_getting_started.rst b/docs/user_guide.rst similarity index 94% rename from docs/guide/user_guide/intro_getting_started.rst rename to docs/user_guide.rst index 4841dda6e..41251a00a 100644 --- a/docs/guide/user_guide/intro_getting_started.rst +++ b/docs/user_guide.rst @@ -1,5 +1,13 @@ .. _intro_getting_started: +########## +User Guide +########## + +Welcome to the |project| User Guide! + +This guide covers how to work with |project|. + *************** Getting Started *************** From 4690e9deeb201bb021ed1a5cccb82ce572119391 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Sat, 8 Aug 2020 02:04:51 +0200 Subject: [PATCH 5/9] Drop unnecessary "User Guide" title --- docs/user_guide.rst | 18 ++++-------------- 1 file changed, 4 insertions(+), 14 deletions(-) diff --git a/docs/user_guide.rst b/docs/user_guide.rst index 41251a00a..4318df189 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -1,18 +1,8 @@ -.. _intro_getting_started: +****************************** +Getting Started with |project| +****************************** -########## -User Guide -########## - -Welcome to the |project| User Guide! - -This guide covers how to work with |project|. - -*************** -Getting Started -*************** - -Now that you have read the :ref:`installation guide` and installed |project| on a your system. +Now that you have read the :ref:`installation guide ` and installed |project| on a your system. .. contents:: :local: From d80def6794fc76b097fdf01365f6eec86b51b826 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Sat, 8 Aug 2020 03:00:02 +0200 Subject: [PATCH 6/9] =?UTF-8?q?=F0=9F=9A=9A=20Migrate=20user=20guide=20sni?= =?UTF-8?q?ppets=20to=20files?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .pre-commit-config.yaml | 8 +++ docs/_samples/copy_files.py | 50 +++++++++++++++++ docs/_samples/get_version.py | 14 +++++ docs/user_guide.rst | 104 +++++++++++++++++------------------ 4 files changed, 121 insertions(+), 55 deletions(-) create mode 100644 docs/_samples/copy_files.py create mode 100644 docs/_samples/get_version.py diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 7a5e64a5a..9b692774b 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -50,7 +50,11 @@ repos: # Heavy checks: - id: check-ast + exclude: >- + ^docs/_samples/.*\.py$ - id: debug-statements + exclude: >- + ^docs/_samples/.*\.py$ - repo: https://gitlab.com/pycqa/flake8.git rev: 3.8.2 @@ -65,6 +69,8 @@ repos: - wemake-python-styleguide files: >- ^.*\.p(xd|y|yx)$ + exclude: >- + ^docs/_samples/.*\.py$ types: [file] - repo: git://github.com/Lucas-C/pre-commit-hooks-markup @@ -78,6 +84,8 @@ repos: rev: 5.0.2 hooks: - id: pydocstyle + exclude: >- + ^docs/_samples/.*\.py$ # - repo: local # hooks: diff --git a/docs/_samples/copy_files.py b/docs/_samples/copy_files.py new file mode 100644 index 000000000..86bf024c3 --- /dev/null +++ b/docs/_samples/copy_files.py @@ -0,0 +1,50 @@ +from pylibsshext.errors import LibsshSessionException +from pylibsshext.session import Session + + +ssh = Session() + +HOST = 'CHANGEME' +USER = 'CHANGEME' +PASSWORD = 'CHANGEME' +TIMEOUT = 30 +PORT = 22 +try: + ssh.connect( + host=HOST, + user=USER, + password=PASSWORD, + timeout=TIMEOUT, + port=PORT, + ) +except LibsshSessionException as ssh_exc: + print(f'Failed to connect to {HOST}:{PORT} over SSH: {ssh_exc!s}') + +print(f'{ssh.is_connected=}') + +ssh_channel = ssh.new_channel() +cmd_resp = ssh_channel.write(b'ls') +print(f'stdout:\n{cmd_resp.stdout}\n') +print(f'stderr:\n{cmd_resp.stderr}\n') +print(f'return code: {cmd_resp.returncode}\n') +ssh_channel.close() + +chan_shell = ssh.invoke_shell() +chan_shell.sendall(b'ls') +data = chan_shell.read_bulk_response(timeout=2, retry=10) +chan_shell.close() +print(data) + +remote_file = '/etc/hosts' +local_file = '/tmp/hosts' +sftp = SFTP(ssh) +sftp.get(remote_file, local_file) +sftp.close() + +remote_file = '/etc/hosts' +local_file = '/tmp/hosts' +sftp = SFTP(ssh) +sftp.put(remote_file, local_file) +sftp.close() + +ssh.close() diff --git a/docs/_samples/get_version.py b/docs/_samples/get_version.py new file mode 100644 index 000000000..0c2f2dae1 --- /dev/null +++ b/docs/_samples/get_version.py @@ -0,0 +1,14 @@ +from pylibsshext import ( + __full_version__, # string with both ansible-pylibssh and libssh versions +) +from pylibsshext import ( + __libssh_version__, # linked libssh lib version as a string +) +from pylibsshext import __version__ # ansible-pylibssh version as a string +from pylibsshext import __version_info__ # ansible-pylibssh version as a tuple + + +print(f'{__full_version__=}') +print(f'{__libssh_version__=}') +print(f'{__version__=}') +print(f'{__version_info__=}') diff --git a/docs/user_guide.rst b/docs/user_guide.rst index 4318df189..80ec146ca 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -7,91 +7,85 @@ Now that you have read the :ref:`installation guide ` and in .. contents:: :local: -Checking libssh version -======================= -.. code-block:: python +.. tip:: - from pylibsshext._libssh_version import LIBSSH_VERSION + The examples on this page use Python 3.8. If your interpreter + is older, you may need to modify the syntax when copying the + snippets. + + +Checking software versions +========================== + +.. literalinclude:: _samples/get_version.py + :language: python - print(LIBSSH_VERSION) Creating a SSH session ====================== -.. code-block:: python +.. attention:: - from pylibsshext.session import Session - from pylibsshext.errors import LibsshSessionException + The APIs that are shown below, are low-level. You should + take a great care to ensure you process any exceptions that + arise and always close all the resources once they are no + longer necessary. - ssh = Session() +.. literalinclude:: _samples/copy_files.py + :language: python + :lines: -5 + :emphasize-lines: 5 Connecting with remote SSH server ================================= -.. code-block:: python - - HOST = "CHANGEME" - USER = "CHANGEME" - PASSWORD = "CHANGEME" - TIMEOUT = 30 - PORT = 22 - try: - ssh.connect( - host=HOST, - user=USER, - password=PASSWORD, - timeout=TIMEOUT, - port=PORT, - ) - except LibsshSessionException as ex: - print(str(ex)) - - print(ssh.is_connected) +.. literalinclude:: _samples/copy_files.py + :language: python + :lines: 7-23 + :emphasize-lines: 7-13 + Passing a command and reading response ====================================== -.. code-block:: python +.. literalinclude:: _samples/copy_files.py + :language: python + :lines: 25-30 + :emphasize-lines: 2 - chan = ssh.new_channel() - print("stdout:\n%s\n stderr:\n%s\n returncode:\n%s\n" % (resp.stdout, resp.stderr, resp.returncode)) - chan.close() Opening a remote shell passing command and receiving response ============================================================= -.. code-block:: python - chan_shell = ssh.invoke_shell() - chan_shell.sendall("ls") - data = chan_shell.read_bulk_response(timeout=2, retry=10) - chan_shell.close() - print(data) +.. literalinclude:: _samples/copy_files.py + :language: python + :lines: 32-36 + :emphasize-lines: 2-3 + Fetch file from remote host =========================== -.. code-block:: python - remote_file = '/etc/hosts' - local_file = '/tmp/hosts' - sftp = SFTP(ssh) - sftp.get(remote_file, local_file) - sftp.close() +.. literalinclude:: _samples/copy_files.py + :language: python + :lines: 38-42 + :emphasize-lines: 3-4 -Copy file from remote host -=========================== -.. code-block:: python - remote_file = '/etc/hosts' - local_file = '/tmp/hosts' - sftp = SFTP(ssh) - sftp.put(remote_file, local_file) - sftp.close() +Copy file to remote host +======================== + +.. literalinclude:: _samples/copy_files.py + :language: python + :lines: 44-48 + :emphasize-lines: 3-4 + Closing SSH session =================== -.. code-block:: python - - ssh.close() +.. literalinclude:: _samples/copy_files.py + :language: python + :lines: 50 From 345063c0018a71367c5d71eab9d031f037bd8652 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Wed, 12 Aug 2020 01:23:50 +0200 Subject: [PATCH 7/9] Drop manually maintained RST ref labels --- docs/user_guide.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/user_guide.rst b/docs/user_guide.rst index 80ec146ca..64b9acc1d 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -2,7 +2,8 @@ Getting Started with |project| ****************************** -Now that you have read the :ref:`installation guide ` and installed |project| on a your system. +Now that you have read the :ref:`installation guide ` and +installed |project| on a your system. .. contents:: :local: From 596c8fcb82b69e653c7413b71e6942d084d63781 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Sat, 29 Aug 2020 00:20:27 +0200 Subject: [PATCH 8/9] Drop not yet existing ref to the install guide --- docs/user_guide.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/user_guide.rst b/docs/user_guide.rst index 64b9acc1d..0e21515ea 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -2,9 +2,6 @@ Getting Started with |project| ****************************** -Now that you have read the :ref:`installation guide ` and -installed |project| on a your system. - .. contents:: :local: From 0b24a05eb4c6966e16463c3eb858203c57410de0 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Sat, 29 Aug 2020 00:30:50 +0200 Subject: [PATCH 9/9] Add a change note for PR #141 --- docs/changelog-fragments/141.doc.rst | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 docs/changelog-fragments/141.doc.rst diff --git a/docs/changelog-fragments/141.doc.rst b/docs/changelog-fragments/141.doc.rst new file mode 100644 index 000000000..f1cce3d78 --- /dev/null +++ b/docs/changelog-fragments/141.doc.rst @@ -0,0 +1,2 @@ +Added the initial user guide to docs +-- by :user:`ganeshrn` and :user:`webknjaz`