fsl.utils.filetree.utils

class fsl.utils.filetree.utils.Part

Bases: object

Individual part of a template

3 subclasses are defined:

• Literal: piece of text

• Required: required variable to fill in (between curly brackets)

• Optional: part of text containing optional variables (between square brackets)

fill_known(variables) → Sequence[Part]

Fills in the given variables

optional_variables() → Set[Part]

Returns all variables in optional parts

required_variables() → Set[Part]

Returns all required variables

contains_optionals(variables: Set[Part] | None = None)

Returns True if this part contains the optional variables

append_variables(variables: List[str])

Appends the variables in this part to the provided list in order

__dict__ = mappingproxy({'__module__': 'fsl.utils.filetree.utils', '__doc__': '\n    Individual part of a template\n\n    3 subclasses are defined:\n\n    - :class:`Literal`: piece of text\n    - :class:`Required`: required variable to fill in (between curly brackets)\n    - :class:`Optional`: part of text containing optional variables (between square brackets)\n    ', 'fill_known': <function Part.fill_known>, 'optional_variables': <function Part.optional_variables>, 'required_variables': <function Part.required_variables>, 'contains_optionals': <function Part.contains_optionals>, 'append_variables': <function Part.append_variables>, '__dict__': <attribute '__dict__' of 'Part' objects>, '__weakref__': <attribute '__weakref__' of 'Part' objects>, '__annotations__': {}})

__module__ = 'fsl.utils.filetree.utils'

__weakref__

list of weak references to the object (if defined)

class fsl.utils.filetree.utils.Literal(text: str)

Bases: Part

__init__(text: str)

Literal part is defined purely by the text it contains

Parameters:

text – part of the template

__str__()

Returns this part of the template as a string

__annotations__ = {}

__module__ = 'fsl.utils.filetree.utils'

class fsl.utils.filetree.utils.Required(var_name, var_formatting=None)

Bases: Part

__init__(var_name, var_formatting=None)

Required part of template (between curly brackets)

Required variable part of template is defined by variable name and its format

Parameters:

• var_name – name of variable

• var_formatting – how to format the variable

__str__()

Returns this part of the template as a string

fill_known(variables)

Fills in the given variables

required_variables()

Returns all required variables

append_variables(variables)

Appends the variables in this part to the provided list in order

__annotations__ = {}

__module__ = 'fsl.utils.filetree.utils'

class fsl.utils.filetree.utils.Optional(sub_template: Template)

Bases: Part

__init__(sub_template: Template)

Optional part of template (between square brackets)

Optional part can contain literal and required parts

Parameters:

sub_template – part of the template within square brackets

__str__()

Return str(self).

fill_known(variables)

Fills in the given variables

optional_variables()

Returns all variables in optional parts

contains_optionals(variables=None)

Returns True if this part contains the optional variables

append_variables(variables)

Appends the variables in this part to the provided list in order

__annotations__ = {}

__module__ = 'fsl.utils.filetree.utils'

class fsl.utils.filetree.utils.Template(parts: Sequence[Part])

Bases: object

Splits a template into its constituent parts

__init__(parts: Sequence[Part])

classmethod parse(text: str) → Template

Parses a text template into its constituent parts

Parameters:

text – input template as string

Returns:

same template split into its parts

__str__()

Returns the template as a string

optional_variables() → Set[str]

Set of optional variables

required_variables() → Set[str]

Set of required variables

ordered_variables() → Tuple[str]

Sequence of all variables in order (can contain duplicates)

fill_known(variables) → Template

Fill in the known variables

Any optional parts, where all variables have been filled will be automatically replaced

_fill_known_single(variables)

Helper method for _fill_known()

remove_optionals(optionals=None) → Template

Removes any optionals containing the provided variables (default: remove all)

resolve(variables) → str

Resolves the template given a set of variables

Parameters:

variables – mapping of variable names to values

Returns:

cleaned string

get_all(variables, glob_vars=()) → Tuple[Dict[str, str]]

Gets all variables for files on disk matching the templates

Parameters:

• variables – (incomplete) mapping of variable names to values

• glob_vars – sequence of undefined variables that can take any possible values when looking for matches on the disk

_get_all_helper(glob_vars)

optional_subsets() → Iterator[Template]

Yields template sub-sets with every combination optional variables

extract_variables(filename, known_vars=None)

Extracts the variable values from the filename

Parameters:

• filename – filename

• known_vars – already known variables

Returns:

dictionary from variable names to string representations (unused variables set to None)

__dict__ = mappingproxy({'__module__': 'fsl.utils.filetree.utils', '__doc__': '\n    Splits a template into its constituent parts\n    ', '__init__': <function Template.__init__>, 'parse': <classmethod(<function Template.parse>)>, '__str__': <function Template.__str__>, 'optional_variables': <function Template.optional_variables>, 'required_variables': <function Template.required_variables>, 'ordered_variables': <function Template.ordered_variables>, 'fill_known': <function Template.fill_known>, '_fill_known_single': <function Template._fill_known_single>, 'remove_optionals': <function Template.remove_optionals>, 'resolve': <function Template.resolve>, 'get_all': <function Template.get_all>, '_get_all_helper': <function Template._get_all_helper>, 'optional_subsets': <function Template.optional_subsets>, 'extract_variables': <function Template.extract_variables>, '__dict__': <attribute '__dict__' of 'Template' objects>, '__weakref__': <attribute '__weakref__' of 'Template' objects>, '__annotations__': {}})

__module__ = 'fsl.utils.filetree.utils'

__weakref__

list of weak references to the object (if defined)

fsl.utils.filetree.utils.resolve(template, variables)

Resolves the template given a set of variables

Parameters:

• template – template

• variables – mapping of variable names to values

Returns:

cleaned string

fsl.utils.filetree.utils.get_all(template, variables, glob_vars=())

Gets all variables matching the templates given the variables

Parameters:

• template – template

• variables – (incomplete) mapping of variable names to values

• 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:

sequence of variables

fsl.utils.filetree.utils.find_variables(template)

Finds all the variables in the template

Parameters:

template – full template

Returns:

sequence of variables

fsl.utils.filetree.utils.optional_variables(template)

Finds the variables that can be skipped

Parameters:

template – full template

Returns:

set of variables that are only present in optional parts of the string

fsl.utils.filetree.utils.extract_variables(template, filename, known_vars=None)

Extracts the variable values from the filename

Parameters:

• template – template matching the given filename

• filename – filename

• known_vars – already known variables

Returns:

dictionary from variable names to string representations (unused variables set to None)