# NiBabel

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

# `filename_parser`

Create filename pairs, triplets etc, with expected extensions

`TypesFilenamesError` |
`parse_filename`(filename, types_exts, ...[, ...]) | Split filename into fileroot, extension, trailing suffix; guess type.
`splitext_addext`(filename[, addexts, match_case]) | Split `/pth/fname.ext.gz` into `/pth/fname, .ext, .gz`
`types_filenames`(template_fname, types_exts) | Return filenames with standard extensions from template name

## `TypesFilenamesError`

class nibabel.filename_parser.TypesFilenamesError

  Bases: `Exception`

  __init__(*args, **kwargs)

## parse_filename

nibabel.filename_parser.parse_filename(filename: FileSpec, types_exts: ty.Sequence[ExtensionSpec], trailing_suffixes: ty.Sequence[str], match_case: bool = False) → tuple[str, str, str | None, str | None]

  Split filename into fileroot, extension, trailing suffix; guess type.

  Parameters:
    filename str or os.PathLike

      filename in which to search for type extensions

    types_exts sequence of sequences

      sequence of (name, extension) str sequences defining type to extension mapping.

    trailing_suffixes sequence of strings

      suffixes that should be ignored when looking for extensions

    match_case bool, optional

      If True, match case of extensions and trailing suffixes when searching in filename, otherwise do case-insensitive match.

  Returns:
    pth str

      path with any matching extensions or trailing suffixes removed

    ext str

      If there were any matching extensions, in types_exts return that; otherwise return extension derived from `os.path.splitext`.

    trailing str

      If there were any matching trailing_suffixes return that matching suffix, otherwise ‘’

    guessed_type str

      If we found a matching extension in types_exts return the corresponding `type`

  Examples

      >>> types_exts = (('t1', 'ext1'),('t2', 'ext2'))
      >>> parse_filename('/path/fname.funny', types_exts, ())
      ('/path/fname', '.funny', None, None)
      >>> parse_filename('/path/fnameext2', types_exts, ())
      ('/path/fname', 'ext2', None, 't2')
      >>> parse_filename('/path/fnameext2', types_exts, ('.gz',))
      ('/path/fname', 'ext2', None, 't2')
      >>> parse_filename('/path/fnameext2.gz', types_exts, ('.gz',))
      ('/path/fname', 'ext2', '.gz', 't2')

## splitext_addext

nibabel.filename_parser.splitext_addext(filename: FileSpec, addexts: ty.Sequence[str] = ('.gz', '.bz2', '.zst'), match_case: bool = False) → tuple[str, str, str]

  Split `/pth/fname.ext.gz` into `/pth/fname, .ext, .gz`

  where `.gz` may be any of passed addext trailing suffixes.

  Parameters:
    filename str or os.PathLike

      filename that may end in any or none of addexts

    match_case bool, optional

      If True, match case of addexts and filename, otherwise do case-insensitive match.

  Returns:
    froot str

      Root of filename - e.g. `/pth/fname` in example above

    ext str

      Extension, where extension is not in addexts - e.g. `.ext` in example above

    addext str

      Any suffixes appearing in addext occurring at end of filename

  Examples

      >>> splitext_addext('fname.ext.gz')
      ('fname', '.ext', '.gz')
      >>> splitext_addext('fname.ext')
      ('fname', '.ext', '')
      >>> splitext_addext('fname.ext.foo', ('.foo', '.bar'))
      ('fname', '.ext', '.foo')

## types_filenames

nibabel.filename_parser.types_filenames(template_fname: FileSpec, types_exts: ty.Sequence[ExtensionSpec], trailing_suffixes: ty.Sequence[str] = ('.gz', '.bz2'), enforce_extensions: bool = True, match_case: bool = False) → dict[str, str]

  Return filenames with standard extensions from template name

  The typical case is returning image and header filenames for an Analyze image, that expects an ‘image’ file type with extension `.img`, and a ‘header’ file type, with extension `.hdr`.

  Parameters:
    template_fname str or os.PathLike

      template filename from which to construct output dict of filenames, with given types_exts type to extension mapping. If `self.enforce_extensions` is True, then filename must have one of the defined extensions from the types list. If `self.enforce_extensions` is False, then the other filenames are guessed at by adding extensions to the base filename. Ignored suffixes (from trailing_suffixes) append themselves to the end of all the filenames.

    types_exts sequence of sequences

      sequence of (name, extension) str sequences defining type to extension mapping.

    trailing_suffixes sequence of strings, optional

      suffixes that should be ignored when looking for extensions - default is `('.gz', '.bz2')`

    enforce_extensions{True, False}, optional

      If True, raise an error when attempting to set value to type which has the wrong extension

    match_case bool, optional

      If True, match case of extensions and trailing suffixes when searching in template_fname, otherwise do case-insensitive match.

  Returns:
    types_fnames dict

      dict with types as keys, and generated filenames as values. The types are given by the first elements of the tuples in types_exts.

  Examples

      >>> types_exts = (('t1','.ext1'),('t2', '.ext2'))
      >>> tfns = types_filenames('/path/test.ext1', types_exts)
      >>> tfns == {'t1': '/path/test.ext1', 't2': '/path/test.ext2'}
      True

  Bare file roots without extensions get them added

      >>> tfns = types_filenames('/path/test', types_exts)
      >>> tfns == {'t1': '/path/test.ext1', 't2': '/path/test.ext2'}
      True

  With enforce_extensions == False, allow first type to have any extension.

      >>> tfns = types_filenames('/path/test.funny', types_exts,
      ...                        enforce_extensions=False)
      >>> tfns == {'t1': '/path/test.funny', 't2': '/path/test.ext2'}
      True