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/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` diff --git a/docs/index.rst b/docs/index.rst index 5a61085f1..38c5fd337 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,6 +16,8 @@ Welcome to |project|'s documentation! :maxdepth: 2 :caption: Contents: + user_guide + .. toctree:: :caption: What's new diff --git a/docs/user_guide.rst b/docs/user_guide.rst new file mode 100644 index 000000000..0e21515ea --- /dev/null +++ b/docs/user_guide.rst @@ -0,0 +1,89 @@ +****************************** +Getting Started with |project| +****************************** + +.. contents:: + :local: + + +.. tip:: + + 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 + + +Creating a SSH session +====================== + +.. attention:: + + 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. + +.. literalinclude:: _samples/copy_files.py + :language: python + :lines: -5 + :emphasize-lines: 5 + + +Connecting with remote SSH server +================================= + +.. literalinclude:: _samples/copy_files.py + :language: python + :lines: 7-23 + :emphasize-lines: 7-13 + + +Passing a command and reading response +====================================== + +.. literalinclude:: _samples/copy_files.py + :language: python + :lines: 25-30 + :emphasize-lines: 2 + + +Opening a remote shell passing command and receiving response +============================================================= + +.. literalinclude:: _samples/copy_files.py + :language: python + :lines: 32-36 + :emphasize-lines: 2-3 + + +Fetch file from remote host +=========================== + +.. literalinclude:: _samples/copy_files.py + :language: python + :lines: 38-42 + :emphasize-lines: 3-4 + + +Copy file to remote host +======================== + +.. literalinclude:: _samples/copy_files.py + :language: python + :lines: 44-48 + :emphasize-lines: 3-4 + + +Closing SSH session +=================== + +.. literalinclude:: _samples/copy_files.py + :language: python + :lines: 50