Buffered files — Paramiko documentation

# Buffered files

class `paramiko.file.` `BufferedFile`

  Reusable base class to implement Python-style file buffering around a simpler stream.

  `__iter__`()

    Returns an iterator that can be used to iterate over the lines in this file. This iterator happens to return the file itself, since a file is its own iterator.

    Raises: | `ValueError` – if the file is closed.

  `close`()

    Close the file. Future read and write operations will fail.

  `flush`()

    Write out any data in the write buffer. This may do nothing if write buffering is not turned on.

  `next`()

    Returns the next line from the input, or raises `StopIteration` when EOF is hit. Unlike Python file objects, it’s okay to mix calls to `next` and `readline`.

    Raises: | `StopIteration` – when the end of the file is reached.
    Returns: | a line (`str`) read from the file.

  `read`(size=None)

    Read at most `size` bytes from the file (less if we hit the end of the file first). If the `size` argument is negative or omitted, read all the remaining data in the file.

    Note

    `'b'` mode flag is ignored (`self.FLAG_BINARY` in `self._flags`), because SSH treats all files as binary, since we have no idea what encoding the file is in, or even if the file is text data.

    Parameters: | size (int) – maximum number of bytes to read
    Returns: | data read from the file (as bytes), or an empty string if EOF was encountered immediately

  `readable`()

    Check if the file can be read from.

    Returns: | `True` if the file can be read from. If `False`, `read` will raise an exception.

  `readinto`(buff)

    Read up to `len(buff)` bytes into `bytearray` buff and return the number of bytes read.

    Returns: | The number of bytes read.

  `readline`(size=None)

    Read one entire line from the file. A trailing newline character is kept in the string (but may be absent when a file ends with an incomplete line). If the size argument is present and non-negative, it is a maximum byte count (including the trailing newline) and an incomplete line may be returned. An empty string is returned only when EOF is encountered immediately.

    Note

    Unlike stdio’s `fgets`, the returned string contains null characters (`'\0'`) if they occurred in the input.

    Parameters: | size (int) – maximum length of returned string.
    Returns: | next line of the file, or an empty string if the end of the file has been reached. If the file was opened in binary (`'b'`) mode: bytes are returned Else: the encoding of the file is assumed to be UTF-8 and character strings (`str`) are returned

  `readlines`(sizehint=None)

    Read all remaining lines using `readline` and return them as a list. If the optional `sizehint` argument is present, instead of reading up to EOF, whole lines totalling approximately sizehint bytes (possibly after rounding up to an internal buffer size) are read.

    Parameters: | sizehint (int) – desired maximum number of bytes to read.
    Returns: | list of lines read from the file.

  `seek`(offset, whence=0)

    Set the file’s current position, like stdio’s `fseek`. Not all file objects support seeking.

    Note

    If a file is opened in append mode (`'a'` or `'a+'`), any seek operations will be undone at the next write (as the file position will move back to the end of the file).

    Parameters: | offset (int) – position to move to within the file, relative to `whence`. whence (int) – type of movement: 0 = absolute; 1 = relative to the current position; 2 = relative to the end of the file.
    Raises: | `IOError` – if the file doesn’t support random access.

  `seekable`()

    Check if the file supports random access.

    Returns: | `True` if the file supports random access. If `False`, `seek` will raise an exception.

  `tell`()

    Return the file’s current position. This may not be accurate or useful if the underlying file doesn’t support random access, or was opened in append mode.

    Returns: | file position (`number` of bytes).

  `writable`()

    Check if the file can be written to.

    Returns: | `True` if the file can be written to. If `False`, `write` will raise an exception.

  `write`(data)

    Write data to the file. If write buffering is on (`bufsize` was specified and non-zero), some or all of the data may not actually be written yet. (Use `flush` or `close` to force buffered data to be written out.)

    Parameters: | data – `str`/`bytes` data to write

  `writelines`(sequence)

    Write a sequence of strings to the file. The sequence can be any iterable object producing strings, typically a list of strings. (The name is intended to match `readlines`; `writelines` does not add line separators.)

    Parameters: | sequence – an iterable sequence of strings.

  `xreadlines`()

    Identical to `iter(f)`. This is a deprecated file interface that predates Python iterator support.