Python Functions

Main API

These functions implement the GNU make API used to interact with a makefile.

gnumake.export(func=None, *, name=None, expand=True, min_args=- 1, max_args=- 1)

Decorator to expose a function to Python.

All parameters passed to the Python function will be strings. The return value of the function will be converted to a string according to the following rules:

  1. Strings are unchanged

  2. True becomes ‘1’

  3. False and None become an empty string

  4. Bytes, bytearrays, and anything supporting the buffer protocol will be converted to a string using the default encoding.

  5. All other objects use str(obj)

Parameters

  • func (function) – Function to decorate

  • name (string) – The GNU make name of the function. If omitted, defaults to the unqualified function name

  • expand (bool) – If True (default) arguments to the function are expanded by make before the function is called. Otherwise the function receives the arguments verbatim, $(variables) and all.

  • min_args (int) – The minimum number of arguments to the function. If -1, (default) then the number of arguments will be guessed.

  • max_args (int) – If > 0, the maximum number of arguments to the function. A value of 0 means any number of arguments. A value of -1 (default) means that the number of parameters will be guessed.

Examples

>>> @gnumake.export
... def newer(file1, file2):
...    '''Returns the newer file'''
...    if os.path.getmtime(file1) > os.path.getmtime(file2):
...        return file1
...    else:
...        return file2

This function can then be used in a makefile as $(newer f1.txt,f2.txt)

>>> @gnumake.export(name='repeat-loop', expand=False):
... def repeat_loop(condition, loop):
...   '''A while-loop for the makefile'''
...    while gnumake.expand(condition):
...        gnumake.expand(loop)

This function can be used in a makefile as $(repeat-loop condition,loop). Both arguments are repeatedly expanded each time through the loop.

May also be used as a function:

>>> export(os.path.isfile, min_args=1, max_args=1)
gnumake.expand(s)

Expand a string according to Makefile rules

Note

GNU make handles errors by exiting the entire program.

gnumake.evaluate(s)

Evaluate a string as Makefile syntax, as if $(eval …) had been used.

Note

GNU make handles errors by exiting the entire program.

Utilities

In addition to the main API, Py-gnumake exposes a few utility functions that may prove useful.

class gnumake.Variables

Convenience class for manipulating variables in a more Pythonic manner.

An instance of this class is available as gnumake.variables or gnumake.vars

__contains__(name)

Synonym for defined(name)

__delitem__(name)

Synonym for undefine(name)

__getitem__(name)

Synonym for get(name)

__setitem__(name, value)

Synonym for set(name, value)

__weakref__

list of weak references to the object (if defined)

append(name, value)

Append a value to a possibly existing variable. Values will be appended with a single space between the old value and the new one. The flavor of the variable will remain unchanged.

defined(name)

Returns True if a variable has been defined, or False otherwise

flavor(name)

Returns the flavor of a variable. May return ‘simple’, ‘recursive’ or ‘undefined’

get(name, default='', expand_value=True)

Get a variable name

Parameters

  • name (string) – The name of the variable. This should not contain a $(…), and computed names are not allowed.

  • default (string) – Value to return if the result is undefined. Defaults to an empty string. This value will be returned only if the variable is undefined, not if it has been defined to an empty string.

  • expand (bool) – If true (default), the value will be expanded according to the flavor of the variable. This is usually what you want. Note that this makes no difference for simply expanded variables, which are fully expanded on assignment.

Returns

The value of the variable

Return type

string

origin(name)

Return the origin of a variable. See make documentation for possible values and their meanings.

set(name, value, flavor='recursive')

Set a variable

Parameters

  • name – The variable name

  • value – The variable value. This string will be escaped to preserve newlines, etc. Dollar signs ($) are _not_ escaped.

  • flavor – May be ‘recursive’ or ‘simple’. Specifying ‘recursive’ is equivalent to name=value, while ‘simple’ is equivalent to name:=value. Default is recursive.

undefine(name)

Undefine a variable

gnumake.escape_string(s)

Escape a string such that it can appear in a define directive. We need to escape ‘endef’ and backslash-newline.

gnumake.fully_escape_string(s)

Escape a string such that it can appear verbatim in a define directive. This version also escapes $ so that variable expansion does not occur. We need to escape ‘endef’, backslash-newline, and $.

gnumake.object_to_string(obj)

Convert a Python object to a string in a way that will be somewhat sensible to the makefile:

  • True becomes ‘1’

  • False and None become an empty string

  • Strings are unchanged.

  • Bytes, bytearrays, and anything supporting the buffer protocol are converted to a string using the default encoding.

  • Anything else returns str(obj)

Parameters

obj (object) – The object to convert.

Returns

a string representation of the object.

Return type

string

Check that a name is a legal makefile variable name