Module entry_trace.

3. entry_trace

The etrace decorator can be used on a function or method to add a debug log item upon entry and exit. The entry trace log item will include the filename, function or method name, the line number where it is defined, and the specified args and/or kwargs. The exit trace will include the return value.

The decorator can be controlled via the following parameters:

  1. enable_trace: boolean value that when True will enable the trace. The default is True.

  2. omit_parms: list of parameter names whose argument values should appear in the trace as ellipses. This can help reduce the size of the trace entry for large arguments. The default is None.

  3. omit_return_value: if True, do not trace the return value in the exit trace entry. The default is False.

  4. omit_caller: if True, the call sequence will not be traced.

Example 1:

Decorate a function with no args nor kwargs.

from scottbrian_utils.entry_trace import etrace

@etrace
def f1() -> None:
    pass

f1()

Expected trace output for Example 1:

test_entry_trace.py::f1:69 entry: caller: test_entry_trace.py::TestEntryTraceExamples.test_etrace_example1:77
test_entry_trace.py::f1:69 exit: return_value=None
Example 2:

Decorate a function that has 1 positional arg and 1 keyword arg.

from scottbrian_utils.entry_trace import etrace

@etrace
def f1(a1: int, kw1: str = "42") -> str:
    return f"{a1=}, {kw1=}"

f1(42, kw1="forty two")

Expected trace output for Example 2:

test_entry_trace.py::f1:122 entry: a1=42, kw1='forty two', caller: test_entry_trace.py::TestEntryTraceExamples.test_etrace_example2:130
test_entry_trace.py::f1:122 exit: return_value="a1=42, kw1='forty two'"
Example 3:

Decorate two functions, the first with etrace enabled and the second with etrace disabled.

from scottbrian_utils.entry_trace import etrace

do_trace: bool = True

@etrace(enable_trace=do_trace)
def f1(a1: int, kw1: str = "42") -> str:
    return f"{a1=}, {kw1=}"

do_trace: bool = False

@etrace(enable_trace=do_trace)
def f2(a1: int, kw1: str = "42"):
    return f"{a1=}, {kw1=}"

f1(42, kw1="forty two")
f2(24, kw1="twenty four")

Expected trace output for Example 3:

test_entry_trace.py::f1:180 entry: a1=42, kw1='forty two', caller: test_entry_trace.py::TestEntryTraceExamples.test_etrace_example3:194
test_entry_trace.py::f1:180 exit: return_value="a1=42, kw1='forty two'"
Example 4:

Decorate a function with the positional arg omitted.

from scottbrian_utils.entry_trace import etrace

@etrace(omit_parms=["a1"])
def f1(a1: int, kw1: str = "42") -> str:
    return f"{a1=}, {kw1=}"

f1(42, kw1="forty two")

Expected trace output for Example 4:

test_entry_trace.py::f1:244 entry: a1='...', kw1='forty two', caller: test_entry_trace.py::TestEntryTraceExamples.test_etrace_example4:252
test_entry_trace.py::f1:244 exit: return_value="a1=42, kw1='forty two'"
Example 5:

Decorate a function with the first keyword arg omitted.

from scottbrian_utils.entry_trace import etrace

@etrace(omit_parms="kw1")
def f1(a1: int, kw1: str = "42", kw2: int = 24) -> str:
    return f"{a1=}, {kw1=}, {kw2=}"

f1(42, kw1="forty two", kw2=84)

Expected trace output for Example 5:

test_entry_trace.py::f1:300 entry: a1=42, kw1='...', kw2=84, caller: test_entry_trace.py::TestEntryTraceExamples.test_etrace_example5:308
test_entry_trace.py::f1:300 exit: return_value="a1=42, kw1='forty two', kw2=84"
Example 6:

Decorate a function with the return value omitted.

from scottbrian_utils.entry_trace import etrace

@etrace(omit_return_value=True)
def f1(a1: int, kw1: str = "42", kw2: int = 24) -> str:
    return f"{a1=}, {kw1=}, {kw2=}"

f1(42, kw1="forty two", kw2=84)

Expected trace output for Example 6:

  test_entry_trace.py::f1:347 entry: a1=42, kw1='forty two', kw2=84, caller: test_entry_trace.py::TestEntryTraceExamples.test_etrace_example6:356
  test_entry_trace.py::f1:347 exit: return value omitted

.. # noqa: E501, W505
entry_trace.etrace(wrapped=None, *, enable_trace=True, omit_parms=None, omit_return_value=False, omit_caller=False, latest=1, depth=1, log_ver=False)

Decorator to produce entry/exit log.

Parameters:

  • wrapped (Optional[TypeVar(F, bound= Callable[..., Any])]) – function to be decorated

  • enable_trace (Union[bool, Callable[..., bool]]) – if True, trace the entry and exit for the decorated function or method.

  • omit_parms (Optional[Iterable[str]]) – list of parameter names whose argument values should appear in the trace as ellipses. This can help reduce the size of the trace entry for large arguments.

  • omit_return_value (bool) – if True, do not place the return value into the exit trace entry.

  • omit_caller (bool) – if True, the call sequence will not be traced.

  • latest (int) – specifies the position in the call sequence that is to be designated as the caller named in the trace output. A value of 1, the default, specifies that the caller is one call back in the sequence and is the normal case. A value greater than 1 is useful when decorators are stacked and the caller of interest is thus further back in the sequence. Note that latest will be ignored if omit_caller is True.

  • depth (int) – specifies the depth of the call sequence to include in the trace output. A value of 1, the default, species that only the latest caller is to be included. Values greater than 1 will include the latest caller and its callers. Note that depth will be ignored if omit_caller is True.

  • log_ver (Union[bool, LogVer]) –

    specifies that the etrace log messages should be added to an instance of LogVer (scottbrian_utils.log_verifier) to be verified along with any other log messages being issued and verified. This is intended for use in a testing environment (e.g., pytest) where the etrace wrapped method is a test case method in a class. There are two possible specifications:

    1. bool: log_ver=True specifies that an instance of LogVer should be instantiated in the class that contains the method that etrace is decorating, and the entry and exit log message for the method will be added to the instantiated log verifier. Note that a new LogVer instance is created for each invocation of the method since pytest could be calling the test method repeatedly with a new set of inputs. log_ver=False (the default) specifies that a LogVer is not to be instantiated by etrace and the entry and exit log messages will not be added to a LogVer instance by etrace.

    2. LogVer: log_ver=log_ver_instance: specifies that the etrace log messages should be added to the LogVer instance specified by log_ver_instance. This is useful for inner functions of a test case where a LogVer instance already exists (e.g., an instance created in the outer method using etrace(log_ver=True)).

Return type:

TypeVar(F, bound= Callable[..., Any])

Returns:

funtools partial (when wrapped is None) or decorated function

Notes

  1. In both the entry and exit trace, the line number following the decorated function or method will be the line number of the etrace decorator. The trace message itself, however, will include the name of the traced function or method along with the line number where it is defined.

  2. The positional and keyword arguments (if any) will appear after “entry:”.

  3. Unless omit_caller is specified as False, the caller of the traced function or method will appear after “caller:” and will include the line number of the call.

  4. The exit trace will include the return value unless omit_return_value specifies True.