aiomegfile.filesystem.sftp module

class aiomegfile.filesystem.sftp.SftpFileSystem(host: str, port: int | None = None, *, username: str | None = None, password: str | None = None, show_port_in_uri: bool | None = None, show_username_in_uri: bool | None = None, show_password_in_uri: bool | None = None)[source]

Bases: BaseFileSystem

Filesystem adapter for sftp:// URIs using asyncssh.

URI formats:

  • Absolute remote path: sftp://[username[:password]@]hostname[:port]//file_path.

  • Home-relative path: sftp://[username[:password]@]hostname[:port]/path/to/file. Path part does not start with // after parsing.

async absolute(path: str) → str[source]

Return absolute URI path without protocol.

Parameters:

path – Path without protocol.

Returns:

Absolute path in / form.

Return type:

str

async access(path: str, mode: Access = Access.READ) → bool[source]

Check read/write access heuristically for a path.

Parameters:

  • path – Path without protocol.

  • mode – Access mode enum.

Returns:

Whether access is likely available.

Return type:

bool

build_uri(path: str) → str

Build URI from path part.

Parameters:

path – Path without protocol.

Returns:

Full SFTP URI.

Return type:

str

async copy(src_path: str, dst_path: str, callback: Callable[[int], None] | None = None) → str[source]

Copy a single file on the same SFTP endpoint.

Parameters:

  • src_path – Source path without protocol.

  • dst_path – Destination path without protocol.

  • callback – Optional copy progress callback.

Returns:

Destination path without protocol.

Return type:

str

async download(src_path: str, dst_path: str, callback: Callable[[int], None] | None = None) → None[source]

Download a single remote file to local filesystem.

Parameters:

  • src_path – Remote source path without protocol.

  • dst_path – Local destination path.

  • callback – Optional download progress callback.

async exists(path: str, followlinks: bool = False) → bool[source]

Return whether path exists.

Parameters:

  • path – Path without protocol.

  • followlinks – Whether to follow symbolic links.

Returns:

True if path exists.

Return type:

bool

classmethod from_uri(uri: str)

Create filesystem instance from URI.

Parameters:

uri – URI string.

Returns:

SftpFileSystem instance.

Return type:

SftpFileSystem

async is_absolute(path: str) → bool[source]

Return whether URI path is absolute in SFTP semantics.

Parameters:

path – Path without protocol.

Returns:

True when path starts with /.

Return type:

bool

async is_dir(path: str, followlinks: bool = False) → bool[source]

Return True when path points to a directory.

Parameters:

  • path – Path without protocol.

  • followlinks – Whether to follow symbolic links.

Returns:

True for directories, otherwise False.

Return type:

bool

async is_file(path: str, followlinks: bool = False) → bool[source]

Return True when path points to a regular file.

Parameters:

  • path – Path without protocol.

  • followlinks – Whether to follow symbolic links.

Returns:

True for files, otherwise False.

Return type:

bool

Return whether path points to a symbolic link.

Parameters:

path – Path without protocol.

Returns:

True when path is a symbolic link.

Return type:

bool

async mkdir(path: str, mode: int = 511, parents: bool = False, exist_ok: bool = False) → None[source]

Create directory.

Parameters:

  • path – Path without protocol.

  • mode – Directory permission bits.

  • parents – Create missing parent directories.

  • exist_ok – Ignore existing target directory.

async move(src_path: str, dst_path: str, overwrite: bool = True) → str[source]

Move file or directory to a destination path.

Parameters:

  • src_path – Source path without protocol.

  • dst_path – Destination path without protocol.

  • overwrite – Overwrite destination when it exists.

Returns:

Destination path without protocol.

Return type:

str

open(path: str, mode: str = 'r', buffering: int = -1, encoding: str | None = None, errors: str | None = None, newline: str | None = None, **kwargs: Any) → AsyncContextManager[source]

Open path as async reader or writer.

Read mode uses native AsyncSSH file handles wrapped in AioSftpReadableFile. Extra reader tuning kwargs are accepted for compatibility but ignored.

Parameters:

  • path – Path without protocol.

  • mode – File open mode.

  • buffering – Unused compatibility argument.

  • encoding – Text encoding in text mode.

  • errors – Text error handling.

  • newline – Currently unused compatibility argument.

  • kwargs – Extra compatibility parameters ignored for SFTP reads.

Returns:

Async context manager for opened file.

Return type:

T.AsyncContextManager

parse_uri(uri: str) → str[source]

Parse URI into path part without protocol.

Parameters:

uri – URI string.

Returns:

Path without protocol.

Return type:

str

protocol = 'sftp'

Return symbolic link target for path.

Parameters:

path – Symbolic link path without protocol.

Returns:

Target path without protocol.

Return type:

str

async remove(path: str, missing_ok: bool = False) → None[source]

Remove file or directory recursively.

Parameters:

  • path – Path without protocol.

  • missing_ok – Ignore missing target when True.

same_endpoint(other_filesystem: BaseFileSystem) → bool[source]

Return whether another filesystem points to same SFTP endpoint.

Parameters:

other_filesystem – Filesystem to compare.

Returns:

True when two filesystems share the same endpoint settings.

Return type:

bool

async samefile(path: str, other_path: str) → bool[source]

Return whether two paths reference the same remote file.

Parameters:

  • path – First path without protocol.

  • other_path – Second path without protocol.

Returns:

True if they resolve to the same real path.

Return type:

bool

scandir(path: str) → AsyncContextManager[AsyncIterator[FileEntry]][source]

Return async iterator over direct children of a directory.

Parameters:

path – Directory path without protocol.

Returns:

Async context manager yielding FileEntry values.

Return type:

T.AsyncContextManager[T.AsyncIterator[FileEntry]]

scanfile(path: str, sort: bool = False) → AsyncContextManager[AsyncIterator[FileEntry]][source]

Return async iterator over files recursively.

Parameters:

  • path – Root path without protocol.

  • sort – Compatibility flag for protocol-aligned scanfile APIs.

Returns:

Async context manager yielding file FileEntry values.

Return type:

T.AsyncContextManager[T.AsyncIterator[FileEntry]]

async stat(path: str, followlinks: bool = False) → StatResult[source]

Return stat information for path.

Parameters:

  • path – Path without protocol.

  • followlinks – Whether to follow symbolic links.

Returns:

StatResult object.

Return type:

StatResult

Create symbolic link.

Parameters:

  • src_path – Source path without protocol.

  • dst_path – Destination symlink path without protocol.

async upload(src_path: str, dst_path: str, callback: Callable[[int], None] | None = None) → None[source]

Upload a single local file to this SFTP endpoint.

Parameters:

  • src_path – Local source path.

  • dst_path – Remote destination path without protocol.

  • callback – Optional upload progress callback.

async aiomegfile.filesystem.sftp.get_sftp_client(host: str, port: int = 22, *, username: str | None = None, password: str | None = None) → Tuple[Any, Any][source]

Get a cached SFTP client pair bound to the current event loop.

Parameters:

  • host – SFTP host.

  • port – SFTP port.

  • username – Optional username.

  • password – Optional password.

Returns:

Tuple of (ssh_connection, sftp_client).

Return type:

tuple[Any, Any]

aiomegfile.filesystem.sftp.is_sftp(path: str | PathLike) → bool[source]

Return whether the given path is an SFTP URI.

Parameters:

path – Path to be tested.

Returns:

True if path is an SFTP URI.

Return type:

bool