Package paramiko :: Class SFTPServerInterface

[frames] | no frames]

Class SFTPServerInterface

object --+
         |
        SFTPServerInterface

This class defines an interface for controlling the behavior of paramiko when using the SFTPServer subsystem to provide an SFTP server.

Methods on this class are called from the SFTP session's thread, so you can block as long as necessary without affecting other sessions (even other SFTP sessions). However, raising an exception will usually cause the SFTP session to abruptly end, so you will usually want to catch exceptions and return an appropriate error code.

All paths are in string form instead of unicode because not all SFTP clients & servers obey the requirement that paths be encoded in UTF-8.

Instance Methods

__init__(self, server, *largs, **kwargs)
Create a new SFTPServerInterface object.

source code

canonicalize(self, path)
Return the canonical form of a path on the server.

source code

int

chattr(self, path, attr)
Change the attributes of a file.

source code

list of SFTPAttributes or error code

list_folder(self, path)
Return a list of files within a given folder.

source code

SFTPAttributes or error code

lstat(self, path)
Return an SFTPAttributes object for a path on the server, or an error code.

source code

int

mkdir(self, path, attr)
Create a new directory with the given attributes.

source code

open(self, path, flags, attr)
Open a file on the server and create a handle for future operations on that file.

source code

str or error code

readlink(self, path)
Return the target of a symbolic link (or shortcut) on the server.

source code

int

remove(self, path)
Delete a file, if possible.

source code

int

rename(self, oldpath, newpath)
Rename (or move) a file.

source code

int

rmdir(self, path)
Remove a directory if it exists.

source code

session_ended(self)
The SFTP server session has just ended, either cleanly or via an exception.

source code

session_started(self)
The SFTP server session has just started.

source code

SFTPAttributes or error code

stat(self, path)
Return an SFTPAttributes object for a path on the server, or an error code.

source code

int

symlink(self, target_path, path)
Create a symbolic link on the server, as new pathname path, with target_path as the target of the link. source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Properties
Inherited from `object`: `__class__`

Method Details

init(self, server, *largs, **kwargs)
(Constructor)

Create a new SFTPServerInterface object. This method does nothing by default and is meant to be overridden by subclasses.

Parameters:

server (ServerInterface) - the server object associated with this channel and SFTP subsystem

Overrides: object.__init__

canonicalize(self, path)

Return the canonical form of a path on the server. For example, if the server's home folder is /home/foo, the path "../betty" would be canonicalized to "/home/betty". Note the obvious security issues: if you're serving files only from a specific folder, you probably don't want this method to reveal path names outside that folder.

You may find the python methods in os.path useful, especially os.path.normpath and os.path.realpath.

The default implementation returns os.path.normpath('/' + path).

chattr(self, path, attr)

Change the attributes of a file. The attr object will contain only those fields provided by the client in its request, so you should check for the presence of fields before using them.

Parameters:

path (str) - requested path (relative or absolute) of the file to change.
attr (SFTPAttributes) - requested attributes to change on the file.

Returns: int

an error code like SFTP_OK.

list_folder(self, path)

Return a list of files within a given folder. The path will use posix notation ("/" separates folder names) and may be an absolute or relative path.

The list of files is expected to be a list of SFTPAttributes objects, which are similar in structure to the objects returned by os.stat. In addition, each object should have its filename field filled in, since this is important to a directory listing and not normally present in os.stat results. The method SFTPAttributes.from_stat will usually do what you want.

In case of an error, you should return one of the SFTP_* error codes, such as SFTP_PERMISSION_DENIED.

Parameters:

path (str) - the requested path (relative or absolute) to be listed.

Returns: list of SFTPAttributes or error code

a list of the files in the given folder, using SFTPAttributes objects.

Note: You should normalize the given path first (see the os.path module) and check appropriate permissions before returning the list of files. Be careful of malicious clients attempting to use relative paths to escape restricted folders, if you're doing a direct translation from the SFTP server path to your local filesystem.

lstat(self, path)

Return an SFTPAttributes object for a path on the server, or an error code. If your server supports symbolic links (also known as "aliases"), you should not follow them -- instead, you should return data on the symlink or alias itself. (stat is the corresponding call that follows symlinks/aliases.)

Parameters:

path (str) - the requested path (relative or absolute) to fetch file statistics for.

Returns: SFTPAttributes or error code

an attributes object for the given file, or an SFTP error code (like SFTP_PERMISSION_DENIED).

mkdir(self, path, attr)

Create a new directory with the given attributes. The attr object may be considered a "hint" and ignored.

The attr object will contain only those fields provided by the client in its request, so you should use hasattr to check for the presense of fields before using them. In some cases, the attr object may be completely empty.

Parameters:

path (str) - requested path (relative or absolute) of the new folder.
attr (SFTPAttributes) - requested attributes of the new folder.

Returns: int

an SFTP error code like SFTP_OK.

open(self, path, flags, attr)

Open a file on the server and create a handle for future operations on that file. On success, a new object subclassed from SFTPHandle should be returned. This handle will be used for future operations on the file (read, write, etc). On failure, an error code such as SFTP_PERMISSION_DENIED should be returned.

flags contains the requested mode for opening (read-only, write-append, etc) as a bitset of flags from the os module:

os.O_RDONLY
os.O_WRONLY
os.O_RDWR
os.O_APPEND
os.O_CREAT
os.O_TRUNC
os.O_EXCL

(One of os.O_RDONLY, os.O_WRONLY, or os.O_RDWR will always be set.)

The attr object contains requested attributes of the file if it has to be created. Some or all attribute fields may be missing if the client didn't specify them.

Parameters:

path (str) - the requested path (relative or absolute) of the file to be opened.
flags (int) - flags or'd together from the os module indicating the requested mode for opening the file.
attr (SFTPAttributes) - requested attributes of the file if it is newly created.

Returns:

a new SFTPHandle or error code. @rtype SFTPHandle

Note: The SFTP protocol defines all files to be in "binary" mode. There is no equivalent to python's "text" mode.

readlink(self, path)

Return the target of a symbolic link (or shortcut) on the server. If the specified path doesn't refer to a symbolic link, an error should be returned.

Parameters:

path (str) - path (relative or absolute) of the symbolic link.

Returns: str or error code

the target path of the symbolic link, or an error code like SFTP_NO_SUCH_FILE.

remove(self, path)

Delete a file, if possible.

Parameters:

path (str) - the requested path (relative or absolute) of the file to delete.

Returns: int

an SFTP error code like SFTP_OK.

rename(self, oldpath, newpath)

Rename (or move) a file. The SFTP specification implies that this method can be used to move an existing file into a different folder, and since there's no other (easy) way to move files via SFTP, it's probably a good idea to implement "move" in this method too, even for files that cross disk partition boundaries, if at all possible.

Parameters:

oldpath (str) - the requested path (relative or absolute) of the existing file.
newpath (str) - the requested new path of the file.

Returns: int

an SFTP error code like SFTP_OK.

Note: You should return an error if a file with the same name as newpath already exists. (The rename operation should be non-desctructive.)

rmdir(self, path)

Remove a directory if it exists. The path should refer to an existing, empty folder -- otherwise this method should return an error.

Parameters:

path (str) - requested path (relative or absolute) of the folder to remove.

Returns: int

an SFTP error code like SFTP_OK.

session_ended(self)

The SFTP server session has just ended, either cleanly or via an exception. This method is meant to be overridden to perform any necessary cleanup before this SFTPServerInterface object is destroyed.

session_started(self)

The SFTP server session has just started. This method is meant to be overridden to perform any necessary setup before handling callbacks from SFTP operations.

stat(self, path)

Return an SFTPAttributes object for a path on the server, or an error code. If your server supports symbolic links (also known as "aliases"), you should follow them. (lstat is the corresponding call that doesn't follow symlinks/aliases.)

Parameters:

path (str) - the requested path (relative or absolute) to fetch file statistics for.

Returns: SFTPAttributes or error code

an attributes object for the given file, or an SFTP error code (like SFTP_PERMISSION_DENIED).

symlink(self, target_path, path)

Create a symbolic link on the server, as new pathname path, with target_path as the target of the link.

Parameters:

target_path (str) - path (relative or absolute) of the target for this new symbolic link.
path (str) - path (relative or absolute) of the symbolic link to create.

Returns: int

an error code like SFTP_OK.