fsl.utils.filetree.filetree

exception fsl.utils.filetree.filetree.MissingVariable[source]

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[source]

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__()[source]

Creates a new filename tree.

parent

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

name

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

all_variables

All tree variables including those inherited from the parent tree

get_variable(name: str, default=None) → str[source]

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()[source]

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]][source]

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: Union[str, NoneType] = None, optional=True, required=True) → Set[str][source]

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[source]

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][source]

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:

sorted sequence of paths

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

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()[source]

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) → fsl.utils.filetree.filetree.FileTree[source]

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][source]

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)[source]

Saves the Filetree to a pickle file

Parameters:filename – filename to store the file tree (usually ending with .pck)
classmethod load_pickle(filename)[source]

Loads the Filetree from a pickle file

Parameters:filename – filename produced from Filetree.save
Returns:stored Filetree
defines(short_names, error=False)[source]

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=())[source]

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
classmethod read(tree_name: str, directory='.', **variables) → fsl.utils.filetree.filetree.FileTree[source]

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)
  • 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>, 'load_pickle': <classmethod object>, 'defines': <function FileTree.defines>, 'on_disk': <function FileTree.on_disk>, 'read': <classmethod object>, '__dict__': <attribute '__dict__' of 'FileTree' objects>, '__weakref__': <attribute '__weakref__' of 'FileTree' objects>})
__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)[source]

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[source]

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