skbio.io.util.open¶

skbio.io.util.open(file, mode='r', encoding=None, errors=None, newline=None, compression='auto', compresslevel=9)[source]¶

Convert input into a filehandle.

State: Stable as of 0.4.0.

Supported inputs:

type	can read	can write	source type
file path	True	True	Binary
URL	True	False	Binary
`["lines list\n"]`	True	True	Text
`io.StringIO`	True	True	Text
`io.BytesIO`	True	True	Binary
`io.TextIOWrapper`	True	True	Text
`io.BufferedReader`	True	False	Binary
`io.BufferedWriter`	False	True	Binary
`io.BufferedRandom`	True	True	Binary
`tempfile.TemporaryFile()`	True	True	Binary
`tempfile.NamedTemporaryFile()`	True	True	Binary

Note

When reading a list of unicode (str) lines, the input for newline is used to determine the number of lines in the resulting file handle, not the number of elements in the list. This is to allow composition with file.readlines().

Parameters:

Parameters:	file : filepath, url, filehandle, list The input to convert to a filehandle. mode : {‘r’, ‘w’}, optional Whether to return a readable or writable file. Conversely, this does not imply that the returned file will be unwritable or unreadable. To get a binary filehandle set encoding to binary. encoding : str, optional The encoding scheme to use for the file. If set to ‘binary’, no bytes will be translated. Otherwise this matches the behavior of `io.open()`. errors : str, optional Specifies how encoding and decoding errors are to be handled. This has no effect when encoding is binary (as there can be no errors). Otherwise this matches the behavior of `io.open()`. newline : {None, “”, ‘\n’, ‘\r\n’, ‘\r’}, optional Matches the behavior of `io.open()`. compression : {‘auto’, ‘gzip’, ‘bz2’, None}, optional Will compress or decompress file depending on mode. If ‘auto’ then determining the compression of the file will be attempted and the result will be transparently decompressed. ‘auto’ will do nothing when writing. Other legal values will use their respective compression schemes. compression cannot be used with a text source. compresslevel : int (0-9 inclusive), optional The level of compression to use, will be passed to the appropriate compression handler. This is only used when writing.
Returns:	filehandle : io.TextIOBase or io.BufferedReader/Writer When encoding=’binary’ an `io.BufferedReader` or `io.BufferedWriter` will be returned depending on mode. Otherwise an implementation of `io.TextIOBase` will be returned. Note Any underlying resources needed to create filehandle are managed transparently. If file was closeable, garbage collection of filehandle will not close file. Calling close on filehandle will close file. Conversely calling close on file will cause filehandle to reflect a closed state. This does not mean that a `flush` has occured for `filehandle`, there may still have been data in its buffer! Additionally, resources may not have been cleaned up properly, so ALWAYS call `close` on `filehandle` and NOT on `file`.

file : filepath, url, filehandle, list

The input to convert to a filehandle.

mode : {‘r’, ‘w’}, optional

Whether to return a readable or writable file. Conversely, this does not imply that the returned file will be unwritable or unreadable. To get a binary filehandle set encoding to binary.

encoding : str, optional

The encoding scheme to use for the file. If set to ‘binary’, no bytes will be translated. Otherwise this matches the behavior of io.open().

errors : str, optional

Specifies how encoding and decoding errors are to be handled. This has no effect when encoding is binary (as there can be no errors). Otherwise this matches the behavior of io.open().

newline : {None, “”, ‘\n’, ‘\r\n’, ‘\r’}, optional

Matches the behavior of io.open().

compression : {‘auto’, ‘gzip’, ‘bz2’, None}, optional

Will compress or decompress file depending on mode. If ‘auto’ then determining the compression of the file will be attempted and the result will be transparently decompressed. ‘auto’ will do nothing when writing. Other legal values will use their respective compression schemes. compression cannot be used with a text source.

compresslevel : int (0-9 inclusive), optional

The level of compression to use, will be passed to the appropriate compression handler. This is only used when writing.

Returns:

filehandle : io.TextIOBase or io.BufferedReader/Writer

When encoding=’binary’ an io.BufferedReader or io.BufferedWriter will be returned depending on mode. Otherwise an implementation of io.TextIOBase will be returned.

Note

Any underlying resources needed to create filehandle are managed transparently. If file was closeable, garbage collection of filehandle will not close file. Calling close on filehandle will close file. Conversely calling close on file will cause filehandle to reflect a closed state. This does not mean that a `flush` has occured for `filehandle`, there may still have been data in its buffer! Additionally, resources may not have been cleaned up properly, so ALWAYS call `close` on `filehandle` and NOT on `file`.