<a name="top"></a>
<a name="overview"></a>
# Overview
This module was inspired by the [SFTP for Sublime Text](https://codexns.io/products/sftp_for_sublime) plugin.
As such, it facilitates interacting with remote hosts via ssh,<br />
with the added bonus of providing a means to mirror your local<br />
working directory to the specified path on the remote host in order<br />
to facilitate local-edit/remote-build.
With this module you can:
- Edit and manipulate your scripts locally and execute them remotely, <br />
with file synchronization capabilities
- Map a local folder to a remote folder
# Prerequisites:
- Python 3.7+
- paramiko
- If working with git repos, the module requires that git be installed locally and remotely
# Installation
* From pypi: `pip3 install bertdotssh`
* From this git repo: `pip3 install git+https://github.com/berttejeda/bert.sshutil.git`<br />
Note: To install a specific version of the library from this git repo, <br />
suffix the git URL in the above command with @{ tag name }, e.g.: <br />
git+https://github.com/berttejeda/bert.sshutil.git@1.0.0
# Usage Examples
## Get process status for a remote host via ssh
```python
from bertdotssh.provider import RemoteCLIProvider
settings = {
'host': 'myhost.example.local',
'remote_path': '/home/myusername',
'port': 22,
'ssh_key_file': '~/.ssh/id_rsa',
'user': 'myusername'
}
remote = RemoteCLIProvider(settings)
remote.run('ps')
```
## Syncronize local files to remote and run a local script against the same host
Given:
- Local working directory: /home/myusername/some/path
- Local script: myscript.sh
```python
from bertdotssh.provider import RemoteCLIProvider
settings = {
'host': 'myhost.example.local',
'remote_path': '/home/myusername',
'port': 22,
'ssh_key_file': '~/.ssh/id_rsa',
'user': 'myusername',
'sync_no_clobber': True,
'sync_on': True
}
remote = RemoteCLIProvider(settings)
remote.run('myscript.sh')
```
## Syncronize local git repo to remote and run a local script against the same host
Given:
- Local working directory (a git repo) at: /home/myusername/some/git/myrepo
- Local script at: /home/myusername/some/git/myrepo/myscript.sh
- Git repo on remote host at: /home/myusername/some/other/path/git/myrepo
```python
from bertdotssh.provider import RemoteCLIProvider
settings = {
'host': 'myhost.example.local',
'remote_path': '/home/myusername/some/other/path/git/myrepo',
'port': 22,
'ssh_key_file': '~/.ssh/id_rsa',
'user': 'myusername',
'sync_no_clobber': True,
'sync_on': True
}
remote = RemoteCLIProvider(settings)
remote.run('myscript.sh',
git_username='my_git_username',
git_password='my_git_password')
```
# File syncrhonization behavior
The above example scenarios exhibit the following programmatic behavior upon sync:
1. Determine if local working directory is a git repo
- If True
- Determine the URL for the git remote via command `git config --get remote.origin.url`
- Determine the paths for any locally changed files via command `git diff-index HEAD --name-status`
- Determine the paths for any untracked files via command `git ls-files --others --exclude-standard`
- Produce a list of files to sync by combining the output of the above two commands
- If False
- Produce a list of files to sync that have changed within the last 5 minutes
2. Determine if remote path exists
- If False
- If local is a git repo
- Perform a git clone of the git repo against the remote path
- Else, create the remote directory and synchronize the file list across the remote
- If True, determines if remote path is a git repo
- Determine set of files that have changed in the remote path
- If True & sync_no_clobber == True, synchronize locally changed <br />
files to remote path, skipping any files that have also changed on the remote
- If True & sync_no_clobber == False, synchronize locally changed <br />
files to remote path, overwriting any files that have also changed on the remote
Raw data
{
"_id": null,
"home_page": "https://github.com/berttejeda/bert.sshutil.git",
"name": "btssh",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "ssh,command,python,invoke,remote,invocation",
"author": "Engelbert Tejeda",
"author_email": "berttejeda@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/3d/10/d2b97ce371daaa6ecff34480c667aa532f0a6df8e866b072e78bc3c1715b/btssh-1.2.0.tar.gz",
"platform": null,
"description": "<a name=\"top\"></a>\n<a name=\"overview\"></a>\n\n# Overview\n\nThis module was inspired by the [SFTP for Sublime Text](https://codexns.io/products/sftp_for_sublime) plugin.\n\nAs such, it facilitates interacting with remote hosts via ssh,<br />\nwith the added bonus of providing a means to mirror your local<br />\nworking directory to the specified path on the remote host in order<br />\nto facilitate local-edit/remote-build.\n\nWith this module you can:\n\n- Edit and manipulate your scripts locally and execute them remotely, <br />\n with file synchronization capabilities\n- Map a local folder to a remote folder\n\n# Prerequisites:\n\n- Python 3.7+\n- paramiko\n- If working with git repos, the module requires that git be installed locally and remotely\n\n# Installation\n\n* From pypi: `pip3 install bertdotssh`\n* From this git repo: `pip3 install git+https://github.com/berttejeda/bert.sshutil.git`<br />\n Note: To install a specific version of the library from this git repo, <br />\n suffix the git URL in the above command with @{ tag name }, e.g.: <br />\n git+https://github.com/berttejeda/bert.sshutil.git@1.0.0\n\n# Usage Examples\n\n## Get process status for a remote host via ssh\n\n```python\n\nfrom bertdotssh.provider import RemoteCLIProvider\n\nsettings = {\n 'host': 'myhost.example.local', \n 'remote_path': '/home/myusername',\n 'port': 22, \n 'ssh_key_file': '~/.ssh/id_rsa', \n 'user': 'myusername'\n}\n\nremote = RemoteCLIProvider(settings)\n\nremote.run('ps')\n```\n\n## Syncronize local files to remote and run a local script against the same host\n\nGiven:\n- Local working directory: /home/myusername/some/path\n- Local script: myscript.sh\n\n```python\n\nfrom bertdotssh.provider import RemoteCLIProvider\n\nsettings = {\n 'host': 'myhost.example.local', \n 'remote_path': '/home/myusername',\n 'port': 22, \n 'ssh_key_file': '~/.ssh/id_rsa', \n 'user': 'myusername',\n 'sync_no_clobber': True,\n 'sync_on': True \n}\n\nremote = RemoteCLIProvider(settings)\n\nremote.run('myscript.sh')\n```\n\n## Syncronize local git repo to remote and run a local script against the same host\n\nGiven:\n- Local working directory (a git repo) at: /home/myusername/some/git/myrepo\n- Local script at: /home/myusername/some/git/myrepo/myscript.sh\n- Git repo on remote host at: /home/myusername/some/other/path/git/myrepo\n\n```python\n\nfrom bertdotssh.provider import RemoteCLIProvider\n\nsettings = {\n 'host': 'myhost.example.local', \n 'remote_path': '/home/myusername/some/other/path/git/myrepo',\n 'port': 22, \n 'ssh_key_file': '~/.ssh/id_rsa', \n 'user': 'myusername',\n 'sync_no_clobber': True,\n 'sync_on': True \n}\n\nremote = RemoteCLIProvider(settings)\n\nremote.run('myscript.sh',\n git_username='my_git_username', \n git_password='my_git_password')\n```\n\n# File syncrhonization behavior\n\nThe above example scenarios exhibit the following programmatic behavior upon sync:\n\n1. Determine if local working directory is a git repo\n - If True\n - Determine the URL for the git remote via command `git config --get remote.origin.url`\n - Determine the paths for any locally changed files via command `git diff-index HEAD --name-status`\n - Determine the paths for any untracked files via command `git ls-files --others --exclude-standard`\n - Produce a list of files to sync by combining the output of the above two commands\n - If False\n - Produce a list of files to sync that have changed within the last 5 minutes\n2. Determine if remote path exists\n - If False\n - If local is a git repo\n - Perform a git clone of the git repo against the remote path\n - Else, create the remote directory and synchronize the file list across the remote\n - If True, determines if remote path is a git repo\n - Determine set of files that have changed in the remote path\n - If True & sync_no_clobber == True, synchronize locally changed <br />\n files to remote path, skipping any files that have also changed on the remote\n - If True & sync_no_clobber == False, synchronize locally changed <br />\n files to remote path, overwriting any files that have also changed on the remote\n",
"bugtrack_url": null,
"license": "",
"summary": "Utility library for command invocation via ssh",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://github.com/berttejeda/bert.sshutil.git"
},
"split_keywords": [
"ssh",
"command",
"python",
"invoke",
"remote",
"invocation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5d4d09f46ff62a848ead185e2056f1761d01149e5388cfb1441d56c351418ab2",
"md5": "4b94813b6639528829677029091984d6",
"sha256": "5631584939e0f808276b277fae54b42d6cfa0d1855a422f191d07bdea6dad14f"
},
"downloads": -1,
"filename": "btssh-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4b94813b6639528829677029091984d6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 15414,
"upload_time": "2023-05-12T14:40:18",
"upload_time_iso_8601": "2023-05-12T14:40:18.141569Z",
"url": "https://files.pythonhosted.org/packages/5d/4d/09f46ff62a848ead185e2056f1761d01149e5388cfb1441d56c351418ab2/btssh-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3d10d2b97ce371daaa6ecff34480c667aa532f0a6df8e866b072e78bc3c1715b",
"md5": "1199c44eb1147f4e55b0439cff89cbee",
"sha256": "5fc27ec6739cc08f38247053cf838defe1474bd20165c617274f5b2f63512a00"
},
"downloads": -1,
"filename": "btssh-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "1199c44eb1147f4e55b0439cff89cbee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 16576,
"upload_time": "2023-05-12T14:40:19",
"upload_time_iso_8601": "2023-05-12T14:40:19.216695Z",
"url": "https://files.pythonhosted.org/packages/3d/10/d2b97ce371daaa6ecff34480c667aa532f0a6df8e866b072e78bc3c1715b/btssh-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-12 14:40:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "berttejeda",
"github_project": "bert.sshutil",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"tox": true,
"lcname": "btssh"
}
JSON
