Package SCons :: Module Action

Module Action

SCons.Action

This encapsulates 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 OO 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 MD5 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 ascii/bytes and not unicode (or py3 strings)

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.

Classes

[hide private]

_null

ActionBase
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.

_ActionAction
Base class for actions that create output objects.

CommandAction
Class for command-execution actions.

CommandGeneratorAction
Class for command-generator actions.

LazyAction
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.

FunctionAction
Class for Python function actions.

ListAction
Class for lists of other actions.

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

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

Functions

[hide private]

rfile(n)

source code

default_exitstatfunc(s)

source code

_callable_contents(obj)
Return the signature contents of a callable Python object.

source code

_object_contents(obj)
Return the signature contents of any Python object.

source code

_code_contents(code, docstring=None)
Return the signature contents of a code object.

source code

_function_contents(func)
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 )

source code

_object_instance_content(obj)
Returns consistant content for a action class or an instance thereof

source code

_actionAppend(act1, act2)

source code

_do_create_keywords(args, kw)
This converts any arguments after the action argument into their equivalent keywords and adds them to the kw argument.

source code

_do_create_action(act, kw)
This is the actual "implementation" for the Action factory method, below. This handles the fact that passing lists to Action() itself has different semantics than passing lists as elements of lists.

source code

_do_create_list_action(act, kw)
A factory for list actions. Convert the input list into Actions and then wrap them in a ListAction.

source code

Action(act, *args, **kw)
A factory for action objects.

source code

_string_from_cmd_list(cmd_list)
Takes a list of command line arguments and returns a pretty representation for printing.

source code

get_default_ENV(env)
A fiddlin' little function that has an 'import SCons.Environment' which can't be moved to the top level without creating an import loop. Since this import creates a local variable named 'SCons', it blocks access to the global variable, so we move it here to prevent complaints about local variables being used uninitialized.

source code

_subproc(scons_env, cmd, error='ignore', **kw)
Do common setup for a subprocess.Popen() call source code

Variables

[hide private]

__revision__ = 'src/engine/SCons/Action.py 3a41ed6b288cee8d085...

print_actions = 1

execute_actions = 1

print_actions_presub = 0

ACTION_SIGNATURE_PICKLE_PROTOCOL = 1

strip_quotes = re.compile(r'^[\'"](.*)[\'"]$')

default_ENV = None
hash(x)

__package__ = 'SCons'

Function Details

[hide private]

_object_contents(obj)

source code

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.

_code_contents(code, docstring=None)

source code

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.

_function_contents(func)

source code

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.

Returns:: Signature contents of a function. (in bytes)

_object_instance_content(obj)

source code

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.

_do_create_action(act, kw)

source code

This is the actual "implementation" for the Action factory method, below. 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.

_subproc(scons_env, cmd, error=`'ignore'`, **kw)

source code

Do common setup for a subprocess.Popen() call

This function is still in draft mode. We're going to need something like it in the long run as more and more places use subprocess, but I'm sure it'll have to be tweaked to get the full desired functionality. one special arg (so far?), 'error', to tell what to do with exceptions.

Variables Details

[hide private]

revision

Value:

'src/engine/SCons/Action.py 3a41ed6b288cee8d085373ad7fa02894e1903864 2
019-01-23 17:30:35 bdeegan'

Module Action

_object_contents(obj)

_code_contents(code, docstring=None)

_function_contents(func)

_object_instance_content(obj)

_do_create_action(act, kw)

_subproc(scons_env, cmd, error='ignore', **kw)

__revision__

_subproc(scons_env, cmd, error=`'ignore'`, **kw)

revision