Package SCons :: Module Util
[hide private]
[frames] | no frames]

Module Util

source code

SCons.Util

Various utility functions go here.

Classes [hide private]
  NodeList
This class is almost exactly like a regular list of Nodes (actually it can hold any object), with one important difference. If you try to get an attribute from this list, it will return that attribute from every item in the list. For example:
  DisplayEngine
  Proxy
A simple generic Proxy class, forwarding all calls to subject. So, for the benefit of the python newbie, what does this really mean? Well, it means that you can take an object, let's call it 'objA', and wrap it in this Proxy class, with a statement like this
  Delegate
A Python Descriptor class that delegates attribute fetches to an underlying wrapped subject of a Proxy. Typical use:
  _NoError
  RegError
  PlainWindowsError
  WinError
  CLVar
A class for command-line construction variables.
  Selector
A callable ordered dictionary that maps file suffixes to dictionary values. We preserve the order in which items are added so that get_suffix() calls always return the first suffix added.
  LogicalLines
Wrapper class for the logical_lines method.
  UniqueList
  Unbuffered
A proxy class that wraps a file object, flushing after every write, and delegating everything else to the wrapped object.
  Null
Null objects always and reliably "do nothing."
  NullSeq
Functions [hide private]
 
dictify(keys, values, result={}) source code
 
rightmost_separator(path, sep) source code
 
containsAny(str, set)
Check whether sequence str contains ANY of the items in set.
source code
 
containsAll(str, set)
Check whether sequence str contains ALL of the items in set.
source code
 
containsOnly(str, set)
Check whether sequence str contains ONLY items in set.
source code
 
splitext(path)
Same as os.path.splitext() but faster.
source code
 
updrive(path)
Make the drive letter (if any) upper case. This is useful because Windows is inconsistent on the case of the drive letter, which can cause inconsistencies when calculating command signatures.
source code
 
get_environment_var(varstr)
Given a string, first determine if it looks like a reference to a single environment variable, like "$FOO" or "${FOO}". If so, return that variable with no decorations ("FOO"). If not, return None.
source code
 
render_tree(root, child_func, prune=0, margin=[0], visited=None)
Render a tree of nodes into an ASCII tree view.
source code
 
IDX(N) source code
 
print_tree(root, child_func, prune=0, showtags=0, margin=[0], visited=None)
Print a tree of nodes. This is like render_tree, except it prints lines directly instead of creating a string representation in memory, so that huge trees can be printed.
source code
 
is_Dict(obj, isinstance=<built-in function isinstance>, DictTypes=dict, UserDict) source code
 
is_List(obj, isinstance=<built-in function isinstance>, ListTypes=(<type 'list'>, <class 'UserList.UserList'>)) source code
 
is_Sequence(obj, isinstance=<built-in function isinstance>, SequenceTypes=(<type 'list'>, <type 'tuple'>, <class 'UserList.UserList'>)) source code
 
is_Tuple(obj, isinstance=<built-in function isinstance>, tuple=<type 'tuple'>) source code
 
is_String(obj, isinstance=<built-in function isinstance>, StringTypes=(<type 'str'>, <type 'unicode'>, <class 'UserString.UserString'>)) source code
 
is_Scalar(obj, isinstance=<built-in function isinstance>, StringTypes=(<type 'str'>, <type 'unicode'>, <class 'UserString.UserString'>), SequenceTypes=(<type 'list'>, <type 'tuple'>, <class 'UserList.UserList'>)) source code
 
do_flatten(sequence, result, isinstance=<built-in function isinstance>, StringTypes=(<type 'str'>, <type 'unicode'>, <class 'UserString.UserString'>), SequenceTypes=(<type 'list'>, <type 'tuple'>, <class 'UserList.UserList'>)) source code
 
flatten(obj, isinstance=<built-in function isinstance>, StringTypes=(<type 'str'>, <type 'unicode'>, <class 'UserString.UserString'>), SequenceTypes=(<type 'list'>, <type 'tuple'>, <class 'UserList.UserList'>), do_flatten=<__builtin__.function object>)
Flatten a sequence to a non-nested list.
source code
 
flatten_sequence(sequence, isinstance=<built-in function isinstance>, StringTypes=(<type 'str'>, <type 'unicode'>, <class 'UserString.UserString'>), SequenceTypes=(<type 'list'>, <type 'tuple'>, <class 'UserList.UserList'>), do_flatten=<__builtin__.function object>)
Flatten a sequence to a non-nested list.
source code
 
to_String(s, isinstance=<built-in function isinstance>, str=<type 'str'>, UserString=<class 'UserString.UserString'>, BaseStringTypes=(<type 'str'>, <type 'unicode'>)) source code
 
to_String_for_subst(s, isinstance=<built-in function isinstance>, str=<type 'str'>, to_String=<__builtin__.function object>, BaseStringTypes=(<type 'str'>, <type 'unicode'>), SequenceTypes=(<type 'list'>, <type 'tuple'>, <class 'UserList.UserList'>), UserString=<class 'UserString.UserString'>) source code
 
to_String_for_signature(obj, to_String_for_subst=<__builtin__.function object>, AttributeError=<type 'exceptions.AttributeError'>) source code
 
semi_deepcopy_dict(x, exclude=[]) source code
 
_semi_deepcopy_list(x) source code
 
_semi_deepcopy_tuple(x) source code
 
semi_deepcopy(x) source code
 
RegGetValue(root, key) source code
 
RegOpenKeyEx(root, key) source code
 
WhereIs(file, path=None, pathext=None, reject=[]) source code
 
PrependPath(oldpath, newpath, sep=':', delete_existing=1, canonicalize=None)
This prepends newpath elements to the given oldpath. Will only add any particular path once (leaving the first one it encounters and ignoring the rest, to preserve path order), and will os.path.normpath and os.path.normcase all paths to help assure this. This can also handle the case where the given old path variable is a list instead of a string, in which case a list will be returned instead of a string.
source code
 
AppendPath(oldpath, newpath, sep=':', delete_existing=1, canonicalize=None)
This appends new path elements to the given old path. Will only add any particular path once (leaving the last one it encounters and ignoring the rest, to preserve path order), and will os.path.normpath and os.path.normcase all paths to help assure this. This can also handle the case where the given old path variable is a list instead of a string, in which case a list will be returned instead of a string.
source code
 
AddPathIfNotExists(env_dict, key, path, sep=':')
This function will take 'key' out of the dictionary 'env_dict', then add the path 'path' to that key if it is not already there. This treats the value of env_dict[key] as if it has a similar format to the PATH variable...a list of paths separated by tokens. The 'path' will get added to the list if it is not already there.
source code
 
get_native_path(path)
Transforms an absolute path into a native path for the system. Non-Cygwin version, just leave the path alone.
source code
 
Split(arg) source code
 
case_sensitive_suffixes(s1, s2) source code
 
adjustixes(fname, pre, suf, ensure_suffix=False) source code
 
unique(s)
Return a list of the elements in s, but without duplicates.
source code
 
uniquer(seq, idfun=None) source code
 
uniquer_hashables(seq) source code
 
logical_lines(physical_lines, joiner=<built-in method join of str object at 0x7fb7d4de6508>) source code
 
make_path_relative(path)
makes an absolute path name to a relative pathname.
source code
 
AddMethod(obj, function, name=None)
Adds either a bound method to an instance or the function itself (or an unbound method in Python 2) to a class. If name is ommited the name of the specified function is used by default.
source code
 
RenameFunction(function, name)
Returns a function identical to the specified function, but with the specified name.
source code
 
MD5signature(s)
Generate a String of Hex digits representing the md5 signature of the string :param s: either string or bytes. Normally should be bytes :return: String of hex digits
source code
 
MD5filesignature(fname, chunksize=65536)
Returns: String of Hex digits
source code
 
MD5collect(signatures)
Collects a list of signatures into an aggregate signature.
source code
 
silent_intern(x)
Perform sys.intern() on the passed argument and return the result. If the input is ineligible (e.g. a unicode string) the original argument is returned and no exception is thrown.
source code
 
to_bytes(s) source code
 
to_str(s) source code
 
cmp(a, b)
Define cmp because it's no longer available in python3 Works under python 2 as well
source code
 
get_env_bool(env, name, default=False)
Get a value of env[name] converted to boolean. The value of env[name] is interpreted as follows: 'true', 'yes', 'y', 'on' (case insensitive) and anything convertible to int that yields non-zero integer are True values; '0', 'false', 'no', 'n' and 'off' (case insensitive) are False values. For all other cases, default value is returned.
source code
 
get_os_env_bool(name, default=False)
Same as get_env_bool(os.environ, name, default).
source code
Variables [hide private]
  PY3 = False
  _altsep = None
hash(x)
  _get_env_var = re.compile(r'^\$([_a-zA-Z]\w*|\{[_a-zA-Z]\w*\})$')
  DictTypes = dict, UserDict
  ListTypes = (<type 'list'>, <class 'UserList.UserList'>)
  SequenceTypes = (<type 'list'>, <type 'tuple'>, <class 'UserLi...
  StringTypes = (<type 'str'>, <type 'unicode'>, <class 'UserStr...
  BaseStringTypes = (<type 'str'>, <type 'unicode'>)
  d = {<type 'tuple'>: <__builtin__.function object>, <type 'dic...
  _semi_deepcopy_dispatch = {<type 'tuple'>: <__builtin__.functi...
  can_read_reg = 0
  hkey_mod = win32con
  RegEnumKey = win32api.RegEnumKey
  RegEnumValue = win32api.RegEnumValue
  RegQueryValueEx = win32api.RegQueryValueEx
  HKEY_CLASSES_ROOT = None
hash(x)
  HKEY_LOCAL_MACHINE = None
hash(x)
  HKEY_CURRENT_USER = None
hash(x)
  HKEY_USERS = None
hash(x)
  display = <SCons.Util.DisplayEngine object>
  md5 = True
  __package__ = 'SCons'
Function Details [hide private]

render_tree(root, child_func, prune=0, margin=[0], visited=None)

source code 
Render a tree of nodes into an ASCII tree view.
Parameters:
  • root - : the root node of the tree
  • child_func - : the function called to get the children of a node
  • prune - : don't visit the same node twice
  • margin - : the format of the left margin to use for children of root. 1 results in a pipe, and 0 results in no pipe.
  • visited - : a dictionary of visited nodes in the current branch if not prune, or in the whole tree if prune.

print_tree(root, child_func, prune=0, showtags=0, margin=[0], visited=None)

source code 
Print a tree of nodes. This is like render_tree, except it prints lines directly instead of creating a string representation in memory, so that huge trees can be printed.
Parameters:
  • root - - the root node of the tree
  • child_func - - the function called to get the children of a node
  • prune - - don't visit the same node twice
  • showtags - - print status information to the left of each node line
  • margin - - the format of the left margin to use for children of root. 1 results in a pipe, and 0 results in no pipe.
  • visited - - a dictionary of visited nodes in the current branch if not prune, or in the whole tree if prune.

flatten(obj, isinstance=<built-in function isinstance>, StringTypes=(<type 'str'>, <type 'unicode'>, <class 'UserString.UserString'>), SequenceTypes=(<type 'list'>, <type 'tuple'>, <class 'UserList.UserList'>), do_flatten=<__builtin__.function object>)

source code 

Flatten a sequence to a non-nested list.

Flatten() converts either a single scalar or a nested sequence to a non-nested list. Note that flatten() considers strings to be scalars instead of sequences like Python would.

flatten_sequence(sequence, isinstance=<built-in function isinstance>, StringTypes=(<type 'str'>, <type 'unicode'>, <class 'UserString.UserString'>), SequenceTypes=(<type 'list'>, <type 'tuple'>, <class 'UserList.UserList'>), do_flatten=<__builtin__.function object>)

source code 

Flatten a sequence to a non-nested list.

Same as flatten(), but it does not handle the single scalar case. This is slightly more efficient when one knows that the sequence to flatten can not be a scalar.

PrependPath(oldpath, newpath, sep=':', delete_existing=1, canonicalize=None)

source code 

This prepends newpath elements to the given oldpath. Will only add any particular path once (leaving the first one it encounters and ignoring the rest, to preserve path order), and will os.path.normpath and os.path.normcase all paths to help assure this. This can also handle the case where the given old path variable is a list instead of a string, in which case a list will be returned instead of a string.

Example:
Old Path: "/foo/bar:/foo" New Path: "/biz/boom:/foo" Result: "/biz/boom:/foo:/foo/bar"

If delete_existing is 0, then adding a path that exists will not move it to the beginning; it will stay where it is in the list.

If canonicalize is not None, it is applied to each element of newpath before use.

AppendPath(oldpath, newpath, sep=':', delete_existing=1, canonicalize=None)

source code 

This appends new path elements to the given old path. Will only add any particular path once (leaving the last one it encounters and ignoring the rest, to preserve path order), and will os.path.normpath and os.path.normcase all paths to help assure this. This can also handle the case where the given old path variable is a list instead of a string, in which case a list will be returned instead of a string.

Example:
Old Path: "/foo/bar:/foo" New Path: "/biz/boom:/foo" Result: "/foo/bar:/biz/boom:/foo"

If delete_existing is 0, then adding a path that exists will not move it to the end; it will stay where it is in the list.

If canonicalize is not None, it is applied to each element of newpath before use.

unique(s)

source code 

Return a list of the elements in s, but without duplicates.

For example, unique([1,2,3,1,2,3]) is some permutation of [1,2,3], unique("abcabc") some permutation of ["a", "b", "c"], and unique(([1, 2], [2, 3], [1, 2])) some permutation of [[2, 3], [1, 2]].

For best speed, all sequence elements should be hashable. Then unique() will usually work in linear time.

If not possible, the sequence elements should enjoy a total ordering, and if list(s).sort() doesn't raise TypeError it's assumed that they do enjoy a total ordering. Then unique() will usually work in O(N*log2(N)) time.

If that's not possible either, the sequence elements must support equality-testing. Then unique() will usually work in quadratic time.

AddMethod(obj, function, name=None)

source code 

Adds either a bound method to an instance or the function itself (or an unbound method in Python 2) to a class. If name is ommited the name of the specified function is used by default.

Example:

a = A()
def f(self, x, y):
self.z = x + y
AddMethod(f, A, "add")
a.add(2, 4)
print(a.z)
AddMethod(lambda self, i: self.l[i], a, "listIndex")
print(a.listIndex(5))

MD5filesignature(fname, chunksize=65536)

source code 
Parameters:
  • fname
  • chunksize
Returns:
String of Hex digits

MD5collect(signatures)

source code 

Collects a list of signatures into an aggregate signature.

signatures - a list of signatures returns - the aggregate signature

get_env_bool(env, name, default=False)

source code 
Get a value of env[name] converted to boolean. The value of env[name] is interpreted as follows: 'true', 'yes', 'y', 'on' (case insensitive) and anything convertible to int that yields non-zero integer are True values; '0', 'false', 'no', 'n' and 'off' (case insensitive) are False values. For all other cases, default value is returned.
Parameters:
  • env - - dict or dict-like object, a convainer with variables
  • name - - name of the variable in env to be returned
  • default - - returned when env[name] does not exist or can't be converted to bool

Variables Details [hide private]

SequenceTypes

Value:
(<type 'list'>, <type 'tuple'>, <class 'UserList.UserList'>)

StringTypes

Value:
(<type 'str'>, <type 'unicode'>, <class 'UserString.UserString'>)

d

Value:
{<type 'tuple'>: <__builtin__.function object>,
 <type 'dict'>: <__builtin__.function object>,
 <type 'list'>: <__builtin__.function object>}

_semi_deepcopy_dispatch

Value:
{<type 'tuple'>: <__builtin__.function object>,
 <type 'dict'>: <__builtin__.function object>,
 <type 'list'>: <__builtin__.function object>}