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
(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
-
__init__
(templates: Dict[str, str], variables: Dict[str, Any], sub_trees: Dict[str, FileTree] = None, parent: Optional[FileTree] = None, name: str = None)[source]¶ Creates a new filename tree.
-
parent
¶ Parent FileTree, of which this sub-tree is a sub-directory
-
name
¶ Name of this
FileTree
, orNone
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
(short_name: str) → Tuple[fsl.utils.filetree.filetree.FileTree, str][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: 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: 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
(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)
-
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 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)
- variables – variable settings
Returns: dictionary from specifier to filename
- tree_name – file containing the filename tree.
Can provide the filename of a tree file or the name for a tree in the
-
__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