sftp_helper.api module

SFTP Helper — FastAPI HTTP surface.

Exposes every public function in sftp_helper.main as an HTTP endpoint so sftp-helper can be dropped behind any reverse proxy and consumed by other services. Kept intentionally minimal:

  • Multipart uploads for local-to-remote transfers (UploadFile), streamed straight to a temporary file so large payloads do not blow up memory.

  • FileResponse for downloads.

  • JSON responses for the exists / delete / mkdir / show-credentials queries.

  • BackgroundTasks cleans temp files after the response has been streamed — no leftover garbage on disk after a request.

Credentials

The credentials are loaded once at import time from the environment (SFTP_HOST / SFTP_LOGIN / …) or from the file pointed at by SFTP_HELPER_CONFIG. We never accept credentials in a request body — the API is meant to be the trusted server-side view of a single SFTP target, not a multitenant relay.

Install the extra to get the runtime dependencies:

pip install 'sftp-helper[api]'

Then run the app with any ASGI server:

uvicorn sftp_helper.api:app --host 0.0.0.0 --port 8000

Usage Example

>>> # Start the server (env-configured credentials):
>>> #   SFTP_HELPER_CONFIG=./sftp_config.json uvicorn sftp_helper.api:app --reload
>>> # Upload a file:
>>> #   curl -F 'file=@local.txt' -F 'remote=/uploads/local.txt' \
>>> #        http://localhost:8000/upload
>>> # Check existence:
>>> #   curl "http://localhost:8000/exists?remote=/uploads/local.txt"
>>> # Full OpenAPI docs at http://localhost:8000/docs

Author

Warith Harchaoui, Ph.D. — https://linkedin.com/in/warith-harchaoui/

sftp_helper.api.delete_endpoint(remote=fastapi.Query)

Delete a remote file. Idempotent — deleting a missing file returns True.

Parameters:

remote (str)

Return type:

fastapi.responses.JSONResponse

sftp_helper.api.dir_exists_endpoint(remote=fastapi.Query)

Return whether a remote directory exists.

Parameters:

remote (str)

Return type:

fastapi.responses.JSONResponse

sftp_helper.api.download_endpoint(background, remote=fastapi.Query, filename=fastapi.Query)

Download a remote file. The response body is the file bytes.

Parameters:

  • background (fastapi.BackgroundTasks)

  • remote (str)

  • filename (str | None)

sftp_helper.api.exists_endpoint(remote=fastapi.Query)

Return whether a remote file exists.

Parameters:

remote (str)

Return type:

fastapi.responses.JSONResponse

sftp_helper.api.health()

Simple liveness probe — no dependency check, just proves the app is up.

Return type:

dict

sftp_helper.api.mkdir_endpoint(remote=fastapi.Form)

Create a remote directory (mkdir -p semantics).

Parameters:

remote (str)

Return type:

fastapi.responses.JSONResponse

sftp_helper.api.normalize_path_endpoint(path=fastapi.Query)

Normalize a remote path (single leading ‘/’, no trailing ‘/’).

Parameters:

path (str)

Return type:

fastapi.responses.JSONResponse

sftp_helper.api.show_credentials()

Return the resolved credentials (password masked).

Return type:

fastapi.responses.JSONResponse

sftp_helper.api.strip_path_endpoint(address=fastapi.Query)

Strip ‘sftp://<host>’ prefix from an SFTP address.

Parameters:

address (str)

Return type:

fastapi.responses.JSONResponse

sftp_helper.api.tempfile_endpoint(ext=fastapi.Form, subdir=fastapi.Form)

Reserve a unique remote path (context immediately closed). Deletes on exit.

Parameters:
Return type:

fastapi.responses.JSONResponse

sftp_helper.api.upload_endpoint(background, file=fastapi.File, remote=fastapi.Form)

Upload the multipart file to the SFTP server. Returns the remote address.

Parameters:

  • background (fastapi.BackgroundTasks)

  • file (fastapi.UploadFile)

  • remote (str)

Return type:

fastapi.responses.JSONResponse