paramiko.file

27 """ + 28 Reusable base class to implement python-style file buffering around a + 29 simpler stream. + 30 """ + 31 + 32 _DEFAULT_BUFSIZE = 8192 + 33 + 34 SEEK_SET = 0 + 35 SEEK_CUR = 1 + 36 SEEK_END = 2 + 37 + 38 FLAG_READ = 0x1 + 39 FLAG_WRITE = 0x2 + 40 FLAG_APPEND = 0x4 + 41 FLAG_BINARY = 0x10 + 42 FLAG_BUFFERED = 0x20 + 43 FLAG_LINE_BUFFERED = 0x40 + 44 FLAG_UNIVERSAL_NEWLINE = 0x80 + 45 +

46 - def __init__(self): +

47 self.newlines = None + 48 self._flags = 0 + 49 self._bufsize = self._DEFAULT_BUFSIZE + 50 self._wbuffer = StringIO() + 51 self._rbuffer = '' + 52 self._at_trailing_cr = False + 53 self._closed = False + 54 # pos - position within the file, according to the user + 55 # realpos - position according the OS + 56 # (these may be different because we buffer for line reading) + 57 self._pos = self._realpos = 0 + 58 # size only matters for seekable files + 59 self._size = 0 +

60 +

61 - def __del__(self): +

62 self.close() +

63 +

64 - def __iter__(self): +

65 """ + 66 Returns an iterator that can be used to iterate over the lines in this + 67 file. This iterator happens to return the file itself, since a file is + 68 its own iterator. + 69 + 70 @raise ValueError: if the file is closed. + 71 + 72 @return: an interator. + 73 @rtype: iterator + 74 """ + 75 if self._closed: + 76 raise ValueError('I/O operation on closed file') + 77 return self +

78 +

79 - def close(self): +

80 """ + 81 Close the file. Future read and write operations will fail. + 82 """ + 83 self.flush() + 84 self._closed = True +

85 +

86 - def flush(self): +

87 """ + 88 Write out any data in the write buffer. This may do nothing if write + 89 buffering is not turned on. + 90 """ + 91 self._write_all(self._wbuffer.getvalue()) + 92 self._wbuffer = StringIO() + 93 return +

94 +

95 - def next(self): +

96 """ + 97 Returns the next line from the input, or raises L{StopIteration} when + 98 EOF is hit. Unlike python file objects, it's okay to mix calls to + 99 C{next} and L{readline}. +100 +101 @raise StopIteration: when the end of the file is reached. +102 +103 @return: a line read from the file. +104 @rtype: str +105 """ +106 line = self.readline() +107 if not line: +108 raise StopIteration +109 return line +

110 +

111 - def read(self, size=None): +

112 """ +113 Read at most C{size} bytes from the file (less if we hit the end of the +114 file first). If the C{size} argument is negative or omitted, read all +115 the remaining data in the file. +116 +117 @param size: maximum number of bytes to read +118 @type size: int +119 @return: data read from the file, or an empty string if EOF was +120 encountered immediately +121 @rtype: str +122 """ +123 if self._closed: +124 raise IOError('File is closed') +125 if not (self._flags & self.FLAG_READ): +126 raise IOError('File is not open for reading') +127 if (size is None) or (size < 0): +128 # go for broke +129 result = self._rbuffer +130 self._rbuffer = '' +131 self._pos += len(result) +132 while True: +133 try: +134 new_data = self._read(self._DEFAULT_BUFSIZE) +135 except EOFError: +136 new_data = None +137 if (new_data is None) or (len(new_data) == 0): +138 break +139 result += new_data +140 self._realpos += len(new_data) +141 self._pos += len(new_data) +142 return result +143 if size <= len(self._rbuffer): +144 result = self._rbuffer[:size] +145 self._rbuffer = self._rbuffer[size:] +146 self._pos += len(result) +147 return result +148 while len(self._rbuffer) < size: +149 read_size = size - len(self._rbuffer) +150 if self._flags & self.FLAG_BUFFERED: +151 read_size = max(self._bufsize, read_size) +152 try: +153 new_data = self._read(read_size) +154 except EOFError: +155 new_data = None +156 if (new_data is None) or (len(new_data) == 0): +157 break +158 self._rbuffer += new_data +159 self._realpos += len(new_data) +160 result = self._rbuffer[:size] +161 self._rbuffer = self._rbuffer[size:] +162 self._pos += len(result) +163 return result +

164 +

165 - def readline(self, size=None): +

166 """ +167 Read one entire line from the file. A trailing newline character is +168 kept in the string (but may be absent when a file ends with an +169 incomplete line). If the size argument is present and non-negative, it +170 is a maximum byte count (including the trailing newline) and an +171 incomplete line may be returned. An empty string is returned only when +172 EOF is encountered immediately. +173 +174 @note: Unlike stdio's C{fgets()}, the returned string contains null +175 characters (C{'\\0'}) if they occurred in the input. +176 +177 @param size: maximum length of returned string. +178 @type size: int +179 @return: next line of the file, or an empty string if the end of the +180 file has been reached. +181 @rtype: str +182 """ +183 # it's almost silly how complex this function is. +184 if self._closed: +185 raise IOError('File is closed') +186 if not (self._flags & self.FLAG_READ): +187 raise IOError('File not open for reading') +188 line = self._rbuffer +189 while True: +190 if self._at_trailing_cr and (self._flags & self.FLAG_UNIVERSAL_NEWLINE) and (len(line) > 0): +191 # edge case: the newline may be '\r\n' and we may have read +192 # only the first '\r' last time. +193 if line[0] == '\n': +194 line = line[1:] +195 self._record_newline('\r\n') +196 else: +197 self._record_newline('\r') +198 self._at_trailing_cr = False +199 # check size before looking for a linefeed, in case we already have +200 # enough. +201 if (size is not None) and (size >= 0): +202 if len(line) >= size: +203 # truncate line and return +204 self._rbuffer = line[size:] +205 line = line[:size] +206 self._pos += len(line) +207 return line +208 n = size - len(line) +209 else: +210 n = self._bufsize +211 if ('\n' in line) or ((self._flags & self.FLAG_UNIVERSAL_NEWLINE) and ('\r' in line)): +212 break +213 try: +214 new_data = self._read(n) +215 except EOFError: +216 new_data = None +217 if (new_data is None) or (len(new_data) == 0): +218 self._rbuffer = '' +219 self._pos += len(line) +220 return line +221 line += new_data +222 self._realpos += len(new_data) +223 # find the newline +224 pos = line.find('\n') +225 if self._flags & self.FLAG_UNIVERSAL_NEWLINE: +226 rpos = line.find('\r') +227 if (rpos >= 0) and ((rpos < pos) or (pos < 0)): +228 pos = rpos +229 xpos = pos + 1 +230 if (line[pos] == '\r') and (xpos < len(line)) and (line[xpos] == '\n'): +231 xpos += 1 +232 self._rbuffer = line[xpos:] +233 lf = line[pos:xpos] +234 line = line[:pos] + '\n' +235 if (len(self._rbuffer) == 0) and (lf == '\r'): +236 # we could read the line up to a '\r' and there could still be a +237 # '\n' following that we read next time. note that and eat it. +238 self._at_trailing_cr = True +239 else: +240 self._record_newline(lf) +241 self._pos += len(line) +242 return line +

243 +

244 - def readlines(self, sizehint=None): +

245 """ +246 Read all remaining lines using L{readline} and return them as a list. +247 If the optional C{sizehint} argument is present, instead of reading up +248 to EOF, whole lines totalling approximately sizehint bytes (possibly +249 after rounding up to an internal buffer size) are read. +250 +251 @param sizehint: desired maximum number of bytes to read. +252 @type sizehint: int +253 @return: list of lines read from the file. +254 @rtype: list +255 """ +256 lines = [] +257 bytes = 0 +258 while True: +259 line = self.readline() +260 if len(line) == 0: +261 break +262 lines.append(line) +263 bytes += len(line) +264 if (sizehint is not None) and (bytes >= sizehint): +265 break +266 return lines +

267 +

268 - def seek(self, offset, whence=0): +

269 """ +270 Set the file's current position, like stdio's C{fseek}. Not all file +271 objects support seeking. +272 +273 @note: If a file is opened in append mode (C{'a'} or C{'a+'}), any seek +274 operations will be undone at the next write (as the file position +275 will move back to the end of the file). +276 +277 @param offset: position to move to within the file, relative to +278 C{whence}. +279 @type offset: int +280 @param whence: type of movement: 0 = absolute; 1 = relative to the +281 current position; 2 = relative to the end of the file. +282 @type whence: int +283 +284 @raise IOError: if the file doesn't support random access. +285 """ +286 raise IOError('File does not support seeking.') +

287 +

288 - def tell(self): +

289 """ +290 Return the file's current position. This may not be accurate or +291 useful if the underlying file doesn't support random access, or was +292 opened in append mode. +293 +294 @return: file position (in bytes). +295 @rtype: int +296 """ +297 return self._pos +

298 +

299 - def write(self, data): +

300 """ +301 Write data to the file. If write buffering is on (C{bufsize} was +302 specified and non-zero), some or all of the data may not actually be +303 written yet. (Use L{flush} or L{close} to force buffered data to be +304 written out.) +305 +306 @param data: data to write. +307 @type data: str +308 """ +309 if self._closed: +310 raise IOError('File is closed') +311 if not (self._flags & self.FLAG_WRITE): +312 raise IOError('File not open for writing') +313 if not (self._flags & self.FLAG_BUFFERED): +314 self._write_all(data) +315 return +316 self._wbuffer.write(data) +317 if self._flags & self.FLAG_LINE_BUFFERED: +318 # only scan the new data for linefeed, to avoid wasting time. +319 last_newline_pos = data.rfind('\n') +320 if last_newline_pos >= 0: +321 wbuf = self._wbuffer.getvalue() +322 last_newline_pos += len(wbuf) - len(data) +323 self._write_all(wbuf[:last_newline_pos + 1]) +324 self._wbuffer = StringIO() +325 self._wbuffer.write(wbuf[last_newline_pos + 1:]) +326 return +327 # even if we're line buffering, if the buffer has grown past the +328 # buffer size, force a flush. +329 if self._wbuffer.tell() >= self._bufsize: +330 self.flush() +331 return +

332 +

333 - def writelines(self, sequence): +

334 """ +335 Write a sequence of strings to the file. The sequence can be any +336 iterable object producing strings, typically a list of strings. (The +337 name is intended to match L{readlines}; C{writelines} does not add line +338 separators.) +339 +340 @param sequence: an iterable sequence of strings. +341 @type sequence: sequence +342 """ +343 for line in sequence: +344 self.write(line) +345 return +

346 +

347 - def xreadlines(self): +

348 """ +349 Identical to C{iter(f)}. This is a deprecated file interface that +350 predates python iterator support. +351 +352 @return: an iterator. +353 @rtype: iterator +354 """ +355 return self +

356 +357 +358 ### overrides... +359 +360 +

361 - def _read(self, size): +

362 """ +363 I{(subclass override)} +364 Read data from the stream. Return C{None} or raise C{EOFError} to +365 indicate EOF. +366 """ +367 raise EOFError() +

368 +

369 - def _write(self, data): +

370 """ +371 I{(subclass override)} +372 Write data into the stream. +373 """ +374 raise IOError('write not implemented') +

375 +

376 - def _get_size(self): +

377 """ +378 I{(subclass override)} +379 Return the size of the file. This is called from within L{_set_mode} +380 if the file is opened in append mode, so the file position can be +381 tracked and L{seek} and L{tell} will work correctly. If the file is +382 a stream that can't be randomly accessed, you don't need to override +383 this method, +384 """ +385 return 0 +

386 +387 +388 ### internals... +389 +390 +

391 - def _set_mode(self, mode='r', bufsize=-1): +

392 """ +393 Subclasses call this method to initialize the BufferedFile. +394 """ +395 # set bufsize in any event, because it's used for readline(). +396 self._bufsize = self._DEFAULT_BUFSIZE +397 if bufsize < 0: +398 # do no buffering by default, because otherwise writes will get +399 # buffered in a way that will probably confuse people. +400 bufsize = 0 +401 if bufsize == 1: +402 # apparently, line buffering only affects writes. reads are only +403 # buffered if you call readline (directly or indirectly: iterating +404 # over a file will indirectly call readline). +405 self._flags |= self.FLAG_BUFFERED | self.FLAG_LINE_BUFFERED +406 elif bufsize > 1: +407 self._bufsize = bufsize +408 self._flags |= self.FLAG_BUFFERED +409 self._flags &= ~self.FLAG_LINE_BUFFERED +410 elif bufsize == 0: +411 # unbuffered +412 self._flags &= ~(self.FLAG_BUFFERED | self.FLAG_LINE_BUFFERED) +413 +414 if ('r' in mode) or ('+' in mode): +415 self._flags |= self.FLAG_READ +416 if ('w' in mode) or ('+' in mode): +417 self._flags |= self.FLAG_WRITE +418 if ('a' in mode): +419 self._flags |= self.FLAG_WRITE | self.FLAG_APPEND +420 self._size = self._get_size() +421 self._pos = self._realpos = self._size +422 if ('b' in mode): +423 self._flags |= self.FLAG_BINARY +424 if ('U' in mode): +425 self._flags |= self.FLAG_UNIVERSAL_NEWLINE +426 # built-in file objects have this attribute to store which kinds of +427 # line terminations they've seen: +428 # <http://www.python.org/doc/current/lib/built-in-funcs.html> +429 self.newlines = None +

430 +

431 - def _write_all(self, data): +

432 # the underlying stream may be something that does partial writes (like +433 # a socket). +434 while len(data) > 0: +435 count = self._write(data) +436 data = data[count:] +437 if self._flags & self.FLAG_APPEND: +438 self._size += count +439 self._pos = self._realpos = self._size +440 else: +441 self._pos += count +442 self._realpos += count +443 return None +

444 +

445 - def _record_newline(self, newline): +

446 # silliness about tracking what kinds of newlines we've seen. +447 # i don't understand why it can be None, a string, or a tuple, instead +448 # of just always being a tuple, but we'll emulate that behavior anyway. +449 if not (self._flags & self.FLAG_UNIVERSAL_NEWLINE): +450 return +451 if self.newlines is None: +452 self.newlines = newline +453 elif (type(self.newlines) is str) and (self.newlines != newline): +454 self.newlines = (self.newlines, newline) +455 elif newline not in self.newlines: +456 self.newlines += (newline,) +

Source Code for Module paramiko.file