# NiBabel

### Access a cacophony of neuro-imaging file formats

# `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 optional mtime argument is the timestamp requested by gzip. The time is in Unix format, i.e., seconds since 00:00:00 UTC, January 1, 1970. If mtime is omitted or None, the current time is used. Use mtime = 0 to generate a compressed stream that does not depend on creation time.

  __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 optional mtime argument is the timestamp requested by gzip. The time is in Unix format, i.e., seconds since 00:00:00 UTC, January 1, 1970. If mtime is omitted or None, the current time is used. Use mtime = 0 to generate a compressed stream that does not depend on creation time.

## `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:
    fileish str or file-like

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

    *args positional 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`.

    **kwargs keyword 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'))