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__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

parse_filename

nibabel.filename_parser.parse_filename(filename, types_exts, trailing_suffixes, match_case=False)

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

Parameters:

filename : str

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, addexts=('.gz', '.bz2'), match_case=False)

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

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

Parameters:

filename : str

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 occuring 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, types_exts, trailing_suffixes=('.gz', '.bz2'), enforce_extensions=True, match_case=False)

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

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