paramiko.sftp

52 """ 53 SFTP client object. C{SFTPClient} is used to open an sftp session across 54 an open ssh L{Transport} and do remote file operations. 55 """ 56

57 - def __init__(self, sock):

58 """ 59 Create an SFTP client from an existing L{Channel}. The channel 60 should already have requested the C{"sftp"} subsystem. 61 62 An alternate way to create an SFTP client context is by using 63 L{from_transport}. 64 65 @param sock: an open L{Channel} using the C{"sftp"} subsystem 66 @type sock: L{Channel} 67 68 @raise SSHException: if there's an exception while negotiating 69 sftp 70 """ 71 BaseSFTP.__init__(self) 72 self.sock = sock 73 self.ultra_debug = False 74 self.request_number = 1 75 # lock for request_number 76 self._lock = threading.Lock() 77 self._cwd = None 78 # request # -> SFTPFile 79 self._expecting = weakref.WeakValueDictionary() 80 if type(sock) is Channel: 81 # override default logger 82 transport = self.sock.get_transport() 83 self.logger = util.get_logger(transport.get_log_channel() + '.sftp') 84 self.ultra_debug = transport.get_hexdump() 85 try: 86 server_version = self._send_version() 87 except EOFError, x: 88 raise SSHException('EOF during negotiation') 89 self._log(INFO, 'Opened sftp connection (server version %d)' % server_version)

90

91 - def from_transport(cls, t):

92 """ 93 Create an SFTP client channel from an open L{Transport}. 94 95 @param t: an open L{Transport} which is already authenticated 96 @type t: L{Transport} 97 @return: a new L{SFTPClient} object, referring to an sftp session 98 (channel) across the transport 99 @rtype: L{SFTPClient} 100 """ 101 chan = t.open_session() 102 if chan is None: 103 return None 104 chan.invoke_subsystem('sftp') 105 return cls(chan)

106 from_transport = classmethod(from_transport) 107

108 - def _log(self, level, msg, *args):

109 super(SFTPClient, self)._log(level, "[chan %s] " + msg, *([ self.sock.get_name() ] + list(args)))

110

111 - def close(self):

112 """ 113 Close the SFTP session and its underlying channel. 114 115 @since: 1.4 116 """ 117 self._log(INFO, 'sftp session closed.') 118 self.sock.close()

119

120 - def get_channel(self):

121 """ 122 Return the underlying L{Channel} object for this SFTP session. This 123 might be useful for doing things like setting a timeout on the channel. 124 125 @return: the SSH channel 126 @rtype: L{Channel} 127 128 @since: 1.7.1 129 """ 130 return self.sock

131

132 - def listdir(self, path='.'):

133 """ 134 Return a list containing the names of the entries in the given C{path}. 135 The list is in arbitrary order. It does not include the special 136 entries C{'.'} and C{'..'} even if they are present in the folder. 137 This method is meant to mirror C{os.listdir} as closely as possible. 138 For a list of full L{SFTPAttributes} objects, see L{listdir_attr}. 139 140 @param path: path to list (defaults to C{'.'}) 141 @type path: str 142 @return: list of filenames 143 @rtype: list of str 144 """ 145 return [f.filename for f in self.listdir_attr(path)]

146

147 - def listdir_attr(self, path='.'):

148 """ 149 Return a list containing L{SFTPAttributes} objects corresponding to 150 files in the given C{path}. The list is in arbitrary order. It does 151 not include the special entries C{'.'} and C{'..'} even if they are 152 present in the folder. 153 154 The returned L{SFTPAttributes} objects will each have an additional 155 field: C{longname}, which may contain a formatted string of the file's 156 attributes, in unix format. The content of this string will probably 157 depend on the SFTP server implementation. 158 159 @param path: path to list (defaults to C{'.'}) 160 @type path: str 161 @return: list of attributes 162 @rtype: list of L{SFTPAttributes} 163 164 @since: 1.2 165 """ 166 path = self._adjust_cwd(path) 167 self._log(DEBUG, 'listdir(%r)' % path) 168 t, msg = self._request(CMD_OPENDIR, path) 169 if t != CMD_HANDLE: 170 raise SFTPError('Expected handle') 171 handle = msg.get_string() 172 filelist = [] 173 while True: 174 try: 175 t, msg = self._request(CMD_READDIR, handle) 176 except EOFError, e: 177 # done with handle 178 break 179 if t != CMD_NAME: 180 raise SFTPError('Expected name response') 181 count = msg.get_int() 182 for i in range(count): 183 filename = _to_unicode(msg.get_string()) 184 longname = _to_unicode(msg.get_string()) 185 attr = SFTPAttributes._from_msg(msg, filename, longname) 186 if (filename != '.') and (filename != '..'): 187 filelist.append(attr) 188 self._request(CMD_CLOSE, handle) 189 return filelist

190

191 - def open(self, filename, mode='r', bufsize=-1):

192 """ 193 Open a file on the remote server. The arguments are the same as for 194 python's built-in C{file} (aka C{open}). A file-like object is 195 returned, which closely mimics the behavior of a normal python file 196 object. 197 198 The mode indicates how the file is to be opened: C{'r'} for reading, 199 C{'w'} for writing (truncating an existing file), C{'a'} for appending, 200 C{'r+'} for reading/writing, C{'w+'} for reading/writing (truncating an 201 existing file), C{'a+'} for reading/appending. The python C{'b'} flag 202 is ignored, since SSH treats all files as binary. The C{'U'} flag is 203 supported in a compatible way. 204 205 Since 1.5.2, an C{'x'} flag indicates that the operation should only 206 succeed if the file was created and did not previously exist. This has 207 no direct mapping to python's file flags, but is commonly known as the 208 C{O_EXCL} flag in posix. 209 210 The file will be buffered in standard python style by default, but 211 can be altered with the C{bufsize} parameter. C{0} turns off 212 buffering, C{1} uses line buffering, and any number greater than 1 213 (C{>1}) uses that specific buffer size. 214 215 @param filename: name of the file to open 216 @type filename: str 217 @param mode: mode (python-style) to open in 218 @type mode: str 219 @param bufsize: desired buffering (-1 = default buffer size) 220 @type bufsize: int 221 @return: a file object representing the open file 222 @rtype: SFTPFile 223 224 @raise IOError: if the file could not be opened. 225 """ 226 filename = self._adjust_cwd(filename) 227 self._log(DEBUG, 'open(%r, %r)' % (filename, mode)) 228 imode = 0 229 if ('r' in mode) or ('+' in mode): 230 imode |= SFTP_FLAG_READ 231 if ('w' in mode) or ('+' in mode) or ('a' in mode): 232 imode |= SFTP_FLAG_WRITE 233 if ('w' in mode): 234 imode |= SFTP_FLAG_CREATE | SFTP_FLAG_TRUNC 235 if ('a' in mode): 236 imode |= SFTP_FLAG_CREATE | SFTP_FLAG_APPEND 237 if ('x' in mode): 238 imode |= SFTP_FLAG_CREATE | SFTP_FLAG_EXCL 239 attrblock = SFTPAttributes() 240 t, msg = self._request(CMD_OPEN, filename, imode, attrblock) 241 if t != CMD_HANDLE: 242 raise SFTPError('Expected handle') 243 handle = msg.get_string() 244 self._log(DEBUG, 'open(%r, %r) -> %s' % (filename, mode, hexlify(handle))) 245 return SFTPFile(self, handle, mode, bufsize)

246 247 # python continues to vacillate about "open" vs "file"... 248 file = open 249

250 - def remove(self, path):

251 """ 252 Remove the file at the given path. This only works on files; for 253 removing folders (directories), use L{rmdir}. 254 255 @param path: path (absolute or relative) of the file to remove 256 @type path: str 257 258 @raise IOError: if the path refers to a folder (directory) 259 """ 260 path = self._adjust_cwd(path) 261 self._log(DEBUG, 'remove(%r)' % path) 262 self._request(CMD_REMOVE, path)

263 264 unlink = remove 265

266 - def rename(self, oldpath, newpath):

267 """ 268 Rename a file or folder from C{oldpath} to C{newpath}. 269 270 @param oldpath: existing name of the file or folder 271 @type oldpath: str 272 @param newpath: new name for the file or folder 273 @type newpath: str 274 275 @raise IOError: if C{newpath} is a folder, or something else goes 276 wrong 277 """ 278 oldpath = self._adjust_cwd(oldpath) 279 newpath = self._adjust_cwd(newpath) 280 self._log(DEBUG, 'rename(%r, %r)' % (oldpath, newpath)) 281 self._request(CMD_RENAME, oldpath, newpath)

282

283 - def mkdir(self, path, mode=0777):

284 """ 285 Create a folder (directory) named C{path} with numeric mode C{mode}. 286 The default mode is 0777 (octal). On some systems, mode is ignored. 287 Where it is used, the current umask value is first masked out. 288 289 @param path: name of the folder to create 290 @type path: str 291 @param mode: permissions (posix-style) for the newly-created folder 292 @type mode: int 293 """ 294 path = self._adjust_cwd(path) 295 self._log(DEBUG, 'mkdir(%r, %r)' % (path, mode)) 296 attr = SFTPAttributes() 297 attr.st_mode = mode 298 self._request(CMD_MKDIR, path, attr)

299

300 - def rmdir(self, path):

301 """ 302 Remove the folder named C{path}. 303 304 @param path: name of the folder to remove 305 @type path: str 306 """ 307 path = self._adjust_cwd(path) 308 self._log(DEBUG, 'rmdir(%r)' % path) 309 self._request(CMD_RMDIR, path)

310

311 - def stat(self, path):

312 """ 313 Retrieve information about a file on the remote system. The return 314 value is an object whose attributes correspond to the attributes of 315 python's C{stat} structure as returned by C{os.stat}, except that it 316 contains fewer fields. An SFTP server may return as much or as little 317 info as it wants, so the results may vary from server to server. 318 319 Unlike a python C{stat} object, the result may not be accessed as a 320 tuple. This is mostly due to the author's slack factor. 321 322 The fields supported are: C{st_mode}, C{st_size}, C{st_uid}, C{st_gid}, 323 C{st_atime}, and C{st_mtime}. 324 325 @param path: the filename to stat 326 @type path: str 327 @return: an object containing attributes about the given file 328 @rtype: SFTPAttributes 329 """ 330 path = self._adjust_cwd(path) 331 self._log(DEBUG, 'stat(%r)' % path) 332 t, msg = self._request(CMD_STAT, path) 333 if t != CMD_ATTRS: 334 raise SFTPError('Expected attributes') 335 return SFTPAttributes._from_msg(msg)

336

337 - def lstat(self, path):

338 """ 339 Retrieve information about a file on the remote system, without 340 following symbolic links (shortcuts). This otherwise behaves exactly 341 the same as L{stat}. 342 343 @param path: the filename to stat 344 @type path: str 345 @return: an object containing attributes about the given file 346 @rtype: SFTPAttributes 347 """ 348 path = self._adjust_cwd(path) 349 self._log(DEBUG, 'lstat(%r)' % path) 350 t, msg = self._request(CMD_LSTAT, path) 351 if t != CMD_ATTRS: 352 raise SFTPError('Expected attributes') 353 return SFTPAttributes._from_msg(msg)

354

355 - def symlink(self, source, dest):

356 """ 357 Create a symbolic link (shortcut) of the C{source} path at 358 C{destination}. 359 360 @param source: path of the original file 361 @type source: str 362 @param dest: path of the newly created symlink 363 @type dest: str 364 """ 365 dest = self._adjust_cwd(dest) 366 self._log(DEBUG, 'symlink(%r, %r)' % (source, dest)) 367 if type(source) is unicode: 368 source = source.encode('utf-8') 369 self._request(CMD_SYMLINK, source, dest)

370

371 - def chmod(self, path, mode):

372 """ 373 Change the mode (permissions) of a file. The permissions are 374 unix-style and identical to those used by python's C{os.chmod} 375 function. 376 377 @param path: path of the file to change the permissions of 378 @type path: str 379 @param mode: new permissions 380 @type mode: int 381 """ 382 path = self._adjust_cwd(path) 383 self._log(DEBUG, 'chmod(%r, %r)' % (path, mode)) 384 attr = SFTPAttributes() 385 attr.st_mode = mode 386 self._request(CMD_SETSTAT, path, attr)

387

388 - def chown(self, path, uid, gid):

389 """ 390 Change the owner (C{uid}) and group (C{gid}) of a file. As with 391 python's C{os.chown} function, you must pass both arguments, so if you 392 only want to change one, use L{stat} first to retrieve the current 393 owner and group. 394 395 @param path: path of the file to change the owner and group of 396 @type path: str 397 @param uid: new owner's uid 398 @type uid: int 399 @param gid: new group id 400 @type gid: int 401 """ 402 path = self._adjust_cwd(path) 403 self._log(DEBUG, 'chown(%r, %r, %r)' % (path, uid, gid)) 404 attr = SFTPAttributes() 405 attr.st_uid, attr.st_gid = uid, gid 406 self._request(CMD_SETSTAT, path, attr)

407

408 - def utime(self, path, times):

409 """ 410 Set the access and modified times of the file specified by C{path}. If 411 C{times} is C{None}, then the file's access and modified times are set 412 to the current time. Otherwise, C{times} must be a 2-tuple of numbers, 413 of the form C{(atime, mtime)}, which is used to set the access and 414 modified times, respectively. This bizarre API is mimicked from python 415 for the sake of consistency -- I apologize. 416 417 @param path: path of the file to modify 418 @type path: str 419 @param times: C{None} or a tuple of (access time, modified time) in 420 standard internet epoch time (seconds since 01 January 1970 GMT) 421 @type times: tuple(int) 422 """ 423 path = self._adjust_cwd(path) 424 if times is None: 425 times = (time.time(), time.time()) 426 self._log(DEBUG, 'utime(%r, %r)' % (path, times)) 427 attr = SFTPAttributes() 428 attr.st_atime, attr.st_mtime = times 429 self._request(CMD_SETSTAT, path, attr)

430

431 - def truncate(self, path, size):

432 """ 433 Change the size of the file specified by C{path}. This usually extends 434 or shrinks the size of the file, just like the C{truncate()} method on 435 python file objects. 436 437 @param path: path of the file to modify 438 @type path: str 439 @param size: the new size of the file 440 @type size: int or long 441 """ 442 path = self._adjust_cwd(path) 443 self._log(DEBUG, 'truncate(%r, %r)' % (path, size)) 444 attr = SFTPAttributes() 445 attr.st_size = size 446 self._request(CMD_SETSTAT, path, attr)

447

448 - def readlink(self, path):

449 """ 450 Return the target of a symbolic link (shortcut). You can use 451 L{symlink} to create these. The result may be either an absolute or 452 relative pathname. 453 454 @param path: path of the symbolic link file 455 @type path: str 456 @return: target path 457 @rtype: str 458 """ 459 path = self._adjust_cwd(path) 460 self._log(DEBUG, 'readlink(%r)' % path) 461 t, msg = self._request(CMD_READLINK, path) 462 if t != CMD_NAME: 463 raise SFTPError('Expected name response') 464 count = msg.get_int() 465 if count == 0: 466 return None 467 if count != 1: 468 raise SFTPError('Readlink returned %d results' % count) 469 return _to_unicode(msg.get_string())

470

471 - def normalize(self, path):

472 """ 473 Return the normalized path (on the server) of a given path. This 474 can be used to quickly resolve symbolic links or determine what the 475 server is considering to be the "current folder" (by passing C{'.'} 476 as C{path}). 477 478 @param path: path to be normalized 479 @type path: str 480 @return: normalized form of the given path 481 @rtype: str 482 483 @raise IOError: if the path can't be resolved on the server 484 """ 485 path = self._adjust_cwd(path) 486 self._log(DEBUG, 'normalize(%r)' % path) 487 t, msg = self._request(CMD_REALPATH, path) 488 if t != CMD_NAME: 489 raise SFTPError('Expected name response') 490 count = msg.get_int() 491 if count != 1: 492 raise SFTPError('Realpath returned %d results' % count) 493 return _to_unicode(msg.get_string())

494

495 - def chdir(self, path):

496 """ 497 Change the "current directory" of this SFTP session. Since SFTP 498 doesn't really have the concept of a current working directory, this 499 is emulated by paramiko. Once you use this method to set a working 500 directory, all operations on this SFTPClient object will be relative 501 to that path. 502 503 @param path: new current working directory 504 @type path: str 505 506 @raise IOError: if the requested path doesn't exist on the server 507 508 @since: 1.4 509 """ 510 self._cwd = self.normalize(path)

511

512 - def getcwd(self):

513 """ 514 Return the "current working directory" for this SFTP session, as 515 emulated by paramiko. If no directory has been set with L{chdir}, 516 this method will return C{None}. 517 518 @return: the current working directory on the server, or C{None} 519 @rtype: str 520 521 @since: 1.4 522 """ 523 return self._cwd

524

525 - def put(self, localpath, remotepath, callback=None):

526 """ 527 Copy a local file (C{localpath}) to the SFTP server as C{remotepath}. 528 Any exception raised by operations will be passed through. This 529 method is primarily provided as a convenience. 530 531 The SFTP operations use pipelining for speed. 532 533 @param localpath: the local file to copy 534 @type localpath: str 535 @param remotepath: the destination path on the SFTP server 536 @type remotepath: str 537 @param callback: optional callback function that accepts the bytes 538 transferred so far and the total bytes to be transferred 539 (since 1.7.4) 540 @type callback: function(int, int) 541 @return: an object containing attributes about the given file 542 (since 1.7.4) 543 @rtype: SFTPAttributes 544 545 @since: 1.4 546 """ 547 file_size = os.stat(localpath).st_size 548 fl = file(localpath, 'rb') 549 fr = self.file(remotepath, 'wb') 550 fr.set_pipelined(True) 551 size = 0 552 while True: 553 data = fl.read(32768) 554 if len(data) == 0: 555 break 556 fr.write(data) 557 size += len(data) 558 if callback is not None: 559 callback(size, file_size) 560 fl.close() 561 fr.close() 562 s = self.stat(remotepath) 563 if s.st_size != size: 564 raise IOError('size mismatch in put! %d != %d' % (s.st_size, size)) 565 return s

566

567 - def get(self, remotepath, localpath, callback=None):

568 """ 569 Copy a remote file (C{remotepath}) from the SFTP server to the local 570 host as C{localpath}. Any exception raised by operations will be 571 passed through. This method is primarily provided as a convenience. 572 573 @param remotepath: the remote file to copy 574 @type remotepath: str 575 @param localpath: the destination path on the local host 576 @type localpath: str 577 @param callback: optional callback function that accepts the bytes 578 transferred so far and the total bytes to be transferred 579 (since 1.7.4) 580 @type callback: function(int, int) 581 582 @since: 1.4 583 """ 584 fr = self.file(remotepath, 'rb') 585 file_size = self.stat(remotepath).st_size 586 fr.prefetch() 587 fl = file(localpath, 'wb') 588 size = 0 589 while True: 590 data = fr.read(32768) 591 if len(data) == 0: 592 break 593 fl.write(data) 594 size += len(data) 595 if callback is not None: 596 callback(size, file_size) 597 fl.close() 598 fr.close() 599 s = os.stat(localpath) 600 if s.st_size != size: 601 raise IOError('size mismatch in get! %d != %d' % (s.st_size, size))

602 603 604 ### internals... 605 606

607 - def _request(self, t, *arg):

608 num = self._async_request(type(None), t, *arg) 609 return self._read_response(num)

610

611 - def _async_request(self, fileobj, t, *arg):

612 # this method may be called from other threads (prefetch) 613 self._lock.acquire() 614 try: 615 msg = Message() 616 msg.add_int(self.request_number) 617 for item in arg: 618 if type(item) is int: 619 msg.add_int(item) 620 elif type(item) is long: 621 msg.add_int64(item) 622 elif type(item) is str: 623 msg.add_string(item) 624 elif type(item) is SFTPAttributes: 625 item._pack(msg) 626 else: 627 raise Exception('unknown type for %r type %r' % (item, type(item))) 628 num = self.request_number 629 self._expecting[num] = fileobj 630 self._send_packet(t, str(msg)) 631 self.request_number += 1 632 finally: 633 self._lock.release() 634 return num

635

636 - def _read_response(self, waitfor=None):

637 while True: 638 try: 639 t, data = self._read_packet() 640 except EOFError, e: 641 raise SSHException('Server connection dropped: %s' % (str(e),)) 642 msg = Message(data) 643 num = msg.get_int() 644 if num not in self._expecting: 645 # might be response for a file that was closed before responses came back 646 self._log(DEBUG, 'Unexpected response #%d' % (num,)) 647 if waitfor is None: 648 # just doing a single check 649 break 650 continue 651 fileobj = self._expecting[num] 652 del self._expecting[num] 653 if num == waitfor: 654 # synchronous 655 if t == CMD_STATUS: 656 self._convert_status(msg) 657 return t, msg 658 if fileobj is not type(None): 659 fileobj._async_response(t, msg) 660 if waitfor is None: 661 # just doing a single check 662 break 663 return (None, None)

664

665 - def _finish_responses(self, fileobj):

666 while fileobj in self._expecting.values(): 667 self._read_response() 668 fileobj._check_exception()

669

670 - def _convert_status(self, msg):

671 """ 672 Raises EOFError or IOError on error status; otherwise does nothing. 673 """ 674 code = msg.get_int() 675 text = msg.get_string() 676 if code == SFTP_OK: 677 return 678 elif code == SFTP_EOF: 679 raise EOFError(text) 680 elif code == SFTP_NO_SUCH_FILE: 681 # clever idea from john a. meinel: map the error codes to errno 682 raise IOError(errno.ENOENT, text) 683 elif code == SFTP_PERMISSION_DENIED: 684 raise IOError(errno.EACCES, text) 685 else: 686 raise IOError(text)

687

688 - def _adjust_cwd(self, path):

689 """ 690 Return an adjusted path if we're emulating a "current working 691 directory" for the server. 692 """ 693 if type(path) is unicode: 694 path = path.encode('utf-8') 695 if self._cwd is None: 696 return path 697 if (len(path) > 0) and (path[0] == '/'): 698 # absolute path 699 return path 700 if self._cwd == '/': 701 return self._cwd + path 702 return self._cwd + '/' + path

Source Code for Module paramiko.sftp_client