Module entry_trace.

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.

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, latest=1, depth=1)

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.

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

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

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