fab.artefacts#

This module contains Artefacts Getter classes which return Artefact Collections from the Artefact Store.

These classes are used by the run method of Step classes to retrieve the artefacts which need to be processed. Most steps have sensible defaults and can be configured with user-defined getters.

Classes

`ArtefactSet`(value)	A simple enum with the artefact types used internally in Fab.
`ArtefactStore`()	This object stores sets of artefacts (which can be of any type).
`ArtefactsGetter`()	Abstract base class for artefact getters.
`CollectionConcat`(collections)	Returns a concatenated list from multiple Artefact Collections (each expected to be an iterable).
`CollectionGetter`(collection_name)	A simple artefact getter which returns one Artefact Collection from the artefact_store.
`FilterBuildTrees`(suffix)	Filter build trees by suffix.
`SuffixFilter`(collection_name, suffix)	Returns the file paths in a Artefact Collection (expected to be an iterable), filtered by suffix.

class fab.artefacts.ArtefactSet(value)#: A simple enum with the artefact types used internally in Fab.

class fab.artefacts.ArtefactStore#

This object stores sets of artefacts (which can be of any type). Each artefact is indexed by either an ArtefactSet enum, or a string.

The constructor calls reset, which will mean all the internal artefact categories are created.

reset()#: Clears the artefact store (but does not delete any files).

add(collection, files)#: Adds the specified artefacts to a collection. The artefact can be specified as a simple string, a list of string or a set, in which case all individual entries of the list/set will be added. :type collection: Union[str, ArtefactSet] :param collection: the name of the collection to add this to. :type files: Union[Path, str, Iterable[Path], Iterable[str]] :param files: the artefacts to add.

update_dict(collection, key, values)#: For ArtefactSets that are a dictionary of sets: update the set with the specified values. :type collection: Union[str, ArtefactSet] :param collection: the name of the collection to add this to. :type key: str :param key: the key in the dictionary to update. :type values: Union[str, Iterable] :param values: the values to update with.

copy_artefacts(source, dest, suffixes=None)#

Copies all artefacts from source to destination. If a suffix_fiter is specified, only files with the given suffix will be copied.

Parameters:

source (Union[str, ArtefactSet]) – the source artefact set.
dest (Union[str, ArtefactSet]) – the destination artefact set.
suffixes (Union[str, List[str], None]) – a string or list of strings specifying the suffixes to copy. (default: None)

replace(artefact, remove_files, add_files)#

Replaces artefacts in one artefact set with other artefacts. This can be used e.g to replace files that have been preprocessed and renamed. There is no requirement for these lists to have the same number of elements, nor is there any check if an artefact to be removed is actually in the artefact set.

Parameters:

artefact (Union[str, ArtefactSet]) – the artefact set to modify.
remove_files (List[Union[Path, str]]) – files to remove from the artefact set.
add_files (Union[List[Union[Path, str]], dict]) – files to add to the artefact set.

class fab.artefacts.ArtefactsGetter#: Abstract base class for artefact getters.

class fab.artefacts.CollectionGetter(collection_name)#

A simple artefact getter which returns one Artefact Collection from the artefact_store.

Example:

`CollectionGetter('preprocessed_fortran')`

Parameters:: collection_name (Union[str, ArtefactSet]) – The name of the artefact collection to retrieve.

class fab.artefacts.CollectionConcat(collections)#

Returns a concatenated list from multiple Artefact Collections (each expected to be an iterable).

An ArtefactsGetter can be provided instead of a collection_name.

Example:

# The default source code getter for the Analyse step might look
# like this.
DEFAULT_SOURCE_GETTER = CollectionConcat([
    'preprocessed_c',
    'preprocessed_fortran',
    SuffixFilter(ArtefactSet.INITIAL_SOURCE, '.f90'),
])

Parameters:: collections (Iterable[Union[ArtefactSet, str, ArtefactsGetter]]) – An iterable containing collection names (strings) or other ArtefactsGetters.

class fab.artefacts.SuffixFilter(collection_name, suffix)#

Returns the file paths in a Artefact Collection (expected to be an iterable), filtered by suffix.

Example:

# The default source getter for the FortranPreProcessor step.
DEFAULT_SOURCE = SuffixFilter(ArtefactSet.INITIAL_SOURCE, '.F90')

Parameters:

collection_name (Union[str, ArtefactSet]) – The name of the artefact collection.
suffix (Union[str, List[str]]) – A suffix string including the dot, or iterable of.

class fab.artefacts.FilterBuildTrees(suffix)#

Filter build trees by suffix.

Example:

# The default source getter for the CompileFortran step.
DEFAULT_SOURCE_GETTER = FilterBuildTrees(suffix='.f90')

Returns:: one list of files to compile per build tree, of the form Dict[name, List[AnalysedDependent]]
Parameters:: suffix (Union[str, List[str]]) – A suffix string, or iterable of, including the preceding dot.