From ed280d5ac360e2af796e9bd973d7b4df89f0c449 Mon Sep 17 00:00:00 2001 From: "Jeremy T. Bouse" Date: Fri, 27 Nov 2009 16:20:12 -0500 Subject: Imported Upstream version 1.7.4 --- docs/paramiko.SFTPServerInterface-class.html | 976 +++++++++++++++++++++++++++ 1 file changed, 976 insertions(+) create mode 100644 docs/paramiko.SFTPServerInterface-class.html (limited to 'docs/paramiko.SFTPServerInterface-class.html') diff --git a/docs/paramiko.SFTPServerInterface-class.html b/docs/paramiko.SFTPServerInterface-class.html new file mode 100644 index 0000000..df785ad --- /dev/null +++ b/docs/paramiko.SFTPServerInterface-class.html @@ -0,0 +1,976 @@ + + + + + paramiko.SFTPServerInterface + + + + + + + + + + + + + + + + + + + + + + +
   Home      Trees      Indices      Help   
+ + + + + +
+ + Package paramiko :: + Class SFTPServerInterface + + + + + +
[frames] | no frames]
+
+ +

Class SFTPServerInterface

source code

+
+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__, + __getattribute__, + __hash__, + __new__, + __reduce__, + __reduce_ex__, + __repr__, + __setattr__, + __str__ +

+
+ + + + + + + + + +
+ Properties
+

Inherited from object: + __class__ +

+
+ + + + + + +
+ Method Details
+ +
+ +
+ + +
+

__init__(self, + server, + *largs, + **kwargs) +
(Constructor) +

+ 		source code  +
+ +

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) +

+ 		source code  +
+ +

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) +

+ 		source code  +
+ +

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) +

+ 		source code  +
+ +

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) +

+ 		source code  +
+ +

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) +

+ 		source code  +
+ +

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) +

+ 		source code  +
+ +

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) +

+ 		source code  +
+ +

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) +

+ 		source code  +
+ +

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) +

+ 		source code  +
+ +

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) +

+ 		source code  +
+ +

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) +

+ 		source code  +
+ +

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) +

+ 		source code  +
+ +

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) +

+ 		source code  +
+ +

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) +

+ 		source code  +
+ +

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.
+
+
+
+
+ + + + + + + + + + + + + + + + + +
   Home      Trees      Indices      Help   
+ + + + + +
+ Generated by Epydoc 3.0.1 on Sun Jul 6 18:30:29 2008 + + http://epydoc.sourceforge.net +
+ + + + -- cgit v1.2.3