Builder¶
Objects to manage builds
- class disseminate.builders.builder.Builder(env, target=None, parameters=None, outfilepath=None, use_cache=None, use_media=None, **kwargs)¶
A build for an output file.
- Parameters
- env: :obj:`.builders.Environment`
The build environment
- parameters, argsTuple[
pathlib.Path, str, tuple, list] The input parameters (dependencies), including filepaths, for the build
- outfilepathOptional[
pathlib.Path] If specified, the path for the output file. If not specified, an outfilepath will be automatically generated.
- use_cacheOptional[bool]
If True, set the builder outfilepath into the cache_path from the builder environment. Note that this will also place temporary files created by the builder in the same directory.
- use_mediaOptional[bool]
If True, set the builder outfilepath subpath in the media_path in the build environment context, if specified.
- Attributes
- actionstr
The command to execute during the build.
- availablebool
Whether this builder is available to factory methods (find_builder_cls)
- active_requirementsUnion[tuple, bool]
If False, the builder will be inactive If a tuple of strings is specified, these conditions will be tested to see if the builder is active:
‘priority’: test that the priority attribute is an int
- ‘required_execs’: tests that the required_execs attribute is
specified
‘all_execs’: tests that the required execs are available
- decision
builders.deciders.decider.decision The decision object for the build, instantiate from environment’s decider, to evaluate whether a build is needed.
- scan_parameters_on_initbool
If True (default), scan the parameters for additional dependencies during the __init__.
- priorityint
If multiple viable builders are available, use the one with the highest priority.
- required_execsTuple[str]
A list of external executables that are needed by the builder.
- infilepath_extstr
The format extension for the input parameters (ex: ‘.pdf’, ‘.render’)
- outfilepath_extstr
The format extension for the output file (ex: ‘.svg’)
- outfilepath_appendstr
For automatically generated outfilepaths, the following string will be appended to the name of the file. ex: ‘_scale’
- targetOptional[str]
If specified, use the given document target for the build. This is used in formatting the TargetPath. ex: ‘html’ target will store built files in the ‘html/’ subdirectory.
- parameters_from_signalsOptional[List[str]]
A list of optional signal names to receive extra parameter dependencies.
- futureUnion[
concurrent.futures.Future, None, str] The future object for the process for the externally run program. The future can also be None, if a process hasn’t been run.
- classmethod active()¶
True if a builder is active
- build(complete=False)¶
Run the build.
- Parameters
- completeOptional[bool]
If True, run the build until it has completed If False, start the build in the background.
- Returns
- statusstr
The current status of the build.
Note
This function will run the sub-builders.
Each builder is atomic
When running a build, not all of the builders might be called in the first build–for example, subsequent builders may rely on the results of previous builds. For this reason, builders should be used in conjunction with an environment to make sure a set of builds are completed or the build complete=True should be used.
- build_needed(reset=False)¶
Decide whether a build is needed
- classmethod find_builder_cls(in_ext, out_ext=None, target=None, raise_error=True)¶
Factory method to return a builder class
- Parameters
- in_ext: str
The extension for the input file.
- out_extstr
The extension for the output file.
- targetOptional[str]
The document target. ex: ‘.html’ or ‘.pdf’
- raise_errorOptional[bool]
If True (default), raise an exception if a builder class couldn’t be found.
- get_parameter(name, *parameters)¶
Return parameters inserted as 2-ples of name/value.
- Parameters
- name
The name of the 2-ple parameter (the 1st 2-ple item)
- *parameters
If specified, use these parameters to get the specified parameter. Otherwise, the builder’s parameters will be used.
- Returns
- value
The corresponding 2-ple value (the 2nd 2-ple item)
- get_parameters_from_signals(sort=True)¶
Retrieve additional parameters from emitted signals specified in the parameters_from_signals list attribute.
- property infilepaths¶
Retrieve the parameters that are filepaths (
pathlib.Path).
- property missing_parameters¶
Returns True if there are no parameters or there are missing parameters.
This function will check the parameters until the parameters are all found, in which case, it will just return False.
- property not_infilepaths¶
Retrieve the parameters that are not filepaths (
pathlib.Path)
- property outfilepath¶
The output filename and path
- property parameters¶
The list of input parameters, including filepaths, needed for the build
- run_cmd(*args)¶
If the action is a external command, run it.
- run_cmd_args()¶
Format the action, if it’s a string.
- Returns
- run_cmd_argsTuple[str]
A tuple of the arguments to run in a process.
- static runtime_error(future, error_msg=None, raise_error=True)¶
Raise an error from a future working with subprocess
- static runtime_success(future)¶
Test whether a future from a subprocess is successful.
- scan_parameters()¶
Use the environment scanners to find additional dependencies in files specified by filepaths in the parameters.
- property status¶
The status of the builder.
- The builder can have the following states:
‘ready’: The builder is active and the parameters have been set
‘inactive’: The builder isn’t active–see the active property
‘missing (parameters)’: All the required parameters have not been specified or files for paths in the parameters do not exist
‘missing (outfilepath)’: The outfilepath was not created
‘cancelled’ : The build was cancelled.
‘building’: The builder is building
‘done’: The builder is done building