fsl.utils.filetree.filetree

exception fsl.utils.filetree.filetree.MissingVariable

Bases: KeyError

Returned when the variables of a tree or its parents do not contain a given variable

__module__ = 'fsl.utils.filetree.filetree'

__weakref__

list of weak references to the object (if defined)

class fsl.utils.filetree.filetree.FileTree(templates: Dict[str, str], variables: Dict[str, Any], sub_trees: Dict[str, FileTree] | None = None, parent: FileTree | None = None, name: str | None = None)

Bases: object

Contains the input/output filename tree

Properties:

• templates: dictionary mapping short names to filename templates

• variables: dictionary mapping variables in the templates to specific values (variables set to None are explicitly unset)

• sub_trees: filename trees describing specific sub-directories

• parent: parent FileTree, of which this sub-tree is a sub-directory

• name: descriptive name of the tree

__init__(templates: Dict[str, str], variables: Dict[str, Any], sub_trees: Dict[str, FileTree] | None = None, parent: FileTree | None = None, name: str | None = None)

Creates a new filename tree.

property parent

Parent FileTree, of which this sub-tree is a sub-directory

property name

Name of this FileTree, or None if it has no name.

property all_variables

All tree variables including those inherited from the parent tree

get_variable(name: str, default=None) → str

Gets a variable used to fill out the template

Parameters:

• name – variable name

• default – default variables (if not set a MissingVariable error is raised if a variable is missing)

Returns:

value of the variable

_get_template_tree(short_name: str) → Tuple[FileTree, str]

Retrieves template text from this tree, parent tree or sub_tree

Parameters:

short_name – filename reference name

Returns:

tuple with the containing tree and the template text

get_template(short_name: str) → Tuple[str, Dict[str, str]]

Returns the sub-tree that defines a given short name

• ‘/’ characters in short_name refer to sub-trees

• ‘../’ characters in short_name refer to parents

For example:

• “eddy/output” refers to the “output” in the “eddy” sub_tree (i.e. self.sub_trees['eddy'].templates['output'])

• “../other/name” refers to the “other” sub-tree of the parent tree (i.e., self.parent.sub_trees['other'].templates['name'])

Parameters:

short_name – name of the template

Returns:

tuple with the template and the variables corresponding to the template

template_variables(short_name: str | None = None, optional=True, required=True) → Set[str]

Returns the variables needed to define a template

Parameters:

• short_name – name of the template (defaults to all)

• optional – if set to False don’t include the optional variables

• required – if set to False don’t include the required variables

Returns:

set of variable names

get(short_name, make_dir=False) → str

Gets a full filename based on its short name

Parameters:

• short_name – identifier in the tree

• make_dir – if True make sure that the directory leading to this file exists

Returns:

full filename

get_all(short_name: str, glob_vars=()) → Tuple[str]

Gets all existing directory/file names matching a specific pattern

Parameters:

• short_name – short name of the path template

• glob_vars – sequence of undefined variables that can take any possible values when looking for matches on the disk. Any defined variables in glob_vars will be ignored. If glob_vars is set to ‘all’, all undefined variables will be used to look up matches.

Returns:

sequence of paths

get_all_vars(short_name: str, glob_vars=()) → Tuple[Dict[str, str]]

Gets all the parameters that generate existing filenames

Parameters:

• short_name – short name of the path template

• glob_vars – sequence of undefined variables that can take any possible values when looking for matches on the disk. Any defined variables in glob_vars will be ignored. If glob_vars is set to ‘all’, all undefined variables will be used to look up matches.

Returns:

sequence of dictionaries with the variables settings used to generate each filename

get_all_trees(short_name: str, glob_vars=(), set_parent=True) → Tuple[FileTree]

Gets all the trees that generate the existing files matching the pattern

tree.get_all(short_name) == tuple(tree.get(short_name) for tree in tree.get_all_trees(short_name))

Parameters:

• short_name – short name of the path template

• glob_vars – sequence of undefined variables that can take any possible values when looking for matches on the disk. Any defined variables in glob_vars will be ignored. If glob_vars is set to ‘all’, all undefined variables will be used to look up matches.

• set_parent – Update the variables of the top-level rather than current tree if True. Ony relevant if self is a sub-tree.

Returns:

sequence of FileTrees used to generate each file on disk matching the pattern of short_name

update(set_parent=True, **variables) → FileTree

Creates a new FileTree with updated variables

Parameters:

• set_parent – Update the variables of the top-level rather than current tree if True. Ony relevant if self is a sub-tree.

• variables – new values for the variables Setting a variable to None will cause the variable to be unset

Returns:

New FileTree with same templates for directory names and filenames, but updated variables

extract_variables(short_name: str, filename: str) → Dict[str, str]

Extracts the variables from the given filename

Parameters:

• short_name – short name of the path template

• filename – filename matching the template

Returns:

variables needed to get to the given filename Variables with None value are optional variables in the template that were not used

save_pickle(filename)

Saves the Filetree to a pickle file

Parameters:

filename – filename to store the file tree (usually ending with .pck)

save_json(filename)

Saves the Filetree to a JSON file

Parameters:

filename – filename to store the file tree in

classmethod load_pickle(filename)

Loads the Filetree from a pickle file

Parameters:

filename – filename produced from Filetree.save_pickle

Returns:

stored Filetree

classmethod load_json(filename)

Loads the FileTree from a JSON file

Parameters:

filename – filename produced by FileTree.save_json

Returns:

stored FileTree

defines(short_names, error=False)

Checks whether templates are defined for all the short_names

Parameters:

• short_names – sequence of expected short names to exist in the tree

• error – if True raises ValueError if any short_names are undefined

Returns:

True if all are defined, False otherwise

Raise:

ValueError if error is set to True and any template is missing

on_disk(short_names, error=False, glob_vars=())

Checks whether at least one file exists for every file in short_names

Parameters:

• short_names – list of expected short names to exist in the tree

• error – if True raises a helpful error when the check fails

• glob_vars – sequence of undefined variables that can take any possible values when looking for matches on the disk If glob_vars contains any defined variables, it will be ignored.

Returns:

True if short names exist and optionally exist on disk (False otherwise)

Raise:

• ValueError if error is set and the tree is incomplete

• IOError if error is set and any files are missing from the disk

partial_fill() → FileTree

Fills in known variables into the templates

Returns:

The resulting tree will have empty variables dictionaries and updated templates

_update_partial_fill()

Helper function for partial_fill that updates the templates in place

copy()

Copies the FileTree

Copies the templates, variables, sub_trees, and parent

Returns:

a copy of the FileTree

_copy(new_parent=None, new_sub_tree=None)

Helper function for copying a FileTree

classmethod read(tree_name: str, directory='.', partial_fill=False, **variables) → FileTree

Reads a FileTree from a specific file

The return type is cls unless the tree_name has been previously registered. The return type of any sub-tree is FileTree unless the tree_name has been previously registered.

Parameters:

• tree_name – file containing the filename tree. Can provide the filename of a tree file or the name for a tree in the filetree.tree_directories.

• directory – parent directory of the full tree (defaults to current directory)

• partial_fill – By default any known variables are filled into the template immediately

• variables – variable settings

Returns:

dictionary from specifier to filename

__dict__ = mappingproxy({'__module__': 'fsl.utils.filetree.filetree', '__doc__': '\n    Contains the input/output filename tree\n\n    Properties:\n\n    - ``templates``: dictionary mapping short names to filename templates\n    - ``variables``: dictionary mapping variables in the templates to specific values (variables set to None are explicitly unset)\n    - ``sub_trees``: filename trees describing specific sub-directories\n    - ``parent``: parent FileTree, of which this sub-tree is a sub-directory\n    - ``name``: descriptive name of the tree\n    ', '__init__': <function FileTree.__init__>, 'parent': <property object>, 'name': <property object>, 'all_variables': <property object>, 'get_variable': <function FileTree.get_variable>, '_get_template_tree': <function FileTree._get_template_tree>, 'get_template': <function FileTree.get_template>, 'template_variables': <function FileTree.template_variables>, 'get': <function FileTree.get>, 'get_all': <function FileTree.get_all>, 'get_all_vars': <function FileTree.get_all_vars>, 'get_all_trees': <function FileTree.get_all_trees>, 'update': <function FileTree.update>, 'extract_variables': <function FileTree.extract_variables>, 'save_pickle': <function FileTree.save_pickle>, 'save_json': <function FileTree.save_json>, 'load_pickle': <classmethod(<function FileTree.load_pickle>)>, 'load_json': <classmethod(<function FileTree.load_json>)>, 'defines': <function FileTree.defines>, 'on_disk': <function FileTree.on_disk>, 'partial_fill': <function FileTree.partial_fill>, '_update_partial_fill': <function FileTree._update_partial_fill>, 'copy': <function FileTree.copy>, '_copy': <function FileTree._copy>, 'read': <classmethod(<function FileTree.read>)>, '__dict__': <attribute '__dict__' of 'FileTree' objects>, '__weakref__': <attribute '__weakref__' of 'FileTree' objects>, '__annotations__': {}})

__module__ = 'fsl.utils.filetree.filetree'

__weakref__

list of weak references to the object (if defined)

fsl.utils.filetree.filetree.register_tree(name: str, tree_subtype: type)

Registers a tree_subtype under name

Loading a tree with given name will lead to the tree_subtype rather than FileTree to be returned

Parameters:

• name – name of tree filename

• tree_subtype – tree subtype

fsl.utils.filetree.filetree.get_registered(name, default=<class 'fsl.utils.filetree.filetree.FileTree'>) → type

Get the previously registered subtype for name

Parameters:

• name – name of the sub-tree

• default – type to return if the name has not been registered

Returns:

FileTree or sub-type thereof