openers

Context manager openers for various fileobject types

DeterministicGzipFile([filename, mode, ...])	Deterministic variant of GzipFile
Fileish(*args, **kwargs)
ImageOpener(fileish, *args, **kwargs)	Opener-type class to collect extra compressed extensions
Opener(fileish, *args, **kwargs)	Class to accept, maybe open, and context-manage file-likes / filenames

DeterministicGzipFile

class nibabel.openers.DeterministicGzipFile(filename: str | None = None, mode: Mode | None = None, compresslevel: int = 9, fileobj: io.FileIO | None = None, mtime: int = 0)

Bases: GzipFile

Deterministic variant of GzipFile

This writer does not add filename information to the header, and defaults to a modification time (mtime) of 0 seconds.

Constructor for the GzipFile class.

At least one of fileobj and filename must be given a non-trivial value.

The new class instance is based on fileobj, which can be a regular file, an io.BytesIO object, or any other object which simulates a file. It defaults to None, in which case filename is opened to provide a file object.

When fileobj is not None, the filename argument is only used to be included in the gzip file header, which may include the original filename of the uncompressed file. It defaults to the filename of fileobj, if discernible; otherwise, it defaults to the empty string, and in this case the original filename is not included in the header.

The mode argument can be any of ‘r’, ‘rb’, ‘a’, ‘ab’, ‘w’, ‘wb’, ‘x’, or ‘xb’ depending on whether the file will be read or written. The default is the mode of fileobj if discernible; otherwise, the default is ‘rb’. A mode of ‘r’ is equivalent to one of ‘rb’, and similarly for ‘w’ and ‘wb’, ‘a’ and ‘ab’, and ‘x’ and ‘xb’.

The compresslevel argument is an integer from 0 to 9 controlling the level of compression; 1 is fastest and produces the least compression, and 9 is slowest and produces the most compression. 0 is no compression at all. The default is 9.

The mtime argument is an optional numeric timestamp to be written to the last modification time field in the stream when compressing. If omitted or None, the current time is used.

__init__(filename: str | None = None, mode: Mode | None = None, compresslevel: int = 9, fileobj: io.FileIO | None = None, mtime: int = 0)

Constructor for the GzipFile class.

At least one of fileobj and filename must be given a non-trivial value.

The new class instance is based on fileobj, which can be a regular file, an io.BytesIO object, or any other object which simulates a file. It defaults to None, in which case filename is opened to provide a file object.

When fileobj is not None, the filename argument is only used to be included in the gzip file header, which may include the original filename of the uncompressed file. It defaults to the filename of fileobj, if discernible; otherwise, it defaults to the empty string, and in this case the original filename is not included in the header.

The mode argument can be any of ‘r’, ‘rb’, ‘a’, ‘ab’, ‘w’, ‘wb’, ‘x’, or ‘xb’ depending on whether the file will be read or written. The default is the mode of fileobj if discernible; otherwise, the default is ‘rb’. A mode of ‘r’ is equivalent to one of ‘rb’, and similarly for ‘w’ and ‘wb’, ‘a’ and ‘ab’, and ‘x’ and ‘xb’.

The compresslevel argument is an integer from 0 to 9 controlling the level of compression; 1 is fastest and produces the least compression, and 9 is slowest and produces the most compression. 0 is no compression at all. The default is 9.

The mtime argument is an optional numeric timestamp to be written to the last modification time field in the stream when compressing. If omitted or None, the current time is used.

Fileish

class nibabel.openers.Fileish(*args, **kwargs)

Bases: Protocol

__init__(*args, **kwargs)

read(size: int = -1, /) → bytes

write(b: bytes, /) → int | None

ImageOpener

class nibabel.openers.ImageOpener(fileish: str | IOBase, *args, **kwargs)

Bases: Opener

Opener-type class to collect extra compressed extensions

A trivial sub-class of opener to which image classes can add extra extensions with custom openers, such as compressed openers.

To add an extension, add a line to the class definition (not __init__):

ImageOpener.compress_ext_map[ext] = func_def

ext is a file extension beginning with ‘.’ and should be included in the image class’s valid_exts tuple.

func_def is a (function, (args,)) tuple, where function accepts a filename as the first parameter, and `args defines the other arguments that function accepts. These arguments must be any (unordered) subset of mode, compresslevel, and buffering.

__init__(fileish: str | IOBase, *args, **kwargs)

compress_ext_map: dict[str | None, OpenerDef] = {'.bz2': (<class 'bz2.BZ2File'>, ('mode', 'buffering', 'compresslevel')), '.gz': (<function _gzip_open>, ('mode', 'compresslevel', 'mtime', 'keep_open')), '.mgz': (<function _gzip_open>, ('mode', 'compresslevel', 'mtime', 'keep_open')), '.zst': (<function _zstd_open>, ('mode', 'level_or_option', 'zstd_dict')), None: (<built-in function open>, ('mode', 'buffering'))}

Opener

class nibabel.openers.Opener(fileish: str | IOBase, *args, **kwargs)

Bases: object

Class to accept, maybe open, and context-manage file-likes / filenames

Provides context manager to close files that the constructor opened for you.

Parameters:

fileishstr or file-like

if str, then open with suitable opening method. If file-like, accept as is

*argspositional arguments

passed to opening method when fileish is str. mode, if not specified, is rb. compresslevel, if relevant, and not specified, is set from class variable default_compresslevel. keep_open, if relevant, and not specified, is False.

**kwargskeyword arguments

passed to opening method when fileish is str. Change of defaults as for *args

__init__(fileish: str | IOBase, *args, **kwargs)

bz2_def = (<class 'bz2.BZ2File'>, ('mode', 'buffering', 'compresslevel'))

close() → None

close_if_mine() → None

Close self.fobj iff we opened it in the constructor

property closed: bool

compress_ext_icase: bool = True

whether to ignore case looking for compression extensions

compress_ext_map: dict[str | None, OpenerDef] = {'.bz2': (<class 'bz2.BZ2File'>, ('mode', 'buffering', 'compresslevel')), '.gz': (<function _gzip_open>, ('mode', 'compresslevel', 'mtime', 'keep_open')), '.zst': (<function _zstd_open>, ('mode', 'level_or_option', 'zstd_dict')), None: (<built-in function open>, ('mode', 'buffering'))}

default_compresslevel = 1

default compression level when writing gz and bz2 files

default_level_or_option = {'r': None, 'rb': None, 'w': 3, 'wb': 3}

default_zst_compresslevel = 3

default option for zst files

fileno() → int

fobj: io.IOBase

gz_def = (<function _gzip_open>, ('mode', 'compresslevel', 'mtime', 'keep_open'))

property mode: str

property name: str | None

Return self.fobj.name or self._name if not present

self._name will be None if object was created with a fileobj, otherwise it will be the filename.

read(size: int = -1, /) → bytes

readinto(buffer: WriteableBuffer, /) → int | None

seek(pos: int, whence: int = 0, /) → int

tell() → int

write(b: bytes, /) → int | None

zstd_def = (<function _zstd_open>, ('mode', 'level_or_option', 'zstd_dict'))