1#!/usr/bin/env python3
2
3r"""
4This module provides functions which are useful for writing python wrapper functions (i.e. in this context, a
5wrapper function is one whose aim is to call some other function on the caller's behalf but to provide some
6additional functionality over and above what the base function provides).
7"""
8
9
10def create_func_def_string(base_func_name,
11                           wrap_func_name,
12                           func_body_template,
13                           replace_dict):
14    r"""
15    Create and return a complete function definition as a string.  The caller may run "exec" on the resulting
16    string to create the desired function.
17
18    Description of argument(s):
19    base_func_name                  The name of the base function around which a wrapper is being created.
20    wrap_func_name                  The name of the wrapper function being created.
21    func_body_template              A function body in the form of a list.  Each list element represents one
22                                    line of a function  This is a template in so far as text substitutions
23                                    will be done on it to arrive at a valid function definition.  This
24                                    template should NOT contain the function definition line (e.g. "def
25                                    func1():").  create_func_def_string will pre-pend the definition line.
26                                    The template should also contain the text "<call_line>" which is to be
27                                    replaced by text which will call the base function with appropriate
28                                    arguments.
29    replace_dict                    A dictionary indicating additional text replacements to be done.  For
30                                    example, if the template contains a "<sub1>" (be sure to include the
31                                    angle brackets), and the dictionary contains a key/value pair of
32                                    'sub1'/'replace1', then all instances of "<sub1>" will be replaced by
33                                    "replace1".
34    """
35
36    # Create the initial function definition list as a copy of the template.
37    func_def = list(func_body_template)
38    func_def_line = "def " + wrap_func_name + "(*args, **kwargs):"
39    call_line = base_func_name + "(*args, **kwargs)"
40    # Insert the func_def_line composed by create_wrapper_def_and_call is the first list entry.
41    func_def.insert(0, func_def_line)
42    # Make sure the replace_dict has a 'call_line'/call_line pair so that any '<call_line>' text gets
43    # replaced as intended.
44    replace_dict['call_line'] = call_line
45
46    # Do the replacements.
47    for key, value in replace_dict.items():
48        func_def = [w.replace("<" + key + ">", value) for w in func_def]
49
50    return '\n'.join(func_def) + "\n"
51