Utils¶
Utilities and platform-specific fixes
The portability fixes try to provide a consistent behavior of the Waf API through Python versions 2.5 to 3.X and across different platforms (win32, linux, etc)
-
waflib.Utils.
SIG_NIL
= b'SIG_NIL_SIG_NIL_'¶ Arbitrary null value for hashes. Modify this value according to the hash function in use
-
waflib.Utils.
O644
= 420¶ Constant representing the permissions for regular files (0644 raises a syntax error on python 3)
-
waflib.Utils.
O755
= 493¶ Constant representing the permissions for executable files (0755 raises a syntax error on python 3)
-
waflib.Utils.
rot_chr
= ['\\', '|', '/', '-']¶ List of characters to use when displaying the throbber (progress bar)
-
waflib.Utils.
rot_idx
= 0¶ Index of the current throbber character (progress bar)
-
class
waflib.Utils.
ordered_iter_dict
(*k, **kw)[source]¶ Bases:
dict
Ordered dictionary that provides iteration from the most recently inserted keys first
-
class
waflib.Utils.
lru_node
[source]¶ Bases:
object
Used by
waflib.Utils.lru_cache
-
__slots__
= ('next', 'prev', 'key', 'val')¶
-
-
class
waflib.Utils.
lru_cache
(maxlen=100)[source]¶ Bases:
object
A simple least-recently used cache with lazy allocation
-
__slots__
= ('maxlen', 'table', 'head')¶
-
maxlen
¶ Maximum amount of elements in the cache
-
table
¶ Mapping key-value
-
-
waflib.Utils.
is_win32
= False¶ Whether this system is a Windows series
-
waflib.Utils.
readf_unix
(fname, m='r', encoding='latin-1')¶ Reads an entire file into a string. See also
waflib.Node.Node.readf()
:def build(ctx): from waflib import Utils txt = Utils.readf(self.path.find_node('wscript').abspath()) txt = ctx.path.find_node('wscript').read()
Parameters: - fname (string) – Path to file
- m (string) – Open mode
- encoding (string) – encoding value, only used for python 3
Return type: string
Returns: Content of the file
-
waflib.Utils.
writef_unix
(fname, data, m='w', encoding='latin-1')¶ Writes an entire file from a string. See also
waflib.Node.Node.writef()
:def build(ctx): from waflib import Utils txt = Utils.writef(self.path.make_node('i_like_kittens').abspath(), 'some data') self.path.make_node('i_like_kittens').write('some data')
Parameters: - fname (string) – Path to file
- data (string) – The contents to write to the file
- m (string) – Open mode
- encoding (string) – encoding value, only used for python 3
-
waflib.Utils.
h_file_unix
(fname)¶ Computes a hash value for a file by using md5. Use the md5_tstamp extension to get faster build hashes if necessary.
Parameters: fname (string) – path to the file to hash Returns: hash of the file contents Return type: string or bytes
-
waflib.Utils.
readf
(fname, m='r', encoding='latin-1')[source]¶ Reads an entire file into a string. See also
waflib.Node.Node.readf()
:def build(ctx): from waflib import Utils txt = Utils.readf(self.path.find_node('wscript').abspath()) txt = ctx.path.find_node('wscript').read()
Parameters: - fname (string) – Path to file
- m (string) – Open mode
- encoding (string) – encoding value, only used for python 3
Return type: string
Returns: Content of the file
-
waflib.Utils.
writef
(fname, data, m='w', encoding='latin-1')[source]¶ Writes an entire file from a string. See also
waflib.Node.Node.writef()
:def build(ctx): from waflib import Utils txt = Utils.writef(self.path.make_node('i_like_kittens').abspath(), 'some data') self.path.make_node('i_like_kittens').write('some data')
Parameters: - fname (string) – Path to file
- data (string) – The contents to write to the file
- m (string) – Open mode
- encoding (string) – encoding value, only used for python 3
-
waflib.Utils.
h_file
(fname)[source]¶ Computes a hash value for a file by using md5. Use the md5_tstamp extension to get faster build hashes if necessary.
Parameters: fname (string) – path to the file to hash Returns: hash of the file contents Return type: string or bytes
-
waflib.Utils.
to_hex
(s)[source]¶ Return the hexadecimal representation of a string
Parameters: s (string) – string to convert
-
waflib.Utils.
listdir_win32
(s)[source]¶ Lists the contents of a folder in a portable manner. On Win32, returns the list of drive letters: [‘C:’, ‘X:’, ‘Z:’] when an empty string is given.
Parameters: s (string) – a string, which can be empty on Windows
-
waflib.Utils.
num2ver
(ver)[source]¶ Converts a string, tuple or version number into an integer. The number is supposed to have at most 4 digits:
from waflib.Utils import num2ver num2ver('1.3.2') == num2ver((1,3,2)) == num2ver((1,3,2,0))
Parameters: ver (string or tuple of numbers) – a version number
-
waflib.Utils.
to_list
(val)[source]¶ Converts a string argument to a list by splitting it by spaces. Returns the object if not a string:
from waflib.Utils import to_list lst = to_list('a b c d')
Parameters: val – list of string or space-separated string Return type: list Returns: Argument converted to list
-
waflib.Utils.
split_path_unix
(path)[source]¶ Splits a path by / or ; do not confuse this function with with
os.path.split
Parameters: path (string) – path to split Returns: list of string
-
waflib.Utils.
split_path
(path)¶ Splits a path by / or ; do not confuse this function with with
os.path.split
Parameters: path (string) – path to split Returns: list of string
-
waflib.Utils.
check_dir
(path)[source]¶ Ensures that a directory exists (similar to
mkdir -p
).Parameters: path (string) – Path to directory Raises: waflib.Errors.WafError
if the folder cannot be added.
-
waflib.Utils.
check_exe
(name, env=None)[source]¶ Ensures that a program exists
Parameters: - name (string) – path to the program
- env (
waflib.ConfigSet.ConfigSet
) – configuration object
Returns: path of the program or None
Raises: waflib.Errors.WafError
if the folder cannot be added.
-
waflib.Utils.
def_attrs
(cls, **kw)[source]¶ Sets default attributes on a class instance
Parameters: - cls (class) – the class to update the given attributes in.
- kw (dict) – dictionary of attributes names and values.
-
waflib.Utils.
quote_define_name
(s)[source]¶ Converts a string into an identifier suitable for C defines.
Parameters: s (string) – String to convert Return type: string Returns: Identifier suitable for C defines
-
waflib.Utils.
re_sh
= re.compile('\\s|\'|"')¶ Regexp used for shell_escape below
-
waflib.Utils.
shell_escape
(cmd)[source]¶ Escapes a command: [‘ls’, ‘-l’, ‘arg space’] -> ls -l ‘arg space’
-
waflib.Utils.
h_list
(lst)[source]¶ Hashes lists of ordered data.
Using hash(tup) for tuples would be much more efficient, but Python now enforces hash randomization
Parameters: lst (list of strings) – list to hash Returns: hash of the list
-
waflib.Utils.
h_fun
(fun)[source]¶ Hash functions
Parameters: fun (function) – function to hash Returns: hash of the function Return type: string or bytes
-
waflib.Utils.
h_cmd
(ins)[source]¶ Hashes objects recursively
Parameters: ins (string or list or tuple or function) – input object Return type: string or bytes
-
waflib.Utils.
subst_vars
(expr, params)[source]¶ Replaces ${VAR} with the value of VAR taken from a dict or a config set:
from waflib import Utils s = Utils.subst_vars('${PREFIX}/bin', env)
Parameters: - expr (string) – String to perform substitution on
- params – Dictionary or config set to look up variable values.
-
waflib.Utils.
destos_to_binfmt
(key)[source]¶ Returns the binary format based on the unversioned platform name, and defaults to
elf
if nothing is found.Parameters: key (string) – platform name Returns: string representing the binary format
-
waflib.Utils.
unversioned_sys_platform
()[source]¶ Returns the unversioned platform name. Some Python platform names contain versions, that depend on the build environment, e.g. linux2, freebsd6, etc. This returns the name without the version number. Exceptions are os2 and win32, which are returned verbatim.
Return type: string Returns: Unversioned platform name
-
class
waflib.Utils.
Timer
[source]¶ Bases:
object
Simple object for timing the execution of commands. Its string representation is the duration:
from waflib.Utils import Timer timer = Timer() a_few_operations() s = str(timer)
-
waflib.Utils.
read_la_file
(path)[source]¶ Reads property files, used by msvc.py
Parameters: path (string) – file to read
-
waflib.Utils.
run_once
(fun)[source]¶ Decorator: let a function cache its results, use like this:
@run_once def foo(k): return 345*2343
Note
in practice this can cause memory leaks, prefer a
waflib.Utils.lru_cache
Parameters: fun (function) – function to execute Returns: the return value of the function executed
-
waflib.Utils.
get_registry_app_path
(key, filename)[source]¶ Returns the value of a registry key for an executable
-
waflib.Utils.
lib64
()[source]¶ Guess the default
/usr/lib
extension for 64-bit applicationsReturns: ‘64’ or ‘’ Return type: string
-
waflib.Utils.
process_pool
= []¶ List of processes started to execute sub-process commands
-
waflib.Utils.
run_prefork_process
(cmd, kwargs, cargs)[source]¶ Delegates process execution to a pre-forked process instance.
-
waflib.Utils.
lchown
(path, user=-1, group=-1)[source]¶ Change the owner/group of a path, raises an OSError if the ownership change fails.
Parameters: - user (int or str) – user to change
- group (int or str) – group to change
-
waflib.Utils.
run_regular_process
(cmd, kwargs, cargs={})[source]¶ Executes a subprocess command by using subprocess.Popen
-
waflib.Utils.
run_process
(cmd, kwargs, cargs={})[source]¶ Executes a subprocess by using a pre-forked process when possible or falling back to subprocess.Popen. See
waflib.Utils.run_prefork_process()
andwaflib.Utils.run_regular_process()
-
waflib.Utils.
get_process
()[source]¶ Returns a process object that can execute commands as sub-processes
Return type: subprocess.Popen
-
waflib.Utils.
alloc_process_pool
(n, force=False)[source]¶ Allocates an amount of processes to the default pool so its size is at least n. It is useful to call this function early so that the pre-forked processes use as little memory as possible.
Parameters: - n (integer) – pool size
- force (bool) – if True then n more processes are added to the existing pool