blob: 3bfb8aa76f8ed850602dabc703357e701d39bf1a [file] [log] [blame]
Michael Walshde791732016-09-06 14:25:24 -05001#!/usr/bin/env python
2
3r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -05004This module provides many print functions such as sprint_var, sprint_time, sprint_error, sprint_call_stack.
Michael Walshde791732016-09-06 14:25:24 -05005"""
6
7import sys
8import os
9import time
10import inspect
11import re
12import grp
13import socket
14import argparse
Michael Walsh4dbb6002019-05-17 15:51:15 -050015import copy
George Keishing3b7115a2018-08-02 10:48:17 -050016try:
17 import __builtin__
18except ImportError:
19 import builtins as __builtin__
Michael Walsh7423c012016-10-04 10:27:21 -050020import logging
Michael Walshbec416d2016-11-10 08:54:52 -060021import collections
Michael Walshfd2733c2017-11-13 11:36:20 -060022from wrap_utils import *
Michael Walshbec416d2016-11-10 08:54:52 -060023
Michael Walshbec416d2016-11-10 08:54:52 -060024try:
Michael Walsh2ee77cd2017-03-08 11:50:17 -060025 robot_env = 1
Michael Walshbec416d2016-11-10 08:54:52 -060026 from robot.utils import DotDict
Michael Walsh8e6deb42017-01-27 14:22:41 -060027 from robot.utils import NormalizedDict
Michael Walsh2ee77cd2017-03-08 11:50:17 -060028 from robot.libraries.BuiltIn import BuiltIn
Michael Walsh46fcecb2019-10-16 17:11:59 -050029 # Having access to the robot libraries alone does not indicate that we are in a robot environment. The
30 # following try block should confirm that.
Michael Walshb1500152017-04-12 15:42:43 -050031 try:
32 var_value = BuiltIn().get_variable_value("${SUITE_NAME}", "")
Joy Onyerikwu004ad3c2018-06-11 16:29:56 -050033 except BaseException:
Michael Walshb1500152017-04-12 15:42:43 -050034 robot_env = 0
Michael Walshbec416d2016-11-10 08:54:52 -060035except ImportError:
Michael Walsh2ee77cd2017-03-08 11:50:17 -060036 robot_env = 0
Michael Walsh7423c012016-10-04 10:27:21 -050037
38import gen_arg as ga
Michael Walshde791732016-09-06 14:25:24 -050039
Michael Walsh46fcecb2019-10-16 17:11:59 -050040# Setting these variables for use both inside this module and by programs importing this module.
Michael Walshbf605652017-09-01 12:33:26 -050041pgm_file_path = sys.argv[0]
42pgm_name = os.path.basename(pgm_file_path)
Michael Walsh3ba8ecd2018-04-24 11:33:25 -050043pgm_dir_path = os.path.normpath(re.sub("/" + pgm_name, "", pgm_file_path)) +\
44 os.path.sep
Michael Walsh7423c012016-10-04 10:27:21 -050045
Michael Walshde791732016-09-06 14:25:24 -050046
Michael Walsh46fcecb2019-10-16 17:11:59 -050047# Some functions (e.g. sprint_pgm_header) have need of a program name value that looks more like a valid
48# variable name. Therefore, we'll swap odd characters like "." out for underscores.
Michael Walshde791732016-09-06 14:25:24 -050049pgm_name_var_name = pgm_name.replace(".", "_")
50
51# Initialize global values used as defaults by print_time, print_var, etc.
Michael Walsh4dbb6002019-05-17 15:51:15 -050052dft_indent = 0
Michael Walshde791732016-09-06 14:25:24 -050053
Michael Walsh46fcecb2019-10-16 17:11:59 -050054# Calculate default column width for print_var functions based on environment variable settings. The
55# objective is to make the variable values line up nicely with the time stamps.
Michael Walsh4dbb6002019-05-17 15:51:15 -050056dft_col1_width = 29
Michael Walshb1500152017-04-12 15:42:43 -050057
58NANOSECONDS = os.environ.get('NANOSECONDS', '1')
59
Michael Walshde791732016-09-06 14:25:24 -050060if NANOSECONDS == "1":
Michael Walsh4dbb6002019-05-17 15:51:15 -050061 dft_col1_width = dft_col1_width + 7
Michael Walshde791732016-09-06 14:25:24 -050062
Michael Walshb1500152017-04-12 15:42:43 -050063SHOW_ELAPSED_TIME = os.environ.get('SHOW_ELAPSED_TIME', '1')
Michael Walshde791732016-09-06 14:25:24 -050064
65if SHOW_ELAPSED_TIME == "1":
66 if NANOSECONDS == "1":
Michael Walsh4dbb6002019-05-17 15:51:15 -050067 dft_col1_width = dft_col1_width + 14
Michael Walshde791732016-09-06 14:25:24 -050068 else:
Michael Walsh4dbb6002019-05-17 15:51:15 -050069 dft_col1_width = dft_col1_width + 7
Michael Walshde791732016-09-06 14:25:24 -050070
71# Initialize some time variables used in module functions.
72start_time = time.time()
Michael Walsh4fea2cf2018-08-22 17:48:18 -050073# sprint_time_last_seconds is used to calculate elapsed seconds.
Michael Walsh61c12982019-03-28 12:38:01 -050074sprint_time_last_seconds = [start_time, start_time]
Michael Walsh4fea2cf2018-08-22 17:48:18 -050075# Define global index for the sprint_time_last_seconds list.
76last_seconds_ix = 0
77
78
Michael Walsh61c12982019-03-28 12:38:01 -050079def set_last_seconds_ix(ix):
80 r"""
81 Set the "last_seconds_ix" module variable to the index value.
82
83 Description of argument(s):
Michael Walsh46fcecb2019-10-16 17:11:59 -050084 ix The index value to be set into the module global last_seconds_ix variable.
Michael Walsh61c12982019-03-28 12:38:01 -050085 """
86 global last_seconds_ix
87 last_seconds_ix = ix
88
89
Michael Walsh46fcecb2019-10-16 17:11:59 -050090# Since output from the lprint_ functions goes to a different location than the output from the print_
91# functions (e.g. a file vs. the console), sprint_time_last_seconds has been created as a list rather than a
92# simple integer so that it can store multiple sprint_time_last_seconds values. Standard print_ functions
93# defined in this file will use sprint_time_last_seconds[0] and the lprint_ functions will use
Michael Walsh4fea2cf2018-08-22 17:48:18 -050094# sprint_time_last_seconds[1].
Michael Walsh61c12982019-03-28 12:38:01 -050095def standard_print_last_seconds_ix():
96 r"""
97 Return the standard print last_seconds index value to the caller.
98 """
99 return 0
100
101
Michael Walsh4fea2cf2018-08-22 17:48:18 -0500102def lprint_last_seconds_ix():
103 r"""
104 Return lprint last_seconds index value to the caller.
105 """
106 return 1
107
Michael Walshde791732016-09-06 14:25:24 -0500108
Michael Walsh46fcecb2019-10-16 17:11:59 -0500109# The user can set environment variable "GEN_PRINT_DEBUG" to get debug output from this module.
Michael Walsh2ee77cd2017-03-08 11:50:17 -0600110gen_print_debug = int(os.environ.get('GEN_PRINT_DEBUG', 0))
Michael Walsh7423c012016-10-04 10:27:21 -0500111
Michael Walshde791732016-09-06 14:25:24 -0500112
Michael Walshde791732016-09-06 14:25:24 -0500113def sprint_func_name(stack_frame_ix=None):
Michael Walshde791732016-09-06 14:25:24 -0500114 r"""
115 Return the function name associated with the indicated stack frame.
116
Michael Walsh4dbb6002019-05-17 15:51:15 -0500117 Description of argument(s):
Michael Walsh46fcecb2019-10-16 17:11:59 -0500118 stack_frame_ix The index of the stack frame whose function name should be returned. If
119 the caller does not specify a value, this function will set the value to
120 1 which is the index of the caller's stack frame. If the caller is the
121 wrapper function "print_func_name", this function will bump it up by 1.
Michael Walshde791732016-09-06 14:25:24 -0500122 """
123
Michael Walsh46fcecb2019-10-16 17:11:59 -0500124 # If user specified no stack_frame_ix, we'll set it to a proper default value.
Michael Walshde791732016-09-06 14:25:24 -0500125 if stack_frame_ix is None:
126 func_name = sys._getframe().f_code.co_name
127 caller_func_name = sys._getframe(1).f_code.co_name
128 if func_name[1:] == caller_func_name:
129 stack_frame_ix = 2
130 else:
131 stack_frame_ix = 1
132
133 func_name = sys._getframe(stack_frame_ix).f_code.co_name
134
135 return func_name
136
Michael Walshde791732016-09-06 14:25:24 -0500137
Michael Walsh6f0362c2019-03-25 14:05:14 -0500138def work_around_inspect_stack_cwd_failure():
139 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -0500140 Work around the inspect.stack() getcwd() failure by making "/tmp" the current working directory.
141
142 NOTES: If the current working directory has been deleted, inspect.stack() will fail with "OSError: [Errno
143 2] No such file or directory" because it tries to do a getcwd().
144
145 This function will try to prevent this failure by detecting the scenario in advance and making "/tmp" the
Michael Walsh6f0362c2019-03-25 14:05:14 -0500146 current working directory.
Michael Walsh6f0362c2019-03-25 14:05:14 -0500147 """
148 try:
149 os.getcwd()
150 except OSError:
151 os.chdir("/tmp")
152
153
Michael Walsh1173a522018-05-21 17:24:51 -0500154def get_line_indent(line):
155 r"""
156 Return the number of spaces at the beginning of the line.
157 """
158
159 return len(line) - len(line.lstrip(' '))
160
161
Michael Walsh46fcecb2019-10-16 17:11:59 -0500162# get_arg_name is not a print function per se. It has been included in this module because it is used by
163# sprint_var which is defined in this module.
Michael Walshde791732016-09-06 14:25:24 -0500164def get_arg_name(var,
165 arg_num=1,
166 stack_frame_ix=1):
Michael Walshde791732016-09-06 14:25:24 -0500167 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -0500168 Return the "name" of an argument passed to a function. This could be a literal or a variable name.
Michael Walshde791732016-09-06 14:25:24 -0500169
Michael Walsh4dbb6002019-05-17 15:51:15 -0500170 Description of argument(s):
171 var The variable whose name is to be returned.
Michael Walsh46fcecb2019-10-16 17:11:59 -0500172 arg_num The arg number whose name is to be returned. To illustrate how arg_num
173 is processed, suppose that a programmer codes this line: "rc, outbuf =
174 my_func(var1, var2)" and suppose that my_func has this line of code:
175 "result = gp.get_arg_name(0, arg_num, 2)". If arg_num is positive, the
176 indicated argument is returned. For example, if arg_num is 1, "var1"
177 would be returned, If arg_num is 2, "var2" would be returned. If arg_num
178 exceeds the number of arguments, get_arg_name will simply return a
179 complete list of the arguments. If arg_num is 0, get_arg_name will
180 return the name of the target function as specified in the calling line
181 ("my_func" in this case). To clarify, if the caller of the target
182 function uses an alias function name, the alias name would be returned.
183 If arg_num is negative, an lvalue variable name is returned. Continuing
184 with the given example, if arg_num is -2 the 2nd parm to the left of the
185 "=" ("rc" in this case) should be returned. If arg_num is -1, the 1st
186 parm to the left of the "=" ("out_buf" in this case) should be returned.
187 If arg_num is less than -2, an entire dictionary is returned. The keys
188 to the dictionary for this example would be -2 and -1.
189 stack_frame_ix The stack frame index of the target function. This value must be 1 or
190 greater. 1 would indicate get_arg_name's stack frame. 2 would be the
191 caller of get_arg_name's stack frame, etc.
Michael Walshde791732016-09-06 14:25:24 -0500192
193 Example 1:
194
195 my_var = "mike"
196 var_name = get_arg_name(my_var)
197
198 In this example, var_name will receive the value "my_var".
199
200 Example 2:
201
202 def test1(var):
Michael Walsh46fcecb2019-10-16 17:11:59 -0500203 # Getting the var name of the first arg to this function, test1. Note, in this case, it doesn't
204 # matter what is passed as the first arg to get_arg_name since it is the caller's variable name that
Michael Walsh4dbb6002019-05-17 15:51:15 -0500205 # matters.
Michael Walshde791732016-09-06 14:25:24 -0500206 dummy = 1
207 arg_num = 1
208 stack_frame = 2
209 var_name = get_arg_name(dummy, arg_num, stack_frame)
210
211 # Mainline...
212
213 another_var = "whatever"
214 test1(another_var)
215
216 In this example, var_name will be set to "another_var".
217
218 """
219
Michael Walsh46fcecb2019-10-16 17:11:59 -0500220 # Note: To avoid infinite recursion, avoid calling any function that calls this function (e.g.
221 # sprint_var, valid_value, etc.).
Michael Walshde791732016-09-06 14:25:24 -0500222
Michael Walsh46fcecb2019-10-16 17:11:59 -0500223 # The user can set environment variable "GET_ARG_NAME_DEBUG" to get debug output from this function.
Michael Walsh23e7f492017-01-10 11:34:47 -0600224 local_debug = int(os.environ.get('GET_ARG_NAME_DEBUG', 0))
Michael Walsh46fcecb2019-10-16 17:11:59 -0500225 # In addition to GET_ARG_NAME_DEBUG, the user can set environment variable "GET_ARG_NAME_SHOW_SOURCE" to
226 # have this function include source code in the debug output.
Michael Walsh23e7f492017-01-10 11:34:47 -0600227 local_debug_show_source = int(
228 os.environ.get('GET_ARG_NAME_SHOW_SOURCE', 0))
Michael Walshde791732016-09-06 14:25:24 -0500229
Michael Walshde791732016-09-06 14:25:24 -0500230 if stack_frame_ix < 1:
Joy Onyerikwu004ad3c2018-06-11 16:29:56 -0500231 print_error("Programmer error - Variable \"stack_frame_ix\" has an"
232 + " invalid value of \"" + str(stack_frame_ix) + "\". The"
233 + " value must be an integer that is greater than or equal"
234 + " to 1.\n")
Michael Walshde791732016-09-06 14:25:24 -0500235 return
236
237 if local_debug:
238 debug_indent = 2
Michael Walsh23e7f492017-01-10 11:34:47 -0600239 print("")
240 print_dashes(0, 120)
Michael Walshde791732016-09-06 14:25:24 -0500241 print(sprint_func_name() + "() parms:")
Michael Walsh4dbb6002019-05-17 15:51:15 -0500242 print_varx("var", var, indent=debug_indent)
243 print_varx("arg_num", arg_num, indent=debug_indent)
244 print_varx("stack_frame_ix", stack_frame_ix, indent=debug_indent)
Michael Walsh23e7f492017-01-10 11:34:47 -0600245 print("")
246 print_call_stack(debug_indent, 2)
Michael Walshde791732016-09-06 14:25:24 -0500247
Michael Walsh6f0362c2019-03-25 14:05:14 -0500248 work_around_inspect_stack_cwd_failure()
Michael Walsh23e7f492017-01-10 11:34:47 -0600249 for count in range(0, 2):
250 try:
251 frame, filename, cur_line_no, function_name, lines, index = \
252 inspect.stack()[stack_frame_ix]
253 except IndexError:
Joy Onyerikwu004ad3c2018-06-11 16:29:56 -0500254 print_error("Programmer error - The caller has asked for"
255 + " information about the stack frame at index \""
256 + str(stack_frame_ix) + "\". However, the stack"
257 + " only contains " + str(len(inspect.stack()))
258 + " entries. Therefore the stack frame index is out"
259 + " of range.\n")
Michael Walsh23e7f492017-01-10 11:34:47 -0600260 return
261 if filename != "<string>":
262 break
Michael Walsh46fcecb2019-10-16 17:11:59 -0500263 # filename of "<string>" may mean that the function in question was defined dynamically and
264 # therefore its code stack is inaccessible. This may happen with functions like "rqprint_var". In
265 # this case, we'll increment the stack_frame_ix and try again.
Michael Walsh23e7f492017-01-10 11:34:47 -0600266 stack_frame_ix += 1
267 if local_debug:
268 print("Adjusted stack_frame_ix...")
Michael Walsh4dbb6002019-05-17 15:51:15 -0500269 print_varx("stack_frame_ix", stack_frame_ix, indent=debug_indent)
Michael Walshde791732016-09-06 14:25:24 -0500270
Michael Walsh1173a522018-05-21 17:24:51 -0500271 real_called_func_name = sprint_func_name(stack_frame_ix)
Michael Walsh23e7f492017-01-10 11:34:47 -0600272
273 module = inspect.getmodule(frame)
274
Michael Walsh46fcecb2019-10-16 17:11:59 -0500275 # Though one would expect inspect.getsourcelines(frame) to get all module source lines if the frame is
276 # "<module>", it doesn't do that. Therefore, for this special case, do inspect.getsourcelines(module).
Michael Walsh23e7f492017-01-10 11:34:47 -0600277 if function_name == "<module>":
278 source_lines, source_line_num =\
279 inspect.getsourcelines(module)
280 line_ix = cur_line_no - source_line_num - 1
281 else:
282 source_lines, source_line_num =\
283 inspect.getsourcelines(frame)
284 line_ix = cur_line_no - source_line_num
285
286 if local_debug:
287 print("\n Variables retrieved from inspect.stack() function:")
Michael Walsh4dbb6002019-05-17 15:51:15 -0500288 print_varx("frame", frame, indent=debug_indent + 2)
289 print_varx("filename", filename, indent=debug_indent + 2)
290 print_varx("cur_line_no", cur_line_no, indent=debug_indent + 2)
291 print_varx("function_name", function_name, indent=debug_indent + 2)
292 print_varx("lines", lines, indent=debug_indent + 2)
293 print_varx("index", index, indent=debug_indent + 2)
294 print_varx("source_line_num", source_line_num, indent=debug_indent)
295 print_varx("line_ix", line_ix, indent=debug_indent)
Michael Walsh23e7f492017-01-10 11:34:47 -0600296 if local_debug_show_source:
Michael Walsh4dbb6002019-05-17 15:51:15 -0500297 print_varx("source_lines", source_lines, indent=debug_indent)
298 print_varx("real_called_func_name", real_called_func_name,
299 indent=debug_indent)
Michael Walsh23e7f492017-01-10 11:34:47 -0600300
Michael Walsh46fcecb2019-10-16 17:11:59 -0500301 # Get a list of all functions defined for the module. Note that this doesn't work consistently when
302 # _run_exitfuncs is at the top of the stack (i.e. if we're running an exit function). I've coded a
303 # work-around below for this deficiency.
Michael Walsh23e7f492017-01-10 11:34:47 -0600304 all_functions = inspect.getmembers(module, inspect.isfunction)
305
Michael Walsh46fcecb2019-10-16 17:11:59 -0500306 # Get called_func_id by searching for our function in the list of all functions.
Michael Walsh23e7f492017-01-10 11:34:47 -0600307 called_func_id = None
308 for func_name, function in all_functions:
Michael Walsh1173a522018-05-21 17:24:51 -0500309 if func_name == real_called_func_name:
Michael Walsh23e7f492017-01-10 11:34:47 -0600310 called_func_id = id(function)
311 break
Michael Walsh46fcecb2019-10-16 17:11:59 -0500312 # NOTE: The only time I've found that called_func_id can't be found is when we're running from an exit
313 # function.
Michael Walsh23e7f492017-01-10 11:34:47 -0600314
315 # Look for other functions in module with matching id.
Michael Walsh1173a522018-05-21 17:24:51 -0500316 aliases = set([real_called_func_name])
Michael Walsh23e7f492017-01-10 11:34:47 -0600317 for func_name, function in all_functions:
Michael Walsh1173a522018-05-21 17:24:51 -0500318 if func_name == real_called_func_name:
Michael Walsh23e7f492017-01-10 11:34:47 -0600319 continue
320 func_id = id(function)
321 if func_id == called_func_id:
322 aliases.add(func_name)
323
Michael Walsh46fcecb2019-10-16 17:11:59 -0500324 # In most cases, my general purpose code above will find all aliases. However, for the odd case (i.e.
325 # running from exit function), I've added code to handle pvar, qpvar, dpvar, etc. aliases explicitly
326 # since they are defined in this module and used frequently.
Michael Walsh23e7f492017-01-10 11:34:47 -0600327 # pvar is an alias for print_var.
Michael Walsh1173a522018-05-21 17:24:51 -0500328 aliases.add(re.sub("print_var", "pvar", real_called_func_name))
Michael Walsh23e7f492017-01-10 11:34:47 -0600329
Michael Walsh46fcecb2019-10-16 17:11:59 -0500330 # The call to the function could be encased in a recast (e.g. int(func_name())).
Joy Onyerikwu004ad3c2018-06-11 16:29:56 -0500331 recast_regex = "([^ ]+\\([ ]*)?"
332 import_name_regex = "([a-zA-Z0-9_]+\\.)?"
Michael Walsh3f248272018-06-01 13:59:35 -0500333 func_name_regex = recast_regex + import_name_regex + "(" +\
334 '|'.join(aliases) + ")"
Joy Onyerikwu004ad3c2018-06-11 16:29:56 -0500335 pre_args_regex = ".*" + func_name_regex + "[ ]*\\("
Michael Walsh23e7f492017-01-10 11:34:47 -0600336
Michael Walsh46fcecb2019-10-16 17:11:59 -0500337 # Search backward through source lines looking for the calling function name.
Michael Walsh23e7f492017-01-10 11:34:47 -0600338 found = False
339 for start_line_ix in range(line_ix, 0, -1):
340 # Skip comment lines.
341 if re.match(r"[ ]*#", source_lines[start_line_ix]):
342 continue
Michael Walsh1173a522018-05-21 17:24:51 -0500343 if re.match(pre_args_regex, source_lines[start_line_ix]):
Michael Walsh23e7f492017-01-10 11:34:47 -0600344 found = True
345 break
346 if not found:
Joy Onyerikwu004ad3c2018-06-11 16:29:56 -0500347 print_error("Programmer error - Could not find the source line with"
348 + " a reference to function \"" + real_called_func_name
349 + "\".\n")
Michael Walsh23e7f492017-01-10 11:34:47 -0600350 return
351
Michael Walsh46fcecb2019-10-16 17:11:59 -0500352 # Search forward through the source lines looking for a line whose indentation is the same or less than
353 # the start line. The end of our composite line should be the line preceding that line.
Michael Walsh1173a522018-05-21 17:24:51 -0500354 start_indent = get_line_indent(source_lines[start_line_ix])
Michael Walsh37cd29d2018-05-24 13:19:18 -0500355 end_line_ix = line_ix
Michael Walsh23e7f492017-01-10 11:34:47 -0600356 for end_line_ix in range(line_ix + 1, len(source_lines)):
357 if source_lines[end_line_ix].strip() == "":
358 continue
Michael Walsh1173a522018-05-21 17:24:51 -0500359 line_indent = get_line_indent(source_lines[end_line_ix])
Michael Walsh82acf002017-05-04 14:33:05 -0500360 if line_indent <= start_indent:
Michael Walsh23e7f492017-01-10 11:34:47 -0600361 end_line_ix -= 1
362 break
Michael Walsh1173a522018-05-21 17:24:51 -0500363 if start_line_ix != 0:
Michael Walsh46fcecb2019-10-16 17:11:59 -0500364 # Check to see whether the start line is a continuation of the prior line.
Michael Walsha52e9eb2018-09-10 13:56:01 -0500365 prior_line = source_lines[start_line_ix - 1]
366 prior_line_stripped = re.sub(r"[ ]*\\([\r\n]$)", " \\1", prior_line)
367 prior_line_indent = get_line_indent(prior_line)
368 if prior_line != prior_line_stripped and\
369 prior_line_indent < start_indent:
Michael Walsh1173a522018-05-21 17:24:51 -0500370 start_line_ix -= 1
Michael Walsha52e9eb2018-09-10 13:56:01 -0500371 # Remove the backslash (continuation char) from prior line.
372 source_lines[start_line_ix] = prior_line_stripped
Michael Walsh23e7f492017-01-10 11:34:47 -0600373
374 # Join the start line through the end line into a composite line.
375 composite_line = ''.join(map(str.strip,
Gunnar Mills096cd562018-03-26 10:19:12 -0500376 source_lines[start_line_ix:end_line_ix + 1]))
Michael Walsh1173a522018-05-21 17:24:51 -0500377 # Insert one space after first "=" if there isn't one already.
378 composite_line = re.sub("=[ ]*([^ ])", "= \\1", composite_line, 1)
Michael Walsh7423c012016-10-04 10:27:21 -0500379
Michael Walsh3f248272018-06-01 13:59:35 -0500380 lvalue_regex = "[ ]*=[ ]+" + func_name_regex + ".*"
Michael Walsh1173a522018-05-21 17:24:51 -0500381 lvalue_string = re.sub(lvalue_regex, "", composite_line)
Michael Walsh3f248272018-06-01 13:59:35 -0500382 if lvalue_string == composite_line:
383 # i.e. the regex did not match so there are no lvalues.
384 lvalue_string = ""
Michael Walsh37762f92018-08-07 14:59:18 -0500385 lvalues_list = list(filter(None, map(str.strip, lvalue_string.split(","))))
Michael Walsh3f248272018-06-01 13:59:35 -0500386 try:
387 lvalues = collections.OrderedDict()
388 except AttributeError:
389 # A non-ordered dict doesn't look as nice when printed but it will do.
390 lvalues = {}
Michael Walsh1173a522018-05-21 17:24:51 -0500391 ix = len(lvalues_list) * -1
392 for lvalue in lvalues_list:
393 lvalues[ix] = lvalue
394 ix += 1
Michael Walsh3f248272018-06-01 13:59:35 -0500395 lvalue_prefix_regex = "(.*=[ ]+)?"
Joy Onyerikwu004ad3c2018-06-11 16:29:56 -0500396 called_func_name_regex = lvalue_prefix_regex + func_name_regex +\
397 "[ ]*\\(.*"
Michael Walsh3f248272018-06-01 13:59:35 -0500398 called_func_name = re.sub(called_func_name_regex, "\\4", composite_line)
Michael Walsh1173a522018-05-21 17:24:51 -0500399 arg_list_etc = "(" + re.sub(pre_args_regex, "", composite_line)
Michael Walshde791732016-09-06 14:25:24 -0500400 if local_debug:
Michael Walsh4dbb6002019-05-17 15:51:15 -0500401 print_varx("aliases", aliases, indent=debug_indent)
402 print_varx("import_name_regex", import_name_regex, indent=debug_indent)
403 print_varx("func_name_regex", func_name_regex, indent=debug_indent)
404 print_varx("pre_args_regex", pre_args_regex, indent=debug_indent)
405 print_varx("start_line_ix", start_line_ix, indent=debug_indent)
406 print_varx("end_line_ix", end_line_ix, indent=debug_indent)
407 print_varx("composite_line", composite_line, indent=debug_indent)
408 print_varx("lvalue_regex", lvalue_regex, indent=debug_indent)
409 print_varx("lvalue_string", lvalue_string, indent=debug_indent)
410 print_varx("lvalues", lvalues, indent=debug_indent)
411 print_varx("called_func_name_regex", called_func_name_regex,
412 indent=debug_indent)
413 print_varx("called_func_name", called_func_name, indent=debug_indent)
414 print_varx("arg_list_etc", arg_list_etc, indent=debug_indent)
Michael Walshde791732016-09-06 14:25:24 -0500415
416 # Parse arg list...
417 # Initialize...
418 nest_level = -1
419 arg_ix = 0
Michael Walsh7423c012016-10-04 10:27:21 -0500420 args_list = [""]
Michael Walshde791732016-09-06 14:25:24 -0500421 for ix in range(0, len(arg_list_etc)):
422 char = arg_list_etc[ix]
423 # Set the nest_level based on whether we've encounted a parenthesis.
424 if char == "(":
425 nest_level += 1
426 if nest_level == 0:
427 continue
428 elif char == ")":
429 nest_level -= 1
430 if nest_level < 0:
431 break
432
Michael Walsh46fcecb2019-10-16 17:11:59 -0500433 # If we reach a comma at base nest level, we are done processing an argument so we increment arg_ix
434 # and initialize a new args_list entry.
Michael Walshde791732016-09-06 14:25:24 -0500435 if char == "," and nest_level == 0:
436 arg_ix += 1
Michael Walsh7423c012016-10-04 10:27:21 -0500437 args_list.append("")
Michael Walshde791732016-09-06 14:25:24 -0500438 continue
439
Michael Walsh46fcecb2019-10-16 17:11:59 -0500440 # For any other character, we append it it to the current arg list entry.
Michael Walsh7423c012016-10-04 10:27:21 -0500441 args_list[arg_ix] += char
Michael Walshde791732016-09-06 14:25:24 -0500442
443 # Trim whitespace from each list entry.
Michael Walsh7423c012016-10-04 10:27:21 -0500444 args_list = [arg.strip() for arg in args_list]
Michael Walshde791732016-09-06 14:25:24 -0500445
Michael Walsh1173a522018-05-21 17:24:51 -0500446 if arg_num < 0:
447 if abs(arg_num) > len(lvalues):
448 argument = lvalues
449 else:
450 argument = lvalues[arg_num]
451 elif arg_num == 0:
452 argument = called_func_name
Michael Walsh2750b442018-05-18 14:49:11 -0500453 else:
Michael Walsh1173a522018-05-21 17:24:51 -0500454 if arg_num > len(args_list):
455 argument = args_list
456 else:
457 argument = args_list[arg_num - 1]
Michael Walshde791732016-09-06 14:25:24 -0500458
459 if local_debug:
Michael Walsh4dbb6002019-05-17 15:51:15 -0500460 print_varx("args_list", args_list, indent=debug_indent)
461 print_varx("argument", argument, indent=debug_indent)
Michael Walsh23e7f492017-01-10 11:34:47 -0600462 print_dashes(0, 120)
Michael Walshde791732016-09-06 14:25:24 -0500463
464 return argument
465
Michael Walshde791732016-09-06 14:25:24 -0500466
Michael Walshde791732016-09-06 14:25:24 -0500467def sprint_time(buffer=""):
Michael Walshde791732016-09-06 14:25:24 -0500468 r"""
469 Return the time in the following format.
470
471 Example:
472
473 The following python code...
474
475 sys.stdout.write(sprint_time())
476 sys.stdout.write("Hi.\n")
477
478 Will result in the following type of output:
479
480 #(CDT) 2016/07/08 15:25:35 - Hi.
481
482 Example:
483
484 The following python code...
485
486 sys.stdout.write(sprint_time("Hi.\n"))
487
488 Will result in the following type of output:
489
490 #(CDT) 2016/08/03 17:12:05 - Hi.
491
Michael Walsh46fcecb2019-10-16 17:11:59 -0500492 The following environment variables will affect the formatting as described:
493 NANOSECONDS This will cause the time stamps to be precise to the microsecond (Yes, it
494 probably should have been named MICROSECONDS but the convention was set
495 long ago so we're sticking with it). Example of the output when
496 environment variable NANOSECONDS=1.
Michael Walshde791732016-09-06 14:25:24 -0500497
498 #(CDT) 2016/08/03 17:16:25.510469 - Hi.
499
Michael Walsh46fcecb2019-10-16 17:11:59 -0500500 SHOW_ELAPSED_TIME This will cause the elapsed time to be included in the output. This is
501 the amount of time that has elapsed since the last time this function was
502 called. The precision of the elapsed time field is also affected by the
503 value of the NANOSECONDS environment variable. Example of the output
504 when environment variable NANOSECONDS=0 and SHOW_ELAPSED_TIME=1.
Michael Walshde791732016-09-06 14:25:24 -0500505
506 #(CDT) 2016/08/03 17:17:40 - 0 - Hi.
507
Michael Walsh46fcecb2019-10-16 17:11:59 -0500508 Example of the output when environment variable NANOSECONDS=1 and SHOW_ELAPSED_TIME=1.
Michael Walshde791732016-09-06 14:25:24 -0500509
510 #(CDT) 2016/08/03 17:18:47.317339 - 0.000046 - Hi.
511
Michael Walsh4dbb6002019-05-17 15:51:15 -0500512 Description of argument(s).
Michael Walsh46fcecb2019-10-16 17:11:59 -0500513 buffer This will be appended to the formatted time string.
Michael Walshde791732016-09-06 14:25:24 -0500514 """
515
516 global NANOSECONDS
517 global SHOW_ELAPSED_TIME
518 global sprint_time_last_seconds
Michael Walsh4fea2cf2018-08-22 17:48:18 -0500519 global last_seconds_ix
Michael Walshde791732016-09-06 14:25:24 -0500520
521 seconds = time.time()
522 loc_time = time.localtime(seconds)
523 nanoseconds = "%0.6f" % seconds
524 pos = nanoseconds.find(".")
525 nanoseconds = nanoseconds[pos:]
526
527 time_string = time.strftime("#(%Z) %Y/%m/%d %H:%M:%S", loc_time)
528 if NANOSECONDS == "1":
529 time_string = time_string + nanoseconds
530
531 if SHOW_ELAPSED_TIME == "1":
532 cur_time_seconds = seconds
533 math_string = "%9.9f" % cur_time_seconds + " - " + "%9.9f" % \
Michael Walsh4fea2cf2018-08-22 17:48:18 -0500534 sprint_time_last_seconds[last_seconds_ix]
Michael Walshde791732016-09-06 14:25:24 -0500535 elapsed_seconds = eval(math_string)
536 if NANOSECONDS == "1":
537 elapsed_seconds = "%11.6f" % elapsed_seconds
538 else:
539 elapsed_seconds = "%4i" % elapsed_seconds
Michael Walsh4fea2cf2018-08-22 17:48:18 -0500540 sprint_time_last_seconds[last_seconds_ix] = cur_time_seconds
Michael Walshde791732016-09-06 14:25:24 -0500541 time_string = time_string + " - " + elapsed_seconds
542
543 return time_string + " - " + buffer
544
Michael Walshde791732016-09-06 14:25:24 -0500545
Michael Walshde791732016-09-06 14:25:24 -0500546def sprint_timen(buffer=""):
Michael Walshde791732016-09-06 14:25:24 -0500547 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -0500548 Append a line feed to the buffer, pass it to sprint_time and return the result.
Michael Walshde791732016-09-06 14:25:24 -0500549 """
550
551 return sprint_time(buffer + "\n")
552
Michael Walshde791732016-09-06 14:25:24 -0500553
Michael Walshde791732016-09-06 14:25:24 -0500554def sprint_error(buffer=""):
Michael Walshde791732016-09-06 14:25:24 -0500555 r"""
556 Return a standardized error string. This includes:
557 - A time stamp
558 - The "**ERROR**" string
559 - The caller's buffer string.
560
561 Example:
562
563 The following python code...
564
565 print(sprint_error("Oops.\n"))
566
567 Will result in the following type of output:
568
569 #(CDT) 2016/08/03 17:12:05 - **ERROR** Oops.
570
Michael Walsh4dbb6002019-05-17 15:51:15 -0500571 Description of argument(s).
Michael Walsh46fcecb2019-10-16 17:11:59 -0500572 buffer This will be appended to the formatted error string.
Michael Walshde791732016-09-06 14:25:24 -0500573 """
574
575 return sprint_time() + "**ERROR** " + buffer
576
Michael Walshde791732016-09-06 14:25:24 -0500577
Michael Walsh3f248272018-06-01 13:59:35 -0500578# Implement "constants" with functions.
579def digit_length_in_bits():
580 r"""
581 Return the digit length in bits.
582 """
583
584 return 4
585
586
587def word_length_in_digits():
588 r"""
589 Return the word length in digits.
590 """
591
592 return 8
593
594
595def bit_length(number):
596 r"""
597 Return the bit length of the number.
598
599 Description of argument(s):
600 number The number to be analyzed.
601 """
602
603 if number < 0:
Michael Walsh46fcecb2019-10-16 17:11:59 -0500604 # Convert negative numbers to positive and subtract one. The following example illustrates the
605 # reason for this:
606 # Consider a single nibble whose signed values can range from -8 to 7 (0x8 to 0x7). A value of 0x7
607 # equals 0b0111. Therefore, its length in bits is 3. Since the negative bit (i.e. 0b1000) is not
608 # set, the value 7 clearly will fit in one nibble. With -8 = 0x8 = 0b1000, one has the smallest
609 # negative value that will fit. Note that it requires 3 bits of 0. So by converting a number value
610 # of -8 to a working_number of 7, this function can accurately calculate the number of bits and
611 # therefore nibbles required to represent the number in print.
Michael Walsh3f248272018-06-01 13:59:35 -0500612 working_number = abs(number) - 1
613 else:
614 working_number = number
615
616 # Handle the special case of the number 0.
617 if working_number == 0:
618 return 0
619
620 return len(bin(working_number)) - 2
621
622
623def get_req_num_hex_digits(number):
624 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -0500625 Return the required number of hex digits required to display the given number.
Michael Walsh3f248272018-06-01 13:59:35 -0500626
627 The returned value will always be rounded up to the nearest multiple of 8.
628
629 Description of argument(s):
630 number The number to be analyzed.
631 """
632
633 if number < 0:
Michael Walsh46fcecb2019-10-16 17:11:59 -0500634 # Convert negative numbers to positive and subtract one. The following example illustrates the
635 # reason for this:
636 # Consider a single nibble whose signed values can range from -8 to 7 (0x8 to 0x7). A value of 0x7
637 # equals 0b0111. Therefore, its length in bits is 3. Since the negative bit (i.e. 0b1000) is not
638 # set, the value 7 clearly will fit in one nibble. With -8 = 0x8 = 0b1000, one has the smallest
639 # negative value that will fit. Note that it requires 3 bits of 0. So by converting a number value
640 # of -8 to a working_number of 7, this function can accurately calculate the number of bits and
641 # therefore nibbles required to represent the number in print.
Michael Walsh3f248272018-06-01 13:59:35 -0500642 working_number = abs(number) - 1
643 else:
644 working_number = number
645
646 # Handle the special case of the number 0.
647 if working_number == 0:
648 return word_length_in_digits()
649
650 num_length_in_bits = bit_length(working_number)
651 num_hex_digits, remainder = divmod(num_length_in_bits,
652 digit_length_in_bits())
653 if remainder > 0:
Michael Walsh46fcecb2019-10-16 17:11:59 -0500654 # Example: the number 7 requires 3 bits. The divmod above produces, 0 with remainder of 3. So
655 # because we have a remainder, we increment num_hex_digits from 0 to 1.
Michael Walsh3f248272018-06-01 13:59:35 -0500656 num_hex_digits += 1
657
Michael Walsh46fcecb2019-10-16 17:11:59 -0500658 # Check to see whether the negative bit is set. This is the left-most bit in the highest order digit.
Michael Walsh3f248272018-06-01 13:59:35 -0500659 negative_mask = 2 ** (num_hex_digits * 4 - 1)
660 if working_number & negative_mask:
Michael Walsh46fcecb2019-10-16 17:11:59 -0500661 # If a number that is intended to be positive has its negative bit on, an additional digit will be
662 # required to represent it correctly in print.
Michael Walsh3f248272018-06-01 13:59:35 -0500663 num_hex_digits += 1
664
665 num_words, remainder = divmod(num_hex_digits, word_length_in_digits())
666 if remainder > 0 or num_words == 0:
667 num_words += 1
668
669 # Round up to the next word length in digits.
670 return num_words * word_length_in_digits()
671
672
673def dft_num_hex_digits():
674 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -0500675 Return the default number of hex digits to be used to represent a hex number in print.
Michael Walsh3f248272018-06-01 13:59:35 -0500676
677 The value returned is a function of sys.maxsize.
678 """
679
680 global _gen_print_dft_num_hex_digits_
681 try:
682 return _gen_print_dft_num_hex_digits_
683 except NameError:
684 _gen_print_dft_num_hex_digits_ = get_req_num_hex_digits(sys.maxsize)
685 return _gen_print_dft_num_hex_digits_
686
687
Michael Walsh4dbb6002019-05-17 15:51:15 -0500688# Create constant functions to describe various types of dictionaries.
689def dict_type():
690 return 1
691
692
693def ordered_dict_type():
694 return 2
695
696
697def dot_dict_type():
698 return 3
699
700
701def normalized_dict_type():
702 return 4
703
704
Michael Walsh91fc8822019-05-29 17:34:17 -0500705def proxy_dict_type():
706 return 5
707
708
Michael Walsh8646d962019-01-21 14:36:13 -0600709def is_dict(var_value):
710 r"""
Michael Walsh4dbb6002019-05-17 15:51:15 -0500711 Return non-zero if var_value is a type of dictionary and 0 if it is not.
712
Michael Walsh46fcecb2019-10-16 17:11:59 -0500713 The specific non-zero value returned will indicate what type of dictionary var_value is (see constant
714 functions above).
Michael Walsh4dbb6002019-05-17 15:51:15 -0500715
716 Description of argument(s):
Michael Walsh46fcecb2019-10-16 17:11:59 -0500717 var_value The object to be analyzed to determine whether it is a dictionary and if
718 so, what type of dictionary.
Michael Walsh8646d962019-01-21 14:36:13 -0600719 """
720
Michael Walsh8646d962019-01-21 14:36:13 -0600721 if isinstance(var_value, dict):
Michael Walsh91fc8822019-05-29 17:34:17 -0500722 return dict_type()
Michael Walsh8646d962019-01-21 14:36:13 -0600723 try:
724 if isinstance(var_value, collections.OrderedDict):
Michael Walsh91fc8822019-05-29 17:34:17 -0500725 return ordered_dict_type()
Michael Walsh8646d962019-01-21 14:36:13 -0600726 except AttributeError:
727 pass
728 try:
729 if isinstance(var_value, DotDict):
Michael Walsh91fc8822019-05-29 17:34:17 -0500730 return dot_dict_type()
Michael Walsh8646d962019-01-21 14:36:13 -0600731 except NameError:
732 pass
733 try:
734 if isinstance(var_value, NormalizedDict):
Michael Walsh91fc8822019-05-29 17:34:17 -0500735 return normalized_dict_type()
Michael Walsh8646d962019-01-21 14:36:13 -0600736 except NameError:
737 pass
Michael Walsh91fc8822019-05-29 17:34:17 -0500738 try:
739 if str(type(var_value)).split("'")[1] == "dictproxy":
740 return proxy_dict_type()
741 except NameError:
742 pass
743 return 0
Michael Walsh8646d962019-01-21 14:36:13 -0600744
745
Michael Walsh4dbb6002019-05-17 15:51:15 -0500746def get_int_types():
747 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -0500748 Return a tuple consisting of the valid integer data types for the system and version of python being run.
Michael Walsh4dbb6002019-05-17 15:51:15 -0500749
750 Example:
751 (int, long)
752 """
753
754 try:
755 int_types = (int, long)
756 except NameError:
757 int_types = (int,)
758 return int_types
759
760
761def get_string_types():
762 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -0500763 Return a tuple consisting of the valid string data types for the system and version of python being run.
Michael Walsh4dbb6002019-05-17 15:51:15 -0500764
765 Example:
766 (str, unicode)
767 """
768
769 try:
770 string_types = (str, unicode)
771 except NameError:
772 string_types = (bytes, str)
773 return string_types
774
775
776def valid_fmts():
777 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -0500778 Return a list of the valid formats that can be specified for the fmt argument of the sprint_varx function
779 (defined below).
Michael Walsh4dbb6002019-05-17 15:51:15 -0500780 """
781
782 return [
783 'hexa',
784 'octal',
785 'binary',
786 'blank',
Michael Walsh6bed4d32019-07-10 14:11:30 -0500787 'verbose',
Michael Walsh4dbb6002019-05-17 15:51:15 -0500788 'quote_keys',
Michael Walshc6acf742019-08-06 11:48:51 -0500789 'show_type',
790 'strip_brackets',
Michael Walsh46fcecb2019-10-16 17:11:59 -0500791 'no_header',
792 'quote_values']
Michael Walsh4dbb6002019-05-17 15:51:15 -0500793
794
795def create_fmt_definition():
796 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -0500797 Create a string consisting of function-definition code that can be executed to create constant fmt
798 definition functions.
Michael Walsh4dbb6002019-05-17 15:51:15 -0500799
Michael Walsh46fcecb2019-10-16 17:11:59 -0500800 These functions can be used by callers of sprint_var/sprint_varx to set the fmt argument correctly.
Michael Walsh4dbb6002019-05-17 15:51:15 -0500801
Michael Walsh46fcecb2019-10-16 17:11:59 -0500802 Likewise, the sprint_varx function will use these generated functions to correctly interpret the fmt
803 argument.
Michael Walsh4dbb6002019-05-17 15:51:15 -0500804
805 Example output from this function:
806
807 def hexa():
808 return 0x00000001
809 def octal_fmt():
810 return 0x00000002
811 etc.
812 """
813
814 buffer = ""
815 bits = 0x00000001
816 for fmt_name in valid_fmts():
817 buffer += "def " + fmt_name + "():\n"
818 buffer += " return " + "0x%08x" % bits + "\n"
819 bits = bits << 1
820 return buffer
821
822
Michael Walsh46fcecb2019-10-16 17:11:59 -0500823# Dynamically create fmt definitions (for use with the fmt argument of sprint_varx function):
Michael Walsh4dbb6002019-05-17 15:51:15 -0500824exec(create_fmt_definition())
825
826
Michael Walsh6bed4d32019-07-10 14:11:30 -0500827def terse():
828 r"""
829 Constant function to return fmt value of 0.
830
Michael Walsh46fcecb2019-10-16 17:11:59 -0500831 Now that sprint_varx defaults to printing in terse format, the terse option is deprecated. This function
832 is here for backward compatibility.
Michael Walsh6bed4d32019-07-10 14:11:30 -0500833
Michael Walsh46fcecb2019-10-16 17:11:59 -0500834 Once the repo has been purged of the use of terse, this function can be removed.
Michael Walsh6bed4d32019-07-10 14:11:30 -0500835 """
836
837 return 0
838
839
Michael Walsh4dbb6002019-05-17 15:51:15 -0500840def list_pop(a_list, index=0, default=None):
841 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -0500842 Pop the list entry indicated by the index and return the entry. If no such entry exists, return default.
Michael Walsh4dbb6002019-05-17 15:51:15 -0500843
844 Note that the list passed to this function will be modified.
845
846 Description of argument(s):
Michael Walsh46fcecb2019-10-16 17:11:59 -0500847 a_list The list from which an entry is to be popped.
848 index The index indicating which entry is to be popped.
849 default The value to be returned if there is no entry at the given index location.
Michael Walsh4dbb6002019-05-17 15:51:15 -0500850 """
851 try:
852 return a_list.pop(index)
853 except IndexError:
854 return default
855
856
857def parse_fmt(fmt):
858 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -0500859 Parse the fmt argument and return a tuple consisting of a format and a child format.
Michael Walsh4dbb6002019-05-17 15:51:15 -0500860
Michael Walsh46fcecb2019-10-16 17:11:59 -0500861 This function was written for use by the sprint_varx function defined in this module.
Michael Walsh4dbb6002019-05-17 15:51:15 -0500862
Michael Walsh46fcecb2019-10-16 17:11:59 -0500863 When sprint_varx is processing a multi-level object such as a list or dictionary (which in turn may
864 contain other lists or dictionaries), it will use the fmt value to dictate the print formatting of the
865 current level and the child_fmt value to dictate the print formatting of subordinate levels. Consider
866 the following example:
Michael Walsh4dbb6002019-05-17 15:51:15 -0500867
868 python code example:
869
870 ord_dict = \
871 collections.OrderedDict([
872 ('one', 1),
873 ('two', 2),
874 ('sub',
875 collections.OrderedDict([
876 ('three', 3), ('four', 4)]))])
877
878 print_var(ord_dict)
879
880 This would generate the following output:
881
882 ord_dict:
Michael Walsh6bed4d32019-07-10 14:11:30 -0500883 [one]: 1
884 [two]: 2
885 [sub]:
886 [three]: 3
887 [four]: 4
Michael Walsh4dbb6002019-05-17 15:51:15 -0500888
Michael Walsh46fcecb2019-10-16 17:11:59 -0500889 The first level in this example is the line that simply says "ord_dict". The second level is comprised
890 of the dictionary entries with the keys 'one', 'two' and 'sub'. The third level is comprised of the last
891 2 lines (i.e. printed values 3 and 4).
Michael Walsh4dbb6002019-05-17 15:51:15 -0500892
Michael Walsh46fcecb2019-10-16 17:11:59 -0500893 Given the data structure shown above, the programmer could code the following where fmt is a simple
894 integer value set by calling the verbose() function.
Michael Walsh4dbb6002019-05-17 15:51:15 -0500895
Michael Walsh6bed4d32019-07-10 14:11:30 -0500896 print_var(ord_dict, fmt=verbose())
Michael Walsh4dbb6002019-05-17 15:51:15 -0500897
898 The output would look like this:
899
900 ord_dict:
Michael Walsh6bed4d32019-07-10 14:11:30 -0500901 ord_dict[one]: 1
902 ord_dict[two]: 2
903 ord_dict[sub]:
904 ord_dict[sub][three]: 3
905 ord_dict[sub][four]: 4
Michael Walsh4dbb6002019-05-17 15:51:15 -0500906
Michael Walsh46fcecb2019-10-16 17:11:59 -0500907 Note the verbose format where the name of the object ("ord_dict") is repeated on every line.
Michael Walsh4dbb6002019-05-17 15:51:15 -0500908
Michael Walsh46fcecb2019-10-16 17:11:59 -0500909 If the programmer wishes to get more granular with the fmt argument, he/she can specify it as a list
910 where each entry corresponds to a level of the object being printed. The last such list entry governs
911 the print formatting of all subordinate parts of the given object.
Michael Walsh4dbb6002019-05-17 15:51:15 -0500912
Michael Walsh46fcecb2019-10-16 17:11:59 -0500913 Look at each of the following code examples and their corresponding output. See how the show_type()
914 formatting affects the printing depending on which position it occupies in the fmt list argument:
Michael Walsh4dbb6002019-05-17 15:51:15 -0500915
916 print_var(ord_dict, fmt=[show_type()])
917
918 ord_dict: <collections.OrderedDict>
919 ord_dict[one]: 1 <int>
920 ord_dict[two]: 2 <int>
921 ord_dict[sub]: <collections.OrderedDict>
922 ord_dict[sub][three]: 3 <int>
923 ord_dict[sub][four]: 4 <int>
924
925 print_var(ord_dict, fmt=[0, show_type()])
926
927 ord_dict:
928 ord_dict[one]: 1 <int>
929 ord_dict[two]: 2 <int>
930 ord_dict[sub]: <collections.OrderedDict>
931 ord_dict[sub][three]: 3 <int>
932 ord_dict[sub][four]: 4 <int>
933
934 print_var(ord_dict, fmt=[0, 0, show_type()])
935
936 ord_dict:
937 ord_dict[one]: 1
938 ord_dict[two]: 2
939 ord_dict[sub]:
940 ord_dict[sub][three]: 3 <int>
941 ord_dict[sub][four]: 4 <int>
942
943 Description of argument(s):
Michael Walsh46fcecb2019-10-16 17:11:59 -0500944 fmt The format argument such as is passed to sprint_varx. This argument may
945 be an integer or a list of integers. See the prolog of sprint_varx for
946 more details.
Michael Walsh4dbb6002019-05-17 15:51:15 -0500947 """
948
Michael Walsh46fcecb2019-10-16 17:11:59 -0500949 # Make a deep copy of the fmt argument in order to avoid modifying the caller's fmt value when it is a
950 # list.
Michael Walsh4dbb6002019-05-17 15:51:15 -0500951 fmt = copy.deepcopy(fmt)
952 try:
953 # Assume fmt is a list. Pop the first element from the list.
954 first_element = list_pop(fmt, index=0, default=0)
Michael Walsh46fcecb2019-10-16 17:11:59 -0500955 # Return the first list element along with either 1) the remainder of the fmt list if not null or 2)
956 # another copy of the first element.
Michael Walsh4dbb6002019-05-17 15:51:15 -0500957 return first_element, fmt if len(fmt) else first_element
958 except AttributeError:
959 # fmt is not a list so treat it as a simple integer value.
960 return fmt, fmt
961
962
Michael Walshde791732016-09-06 14:25:24 -0500963def sprint_varx(var_name,
964 var_value,
Michael Walsh4dbb6002019-05-17 15:51:15 -0500965 fmt=0,
966 indent=dft_indent,
967 col1_width=dft_col1_width,
Michael Walshd2869032018-03-22 16:12:11 -0500968 trailing_char="\n",
Michael Walsh4dbb6002019-05-17 15:51:15 -0500969 key_list=None,
970 delim=":"):
Michael Walshde791732016-09-06 14:25:24 -0500971 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -0500972 Print the var name/value passed to it. If the caller lets col1_width default, the printing lines up
973 nicely with output generated by the print_time functions.
Michael Walshde791732016-09-06 14:25:24 -0500974
Michael Walsh46fcecb2019-10-16 17:11:59 -0500975 Note that the sprint_var function (defined below) can be used to call this function so that the
976 programmer does not need to pass the var_name. sprint_var will figure out the var_name. The sprint_var
977 function is the one that would normally be used by the general user.
Michael Walshde791732016-09-06 14:25:24 -0500978
979 For example, the following python code:
980
981 first_name = "Mike"
982 print_time("Doing this...\n")
983 print_varx("first_name", first_name)
984 print_time("Doing that...\n")
985
986 Will generate output like this:
987
988 #(CDT) 2016/08/10 17:34:42.847374 - 0.001285 - Doing this...
989 first_name: Mike
990 #(CDT) 2016/08/10 17:34:42.847510 - 0.000136 - Doing that...
991
Michael Walsh46fcecb2019-10-16 17:11:59 -0500992 This function recognizes several complex types of data such as dict, list or tuple.
Michael Walshde791732016-09-06 14:25:24 -0500993
994 For example, the following python code:
995
996 my_dict = dict(one=1, two=2, three=3)
997 print_var(my_dict)
998
999 Will generate the following output:
1000
1001 my_dict:
1002 my_dict[three]: 3
1003 my_dict[two]: 2
1004 my_dict[one]: 1
1005
Michael Walsh4dbb6002019-05-17 15:51:15 -05001006 Description of argument(s).
Michael Walshde791732016-09-06 14:25:24 -05001007 var_name The name of the variable to be printed.
1008 var_value The value of the variable to be printed.
Michael Walsh46fcecb2019-10-16 17:11:59 -05001009 fmt A bit map to dictate the format of the output. For printing multi-level
1010 objects like lists and dictionaries, this argument may also be a list of
1011 bit maps. The first list element pertains to the highest level of
1012 output, the second element pertains to the 2nd level of output, etc. The
1013 last element in the list pertains to all subordinate levels. The bits
1014 can be set using the dynamically created functionhs above. Example:
1015 sprint_varx("var1", var1, fmt=verbose()). Note that these values can be
1016 OR'ed together: print_var(var1, hexa() | verbose()). If the caller ORs
1017 mutually exclusive bits (hexa() | octal()), behavior is not guaranteed.
1018 The following features are supported:
1019 hexa Print all integer values in hexadecimal format.
Michael Walsh4dbb6002019-05-17 15:51:15 -05001020 octal Print all integer values in octal format.
1021 binary Print all integer values in binary format.
Michael Walsh46fcecb2019-10-16 17:11:59 -05001022 blank For blank string values, print "<blank>" instead of an actual blank.
1023 verbose For structured values like dictionaries, lists, etc. repeat the name of
1024 the variable on each line to the right of the key or subscript value.
1025 Example: print "my_dict[key1]" instead of just "[key1]".
1026 quote_keys Quote dictionary keys in the output. Example: my_dict['key1'] instead of
Michael Walsh4dbb6002019-05-17 15:51:15 -05001027 my_dict[key1].
Michael Walsh46fcecb2019-10-16 17:11:59 -05001028 show_type Show the type of the data in angled brackets just to the right of the
1029 data.
1030 strip_brackets Strip the brackets from the variable name portion of the output. This is
1031 applicable when printing complex objects like lists or dictionaries.
1032 no_header For complex objects like dictionaries, do not include a header line.
1033 This necessarily means that the member lines will be indented 2
1034 characters less than they otherwise would have been.
1035 quote_values Quote the values printed.
Michael Walsh4dbb6002019-05-17 15:51:15 -05001036 indent The number of spaces to indent the output.
Michael Walsh46fcecb2019-10-16 17:11:59 -05001037 col1_width The width of the output column containing the variable name. The default
1038 value of this is adjusted so that the var_value lines up with text
1039 printed via the print_time function.
1040 trailing_char The character to be used at the end of the returned string. The default
1041 value is a line feed.
1042 key_list A list of which dictionary keys should be printed. All others keys will
1043 be skipped. Each value in key_list will be regarded as a regular
1044 expression and it will be regarded as anchored to the beginning and ends
1045 of the dictionary key being referenced. For example if key_list is
1046 ["one", "two"], the resulting regex used will be "^one|two$", i.e. only
1047 keys "one" and "two" from the var_value dictionary will be printed. As
1048 another example, if the caller were to specify a key_list of ["one.*"],
1049 then only dictionary keys whose names begin with "one" will be printed.
1050 Note: This argument pertains only to var_values which are dictionaries.
1051 delim The value to be used to delimit the variable name from the variable value
1052 in the output.
Michael Walsh7423c012016-10-04 10:27:21 -05001053 """
Michael Walshde791732016-09-06 14:25:24 -05001054
Michael Walsh4dbb6002019-05-17 15:51:15 -05001055 fmt, child_fmt = parse_fmt(fmt)
1056
1057 if fmt & show_type():
1058 type_str = "<" + str(type(var_value)).split("'")[1] + ">"
1059 # Compose object type categories.
1060 int_types = get_int_types()
1061 string_types = get_string_types()
1062 simple_types = int_types + string_types + (float, bool, type, type(None))
1063 # Determine the type.
1064 if type(var_value) in simple_types:
Michael Walsh46fcecb2019-10-16 17:11:59 -05001065 # The data type is simple in the sense that it has no subordinate parts.
Michael Walsh4dbb6002019-05-17 15:51:15 -05001066 # Adjust col1_width.
1067 col1_width = col1_width - indent
1068 # Set default value for value_format.
1069 value_format = "%s"
1070 # Process format requests.
1071 if type(var_value) in int_types:
1072 # Process format values pertaining to int types.
1073 if fmt & hexa():
Michael Walsh3f248272018-06-01 13:59:35 -05001074 num_hex_digits = max(dft_num_hex_digits(),
1075 get_req_num_hex_digits(var_value))
Michael Walsh46fcecb2019-10-16 17:11:59 -05001076 # Convert a negative number to its positive twos complement for proper printing. For
1077 # example, instead of printing -1 as "0x-000000000000001" it will be printed as
Michael Walsh3f248272018-06-01 13:59:35 -05001078 # "0xffffffffffffffff".
1079 var_value = var_value & (2 ** (num_hex_digits * 4) - 1)
1080 value_format = "0x%0" + str(num_hex_digits) + "x"
Michael Walsh4dbb6002019-05-17 15:51:15 -05001081 elif fmt & octal():
1082 value_format = "0o%016o"
1083 elif fmt & binary():
1084 num_digits, remainder = \
1085 divmod(max(bit_length(var_value), 1), 8)
1086 num_digits *= 8
1087 if remainder:
1088 num_digits += 8
1089 num_digits += 2
1090 value_format = '#0' + str(num_digits) + 'b'
1091 var_value = format(var_value, value_format)
1092 value_format = "%s"
1093 elif type(var_value) in string_types:
1094 # Process format values pertaining to string types.
1095 if fmt & blank() and var_value == "":
1096 value_format = "%s"
1097 var_value = "<blank>"
1098 elif type(var_value) is type:
1099 var_value = str(var_value).split("'")[1]
1100 format_string = "%" + str(indent) + "s%-" + str(col1_width) + "s" \
1101 + value_format
1102 if fmt & show_type():
1103 if var_value != "":
1104 format_string += " "
1105 format_string += type_str
1106 format_string += trailing_char
Michael Walsh46fcecb2019-10-16 17:11:59 -05001107 if fmt & quote_values():
1108 var_value = "'" + var_value + "'"
Michael Walsh6bed4d32019-07-10 14:11:30 -05001109 if not (fmt & verbose()):
Michael Walsh4dbb6002019-05-17 15:51:15 -05001110 # Strip everything leading up to the first left square brace.
1111 var_name = re.sub(r".*\[", "[", var_name)
Michael Walshc6acf742019-08-06 11:48:51 -05001112 if (fmt & strip_brackets()):
1113 var_name = re.sub(r"[\[\]]", "", var_name)
Michael Walsh3383e652017-09-01 17:10:59 -05001114 if value_format == "0x%08x":
Michael Walsh4dbb6002019-05-17 15:51:15 -05001115 return format_string % ("", str(var_name) + delim,
Michael Walsh3383e652017-09-01 17:10:59 -05001116 var_value & 0xffffffff)
1117 else:
Michael Walsh4dbb6002019-05-17 15:51:15 -05001118 return format_string % ("", str(var_name) + delim, var_value)
Michael Walshde791732016-09-06 14:25:24 -05001119 else:
1120 # The data type is complex in the sense that it has subordinate parts.
Michael Walshc6acf742019-08-06 11:48:51 -05001121 if (fmt & no_header()):
1122 buffer = ""
Michael Walsh4dbb6002019-05-17 15:51:15 -05001123 else:
Michael Walshc6acf742019-08-06 11:48:51 -05001124 # Create header line.
1125 if not (fmt & verbose()):
1126 # Strip everything leading up to the first square brace.
1127 loc_var_name = re.sub(r".*\[", "[", var_name)
1128 else:
1129 loc_var_name = var_name
Michael Walshadf4ab22019-09-06 16:23:41 -05001130 if (fmt & strip_brackets()):
1131 loc_var_name = re.sub(r"[\[\]]", "", loc_var_name)
Michael Walshc6acf742019-08-06 11:48:51 -05001132 format_string = "%" + str(indent) + "s%s\n"
1133 buffer = format_string % ("", loc_var_name + ":")
1134 if fmt & show_type():
1135 buffer = buffer.replace("\n", " " + type_str + "\n")
1136 indent += 2
Michael Walsh7423c012016-10-04 10:27:21 -05001137 try:
1138 length = len(var_value)
1139 except TypeError:
Michael Walsh23e7f492017-01-10 11:34:47 -06001140 length = 0
Michael Walsh7423c012016-10-04 10:27:21 -05001141 ix = 0
1142 loc_trailing_char = "\n"
Michael Walsh8646d962019-01-21 14:36:13 -06001143 if is_dict(var_value):
Michael Walsh4dbb6002019-05-17 15:51:15 -05001144 if type(child_fmt) is list:
1145 child_quote_keys = (child_fmt[0] & quote_keys())
1146 else:
1147 child_quote_keys = (child_fmt & quote_keys())
Michael Walsh37762f92018-08-07 14:59:18 -05001148 for key, value in var_value.items():
Michael Walshd2869032018-03-22 16:12:11 -05001149 if key_list is not None:
1150 key_list_regex = "^" + "|".join(key_list) + "$"
1151 if not re.match(key_list_regex, key):
1152 continue
Michael Walsh7423c012016-10-04 10:27:21 -05001153 ix += 1
1154 if ix == length:
1155 loc_trailing_char = trailing_char
Michael Walsh4dbb6002019-05-17 15:51:15 -05001156 if child_quote_keys:
1157 key = "'" + key + "'"
1158 key = "[" + str(key) + "]"
1159 buffer += sprint_varx(var_name + key, value, child_fmt, indent,
Michael Walshc6acf742019-08-06 11:48:51 -05001160 col1_width, loc_trailing_char, key_list,
1161 delim)
Michael Walsh7423c012016-10-04 10:27:21 -05001162 elif type(var_value) in (list, tuple, set):
Michael Walshde791732016-09-06 14:25:24 -05001163 for key, value in enumerate(var_value):
Michael Walsh7423c012016-10-04 10:27:21 -05001164 ix += 1
1165 if ix == length:
1166 loc_trailing_char = trailing_char
Michael Walsh4dbb6002019-05-17 15:51:15 -05001167 key = "[" + str(key) + "]"
1168 buffer += sprint_varx(var_name + key, value, child_fmt, indent,
Michael Walshc6acf742019-08-06 11:48:51 -05001169 col1_width, loc_trailing_char, key_list,
1170 delim)
Joy Onyerikwu004ad3c2018-06-11 16:29:56 -05001171 elif isinstance(var_value, argparse.Namespace):
Michael Walshde791732016-09-06 14:25:24 -05001172 for key in var_value.__dict__:
Michael Walsh7423c012016-10-04 10:27:21 -05001173 ix += 1
1174 if ix == length:
1175 loc_trailing_char = trailing_char
Michael Walshde791732016-09-06 14:25:24 -05001176 cmd_buf = "buffer += sprint_varx(var_name + \".\" + str(key)" \
Michael Walsh4dbb6002019-05-17 15:51:15 -05001177 + ", var_value." + key + ", child_fmt, indent," \
Michael Walshc6acf742019-08-06 11:48:51 -05001178 + " col1_width, loc_trailing_char, key_list," \
1179 + " delim)"
Michael Walshde791732016-09-06 14:25:24 -05001180 exec(cmd_buf)
1181 else:
1182 var_type = type(var_value).__name__
1183 func_name = sys._getframe().f_code.co_name
Michael Walsh7423c012016-10-04 10:27:21 -05001184 var_value = "<" + var_type + " type not supported by " + \
1185 func_name + "()>"
Michael Walshde791732016-09-06 14:25:24 -05001186 value_format = "%s"
Michael Walsh4dbb6002019-05-17 15:51:15 -05001187 indent -= 2
1188 # Adjust col1_width.
1189 col1_width = col1_width - indent
1190 format_string = "%" + str(indent) + "s%-" \
1191 + str(col1_width) + "s" + value_format + trailing_char
Michael Walsh0f2ea5f2017-02-20 15:55:00 -06001192 return format_string % ("", str(var_name) + ":", var_value)
Michael Walsh23e7f492017-01-10 11:34:47 -06001193
Michael Walshde791732016-09-06 14:25:24 -05001194 return buffer
1195
1196 return ""
1197
Michael Walshde791732016-09-06 14:25:24 -05001198
Michael Walsh4dbb6002019-05-17 15:51:15 -05001199def sprint_var(*args, **kwargs):
Michael Walshde791732016-09-06 14:25:24 -05001200 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -05001201 Figure out the name of the first argument for the caller and then call sprint_varx with it. Therefore,
1202 the following 2 calls are equivalent:
Michael Walshde791732016-09-06 14:25:24 -05001203 sprint_varx("var1", var1)
1204 sprint_var(var1)
Michael Walsh4dbb6002019-05-17 15:51:15 -05001205
1206 See sprint_varx for description of arguments.
Michael Walshde791732016-09-06 14:25:24 -05001207 """
1208
Michael Walshde791732016-09-06 14:25:24 -05001209 stack_frame = 2
Michael Walsh7423c012016-10-04 10:27:21 -05001210 caller_func_name = sprint_func_name(2)
1211 if caller_func_name.endswith("print_var"):
Michael Walshde791732016-09-06 14:25:24 -05001212 stack_frame += 1
Michael Walsh4dbb6002019-05-17 15:51:15 -05001213 # Get the name of the first variable passed to this function.
Michael Walshde791732016-09-06 14:25:24 -05001214 var_name = get_arg_name(None, 1, stack_frame)
Michael Walsh4dbb6002019-05-17 15:51:15 -05001215 return sprint_varx(var_name, *args, **kwargs)
Michael Walshde791732016-09-06 14:25:24 -05001216
1217
Michael Walsh4dbb6002019-05-17 15:51:15 -05001218def sprint_vars(*args, **kwargs):
Michael Walsh18176322016-11-15 15:11:21 -06001219 r"""
1220 Sprint the values of one or more variables.
1221
Michael Walsh4dbb6002019-05-17 15:51:15 -05001222 Description of argument(s):
Michael Walsh46fcecb2019-10-16 17:11:59 -05001223 args The variable values which are to be printed.
1224 kwargs See sprint_varx (above) for description of additional arguments.
Michael Walsh18176322016-11-15 15:11:21 -06001225 """
1226
Michael Walsh18176322016-11-15 15:11:21 -06001227 stack_frame = 2
1228 caller_func_name = sprint_func_name(2)
1229 if caller_func_name.endswith("print_vars"):
1230 stack_frame += 1
1231
Michael Walsh18176322016-11-15 15:11:21 -06001232 buffer = ""
Michael Walsh4dbb6002019-05-17 15:51:15 -05001233 arg_num = 1
1234 for var_value in args:
1235 var_name = get_arg_name(None, arg_num, stack_frame)
1236 buffer += sprint_varx(var_name, var_value, **kwargs)
1237 arg_num += 1
Michael Walsh18176322016-11-15 15:11:21 -06001238
1239 return buffer
1240
Michael Walsh18176322016-11-15 15:11:21 -06001241
Michael Walsh4dbb6002019-05-17 15:51:15 -05001242def sprint_dashes(indent=dft_indent,
Michael Walsh7423c012016-10-04 10:27:21 -05001243 width=80,
1244 line_feed=1,
1245 char="-"):
Michael Walshde791732016-09-06 14:25:24 -05001246 r"""
1247 Return a string of dashes to the caller.
1248
Michael Walsh4dbb6002019-05-17 15:51:15 -05001249 Description of argument(s):
Michael Walsh46fcecb2019-10-16 17:11:59 -05001250 indent The number of characters to indent the output.
Michael Walshde791732016-09-06 14:25:24 -05001251 width The width of the string of dashes.
Michael Walsh46fcecb2019-10-16 17:11:59 -05001252 line_feed Indicates whether the output should end with a line feed.
1253 char The character to be repeated in the output string.
Michael Walshde791732016-09-06 14:25:24 -05001254 """
1255
Michael Walsh7423c012016-10-04 10:27:21 -05001256 width = int(width)
Michael Walsh23e7f492017-01-10 11:34:47 -06001257 buffer = " " * int(indent) + char * width
Michael Walshde791732016-09-06 14:25:24 -05001258 if line_feed:
1259 buffer += "\n"
1260
1261 return buffer
1262
Michael Walshde791732016-09-06 14:25:24 -05001263
Michael Walsh7423c012016-10-04 10:27:21 -05001264def sindent(text="",
1265 indent=0):
Michael Walsh7423c012016-10-04 10:27:21 -05001266 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -05001267 Pre-pend the specified number of characters to the text string (i.e. indent it) and return it.
Michael Walsh7423c012016-10-04 10:27:21 -05001268
Michael Walsh4dbb6002019-05-17 15:51:15 -05001269 Description of argument(s):
Michael Walsh7423c012016-10-04 10:27:21 -05001270 text The string to be indented.
Michael Walsh46fcecb2019-10-16 17:11:59 -05001271 indent The number of characters to indent the string.
Michael Walsh7423c012016-10-04 10:27:21 -05001272 """
1273
1274 format_string = "%" + str(indent) + "s%s"
1275 buffer = format_string % ("", text)
1276
1277 return buffer
1278
Michael Walsh7423c012016-10-04 10:27:21 -05001279
Michael Walsh662e13b2019-03-01 15:54:08 -06001280func_line_style_std = None
1281func_line_style_short = 1
1282
1283
1284def sprint_func_line(stack_frame, style=None):
Michael Walsh47aa2a42018-12-10 15:06:02 -06001285 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -05001286 For the given stack_frame, return a formatted string containing the function name and all its arguments.
Michael Walsh47aa2a42018-12-10 15:06:02 -06001287
1288 Example:
1289
1290 func1(last_name = 'walsh', first_name = 'mikey')
1291
1292 Description of argument(s):
Michael Walsh46fcecb2019-10-16 17:11:59 -05001293 stack_frame A stack frame (such as is returned by inspect.stack()).
1294 style Indicates the style or formatting of the result string. Acceptable
1295 values are shown above.
Michael Walsh662e13b2019-03-01 15:54:08 -06001296
1297 Description of styles:
1298 func_line_style_std The standard formatting.
Michael Walsh46fcecb2019-10-16 17:11:59 -05001299 func_line_style_short 1) The self parm (associated with methods) will be dropped. 2) The args
1300 and kwargs values will be treated as special. In both cases the arg name
1301 ('args' or 'kwargs') will be dropped and only the values will be shown.
Michael Walsh47aa2a42018-12-10 15:06:02 -06001302 """
1303
1304 func_name = str(stack_frame[3])
1305 if func_name == "?":
1306 # "?" is the name used when code is not in a function.
1307 func_name = "(none)"
1308
1309 if func_name == "<module>":
Michael Walsh46fcecb2019-10-16 17:11:59 -05001310 # If the func_name is the "main" program, we simply get the command line call string.
Michael Walsh47aa2a42018-12-10 15:06:02 -06001311 func_and_args = ' '.join(sys.argv)
1312 else:
1313 # Get the program arguments.
1314 (args, varargs, keywords, locals) =\
1315 inspect.getargvalues(stack_frame[0])
1316
1317 args_list = []
1318 for arg_name in filter(None, args + [varargs, keywords]):
1319 # Get the arg value from frame locals.
1320 arg_value = locals[arg_name]
1321 if arg_name == 'self':
Michael Walsh662e13b2019-03-01 15:54:08 -06001322 if style == func_line_style_short:
1323 continue
Michael Walsh47aa2a42018-12-10 15:06:02 -06001324 # Manipulations to improve output for class methods.
1325 func_name = arg_value.__class__.__name__ + "." + func_name
1326 args_list.append(arg_name + " = <self>")
Michael Walsh662e13b2019-03-01 15:54:08 -06001327 elif (style == func_line_style_short
1328 and arg_name == 'args'
1329 and type(arg_value) in (list, tuple)):
1330 if len(arg_value) == 0:
1331 continue
1332 args_list.append(repr(', '.join(arg_value)))
1333 elif (style == func_line_style_short
1334 and arg_name == 'kwargs'
1335 and type(arg_value) is dict):
1336 for key, value in arg_value.items():
1337 args_list.append(key + "=" + repr(value))
Michael Walsh47aa2a42018-12-10 15:06:02 -06001338 else:
1339 args_list.append(arg_name + " = " + repr(arg_value))
1340 args_str = "(" + ', '.join(map(str, args_list)) + ")"
1341
1342 # Now we need to print this in a nicely-wrapped way.
1343 func_and_args = func_name + args_str
1344
1345 return func_and_args
1346
1347
Michael Walsh7423c012016-10-04 10:27:21 -05001348def sprint_call_stack(indent=0,
Michael Walsh662e13b2019-03-01 15:54:08 -06001349 stack_frame_ix=0,
1350 style=None):
Michael Walshde791732016-09-06 14:25:24 -05001351 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -05001352 Return a call stack report for the given point in the program with line numbers, function names and
1353 function parameters and arguments.
Michael Walshde791732016-09-06 14:25:24 -05001354
1355 Sample output:
1356
1357 -------------------------------------------------------------------------
1358 Python function call stack
1359
1360 Line # Function name and arguments
1361 ------ ------------------------------------------------------------------
Michael Walsh47aa2a42018-12-10 15:06:02 -06001362 424 sprint_call_stack()
1363 4 print_call_stack()
1364 31 func1(last_name = 'walsh', first_name = 'mikey')
Michael Walshde791732016-09-06 14:25:24 -05001365 59 /tmp/scr5.py
1366 -------------------------------------------------------------------------
1367
Michael Walsh4dbb6002019-05-17 15:51:15 -05001368 Description of argument(s):
Michael Walsh46fcecb2019-10-16 17:11:59 -05001369 indent The number of characters to indent each line of output.
1370 stack_frame_ix The index of the first stack frame which is to be returned.
1371 style See the sprint_line_func prolog above for details.
Michael Walshde791732016-09-06 14:25:24 -05001372 """
1373
1374 buffer = ""
Michael Walsh7423c012016-10-04 10:27:21 -05001375 buffer += sprint_dashes(indent)
1376 buffer += sindent("Python function call stack\n\n", indent)
1377 buffer += sindent("Line # Function name and arguments\n", indent)
1378 buffer += sprint_dashes(indent, 6, 0) + " " + sprint_dashes(0, 73)
Michael Walshde791732016-09-06 14:25:24 -05001379
1380 # Grab the current program stack.
Michael Walsh6f0362c2019-03-25 14:05:14 -05001381 work_around_inspect_stack_cwd_failure()
Michael Walshde791732016-09-06 14:25:24 -05001382 current_stack = inspect.stack()
1383
1384 # Process each frame in turn.
1385 format_string = "%6s %s\n"
Michael Walsh7423c012016-10-04 10:27:21 -05001386 ix = 0
Michael Walshde791732016-09-06 14:25:24 -05001387 for stack_frame in current_stack:
Michael Walsh7423c012016-10-04 10:27:21 -05001388 if ix < stack_frame_ix:
1389 ix += 1
1390 continue
Michael Walsh46fcecb2019-10-16 17:11:59 -05001391 # Make the line number shown to be the line where one finds the line shown.
Michael Walsh23e7f492017-01-10 11:34:47 -06001392 try:
1393 line_num = str(current_stack[ix + 1][2])
1394 except IndexError:
1395 line_num = ""
Michael Walsh662e13b2019-03-01 15:54:08 -06001396 func_and_args = sprint_func_line(stack_frame, style=style)
Michael Walshde791732016-09-06 14:25:24 -05001397
Michael Walsh23e7f492017-01-10 11:34:47 -06001398 buffer += sindent(format_string % (line_num, func_and_args), indent)
Michael Walsh7423c012016-10-04 10:27:21 -05001399 ix += 1
Michael Walshde791732016-09-06 14:25:24 -05001400
Michael Walsh7423c012016-10-04 10:27:21 -05001401 buffer += sprint_dashes(indent)
Michael Walshde791732016-09-06 14:25:24 -05001402
1403 return buffer
1404
Michael Walshde791732016-09-06 14:25:24 -05001405
Michael Walsh662e13b2019-03-01 15:54:08 -06001406def sprint_executing(stack_frame_ix=None, style=None):
Michael Walshde791732016-09-06 14:25:24 -05001407 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -05001408 Print a line indicating what function is executing and with what parameter values. This is useful for
1409 debugging.
Michael Walshde791732016-09-06 14:25:24 -05001410
1411 Sample output:
1412
Michael Walsh47aa2a42018-12-10 15:06:02 -06001413 #(CDT) 2016/08/25 17:54:27 - Executing: func1(x = 1)
Michael Walshde791732016-09-06 14:25:24 -05001414
Michael Walsh4dbb6002019-05-17 15:51:15 -05001415 Description of argument(s):
Michael Walsh46fcecb2019-10-16 17:11:59 -05001416 stack_frame_ix The index of the stack frame whose function info should be returned. If
1417 the caller does not specify a value, this function will set the value to
1418 1 which is the index of the caller's stack frame. If the caller is the
1419 wrapper function "print_executing", this function will bump it up by 1.
1420 style See the sprint_line_func prolog above for details.
Michael Walshde791732016-09-06 14:25:24 -05001421 """
1422
1423 # If user wants default stack_frame_ix.
1424 if stack_frame_ix is None:
1425 func_name = sys._getframe().f_code.co_name
1426 caller_func_name = sys._getframe(1).f_code.co_name
Michael Walsh7423c012016-10-04 10:27:21 -05001427 if caller_func_name.endswith(func_name[1:]):
Michael Walshde791732016-09-06 14:25:24 -05001428 stack_frame_ix = 2
1429 else:
1430 stack_frame_ix = 1
1431
Michael Walsh6f0362c2019-03-25 14:05:14 -05001432 work_around_inspect_stack_cwd_failure()
Michael Walshde791732016-09-06 14:25:24 -05001433 stack_frame = inspect.stack()[stack_frame_ix]
1434
Michael Walsh662e13b2019-03-01 15:54:08 -06001435 func_and_args = sprint_func_line(stack_frame, style)
Michael Walshde791732016-09-06 14:25:24 -05001436
1437 return sprint_time() + "Executing: " + func_and_args + "\n"
1438
Michael Walshde791732016-09-06 14:25:24 -05001439
Michael Walshbec416d2016-11-10 08:54:52 -06001440def sprint_pgm_header(indent=0,
1441 linefeed=1):
Michael Walshde791732016-09-06 14:25:24 -05001442 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -05001443 Return a standardized header that programs should print at the beginning of the run. It includes useful
1444 information like command line, pid, userid, program parameters, etc.
Michael Walshde791732016-09-06 14:25:24 -05001445
Michael Walsh4dbb6002019-05-17 15:51:15 -05001446 Description of argument(s):
Michael Walsh46fcecb2019-10-16 17:11:59 -05001447 indent The number of characters to indent each line of output.
1448 linefeed Indicates whether a line feed be included at the beginning and end of the
1449 report.
Michael Walshde791732016-09-06 14:25:24 -05001450 """
1451
Michael Walsh4dbb6002019-05-17 15:51:15 -05001452 col1_width = dft_col1_width + indent
Michael Walshbec416d2016-11-10 08:54:52 -06001453
1454 buffer = ""
1455 if linefeed:
1456 buffer = "\n"
Michael Walsh7423c012016-10-04 10:27:21 -05001457
Michael Walshdb6e68a2017-05-23 17:55:31 -05001458 if robot_env:
1459 suite_name = BuiltIn().get_variable_value("${suite_name}")
Joy Onyerikwu004ad3c2018-06-11 16:29:56 -05001460 buffer += sindent(sprint_time("Running test suite \"" + suite_name
1461 + "\".\n"), indent)
Michael Walshdb6e68a2017-05-23 17:55:31 -05001462
Michael Walsh7423c012016-10-04 10:27:21 -05001463 buffer += sindent(sprint_time() + "Running " + pgm_name + ".\n", indent)
1464 buffer += sindent(sprint_time() + "Program parameter values, etc.:\n\n",
1465 indent)
Michael Walshbec416d2016-11-10 08:54:52 -06001466 buffer += sprint_varx("command_line", ' '.join(sys.argv), 0, indent,
Michael Walsh4dbb6002019-05-17 15:51:15 -05001467 col1_width)
Michael Walsh46fcecb2019-10-16 17:11:59 -05001468 # We want the output to show a customized name for the pid and pgid but we want it to look like a valid
1469 # variable name. Therefore, we'll use pgm_name_var_name which was set when this module was imported.
Michael Walshbec416d2016-11-10 08:54:52 -06001470 buffer += sprint_varx(pgm_name_var_name + "_pid", os.getpid(), 0, indent,
Michael Walsh4dbb6002019-05-17 15:51:15 -05001471 col1_width)
Michael Walshbec416d2016-11-10 08:54:52 -06001472 buffer += sprint_varx(pgm_name_var_name + "_pgid", os.getpgrp(), 0, indent,
Michael Walsh4dbb6002019-05-17 15:51:15 -05001473 col1_width)
Michael Walsh86de0d22016-12-05 10:13:15 -06001474 userid_num = str(os.geteuid())
1475 try:
1476 username = os.getlogin()
1477 except OSError:
1478 if userid_num == "0":
1479 username = "root"
1480 else:
1481 username = "?"
Joy Onyerikwu004ad3c2018-06-11 16:29:56 -05001482 buffer += sprint_varx("uid", userid_num + " (" + username
Michael Walsh4dbb6002019-05-17 15:51:15 -05001483 + ")", 0, indent, col1_width)
Joy Onyerikwu004ad3c2018-06-11 16:29:56 -05001484 buffer += sprint_varx("gid", str(os.getgid()) + " ("
1485 + str(grp.getgrgid(os.getgid()).gr_name) + ")", 0,
Michael Walsh4dbb6002019-05-17 15:51:15 -05001486 indent, col1_width)
Michael Walshbec416d2016-11-10 08:54:52 -06001487 buffer += sprint_varx("host_name", socket.gethostname(), 0, indent,
Michael Walsh4dbb6002019-05-17 15:51:15 -05001488 col1_width)
Michael Walsh86de0d22016-12-05 10:13:15 -06001489 try:
1490 DISPLAY = os.environ['DISPLAY']
1491 except KeyError:
1492 DISPLAY = ""
Michael Walsh91fc8822019-05-29 17:34:17 -05001493 buffer += sprint_var(DISPLAY, 0, indent, col1_width)
1494 PYTHON_VERSION = os.environ.get('PYTHON_VERSION', None)
1495 if PYTHON_VERSION is not None:
Michael Walshc9a7ee72019-08-28 16:45:50 -05001496 buffer += sprint_var(PYTHON_VERSION, 0, indent, col1_width)
Michael Walsh91fc8822019-05-29 17:34:17 -05001497 PYTHON_PGM_PATH = os.environ.get('PYTHON_PGM_PATH', None)
1498 if PYTHON_PGM_PATH is not None:
Michael Walshc9a7ee72019-08-28 16:45:50 -05001499 buffer += sprint_var(PYTHON_PGM_PATH, 0, indent, col1_width)
Michael Walsh91fc8822019-05-29 17:34:17 -05001500 python_version = sys.version.replace("\n", "")
Michael Walshc9a7ee72019-08-28 16:45:50 -05001501 buffer += sprint_var(python_version, 0, indent, col1_width)
Michael Walsh91fc8822019-05-29 17:34:17 -05001502 ROBOT_VERSION = os.environ.get('ROBOT_VERSION', None)
1503 if ROBOT_VERSION is not None:
Michael Walshc9a7ee72019-08-28 16:45:50 -05001504 buffer += sprint_var(ROBOT_VERSION, 0, indent, col1_width)
Michael Walsh91fc8822019-05-29 17:34:17 -05001505 ROBOT_PGM_PATH = os.environ.get('ROBOT_PGM_PATH', None)
1506 if ROBOT_PGM_PATH is not None:
Michael Walshc9a7ee72019-08-28 16:45:50 -05001507 buffer += sprint_var(ROBOT_PGM_PATH, 0, indent, col1_width)
Michael Walsh91fc8822019-05-29 17:34:17 -05001508
Michael Walsh4dbb6002019-05-17 15:51:15 -05001509 # TODO: Add code to print caller's parms.
Michael Walshde791732016-09-06 14:25:24 -05001510
Michael Walsh46fcecb2019-10-16 17:11:59 -05001511 # __builtin__.arg_obj is created by the get_arg module function, gen_get_options.
Michael Walsh7423c012016-10-04 10:27:21 -05001512 try:
1513 buffer += ga.sprint_args(__builtin__.arg_obj, indent)
1514 except AttributeError:
1515 pass
1516
Michael Walshdb6e68a2017-05-23 17:55:31 -05001517 if robot_env:
1518 # Get value of global parm_list.
1519 parm_list = BuiltIn().get_variable_value("${parm_list}")
1520
1521 for parm in parm_list:
1522 parm_value = BuiltIn().get_variable_value("${" + parm + "}")
Michael Walsh4dbb6002019-05-17 15:51:15 -05001523 buffer += sprint_varx(parm, parm_value, 0, indent, col1_width)
Michael Walshdb6e68a2017-05-23 17:55:31 -05001524
1525 # Setting global program_pid.
1526 BuiltIn().set_global_variable("${program_pid}", os.getpid())
1527
Michael Walshbec416d2016-11-10 08:54:52 -06001528 if linefeed:
1529 buffer += "\n"
Michael Walshde791732016-09-06 14:25:24 -05001530
1531 return buffer
1532
Michael Walshde791732016-09-06 14:25:24 -05001533
Michael Walsh7423c012016-10-04 10:27:21 -05001534def sprint_error_report(error_text="\n",
Michael Walshdb6e68a2017-05-23 17:55:31 -05001535 indent=2,
Michael Walshe7ca2b02019-08-01 11:09:45 -05001536 format=None,
1537 stack_frame_ix=None):
Michael Walsh7423c012016-10-04 10:27:21 -05001538 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -05001539 Return a string with a standardized report which includes the caller's error text, the call stack and the
1540 program header.
Michael Walsh7423c012016-10-04 10:27:21 -05001541
Michael Walsh4dbb6002019-05-17 15:51:15 -05001542 Description of argument(s):
Michael Walsh46fcecb2019-10-16 17:11:59 -05001543 error_text The error text to be included in the report. The caller should include
1544 any needed linefeeds.
1545 indent The number of characters to indent each line of output.
1546 format Long or short format. Long includes extras like lines of dashes, call
1547 stack, etc.
1548 stack_frame_ix The index of the first stack frame which is to be shown in the
1549 print_call_stack portion of the error report.
Michael Walsh7423c012016-10-04 10:27:21 -05001550 """
1551
Michael Walshdb6e68a2017-05-23 17:55:31 -05001552 # Process input.
1553 indent = int(indent)
1554 if format is None:
1555 if robot_env:
1556 format = 'short'
1557 else:
1558 format = 'long'
1559 error_text = error_text.rstrip('\n') + '\n'
1560
1561 if format == 'short':
1562 return sprint_error(error_text)
1563
Michael Walsh7423c012016-10-04 10:27:21 -05001564 buffer = ""
1565 buffer += sprint_dashes(width=120, char="=")
1566 buffer += sprint_error(error_text)
1567 buffer += "\n"
Michael Walshe7ca2b02019-08-01 11:09:45 -05001568 if not stack_frame_ix:
Michael Walsh46fcecb2019-10-16 17:11:59 -05001569 # Calling sprint_call_stack with stack_frame_ix of 0 causes it to show itself and this function in
1570 # the call stack. This is not helpful to a debugger and is therefore clutter. We will adjust the
Michael Walshe7ca2b02019-08-01 11:09:45 -05001571 # stack_frame_ix to hide that information.
1572 stack_frame_ix = 1
1573 caller_func_name = sprint_func_name(1)
1574 if caller_func_name.endswith("print_error_report"):
1575 stack_frame_ix += 1
1576 caller_func_name = sprint_func_name(2)
1577 if caller_func_name.endswith("print_error_report"):
1578 stack_frame_ix += 1
Michael Walsh7bfa9ab2018-11-16 15:24:26 -06001579 buffer += sprint_call_stack(indent, stack_frame_ix)
Michael Walsh7423c012016-10-04 10:27:21 -05001580 buffer += sprint_pgm_header(indent)
1581 buffer += sprint_dashes(width=120, char="=")
1582
1583 return buffer
1584
Michael Walsh7423c012016-10-04 10:27:21 -05001585
Michael Walsh18176322016-11-15 15:11:21 -06001586def sprint_issuing(cmd_buf,
1587 test_mode=0):
Michael Walshde791732016-09-06 14:25:24 -05001588 r"""
1589 Return a line indicating a command that the program is about to execute.
1590
1591 Sample output for a cmd_buf of "ls"
1592
1593 #(CDT) 2016/08/25 17:57:36 - Issuing: ls
Michael Walshbec416d2016-11-10 08:54:52 -06001594
Michael Walsh4dbb6002019-05-17 15:51:15 -05001595 Description of argument(s):
Michael Walshde791732016-09-06 14:25:24 -05001596 cmd_buf The command to be executed by caller.
Michael Walsh46fcecb2019-10-16 17:11:59 -05001597 test_mode With test_mode set, the output will look like this:
Michael Walshbec416d2016-11-10 08:54:52 -06001598
1599 #(CDT) 2016/08/25 17:57:36 - (test_mode) Issuing: ls
1600
Michael Walshde791732016-09-06 14:25:24 -05001601 """
1602
Michael Walshbec416d2016-11-10 08:54:52 -06001603 buffer = sprint_time()
1604 if test_mode:
1605 buffer += "(test_mode) "
Michael Walsh61c12982019-03-28 12:38:01 -05001606 if type(cmd_buf) is list:
1607 # Assume this is a robot command in the form of a list.
1608 cmd_buf = ' '.join([str(element) for element in cmd_buf])
Michael Walshbec416d2016-11-10 08:54:52 -06001609 buffer += "Issuing: " + cmd_buf + "\n"
Michael Walshde791732016-09-06 14:25:24 -05001610
1611 return buffer
1612
Michael Walshde791732016-09-06 14:25:24 -05001613
Michael Walshde791732016-09-06 14:25:24 -05001614def sprint_pgm_footer():
Michael Walshde791732016-09-06 14:25:24 -05001615 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -05001616 Return a standardized footer that programs should print at the end of the program run. It includes
1617 useful information like total run time, etc.
Michael Walshde791732016-09-06 14:25:24 -05001618 """
1619
1620 buffer = "\n" + sprint_time() + "Finished running " + pgm_name + ".\n\n"
1621
1622 total_time = time.time() - start_time
1623 total_time_string = "%0.6f" % total_time
1624
Michael Walsh7423c012016-10-04 10:27:21 -05001625 buffer += sprint_varx(pgm_name_var_name + "_runtime", total_time_string)
Michael Walshbec416d2016-11-10 08:54:52 -06001626 buffer += "\n"
Michael Walsh7423c012016-10-04 10:27:21 -05001627
1628 return buffer
1629
Michael Walsh7423c012016-10-04 10:27:21 -05001630
Michael Walsh7423c012016-10-04 10:27:21 -05001631def sprint(buffer=""):
Michael Walsh7423c012016-10-04 10:27:21 -05001632 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -05001633 Simply return the user's buffer. This function is used by the qprint and dprint functions defined
1634 dynamically below, i.e. it would not normally be called for general use.
Michael Walsh7423c012016-10-04 10:27:21 -05001635
Michael Walsh4dbb6002019-05-17 15:51:15 -05001636 Description of argument(s).
Michael Walsh7423c012016-10-04 10:27:21 -05001637 buffer This will be returned to the caller.
1638 """
Michael Walshde791732016-09-06 14:25:24 -05001639
Michael Walsh95e45102018-02-09 12:44:43 -06001640 try:
1641 return str(buffer)
1642 except UnicodeEncodeError:
1643 return buffer
Michael Walshbec416d2016-11-10 08:54:52 -06001644
Michael Walshbec416d2016-11-10 08:54:52 -06001645
Michael Walshbec416d2016-11-10 08:54:52 -06001646def sprintn(buffer=""):
Michael Walshbec416d2016-11-10 08:54:52 -06001647 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -05001648 Simply return the user's buffer with a line feed. This function is used by the qprint and dprint
1649 functions defined dynamically below, i.e. it would not normally be called for general use.
Michael Walshbec416d2016-11-10 08:54:52 -06001650
Michael Walsh4dbb6002019-05-17 15:51:15 -05001651 Description of argument(s).
Michael Walshbec416d2016-11-10 08:54:52 -06001652 buffer This will be returned to the caller.
1653 """
1654
Michael Walsh95e45102018-02-09 12:44:43 -06001655 try:
1656 buffer = str(buffer) + "\n"
1657 except UnicodeEncodeError:
1658 buffer = buffer + "\n"
Michael Walshbec416d2016-11-10 08:54:52 -06001659
Michael Walshde791732016-09-06 14:25:24 -05001660 return buffer
1661
Michael Walsh168eb0f2017-12-01 15:35:32 -06001662
Michael Walshfd2733c2017-11-13 11:36:20 -06001663def gp_print(buffer,
1664 stream='stdout'):
Michael Walshfd2733c2017-11-13 11:36:20 -06001665 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -05001666 Print the buffer using either sys.stdout.write or BuiltIn().log_to_console depending on whether we are
1667 running in a robot environment.
Michael Walshfd2733c2017-11-13 11:36:20 -06001668
1669 This function is intended for use only by other functions in this module.
1670
Michael Walsh4dbb6002019-05-17 15:51:15 -05001671 Description of argument(s):
Michael Walshfd2733c2017-11-13 11:36:20 -06001672 buffer The string to be printed.
1673 stream Either "stdout" or "stderr".
1674 """
1675
1676 if robot_env:
1677 BuiltIn().log_to_console(buffer, stream=stream, no_newline=True)
1678 else:
1679 if stream == "stdout":
1680 sys.stdout.write(buffer)
1681 sys.stdout.flush()
1682 else:
1683 sys.stderr.write(buffer)
1684 sys.stderr.flush()
Michael Walshde791732016-09-06 14:25:24 -05001685
1686
Michael Walsh168eb0f2017-12-01 15:35:32 -06001687def gp_log(buffer):
Michael Walsh168eb0f2017-12-01 15:35:32 -06001688 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -05001689 Log the buffer using either python logging or BuiltIn().log depending on whether we are running in a
1690 robot environment.
Michael Walsh168eb0f2017-12-01 15:35:32 -06001691
1692 This function is intended for use only by other functions in this module.
1693
Michael Walsh4dbb6002019-05-17 15:51:15 -05001694 Description of argument(s):
Michael Walsh168eb0f2017-12-01 15:35:32 -06001695 buffer The string to be logged.
1696 """
1697
1698 if robot_env:
1699 BuiltIn().log(buffer)
1700 else:
1701 logging.warning(buffer)
1702
1703
Michael Walsh2ee77cd2017-03-08 11:50:17 -06001704def gp_debug_print(buffer):
Michael Walsh2ee77cd2017-03-08 11:50:17 -06001705 r"""
Michael Walshfd2733c2017-11-13 11:36:20 -06001706 Print with gp_print only if gen_print_debug is set.
Michael Walsh2ee77cd2017-03-08 11:50:17 -06001707
1708 This function is intended for use only by other functions in this module.
1709
Michael Walsh4dbb6002019-05-17 15:51:15 -05001710 Description of argument(s):
Michael Walsh2ee77cd2017-03-08 11:50:17 -06001711 buffer The string to be printed.
1712 """
1713
1714 if not gen_print_debug:
1715 return
1716
Michael Walshfd2733c2017-11-13 11:36:20 -06001717 gp_print(buffer)
Michael Walsh2ee77cd2017-03-08 11:50:17 -06001718
1719
Michael Walshb1500152017-04-12 15:42:43 -05001720def get_var_value(var_value=None,
1721 default=1,
1722 var_name=None):
Michael Walsh2ee77cd2017-03-08 11:50:17 -06001723 r"""
Michael Walshb1500152017-04-12 15:42:43 -05001724 Return either var_value, the corresponding global value or default.
Michael Walsh2ee77cd2017-03-08 11:50:17 -06001725
Michael Walshb1500152017-04-12 15:42:43 -05001726 If var_value is not None, it will simply be returned.
Michael Walsh2ee77cd2017-03-08 11:50:17 -06001727
Michael Walsh46fcecb2019-10-16 17:11:59 -05001728 If var_value is None, this function will return the corresponding global value of the variable in
1729 question.
Michael Walshb1500152017-04-12 15:42:43 -05001730
Michael Walsh46fcecb2019-10-16 17:11:59 -05001731 Note: For global values, if we are in a robot environment, get_variable_value will be used. Otherwise,
1732 the __builtin__ version of the variable is returned (which are set by gen_arg.py functions).
Michael Walshb1500152017-04-12 15:42:43 -05001733
Michael Walsh46fcecb2019-10-16 17:11:59 -05001734 If there is no global value associated with the variable, default is returned.
Michael Walshb1500152017-04-12 15:42:43 -05001735
Michael Walsh46fcecb2019-10-16 17:11:59 -05001736 This function is useful for other functions in setting default values for parameters.
Michael Walshb1500152017-04-12 15:42:43 -05001737
1738 Example use:
1739
1740 def my_func(quiet=None):
1741
1742 quiet = int(get_var_value(quiet, 0))
1743
1744 Example calls to my_func():
1745
Michael Walsh46fcecb2019-10-16 17:11:59 -05001746 In the following example, the caller is explicitly asking to have quiet be set to 1.
Michael Walshb1500152017-04-12 15:42:43 -05001747
1748 my_func(quiet=1)
1749
Michael Walsh46fcecb2019-10-16 17:11:59 -05001750 In the following example, quiet will be set to the global value of quiet, if defined, or to 0 (the
1751 default).
Michael Walshb1500152017-04-12 15:42:43 -05001752
1753 my_func()
Michael Walsh2ee77cd2017-03-08 11:50:17 -06001754
Michael Walsh4dbb6002019-05-17 15:51:15 -05001755 Description of argument(s):
Michael Walsh46fcecb2019-10-16 17:11:59 -05001756 var_value The value to be returned (if not equal to None).
1757 default The value that is returned if var_value is None and there is no
1758 corresponding global value defined.
1759 var_name The name of the variable whose value is to be returned. Under most
1760 circumstances, this value need not be provided. This function can figure
1761 out the name of the variable passed as var_value. One exception to this
1762 would be if this function is called directly from a .robot file.
Michael Walsh2ee77cd2017-03-08 11:50:17 -06001763 """
1764
Michael Walshb1500152017-04-12 15:42:43 -05001765 if var_value is not None:
1766 return var_value
1767
1768 if var_name is None:
1769 var_name = get_arg_name(None, 1, 2)
1770
Michael Walsh2ee77cd2017-03-08 11:50:17 -06001771 if robot_env:
Michael Walshc6537442017-06-06 15:33:52 -05001772 var_value = BuiltIn().get_variable_value("${" + var_name + "}",
1773 default)
Michael Walsh2ee77cd2017-03-08 11:50:17 -06001774 else:
1775 var_value = getattr(__builtin__, var_name, default)
1776
1777 return var_value
1778
Michael Walsh2ee77cd2017-03-08 11:50:17 -06001779
Michael Walsh052ff812018-05-18 16:09:09 -05001780def get_stack_var(var_name,
1781 default="",
1782 init_stack_ix=2):
Michael Walsh052ff812018-05-18 16:09:09 -05001783 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -05001784 Starting with the caller's stack level, search upward in the call stack for a variable named var_name and
1785 return its value. If the variable cannot be found in the stack, attempt to get the global value. If the
Michael Walshc9a7ee72019-08-28 16:45:50 -05001786 variable still cannot be found, return default.
Michael Walsh052ff812018-05-18 16:09:09 -05001787
1788 Example code:
1789
1790 def func12():
1791 my_loc_var1 = get_stack_var('my_var1', "default value")
1792
1793 def func11():
1794 my_var1 = 11
1795 func12()
1796
Michael Walsh46fcecb2019-10-16 17:11:59 -05001797 In this example, get_stack_var will find the value of my_var1 in func11's stack and will therefore return
1798 the value 11. Therefore, my_loc_var1 would get set to 11.
Michael Walsh052ff812018-05-18 16:09:09 -05001799
1800 Description of argument(s):
Michael Walsh46fcecb2019-10-16 17:11:59 -05001801 var_name The name of the variable to be searched for.
1802 default The value to return if the the variable cannot be found.
1803 init_stack_ix The initial stack index from which to begin the search. 0 would be the
1804 index of this func1tion ("get_stack_var"), 1 would be the index of the
1805 function calling this function, etc.
Michael Walsh052ff812018-05-18 16:09:09 -05001806 """
1807
Michael Walsh6f0362c2019-03-25 14:05:14 -05001808 work_around_inspect_stack_cwd_failure()
Michael Walshc9a7ee72019-08-28 16:45:50 -05001809 default = get_var_value(var_name=var_name, default=default)
Michael Walsh052ff812018-05-18 16:09:09 -05001810 return next((frame[0].f_locals[var_name]
Joy Onyerikwu004ad3c2018-06-11 16:29:56 -05001811 for frame in inspect.stack()[init_stack_ix:]
1812 if var_name in frame[0].f_locals), default)
Michael Walsh052ff812018-05-18 16:09:09 -05001813
1814
Michael Walsh46fcecb2019-10-16 17:11:59 -05001815# hidden_text is a list of passwords which are to be replaced with asterisks by print functions defined in
1816# this module.
Michael Walsh82acf002017-05-04 14:33:05 -05001817hidden_text = []
1818# password_regex is created based on the contents of hidden_text.
1819password_regex = ""
1820
1821
Michael Walsh82acf002017-05-04 14:33:05 -05001822def register_passwords(*args):
Michael Walsh82acf002017-05-04 14:33:05 -05001823 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -05001824 Register one or more passwords which are to be hidden in output produced by the print functions in this
1825 module.
Michael Walsh82acf002017-05-04 14:33:05 -05001826
1827 Note: Blank password values are NOT registered. They are simply ignored.
1828
1829 Description of argument(s):
Michael Walsh46fcecb2019-10-16 17:11:59 -05001830 args One or more password values. If a given password value is already
1831 registered, this function will simply do nothing.
Michael Walsh82acf002017-05-04 14:33:05 -05001832 """
1833
1834 global hidden_text
1835 global password_regex
1836
1837 for password in args:
1838 if password == "":
1839 break
1840 if password in hidden_text:
1841 break
1842
1843 # Place the password into the hidden_text list.
1844 hidden_text.append(password)
Michael Walsh46fcecb2019-10-16 17:11:59 -05001845 # Create a corresponding password regular expression. Escape regex special characters too.
Michael Walsh82acf002017-05-04 14:33:05 -05001846 password_regex = '(' +\
1847 '|'.join([re.escape(x) for x in hidden_text]) + ')'
1848
Michael Walsh82acf002017-05-04 14:33:05 -05001849
Michael Walsh82acf002017-05-04 14:33:05 -05001850def replace_passwords(buffer):
Michael Walsh82acf002017-05-04 14:33:05 -05001851 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -05001852 Return the buffer but with all registered passwords replaced by a string of asterisks.
Michael Walsh82acf002017-05-04 14:33:05 -05001853
1854
1855 Description of argument(s):
Michael Walsh46fcecb2019-10-16 17:11:59 -05001856 buffer The string to be returned but with passwords replaced.
Michael Walsh82acf002017-05-04 14:33:05 -05001857 """
1858
1859 global password_regex
1860
1861 if int(os.environ.get("DEBUG_SHOW_PASSWORDS", "0")):
1862 return buffer
1863
1864 if password_regex == "":
1865 # No passwords to replace.
1866 return buffer
1867
1868 return re.sub(password_regex, "********", buffer)
1869
Michael Walshfd2733c2017-11-13 11:36:20 -06001870
1871def create_print_wrapper_funcs(func_names,
1872 stderr_func_names,
Michael Walsh61c12982019-03-28 12:38:01 -05001873 replace_dict,
1874 func_prefix=""):
Michael Walshfd2733c2017-11-13 11:36:20 -06001875 r"""
Michael Walsh46fcecb2019-10-16 17:11:59 -05001876 Generate code for print wrapper functions and return the generated code as a string.
Michael Walshfd2733c2017-11-13 11:36:20 -06001877
Michael Walsh46fcecb2019-10-16 17:11:59 -05001878 To illustrate, suppose there is a "print_foo_bar" function in the func_names list.
Michael Walshfd2733c2017-11-13 11:36:20 -06001879 This function will...
1880 - Expect that there is an sprint_foo_bar function already in existence.
Michael Walsh46fcecb2019-10-16 17:11:59 -05001881 - Create a print_foo_bar function which calls sprint_foo_bar and prints the result.
1882 - Create a qprint_foo_bar function which calls upon sprint_foo_bar only if global value quiet is 0.
1883 - Create a dprint_foo_bar function which calls upon sprint_foo_bar only if global value debug is 1.
Michael Walshfd2733c2017-11-13 11:36:20 -06001884
Michael Walsh46fcecb2019-10-16 17:11:59 -05001885 Also, code will be generated to define aliases for each function as well. Each alias will be created by
1886 replacing "print_" in the function name with "p" For example, the alias for print_foo_bar will be
1887 pfoo_bar.
Michael Walshfd2733c2017-11-13 11:36:20 -06001888
1889 Description of argument(s):
Michael Walsh46fcecb2019-10-16 17:11:59 -05001890 func_names A list of functions for which print wrapper function code is to be
1891 generated.
1892 stderr_func_names A list of functions whose generated code should print to stderr rather
1893 than to stdout.
1894 replace_dict Please see the create_func_def_string function in wrap_utils.py for
1895 details on this parameter. This parameter will be passed directly to
1896 create_func_def_string.
1897 func_prefix Prefix to be pre-pended to the generated function name.
Michael Walshfd2733c2017-11-13 11:36:20 -06001898 """
1899
1900 buffer = ""
1901
1902 for func_name in func_names:
1903 if func_name in stderr_func_names:
1904 replace_dict['output_stream'] = "stderr"
1905 else:
1906 replace_dict['output_stream'] = "stdout"
1907
1908 s_func_name = "s" + func_name
1909 q_func_name = "q" + func_name
1910 d_func_name = "d" + func_name
1911
Michael Walsh46fcecb2019-10-16 17:11:59 -05001912 # We don't want to try to redefine the "print" function, thus the following if statement.
Michael Walshfd2733c2017-11-13 11:36:20 -06001913 if func_name != "print":
Michael Walsh61c12982019-03-28 12:38:01 -05001914 func_def = create_func_def_string(s_func_name,
1915 func_prefix + func_name,
Michael Walshfd2733c2017-11-13 11:36:20 -06001916 print_func_template,
1917 replace_dict)
1918 buffer += func_def
1919
Michael Walsh61c12982019-03-28 12:38:01 -05001920 func_def = create_func_def_string(s_func_name,
1921 func_prefix + "q" + func_name,
Michael Walshfd2733c2017-11-13 11:36:20 -06001922 qprint_func_template, replace_dict)
1923 buffer += func_def
1924
Michael Walsh61c12982019-03-28 12:38:01 -05001925 func_def = create_func_def_string(s_func_name,
1926 func_prefix + "d" + func_name,
Michael Walshfd2733c2017-11-13 11:36:20 -06001927 dprint_func_template, replace_dict)
1928 buffer += func_def
1929
Michael Walsh61c12982019-03-28 12:38:01 -05001930 func_def = create_func_def_string(s_func_name,
1931 func_prefix + "l" + func_name,
Michael Walsh168eb0f2017-12-01 15:35:32 -06001932 lprint_func_template, replace_dict)
1933 buffer += func_def
1934
Michael Walshfd2733c2017-11-13 11:36:20 -06001935 # Create abbreviated aliases (e.g. spvar is an alias for sprint_var).
1936 alias = re.sub("print_", "p", func_name)
1937 alias = re.sub("print", "p", alias)
Michael Walsh61c12982019-03-28 12:38:01 -05001938 prefixes = [func_prefix + "", "s", func_prefix + "q",
1939 func_prefix + "d", func_prefix + "l"]
Michael Walshfd2733c2017-11-13 11:36:20 -06001940 for prefix in prefixes:
1941 if alias == "p":
1942 continue
1943 func_def = prefix + alias + " = " + prefix + func_name
1944 buffer += func_def + "\n"
1945
1946 return buffer
Michael Walsh82acf002017-05-04 14:33:05 -05001947
1948
Michael Walsh46fcecb2019-10-16 17:11:59 -05001949# In the following section of code, we will dynamically create print versions for each of the sprint
1950# functions defined above. So, for example, where we have an sprint_time() function defined above that
1951# returns the time to the caller in a string, we will create a corresponding print_time() function that will
1952# print that string directly to stdout.
Michael Walshde791732016-09-06 14:25:24 -05001953
Michael Walsh46fcecb2019-10-16 17:11:59 -05001954# It can be complicated to follow what's being created below. Here is an example of the print_time()
1955# function that will be created:
Michael Walshde791732016-09-06 14:25:24 -05001956
Michael Walshfd2733c2017-11-13 11:36:20 -06001957# def print_time(buffer=''):
Michael Walsh61c12982019-03-28 12:38:01 -05001958# gp_print(replace_passwords(sprint_time(buffer=buffer)), stream='stdout')
1959
Michael Walsh46fcecb2019-10-16 17:11:59 -05001960# For each print function defined below, there will also be a qprint, a dprint and an lprint version defined
1961# (e.g. qprint_time, dprint_time, lprint_time).
Michael Walsh61c12982019-03-28 12:38:01 -05001962
Michael Walsh46fcecb2019-10-16 17:11:59 -05001963# The q version of each print function will only print if the quiet variable is 0.
1964# The d version of each print function will only print if the debug variable is 1.
1965# The l version of each print function will print the contents as log data. For conventional programs, this
1966# means use of the logging module. For robot programs it means use of the BuiltIn().log() function.
Michael Walshde791732016-09-06 14:25:24 -05001967
Michael Walshfd2733c2017-11-13 11:36:20 -06001968# Templates for the various print wrapper functions.
1969print_func_template = \
1970 [
Joy Onyerikwu004ad3c2018-06-11 16:29:56 -05001971 " <mod_qualifier>gp_print(<mod_qualifier>replace_passwords("
1972 + "<call_line>), stream='<output_stream>')"
Michael Walshfd2733c2017-11-13 11:36:20 -06001973 ]
1974
1975qprint_func_template = \
1976 [
Michael Walshc9a7ee72019-08-28 16:45:50 -05001977 " quiet = <mod_qualifier>get_stack_var(\"quiet\", 0)",
Michael Walsh589ae762019-03-19 13:22:39 -05001978 " if int(quiet): return"
Michael Walshfd2733c2017-11-13 11:36:20 -06001979 ] + print_func_template
1980
1981dprint_func_template = \
1982 [
Michael Walshc9a7ee72019-08-28 16:45:50 -05001983 " debug = <mod_qualifier>get_stack_var(\"debug\", 0)",
Michael Walsh589ae762019-03-19 13:22:39 -05001984 " if not int(debug): return"
Michael Walshfd2733c2017-11-13 11:36:20 -06001985 ] + print_func_template
1986
Michael Walsh168eb0f2017-12-01 15:35:32 -06001987lprint_func_template = \
1988 [
Michael Walsh61c12982019-03-28 12:38:01 -05001989 " <mod_qualifier>set_last_seconds_ix(<mod_qualifier>"
1990 + "lprint_last_seconds_ix())",
1991 " <mod_qualifier>gp_log(<mod_qualifier>replace_passwords"
1992 + "(<call_line>))",
1993 " <mod_qualifier>set_last_seconds_ix(<mod_qualifier>"
1994 + "standard_print_last_seconds_ix())"
Michael Walsh168eb0f2017-12-01 15:35:32 -06001995 ]
1996
Michael Walsh81c02342018-01-05 15:43:28 -06001997replace_dict = {'output_stream': 'stdout', 'mod_qualifier': ''}
Michael Walshfd2733c2017-11-13 11:36:20 -06001998
Michael Walsh61c12982019-03-28 12:38:01 -05001999gp_debug_print("robot_env: " + str(robot_env) + "\n")
Michael Walshde791732016-09-06 14:25:24 -05002000
Michael Walsh46fcecb2019-10-16 17:11:59 -05002001# func_names contains a list of all print functions which should be created from their sprint counterparts.
Michael Walshde791732016-09-06 14:25:24 -05002002func_names = ['print_time', 'print_timen', 'print_error', 'print_varx',
Michael Walsh18176322016-11-15 15:11:21 -06002003 'print_var', 'print_vars', 'print_dashes', 'indent',
2004 'print_call_stack', 'print_func_name', 'print_executing',
2005 'print_pgm_header', 'print_issuing', 'print_pgm_footer',
2006 'print_error_report', 'print', 'printn']
Michael Walshde791732016-09-06 14:25:24 -05002007
Michael Walsh46fcecb2019-10-16 17:11:59 -05002008# stderr_func_names is a list of functions whose output should go to stderr rather than stdout.
Michael Walsh2ee77cd2017-03-08 11:50:17 -06002009stderr_func_names = ['print_error', 'print_error_report']
Michael Walshde791732016-09-06 14:25:24 -05002010
Michael Walshfd2733c2017-11-13 11:36:20 -06002011func_defs = create_print_wrapper_funcs(func_names, stderr_func_names,
2012 replace_dict)
2013gp_debug_print(func_defs)
2014exec(func_defs)