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