# `miarec_sshfs` SFTP filesystem for PyFilesystem2
[](https://github.com/miarec/miarec_sshfs/actions)
[](https://choosealicense.com/licenses/lgpl-2.1/)
This is a fork of [fs.sshfs](https://github.com/althonos/fs.sshfs) project, with modifications that are required for our needs.
## Requirements
| **PyFilesystem2** | [](https://pypi.python.org/pypi/fs) | [](https://github.com/PyFilesystem/pyfilesystem2) | [](https://choosealicense.com/licenses/mit/) |
|:-|:-|:-|:-|
| **six** | [](https://pypi.python.org/pypi/six) | []( https://github.com/benjaminp/six) | [](https://choosealicense.com/licenses/mit/) |
| **paramiko** | [](https://pypi.python.org/pypi/paramiko) | []( https://github.com/paramiko/paramiko) | [](https://choosealicense.com/licenses/lgpl-2.1/) |
| **property-cached** | [](https://pypi.python.org/pypi/property-cached) | [](https://github.com/althonos/property-cached) | []( https://choosealicense.com/licenses/bsd-3-clause/) |
`miarec_sshfs` supports Python versions 3.6+
## Notable differences to `fs.sshfs`
1. Loading of configuration from SSH Config files (`~/.ssh/config`) is removed due to potential security issues,
when this component used in SaaS project.
2. Automatic loading of SSH keys from SSH Agent is forbidden due to potential security issues, when this components
is used in SaaS project.
3. The opener protocol prefixes are `mssh://` and `msftp://` (instead of the original `ssh://` and `sftp://`)
4. URL is forbidden due to potential leak of SFTP credentials via url.
## Installation
Install from GitHub, using [pip](https://pip.pypa.io/):
```console
$ pip install git+https://github.com/miarec/miarec_sshfs@master
```
## Usage
To connect to an SSH server, use the `fs.sshfs.SSHFS` constructor, which signature is:
```python
from miarec_sshfs import SSHFS
my_fs = SSHFS(
host, user=None, passwd=None, pkey=None, timeout=10, port=22,
keepalive=10, compress=False, config_path='~/.ssh/config'
)
```
with each argument explained below:
- `host`: the name or IP address of the SSH server
- `user`: the username to connect with, defaults to the current user.
- `passwd`: an optional password, used to connect directly to the server or
to decrypt the public key, if any given.
- `pkey`: a [`paramiko.PKey`](http://docs.paramiko.org/en/stable/api/keys.html#paramiko.pkey.PKey)
object, a path, or a list of paths to an SSH key.
- `timeout`: the timeout, in seconds, for networking operations.
- `port`: the port the SSH server is listening on.
- `keepalive`: the interval of time between *keepalive* packets, in seconds.
Set to 0 to disable.
- `compress`: set to `True` to compress the communications with the server.
- `config_path`: the path to an OpenSSH configuration file.
- `exec_timeout`: the timeout, in seconds, for arbitrary SSH commands on
the server.
- `policy`: a
[`paramiko.MissingHostKeyPolicy`](http://docs.paramiko.org/en/stable/api/client.html#paramiko.client.MissingHostKeyPolicy)
instance, or `None` to use
[`paramiko.AutoAddPolicy`](http://docs.paramiko.org/en/stable/api/client.html#paramiko.client.AutoAddPolicy).
Additional keyword arguments will be passed to the underlying
[`paramiko.SSHClient.connect`](http://docs.paramiko.org/en/stable/api/client.html#paramiko.client.SSHClient.connect)
call, taking precedence over implicitly derived arguments. Once created, the `SSHFS` filesystem behaves like any
other filesystem (see the [PyFilesystem2 documentation](https://pyfilesystem2.readthedocs.io)).
### Files
`SSHFS.openbin` has the following extra options that can be passed as
keyword arguments to control the file buffering:
- `prefetch`: enabled by default, use a background thread to prefetch the content
of a file opened in reading mode. Does nothing for files in writing mode.
- `pipelined`: enable pipelined mode, avoid waiting for server answer between
two uploaded chunks. Does nothing for files in reading mode.
## Testing
Automated unit tests are run on [GitHub Actions](https://github.com/miarec/miarec_sshfs/actions)
To run the tests locally, do the following.
Install Docker on local machine.
Create activate python virtual environment:
python -m vevn venv
source venv\bin\activate
Install the project and test dependencies:
pip install -e ".[test]"
Run tests:
pytest -v
## Feedback
Found a bug ? Have an enhancement request ? Head over to the [GitHub
issue tracker](https://github.com/miarec/miarec_sshfs/issues) of the
project if you need to report or ask something. If you are filling in on
a bug, please include as much information as you can about the issue,
and try to recreate the same bug in a simple, easily reproductible
situation.
## Credits
`miarec_ssfs` is developed and maintained by [MiaRec](https://www.miarec.com)
Original code (`fs.sshfs`) was developed by:
- [Martin Larralde](https://github.com/althonos)
The following people contributed to `fs.sshfs`:
- [Reimar Bauer](https://github.com/ReimarBauer)
- [Paul Gessinger](https://github.com/paulgessinger)
- [Mariusz Kryński](https://github.com/mrk-its)
- [Will McGugan](https://github.com/willmcgugan)
- [Jeremy Nimmer](https://github.com/jwnimmer-tri)
- [Tim Nyborg](https://github.com/timnyborg)
- [Danica J. Sutherland](https://github.com/djsutherland)
- [John Vandenberg](https://github.com/jayvdb)
This project obviously owes a lot to the PyFilesystem2 project and
[all its contributors](https://github.com/PyFilesystem/pyfilesystem2/blob/master/CONTRIBUTORS.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/miarec/miarec_sshfs",
"name": "miarec-sshfs",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "filesystem,Pyfilesystem2,ssh,sftp,paramiko",
"author": "MiaRec",
"author_email": "support@miarec.com",
"download_url": "https://files.pythonhosted.org/packages/6e/7b/ffd7ebdf91850c1de7b350cff1f4366161de1bd755e53639f1aa6b690091/miarec_sshfs-2024.1.5.tar.gz",
"platform": "any",
"description": "# `miarec_sshfs` SFTP filesystem for PyFilesystem2\n\n[](https://github.com/miarec/miarec_sshfs/actions)\n[](https://choosealicense.com/licenses/lgpl-2.1/)\n\nThis is a fork of [fs.sshfs](https://github.com/althonos/fs.sshfs) project, with modifications that are required for our needs.\n\n\n## Requirements\n\n| **PyFilesystem2** | [](https://pypi.python.org/pypi/fs) | [](https://github.com/PyFilesystem/pyfilesystem2) | [](https://choosealicense.com/licenses/mit/) |\n|:-|:-|:-|:-|\n| **six** | [](https://pypi.python.org/pypi/six) | []( https://github.com/benjaminp/six) | [](https://choosealicense.com/licenses/mit/) |\n| **paramiko** | [](https://pypi.python.org/pypi/paramiko) | []( https://github.com/paramiko/paramiko) | [](https://choosealicense.com/licenses/lgpl-2.1/) |\n| **property-cached** | [](https://pypi.python.org/pypi/property-cached) | [](https://github.com/althonos/property-cached) | []( https://choosealicense.com/licenses/bsd-3-clause/) |\n\n`miarec_sshfs` supports Python versions 3.6+ \n\n## Notable differences to `fs.sshfs`\n\n1. Loading of configuration from SSH Config files (`~/.ssh/config`) is removed due to potential security issues, \nwhen this component used in SaaS project. \n \n2. Automatic loading of SSH keys from SSH Agent is forbidden due to potential security issues, when this components\nis used in SaaS project.\n \n3. The opener protocol prefixes are `mssh://` and `msftp://` (instead of the original `ssh://` and `sftp://`)\n\n4. URL is forbidden due to potential leak of SFTP credentials via url.\n\n## Installation\n\nInstall from GitHub, using [pip](https://pip.pypa.io/):\n\n```console\n$ pip install git+https://github.com/miarec/miarec_sshfs@master\n```\n\n## Usage\n\nTo connect to an SSH server, use the `fs.sshfs.SSHFS` constructor, which signature is:\n\n```python\nfrom miarec_sshfs import SSHFS\nmy_fs = SSHFS(\n host, user=None, passwd=None, pkey=None, timeout=10, port=22,\n keepalive=10, compress=False, config_path='~/.ssh/config'\n)\n```\n\nwith each argument explained below:\n\n- `host`: the name or IP address of the SSH server\n- `user`: the username to connect with, defaults to the current user.\n- `passwd`: an optional password, used to connect directly to the server or\n to decrypt the public key, if any given.\n- `pkey`: a [`paramiko.PKey`](http://docs.paramiko.org/en/stable/api/keys.html#paramiko.pkey.PKey)\n object, a path, or a list of paths to an SSH key.\n- `timeout`: the timeout, in seconds, for networking operations.\n- `port`: the port the SSH server is listening on.\n- `keepalive`: the interval of time between *keepalive* packets, in seconds.\n Set to 0 to disable.\n- `compress`: set to `True` to compress the communications with the server.\n- `config_path`: the path to an OpenSSH configuration file.\n- `exec_timeout`: the timeout, in seconds, for arbitrary SSH commands on\n the server.\n- `policy`: a\n [`paramiko.MissingHostKeyPolicy`](http://docs.paramiko.org/en/stable/api/client.html#paramiko.client.MissingHostKeyPolicy)\n instance, or `None` to use\n [`paramiko.AutoAddPolicy`](http://docs.paramiko.org/en/stable/api/client.html#paramiko.client.AutoAddPolicy).\n\nAdditional keyword arguments will be passed to the underlying\n[`paramiko.SSHClient.connect`](http://docs.paramiko.org/en/stable/api/client.html#paramiko.client.SSHClient.connect)\ncall, taking precedence over implicitly derived arguments. Once created, the `SSHFS` filesystem behaves like any\nother filesystem (see the [PyFilesystem2 documentation](https://pyfilesystem2.readthedocs.io)).\n\n### Files\n\n`SSHFS.openbin` has the following extra options that can be passed as\nkeyword arguments to control the file buffering:\n\n- `prefetch`: enabled by default, use a background thread to prefetch the content\n of a file opened in reading mode. Does nothing for files in writing mode.\n- `pipelined`: enable pipelined mode, avoid waiting for server answer between\n two uploaded chunks. Does nothing for files in reading mode.\n\n\n## Testing\n\nAutomated unit tests are run on [GitHub Actions](https://github.com/miarec/miarec_sshfs/actions)\n\nTo run the tests locally, do the following.\n\nInstall Docker on local machine.\n\nCreate activate python virtual environment:\n\n python -m vevn venv\n source venv\\bin\\activate\n\nInstall the project and test dependencies:\n\n pip install -e \".[test]\"\n\nRun tests:\n\n pytest -v\n\n\n## Feedback\n\nFound a bug ? Have an enhancement request ? Head over to the [GitHub\nissue tracker](https://github.com/miarec/miarec_sshfs/issues) of the\nproject if you need to report or ask something. If you are filling in on\na bug, please include as much information as you can about the issue,\nand try to recreate the same bug in a simple, easily reproductible\nsituation.\n\n\n## Credits\n\n`miarec_ssfs` is developed and maintained by [MiaRec](https://www.miarec.com)\n\nOriginal code (`fs.sshfs`) was developed by:\n- [Martin Larralde](https://github.com/althonos)\n\nThe following people contributed to `fs.sshfs`:\n- [Reimar Bauer](https://github.com/ReimarBauer)\n- [Paul Gessinger](https://github.com/paulgessinger)\n- [Mariusz Kry\u0144ski](https://github.com/mrk-its)\n- [Will McGugan](https://github.com/willmcgugan)\n- [Jeremy Nimmer](https://github.com/jwnimmer-tri)\n- [Tim Nyborg](https://github.com/timnyborg)\n- [Danica J. Sutherland](https://github.com/djsutherland)\n- [John Vandenberg](https://github.com/jayvdb)\n\nThis project obviously owes a lot to the PyFilesystem2 project and\n[all its contributors](https://github.com/PyFilesystem/pyfilesystem2/blob/master/CONTRIBUTORS.md).\n\n",
"bugtrack_url": null,
"license": "LGPLv2+",
"summary": "Pyfilesystem2 over SSH using paramiko",
"version": "2024.1.5",
"project_urls": {
"Bug Tracker": "https://github.com/miarec/miarec_sshfs/issues",
"Builds": "https://github.com/miarec/miarec_sshfs/actions",
"Homepage": "https://github.com/miarec/miarec_sshfs"
},
"split_keywords": [
"filesystem",
"pyfilesystem2",
"ssh",
"sftp",
"paramiko"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "62f94b9b0a3299a3b36853721b7216c5f8168b4dce1139127c9232f6ecba0426",
"md5": "d2f3b87e403098c2611a6f4fbf371a72",
"sha256": "4840d286913ca1dfe1201515aaf05f36ad9b54ad69a7316437c3da8b5b40f1ff"
},
"downloads": -1,
"filename": "miarec_sshfs-2024.1.5-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "d2f3b87e403098c2611a6f4fbf371a72",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 25435,
"upload_time": "2024-01-23T22:18:59",
"upload_time_iso_8601": "2024-01-23T22:18:59.367719Z",
"url": "https://files.pythonhosted.org/packages/62/f9/4b9b0a3299a3b36853721b7216c5f8168b4dce1139127c9232f6ecba0426/miarec_sshfs-2024.1.5-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6e7bffd7ebdf91850c1de7b350cff1f4366161de1bd755e53639f1aa6b690091",
"md5": "1ba0af5cc0f68293954dc1efde91d601",
"sha256": "ef977d90e8afd1007ababc6340ccc2947c32d0bf8dddeb03f45efc96e3d3cdf8"
},
"downloads": -1,
"filename": "miarec_sshfs-2024.1.5.tar.gz",
"has_sig": false,
"md5_digest": "1ba0af5cc0f68293954dc1efde91d601",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 31656,
"upload_time": "2024-01-23T22:19:01",
"upload_time_iso_8601": "2024-01-23T22:19:01.055931Z",
"url": "https://files.pythonhosted.org/packages/6e/7b/ffd7ebdf91850c1de7b350cff1f4366161de1bd755e53639f1aa6b690091/miarec_sshfs-2024.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-23 22:19:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "miarec",
"github_project": "miarec_sshfs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "miarec-sshfs"
}
JSON
