paramiko.sftp

30 """ + 31 Abstract object representing a handle to an open file (or folder) in an + 32 SFTP server implementation. Each handle has a string representation used + 33 by the client to refer to the underlying file. + 34 + 35 Server implementations can (and should) subclass SFTPHandle to implement + 36 features of a file handle, like L{stat} or L{chattr}. + 37 """ +

38 - def __init__(self, flags=0): +

39 """ + 40 Create a new file handle representing a local file being served over + 41 SFTP. If C{flags} is passed in, it's used to determine if the file + 42 is open in append mode. + 43 + 44 @param flags: optional flags as passed to L{SFTPServerInterface.open} + 45 @type flags: int + 46 """ + 47 self.__flags = flags + 48 self.__name = None + 49 # only for handles to folders: + 50 self.__files = { } + 51 self.__tell = None +

52 +

53 - def close(self): +

54 """ + 55 When a client closes a file, this method is called on the handle. + 56 Normally you would use this method to close the underlying OS level + 57 file object(s). + 58 + 59 The default implementation checks for attributes on C{self} named + 60 C{readfile} and/or C{writefile}, and if either or both are present, + 61 their C{close()} methods are called. This means that if you are + 62 using the default implementations of L{read} and L{write}, this + 63 method's default implementation should be fine also. + 64 """ + 65 readfile = getattr(self, 'readfile', None) + 66 if readfile is not None: + 67 readfile.close() + 68 writefile = getattr(self, 'writefile', None) + 69 if writefile is not None: + 70 writefile.close() +

71 +

72 - def read(self, offset, length): +

73 """ + 74 Read up to C{length} bytes from this file, starting at position + 75 C{offset}. The offset may be a python long, since SFTP allows it + 76 to be 64 bits. + 77 + 78 If the end of the file has been reached, this method may return an + 79 empty string to signify EOF, or it may also return L{SFTP_EOF}. + 80 + 81 The default implementation checks for an attribute on C{self} named + 82 C{readfile}, and if present, performs the read operation on the python + 83 file-like object found there. (This is meant as a time saver for the + 84 common case where you are wrapping a python file object.) + 85 + 86 @param offset: position in the file to start reading from. + 87 @type offset: int or long + 88 @param length: number of bytes to attempt to read. + 89 @type length: int + 90 @return: data read from the file, or an SFTP error code. + 91 @rtype: str + 92 """ + 93 readfile = getattr(self, 'readfile', None) + 94 if readfile is None: + 95 return SFTP_OP_UNSUPPORTED + 96 try: + 97 if self.__tell is None: + 98 self.__tell = readfile.tell() + 99 if offset != self.__tell: +100 readfile.seek(offset) +101 self.__tell = offset +102 data = readfile.read(length) +103 except IOError, e: +104 self.__tell = None +105 return SFTPServer.convert_errno(e.errno) +106 self.__tell += len(data) +107 return data +

108 +

109 - def write(self, offset, data): +

110 """ +111 Write C{data} into this file at position C{offset}. Extending the +112 file past its original end is expected. Unlike python's normal +113 C{write()} methods, this method cannot do a partial write: it must +114 write all of C{data} or else return an error. +115 +116 The default implementation checks for an attribute on C{self} named +117 C{writefile}, and if present, performs the write operation on the +118 python file-like object found there. The attribute is named +119 differently from C{readfile} to make it easy to implement read-only +120 (or write-only) files, but if both attributes are present, they should +121 refer to the same file. +122 +123 @param offset: position in the file to start reading from. +124 @type offset: int or long +125 @param data: data to write into the file. +126 @type data: str +127 @return: an SFTP error code like L{SFTP_OK}. +128 """ +129 writefile = getattr(self, 'writefile', None) +130 if writefile is None: +131 return SFTP_OP_UNSUPPORTED +132 try: +133 # in append mode, don't care about seeking +134 if (self.__flags & os.O_APPEND) == 0: +135 if self.__tell is None: +136 self.__tell = writefile.tell() +137 if offset != self.__tell: +138 writefile.seek(offset) +139 self.__tell = offset +140 writefile.write(data) +141 writefile.flush() +142 except IOError, e: +143 self.__tell = None +144 return SFTPServer.convert_errno(e.errno) +145 if self.__tell is not None: +146 self.__tell += len(data) +147 return SFTP_OK +

148 +

149 - def stat(self): +

150 """ +151 Return an L{SFTPAttributes} object referring to this open file, or an +152 error code. This is equivalent to L{SFTPServerInterface.stat}, except +153 it's called on an open file instead of a path. +154 +155 @return: an attributes object for the given file, or an SFTP error +156 code (like L{SFTP_PERMISSION_DENIED}). +157 @rtype: L{SFTPAttributes} I{or error code} +158 """ +159 return SFTP_OP_UNSUPPORTED +

160 +

161 - def chattr(self, attr): +

162 """ +163 Change the attributes of this file. The C{attr} object will contain +164 only those fields provided by the client in its request, so you should +165 check for the presence of fields before using them. +166 +167 @param attr: the attributes to change on this file. +168 @type attr: L{SFTPAttributes} +169 @return: an error code like L{SFTP_OK}. +170 @rtype: int +171 """ +172 return SFTP_OP_UNSUPPORTED +

173 +174 +175 ### internals... +176 +177 +

178 - def _set_files(self, files): +

179 """ +180 Used by the SFTP server code to cache a directory listing. (In +181 the SFTP protocol, listing a directory is a multi-stage process +182 requiring a temporary handle.) +183 """ +184 self.__files = files +

185 +

186 - def _get_next_files(self): +

187 """ +188 Used by the SFTP server code to retreive a cached directory +189 listing. +190 """ +191 fnlist = self.__files[:16] +192 self.__files = self.__files[16:] +193 return fnlist +

194 +

195 - def _get_name(self): +

196 return self.__name +

197 +

198 - def _set_name(self, name): +

199 self.__name = name +

Source Code for Module paramiko.sftp_handle