Package paramiko :: Module sftp_si
[frames] | no frames]

Source Code for Module paramiko.sftp_si

  1  # Copyright (C) 2003-2007  Robey Pointer <robeypointer@gmail.com> 
  2  # 
  3  # This file is part of paramiko. 
  4  # 
  5  # Paramiko is free software; you can redistribute it and/or modify it under the 
  6  # terms of the GNU Lesser General Public License as published by the Free 
  7  # Software Foundation; either version 2.1 of the License, or (at your option) 
  8  # any later version. 
  9  # 
 10  # Paramiko is distributed in the hope that it will be useful, but WITHOUT ANY 
 11  # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 
 12  # A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more 
 13  # details. 
 14  # 
 15  # You should have received a copy of the GNU Lesser General Public License 
 16  # along with Paramiko; if not, write to the Free Software Foundation, Inc., 
 17  # 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA. 
 18   
 19  """ 
 20  An interface to override for SFTP server support. 
 21  """ 
 22   
 23  import os 
 24  import sys 
 25  from paramiko.sftp import SFTP_OP_UNSUPPORTED 
 26   
 27   
28 -class SFTPServerInterface (object):
29 """ 30 This class defines an interface for controlling the behavior of paramiko 31 when using the `.SFTPServer` subsystem to provide an SFTP server. 32 33 Methods on this class are called from the SFTP session's thread, so you can 34 block as long as necessary without affecting other sessions (even other 35 SFTP sessions). However, raising an exception will usually cause the SFTP 36 session to abruptly end, so you will usually want to catch exceptions and 37 return an appropriate error code. 38 39 All paths are in string form instead of unicode because not all SFTP 40 clients & servers obey the requirement that paths be encoded in UTF-8. 41 """ 42
43 - def __init__(self, server, *largs, **kwargs):
44 """ 45 Create a new SFTPServerInterface object. This method does nothing by 46 default and is meant to be overridden by subclasses. 47 48 :param .ServerInterface server: 49 the server object associated with this channel and SFTP subsystem 50 """ 51 super(SFTPServerInterface, self).__init__(*largs, **kwargs)
52
53 - def session_started(self):
54 """ 55 The SFTP server session has just started. This method is meant to be 56 overridden to perform any necessary setup before handling callbacks 57 from SFTP operations. 58 """ 59 pass
60
61 - def session_ended(self):
62 """ 63 The SFTP server session has just ended, either cleanly or via an 64 exception. This method is meant to be overridden to perform any 65 necessary cleanup before this `.SFTPServerInterface` object is 66 destroyed. 67 """ 68 pass
69
70 - def open(self, path, flags, attr):
71 """ 72 Open a file on the server and create a handle for future operations 73 on that file. On success, a new object subclassed from `.SFTPHandle` 74 should be returned. This handle will be used for future operations 75 on the file (read, write, etc). On failure, an error code such as 76 `.SFTP_PERMISSION_DENIED` should be returned. 77 78 ``flags`` contains the requested mode for opening (read-only, 79 write-append, etc) as a bitset of flags from the ``os`` module: 80 81 - ``os.O_RDONLY`` 82 - ``os.O_WRONLY`` 83 - ``os.O_RDWR`` 84 - ``os.O_APPEND`` 85 - ``os.O_CREAT`` 86 - ``os.O_TRUNC`` 87 - ``os.O_EXCL`` 88 89 (One of ``os.O_RDONLY``, ``os.O_WRONLY``, or ``os.O_RDWR`` will always 90 be set.) 91 92 The ``attr`` object contains requested attributes of the file if it 93 has to be created. Some or all attribute fields may be missing if 94 the client didn't specify them. 95 96 .. note:: The SFTP protocol defines all files to be in "binary" mode. 97 There is no equivalent to Python's "text" mode. 98 99 :param str path: 100 the requested path (relative or absolute) of the file to be opened. 101 :param int flags: 102 flags or'd together from the ``os`` module indicating the requested 103 mode for opening the file. 104 :param .SFTPAttributes attr: 105 requested attributes of the file if it is newly created. 106 :return: a new `.SFTPHandle` or error code. 107 """ 108 return SFTP_OP_UNSUPPORTED
109
110 - def list_folder(self, path):
111 """ 112 Return a list of files within a given folder. The ``path`` will use 113 posix notation (``"/"`` separates folder names) and may be an absolute 114 or relative path. 115 116 The list of files is expected to be a list of `.SFTPAttributes` 117 objects, which are similar in structure to the objects returned by 118 ``os.stat``. In addition, each object should have its ``filename`` 119 field filled in, since this is important to a directory listing and 120 not normally present in ``os.stat`` results. The method 121 `.SFTPAttributes.from_stat` will usually do what you want. 122 123 In case of an error, you should return one of the ``SFTP_*`` error 124 codes, such as `.SFTP_PERMISSION_DENIED`. 125 126 :param str path: the requested path (relative or absolute) to be listed. 127 :return: 128 a list of the files in the given folder, using `.SFTPAttributes` 129 objects. 130 131 .. note:: 132 You should normalize the given ``path`` first (see the `os.path` 133 module) and check appropriate permissions before returning the list 134 of files. Be careful of malicious clients attempting to use 135 relative paths to escape restricted folders, if you're doing a 136 direct translation from the SFTP server path to your local 137 filesystem. 138 """ 139 return SFTP_OP_UNSUPPORTED
140
141 - def stat(self, path):
142 """ 143 Return an `.SFTPAttributes` object for a path on the server, or an 144 error code. If your server supports symbolic links (also known as 145 "aliases"), you should follow them. (`lstat` is the corresponding 146 call that doesn't follow symlinks/aliases.) 147 148 :param str path: 149 the requested path (relative or absolute) to fetch file statistics 150 for. 151 :return: 152 an `.SFTPAttributes` object for the given file, or an SFTP error 153 code (like `.SFTP_PERMISSION_DENIED`). 154 """ 155 return SFTP_OP_UNSUPPORTED
156
157 - def lstat(self, path):
158 """ 159 Return an `.SFTPAttributes` object for a path on the server, or an 160 error code. If your server supports symbolic links (also known as 161 "aliases"), you should not follow them -- instead, you should 162 return data on the symlink or alias itself. (`stat` is the 163 corresponding call that follows symlinks/aliases.) 164 165 :param str path: 166 the requested path (relative or absolute) to fetch file statistics 167 for. 168 :type path: str 169 :return: 170 an `.SFTPAttributes` object for the given file, or an SFTP error 171 code (like `.SFTP_PERMISSION_DENIED`). 172 """ 173 return SFTP_OP_UNSUPPORTED
174
175 - def remove(self, path):
176 """ 177 Delete a file, if possible. 178 179 :param str path: 180 the requested path (relative or absolute) of the file to delete. 181 :return: an SFTP error code `int` like `.SFTP_OK`. 182 """ 183 return SFTP_OP_UNSUPPORTED
184
185 - def rename(self, oldpath, newpath):
186 """ 187 Rename (or move) a file. The SFTP specification implies that this 188 method can be used to move an existing file into a different folder, 189 and since there's no other (easy) way to move files via SFTP, it's 190 probably a good idea to implement "move" in this method too, even for 191 files that cross disk partition boundaries, if at all possible. 192 193 .. note:: You should return an error if a file with the same name as 194 ``newpath`` already exists. (The rename operation should be 195 non-desctructive.) 196 197 :param str oldpath: 198 the requested path (relative or absolute) of the existing file. 199 :param str newpath: the requested new path of the file. 200 :return: an SFTP error code `int` like `.SFTP_OK`. 201 """ 202 return SFTP_OP_UNSUPPORTED
203
204 - def mkdir(self, path, attr):
205 """ 206 Create a new directory with the given attributes. The ``attr`` 207 object may be considered a "hint" and ignored. 208 209 The ``attr`` object will contain only those fields provided by the 210 client in its request, so you should use ``hasattr`` to check for 211 the presense of fields before using them. In some cases, the ``attr`` 212 object may be completely empty. 213 214 :param str path: 215 requested path (relative or absolute) of the new folder. 216 :param .SFTPAttributes attr: requested attributes of the new folder. 217 :return: an SFTP error code `int` like `.SFTP_OK`. 218 """ 219 return SFTP_OP_UNSUPPORTED
220
221 - def rmdir(self, path):
222 """ 223 Remove a directory if it exists. The ``path`` should refer to an 224 existing, empty folder -- otherwise this method should return an 225 error. 226 227 :param str path: 228 requested path (relative or absolute) of the folder to remove. 229 :return: an SFTP error code `int` like `.SFTP_OK`. 230 """ 231 return SFTP_OP_UNSUPPORTED
232
233 - def chattr(self, path, attr):
234 """ 235 Change the attributes of a file. The ``attr`` object will contain 236 only those fields provided by the client in its request, so you 237 should check for the presence of fields before using them. 238 239 :param str path: 240 requested path (relative or absolute) of the file to change. 241 :param attr: 242 requested attributes to change on the file (an `.SFTPAttributes` 243 object) 244 :return: an error code `int` like `.SFTP_OK`. 245 """ 246 return SFTP_OP_UNSUPPORTED
247
248 - def canonicalize(self, path):
249 """ 250 Return the canonical form of a path on the server. For example, 251 if the server's home folder is ``/home/foo``, the path 252 ``"../betty"`` would be canonicalized to ``"/home/betty"``. Note 253 the obvious security issues: if you're serving files only from a 254 specific folder, you probably don't want this method to reveal path 255 names outside that folder. 256 257 You may find the Python methods in ``os.path`` useful, especially 258 ``os.path.normpath`` and ``os.path.realpath``. 259 260 The default implementation returns ``os.path.normpath('/' + path)``. 261 """ 262 if os.path.isabs(path): 263 out = os.path.normpath(path) 264 else: 265 out = os.path.normpath('/' + path) 266 if sys.platform == 'win32': 267 # on windows, normalize backslashes to sftp/posix format 268 out = out.replace('\\', '/') 269 return out
270 283
297