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
-
class
fsl.utils.filetree.filetree.
FileTree
(templates: Dict[str, str], variables: Dict[str, Any], sub_trees: Dict[str, FileTree] = None, parent: Optional[FileTree] = None, name: str = None)[source]¶ Bases:
object
Contains the input/output filename tree
Properties:
templates
: dictionary mapping short names to filename templatesvariables
: dictionary mapping variables in the templates to specific values (variables set to None are explicitly unset)sub_trees
: filename trees describing specific sub-directoriesparent
: parent FileTree, of which this sub-tree is a sub-directoryname
: descriptive name of the tree
-
property
parent
¶ Parent FileTree, of which this sub-tree is a sub-directory
-
property
name
¶ Name of this
FileTree
, orNone
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[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
(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: Optional[str] = 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
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
(short_name: str, glob_vars=(), set_parent=True) → Tuple[fsl.utils.filetree.filetree.FileTree][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)
-
save_json
(filename)[source]¶ Saves the Filetree to a JSON file
- Parameters
filename – filename to store the file tree in
-
classmethod
load_pickle
(filename)[source]¶ Loads the Filetree from a pickle file
- Parameters
filename – filename produced from Filetree.save_pickle
- Returns
stored Filetree
-
classmethod
load_json
(filename)[source]¶ Loads the FileTree from a JSON file
- Parameters
filename – filename produced by FileTree.save_json
- 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
-
partial_fill
() → fsl.utils.filetree.filetree.FileTree[source]¶ Fills in known variables into the templates
- Returns
The resulting tree will have empty variables dictionaries and updated templates
-
classmethod
read
(tree_name: str, directory='.', partial_fill=False, **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 isFileTree
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
-
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