See also
- Purpose:
This variant of @transform allows additional inputs or dependencies to be added dynamically to the task.
Output file names and strings in the extra parameters are determined from tasks_or_file_names, i.e. from the output of up stream tasks, or a list of file names.
This variant of @transform allows input file names to be derived in the same way.
String replacement occurs either through suffix matches via suffix or the formatter or regex indicators.
@collate groups together all Input which result in identical Output and extra parameters.
It is a many to fewer operation.
add_inputs nests the the original input parameters in a list before adding additional dependencies.
inputs replaces the original input parameters wholescale.
Only out of date tasks (comparing input and output files) will be run
Example of add_inputs
A common task in compiling C code is to include the corresponding header file for the source.
- To compile *.c to *.o, adding *.h and the common header universal.h:
@transform(["1.c", "2.c"], suffix(".c"), add_inputs([r"\1.h", "universal.h"]), ".o") def compile(infile, outfile): pass- This will result in the following functional calls:
compile(["1.c", "1.h", "universal.h"], "1.o") compile(["2.c", "2.h", "universal.h"], "2.o")Example of inputs
inputs(...) allows the original input parameters to be replaced wholescale.
- This can be seen in the following example:
@transform([ ["1.c", "A.c", 2] ["2.c", "B.c", "C.c", 3]], suffix(".c"), inputs([r"\1.py", "docs.rst"]), ".pyc") def compile(infile, outfile): pass- This will result in the following functional calls:
compile(["1.py", "docs.rst"], "1.pyc") compile(["2.py", "docs.rst"], "2.pyc")Parameters:
- tasks_or_file_names
can be a:
- Task / list of tasks (as in the example above).
File names are taken from the output of the specified task(s)
- (Nested) list of file name strings.
- File names containing *[]? will be expanded as a glob.
E.g.:"a.*" => "a.1", "a.2"
- suffix_string
must be wrapped in a suffix indicator object. The end of each file name which matches suffix_string will be replaced by output_pattern. Thus:
@transform(["a.c", "b.c"], suffix(".c"), ".o") def compile(infile, outfile): passwill result in the following function calls:
compile("a.c", "a.o") compile("b.c", "b.o")File names which do not match suffix_string will be ignored
- matching_regex
is a python regular expression string, which must be wrapped in a regex indicator object See python regular expression (re) documentation for details of regular expression syntax Each output file name is created using regular expression substitution with output_pattern
- matching_formatter
a formatter indicator object containing optionally a python regular expression (re).
- input_pattern
Specifies the resulting input(s) to each job. Must be wrapped in an inputs or an inputs indicator object.
Can be a:
- Task / list of tasks (as in the example above).
File names are taken from the output of the specified task(s)
- (Nested) list of file name strings.
Strings will be subject to substitution. File names containing *[]? will be expanded as a glob. E.g.:"a.*" => "a.1", "a.2"
- output_pattern
Specifies the resulting output file name(s).
- [extra_parameters, ...]
Any extra parameters are passed to the task function.
If the regex(...) or formatter(...) parameter is used, then substitution is first applied to (even nested) string parameters. Other data types are passed verbatim.
For example:
@transform(["a.c", "b.c"], regex(r"(.*).c"), inputs(r"\1.c", r"\1.h", "universal.h"), r"\1.o", r"\1") def compile(infiles, outfile, file_name_root): # do something here passwill result in the following function calls:
compile(["1.c", "1.h", "universal.h"], "1.o", "1") compile(["2.c", "2.h", "universal.h"], "2.o", "2")
See here for more straightforward ways to use transform.