SCons package

SCons package#

Module contents#

Subpackages#

Submodules#

SCons.Action module#

SCons Actions.

Information about executing any sort of action that can build one or more target Nodes (typically files) from one or more source Nodes (also typically files) given a specific Environment.

The base class here is ActionBase. The base class supplies just a few utility methods and some generic methods for displaying information about an Action in response to the various commands that control printing.

A second-level base class is _ActionAction. This extends ActionBase by providing the methods that can be used to show and perform an action. True Action objects will subclass _ActionAction; Action factory class objects will subclass ActionBase.

The heavy lifting is handled by subclasses for the different types of actions we might execute:

CommandAction CommandGeneratorAction FunctionAction ListAction

The subclasses supply the following public interface methods used by other modules:

__call__()
THE public interface, “calling” an Action object executes the command or Python function. This also takes care of printing a pre-substitution command for debugging purposes.

get_contents()
Fetches the “contents” of an Action for signature calculation plus the varlist. This is what gets checksummed to decide if a target needs to be rebuilt because its action changed.

genstring()
Returns a string representation of the Action without command substitution, but allows a CommandGeneratorAction to generate the right action based on the specified target, source and env. This is used by the Signature subsystem (through the Executor) to obtain an (imprecise) representation of the Action operation for informative purposes.

Subclasses also supply the following methods for internal use within this module:

__str__()
Returns a string approximation of the Action; no variable substitution is performed.

execute()
The internal method that really, truly, actually handles the execution of a command or Python function. This is used so that the __call__() methods can take care of displaying any pre-substitution representations, and then execute an action without worrying about the specific Actions involved.

get_presig()
Fetches the “contents” of a subclass for signature calculation. The varlist is added to this to produce the Action’s contents. TODO(?): Change this to always return bytes and not str?

strfunction()
Returns a substituted string representation of the Action. This is used by the _ActionAction.show() command to display the command/function that will be executed to generate the target(s).

There is a related independent ActionCaller class that looks like a regular Action, and which serves as a wrapper for arbitrary functions that we want to let the user specify the arguments to now, but actually execute later (when an out-of-date check determines that it’s needed to be executed, for example). Objects of this class are returned by an ActionFactory class that provides a __call__() method as a convenient way for wrapping up the functions.

SCons.Action.Action(act, *args, **kw)[source]#: A factory for action objects.

class SCons.Action.ActionBase[source]#

Bases: ABC

Base class for all types of action objects that can be held by other objects (Builders, Executors, etc.) This provides the common methods for manipulating and combining those actions.

_abc_impl = <_abc._abc_data object>#

batch_key(env, target, source)#

genstring(target, source, env, executor: Executor | None = None) → str[source]#

get_contents(target, source, env)[source]#

abstract get_implicit_deps(target, source, env, executor: Executor | None = None)[source]#

abstract get_presig(target, source, env, executor: Executor | None = None)[source]#

get_targets(env, executor: Executor | None)[source]#: Returns the type of targets ($TARGETS, $CHANGED_TARGETS) used by this action.

get_varlist(target, source, env, executor: Executor | None = None)[source]#

no_batch_key(env, target, source)[source]#

presub_lines(env)[source]#

class SCons.Action.ActionCaller(parent, args, kw)[source]#

Bases: object

A class for delaying calling an Action function with specific (positional and keyword) arguments until the Action is actually executed.

This class looks to the rest of the world like a normal Action object, but what it’s really doing is hanging on to the arguments until we have a target, source and env to use for the expansion.

get_contents(target, source, env)[source]#

strfunction(target, source, env)[source]#

subst(s, target, source, env)[source]#

subst_args(target, source, env)[source]#

subst_kw(target, source, env)[source]#

class SCons.Action.ActionFactory(actfunc, strfunc, convert=<function ActionFactory.<lambda>>)[source]#

Bases: object

A factory class that will wrap up an arbitrary function as an SCons-executable Action object.

The real heavy lifting here is done by the ActionCaller class. We just collect the (positional and keyword) arguments that we’re called with and give them to the ActionCaller object we create, so it can hang onto them until it needs them.

class SCons.Action.CommandAction(cmd, **kw)[source]#

Bases: _ActionAction

Class for command-execution actions.

_abc_impl = <_abc._abc_data object>#

_get_implicit_deps_heavyweight(target, source, env, executor: Executor | None, icd_int)[source]#

Heavyweight dependency scanning involves scanning more than just the first entry in an action string. The exact behavior depends on the value of icd_int. Only files are taken as implicit dependencies; directories are ignored.

If icd_int is an integer value, it specifies the number of entries to scan for implicit dependencies. Action strings are also scanned after a &&. So for example, if icd_int=2 and the action string is “cd <some_dir> && $PYTHON $SCRIPT_PATH <another_path>”, the implicit dependencies would be the path to the python binary and the path to the script.

If icd_int is None, all entries are scanned for implicit dependencies.

_get_implicit_deps_lightweight(target, source, env, executor: Executor | None)[source]#: Lightweight dependency scanning involves only scanning the first entry in an action string, even if it contains &&.

batch_key(env, target, source)#

execute(target, source, env, executor: Executor | None = None)[source]#

Execute a command action.

This will handle lists of commands as well as individual commands, because construction variable substitution may turn a single “command” into a list. This means that this class can actually handle lists of commands, even though that’s not how we use it externally.

genstring(target, source, env, executor: Executor | None = None) → str#

get_contents(target, source, env)#

get_implicit_deps(target, source, env, executor: Executor | None = None)[source]#: Return the implicit dependencies of this action’s command line.

get_presig(target, source, env, executor: Executor | None = None)[source]#

Return the signature contents of this action’s command line.

This strips $(-$) and everything in between the string, since those parts don’t affect signatures.

get_targets(env, executor: Executor | None)#: Returns the type of targets ($TARGETS, $CHANGED_TARGETS) used by this action.

get_varlist(target, source, env, executor: Executor | None = None)#

no_batch_key(env, target, source)#

presub_lines(env)#

print_cmd_line(s, target, source, env) → None#: In python 3, and in some of our tests, sys.stdout is a String io object, and it takes unicode strings only This code assumes s is a regular string.

process(target, source, env, executor=None, overrides: dict | None = None) → Tuple[List, bool, bool][source]#

strfunction(target, source, env, executor: Executor | None = None, overrides: dict | None = None) → str[source]#

class SCons.Action.CommandGeneratorAction(generator, kw)[source]#

Bases: ActionBase

Class for command-generator actions.

_abc_impl = <_abc._abc_data object>#

_generate(target, source, env, for_signature, executor: Executor | None = None)[source]#

batch_key(env, target, source)[source]#

genstring(target, source, env, executor: Executor | None = None) → str[source]#

get_contents(target, source, env)#

get_implicit_deps(target, source, env, executor: Executor | None = None)[source]#

get_presig(target, source, env, executor: Executor | None = None)[source]#

Return the signature contents of this action’s command line.

This strips $(-$) and everything in between the string, since those parts don’t affect signatures.

get_targets(env, executor: Executor | None)[source]#: Returns the type of targets ($TARGETS, $CHANGED_TARGETS) used by this action.

get_varlist(target, source, env, executor: Executor | None = None)[source]#

no_batch_key(env, target, source)#

presub_lines(env)#

class SCons.Action.FunctionAction(execfunction, kw)[source]#

Bases: _ActionAction

Class for Python function actions.

_abc_impl = <_abc._abc_data object>#

batch_key(env, target, source)#

execute(target, source, env, executor: Executor | None = None)[source]#

function_name()[source]#

genstring(target, source, env, executor: Executor | None = None) → str#

get_contents(target, source, env)#

get_implicit_deps(target, source, env, executor: Executor | None = None)[source]#

get_presig(target, source, env, executor: Executor | None = None)[source]#: Return the signature contents of this callable action.

get_targets(env, executor: Executor | None)#: Returns the type of targets ($TARGETS, $CHANGED_TARGETS) used by this action.

get_varlist(target, source, env, executor: Executor | None = None)#

no_batch_key(env, target, source)#

presub_lines(env)#

print_cmd_line(s, target, source, env) → None#: In python 3, and in some of our tests, sys.stdout is a String io object, and it takes unicode strings only This code assumes s is a regular string.

strfunction(target, source, env, executor: Executor | None = None)[source]#

class SCons.Action.LazyAction(var, kw)[source]#

Bases: CommandGeneratorAction, CommandAction

A LazyAction is a kind of hybrid generator and command action for strings of the form “$VAR”. These strings normally expand to other strings (think “$CCCOM” to “$CC -c -o $TARGET $SOURCE”), but we also want to be able to replace them with functions in the construction environment. Consequently, we want lazy evaluation and creation of an Action in the case of the function, but that’s overkill in the more normal case of expansion to other strings.

So we do this with a subclass that’s both a generator and a command action. The overridden methods all do a quick check of the construction variable, and if it’s a string we just call the corresponding CommandAction method to do the heavy lifting. If not, then we call the same-named CommandGeneratorAction method. The CommandGeneratorAction methods work by using the overridden _generate() method, that is, our own way of handling “generation” of an action based on what’s in the construction variable.

_abc_impl = <_abc._abc_data object>#

_generate(target, source, env, for_signature, executor: Executor | None = None)[source]#

_generate_cache(env)[source]#

_get_implicit_deps_heavyweight(target, source, env, executor: Executor | None, icd_int)#

If icd_int is None, all entries are scanned for implicit dependencies.

_get_implicit_deps_lightweight(target, source, env, executor: Executor | None)#: Lightweight dependency scanning involves only scanning the first entry in an action string, even if it contains &&.

batch_key(env, target, source)#

execute(target, source, env, executor: Executor | None = None)#

Execute a command action.

genstring(target, source, env, executor: Executor | None = None) → str#

get_contents(target, source, env)#

get_implicit_deps(target, source, env, executor: Executor | None = None)[source]#: Return the implicit dependencies of this action’s command line.

get_parent_class(env)[source]#

get_presig(target, source, env, executor: Executor | None = None)[source]#

Return the signature contents of this action’s command line.

This strips $(-$) and everything in between the string, since those parts don’t affect signatures.

get_targets(env, executor: Executor | None)#: Returns the type of targets ($TARGETS, $CHANGED_TARGETS) used by this action.

get_varlist(target, source, env, executor: Executor | None = None)[source]#

no_batch_key(env, target, source)#

presub_lines(env)#

print_cmd_line(s, target, source, env) → None#: In python 3, and in some of our tests, sys.stdout is a String io object, and it takes unicode strings only This code assumes s is a regular string.

process(target, source, env, executor=None, overrides: dict | None = None) → Tuple[List, bool, bool]#

strfunction(target, source, env, executor: Executor | None = None, overrides: dict | None = None) → str#

class SCons.Action.ListAction(actionlist)[source]#

Bases: ActionBase

Class for lists of other actions.

_abc_impl = <_abc._abc_data object>#

batch_key(env, target, source)#

genstring(target, source, env, executor: Executor | None = None) → str[source]#

get_contents(target, source, env)#

get_implicit_deps(target, source, env, executor: Executor | None = None)[source]#

get_presig(target, source, env, executor: Executor | None = None)[source]#

Return the signature contents of this action list.

Simple concatenation of the signatures of the elements.

get_targets(env, executor: Executor | None)#: Returns the type of targets ($TARGETS, $CHANGED_TARGETS) used by this action.

get_varlist(target, source, env, executor: Executor | None = None)[source]#

no_batch_key(env, target, source)#

presub_lines(env)[source]#

class SCons.Action._ActionAction(cmdstr=<class 'SCons.Action._null'>, strfunction=<class 'SCons.Action._null'>, varlist=(), presub=<class 'SCons.Action._null'>, chdir=None, exitstatfunc=None, batch_key=None, targets: str = '$TARGETS', **kw)[source]#

Bases: ActionBase

Base class for actions that create output objects.

_abc_impl = <_abc._abc_data object>#

batch_key(env, target, source)#

genstring(target, source, env, executor: Executor | None = None) → str#

get_contents(target, source, env)#

get_implicit_deps(target, source, env, executor: Executor | None = None)[source]#

get_presig(target, source, env, executor: Executor | None = None)[source]#

get_targets(env, executor: Executor | None)#: Returns the type of targets ($TARGETS, $CHANGED_TARGETS) used by this action.

get_varlist(target, source, env, executor: Executor | None = None)#

no_batch_key(env, target, source)#

presub_lines(env)#

print_cmd_line(s, target, source, env) → None[source]#: In python 3, and in some of our tests, sys.stdout is a String io object, and it takes unicode strings only This code assumes s is a regular string.

SCons.Action._actionAppend(act1, act2)[source]#

Joins two actions together.

Mainly, it handles ListActions by concatenating into a single ListAction.

SCons.Action._callable_contents(obj) → bytearray[source]#: Return the signature contents of a callable Python object.

SCons.Action._code_contents(code, docstring=None) → bytearray[source]#

Return the signature contents of a code object.

By providing direct access to the code object of the function, Python makes this extremely easy. Hooray!

Unfortunately, older versions of Python include line number indications in the compiled byte code. Boo! So we remove the line number byte codes to prevent recompilations from moving a Python function.

See:

For info on what each co_ variable provides

The signature is as follows (should be byte/chars): co_argcount, len(co_varnames), len(co_cellvars), len(co_freevars), ( comma separated signature for each object in co_consts ), ( comma separated signature for each object in co_names ), ( The bytecode with line number bytecodes removed from co_code )

co_argcount - Returns the number of positional arguments (including arguments with default values). co_varnames - Returns a tuple containing the names of the local variables (starting with the argument names). co_cellvars - Returns a tuple containing the names of local variables that are referenced by nested functions. co_freevars - Returns a tuple containing the names of free variables. (?) co_consts - Returns a tuple containing the literals used by the bytecode. co_names - Returns a tuple containing the names used by the bytecode. co_code - Returns a string representing the sequence of bytecode instructions.

SCons.Action._do_create_action(act, kw)[source]#

The internal implementation for the Action factory method.

This handles the fact that passing lists to Action() itself has different semantics than passing lists as elements of lists. The former will create a ListAction, the latter will create a CommandAction by converting the inner list elements to strings.

SCons.Action._do_create_keywords(args, kw)[source]#: This converts any arguments after the action argument into their equivalent keywords and adds them to the kw argument.

SCons.Action._do_create_list_action(act, kw) → ListAction[source]#

A factory for list actions.

Convert the input list act into Actions and then wrap them in a ListAction. If act has only a single member, return that member, not a ListAction. This is intended to allow a contained list to specify a command action without being processed into a list action.

SCons.Action._function_contents(func) → bytearray[source]#

Return the signature contents of a function.

The signature is as follows (should be byte/chars): < _code_contents (see above) from func.__code__ > ,( comma separated _object_contents for function argument defaults) ,( comma separated _object_contents for any closure contents )

func.__code__ - The code object representing the compiled function body.
func.__defaults__ - A tuple containing default argument values for those arguments that have defaults, or None if no arguments have a default value
func.__closure__ - None or a tuple of cells that contain bindings for the function’s free variables.

class SCons.Action._null[source]#: Bases: object

SCons.Action._object_contents(obj) → bytearray[source]#

Return the signature contents of any Python object.

We have to handle the case where object contains a code object since it can be pickled directly.

SCons.Action._object_instance_content(obj)[source]#

Returns consistant content for a action class or an instance thereof

Parameters:

obj Should be either and action class or an instance thereof

Returns:

bytearray or bytes representing the obj suitable for generating a signature from.

SCons.Action._resolve_shell_env(env, target, source)[source]

SCons package

Contents

SCons package#

Module contents#

Subpackages#

Submodules#

SCons.Action module#