pain001.transport package#

Optional payment-file transports; network activity is always explicit.

Submodules#

pain001.transport.cli module#

Click entry point for explicit SFTP uploads and host-key inspection.

pain001.transport.sftp module#

Pinned-host SFTP uploads with atomic publication and retry detection.

class pain001.transport.sftp.SFTPTarget(host: str, port: int, username: str, path: str)[source]#

Bases: object

Validated connection coordinates without embedded credentials.

host: str#
path: str#
port: int#
username: str#
class pain001.transport.sftp.UploadResult(destination: str, sha256: str, reused: bool)[source]#

Bases: object

Receipt for a published file or a byte-identical earlier upload.

destination: str#
reused: bool#
sha256: str#
pain001.transport.sftp.fingerprint(key: PKey) → str[source]#

Return the OpenSSH SHA256 fingerprint of an SSH public host key.

pain001.transport.sftp.parse_target(url: str) → SFTPTarget[source]#

Parse an SFTP URL, refusing passwords and ambiguous remote paths.

Parameters:

url – An sftp://user@host[:port]/absolute/path URL.

Returns:

Validated host, port, username and decoded POSIX path.

Raises:

ValueError – If the URL contains unsupported or unsafe components.

pain001.transport.sftp.print_host_fingerprint(url: str, timeout: float = 15) → str[source]#

Observe a server’s unverified host fingerprint without authenticating.

Parameters:

  • url – The SFTP server URL.

  • timeout – Connection and SSH handshake timeout in seconds.

Returns:

An untrusted fingerprint to compare with an independent source.

pain001.transport.sftp.upload_sftp(file_path: str, url: str, *, known_hosts: str | None = None, accept_host_key: str | None = None, identity_file: str | None = None, password: str | None = None, passphrase: str | None = None, timeout: float = 15) → UploadResult[source]#

Atomically publish a file, refusing to replace different remote data.

A matching remote SHA256 is a successful retry. New uploads use an exclusive temporary file in the same directory and a no-clobber SFTP rename. Authentication occurs only after host-key verification.

Parameters:

  • file_path – Local file to deliver.

  • url – Remote file URL, or a directory URL ending in a slash.

  • known_hosts – Explicit known_hosts file; otherwise use standard files.

  • accept_host_key – Independently verified OpenSSH SHA256 fingerprint.

  • identity_file – Optional private key filename.

  • password – Optional password supplied by the caller, never logged.

  • passphrase – Optional private-key passphrase, never logged.

  • timeout – Network operation timeout in seconds.

Returns:

Destination, content hash and whether an earlier upload was reused.

Raises:

  • ValueError – If the URL, pin, filename or timeout is invalid.

  • FileExistsError – If different data already occupies the destination.

  • OSError – If local I/O or the SFTP transfer fails.

  • paramiko.SSHException – If host verification or authentication fails.

  • BaseException – Interruptions propagate after best-effort cleanup.