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]¶

Ordered dictionary that provides iteration from the most recently inserted keys first

clear() → None. Remove all items from D.[source]¶

keys() → a set-like object providing a view on D's keys[source]¶

class waflib.Utils.lru_node[source]¶

Used by waflib.Utils.lru_cache

__slots__ = ('next', 'prev', 'key', 'val')¶

next¶

prev¶

key¶

val¶

class waflib.Utils.lru_cache(maxlen=100)[source]¶

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

head¶

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

waflib.Utils.nada(*k, **kw)[source]¶

Does nothing

Returns: None

class waflib.Utils.Timer[source]¶

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 applications

Returns: ‘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() and waflib.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

Utils¶

Previous topic

Next topic

This Page