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 = '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:
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 = <_sre.SRE_Pattern object>

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_python2(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_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]

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