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:

filenamestr or os.PathLike

filename in which to search for type extensions

types_extssequence of sequences

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

trailing_suffixessequence of strings

suffixes that should be ignored when looking for extensions

match_casebool, optional

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

Returns:

pthstr

path with any matching extensions or trailing suffixes removed

extstr

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

trailingstr

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

guessed_typestr

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:

filenamestr or os.PathLike

filename that may end in any or none of addexts

match_casebool, optional

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

Returns:

frootstr

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

extstr

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

addextstr

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_fnamestr 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_extssequence of sequences

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

trailing_suffixessequence 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_casebool, optional

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

Returns:

types_fnamesdict

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