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