debugtrace 1.5.0

Output trace logs when debugging Python programs

DebugTrace-py

Japanese

DebugTrace-py is a library that outputs trace logs when debugging your Python programs. It supports Python 3.7 or later. By embedding "_ = debugtrace.enter()" at the start of the method, you can output the execution status of the program under development.

1. Features

• Automatically outputs the method name, source file name and line number of invokers of debugtrace.enter function.
• Also outputs end logs when the scope ends.
• Indents logs automatically with nested methods and objects.
• Automatically line breaks in value output.
• Uses reflection to output content even for objects of classes that do not implement the __str__ method.
• You can customize output contents by setting debugtrace.ini file.
• You can select sys.stdout, sys.stderr or logging.Logger to output.

2. Install

pip install debugtrace

3. How to use

Do the following for the debug target and related functions and methods:

• Insert "_ = debugtrace.enter()" at the beginning of functions and methods.
• Insert "debugtrace.print('foo', foo)" to output variables to the log if necessary.

The following is an example of a Python program using DebugTrace-py and a log when it is executed.

# readme_example.py
import datetime
import debugtrace

# Contact class
class Contact(object):
    def __init__(self, id: int, firstName: str, lastName: str, birthday: datetime.date) -> None:
        _ = debugtrace.enter(self)
        self.id = id
        self.firstName = firstName
        self.lastName  = lastName
        self.birthday  = birthday

def func2():
    _ = debugtrace.enter()
    contact = [
        Contact(1, 'Akane' , 'Apple', datetime.date(1991, 2, 3)),
        Contact(2, 'Yukari', 'Apple', datetime.date(1992, 3, 4))
    ]
    debugtrace.print('contact', contact)

def func1():
    _ = debugtrace.enter()
    debugtrace.print('Hello, World!')
    func2()

func1()

Log output contents:

2025-06-01 20:52:25.578627+0900 DebugTrace-py 1.5.0 on Python 3.13.2
2025-06-01 20:52:25.580427+0900   config file path: Tests/debugtrace.ini
2025-06-01 20:52:25.581744+0900   logger: File: 'Tests/logs/debugtrace.log', append: False
2025-06-01 20:52:25.582618+0900 
2025-06-01 20:52:25.583340+0900 ______________________________ MainThread #140621705785856 ______________________________
2025-06-01 20:52:25.584029+0900 
2025-06-01 20:52:25.585793+0900 Enter func1 (readme_example.py:22) <- (readme_example.py:26)
2025-06-01 20:52:25.586647+0900 | Hello, World! (readme_example.py:23)
2025-06-01 20:52:25.587471+0900 | Enter func2 (readme_example.py:14) <- (readme_example.py:24)
2025-06-01 20:52:25.588197+0900 | | Enter Contact.__init__ (readme_example.py:7) <- (readme_example.py:16)
2025-06-01 20:52:25.588852+0900 | | Leave Contact.__init__ (readme_example.py:7) duration: 0:00:00.000009
2025-06-01 20:52:25.589701+0900 | | 
2025-06-01 20:52:25.590445+0900 | | Enter Contact.__init__ (readme_example.py:7) <- (readme_example.py:17)
2025-06-01 20:52:25.591155+0900 | | Leave Contact.__init__ (readme_example.py:7) duration: 0:00:00.000023
2025-06-01 20:52:25.592112+0900 | | 
2025-06-01 20:52:25.592785+0900 | | contacts = [
2025-06-01 20:52:25.593440+0900 | |   (__main__.Contact){
2025-06-01 20:52:25.594087+0900 | |   birthday: 1991-02-03, firstName: 'Akane', id: 1, lastName: 'Apple'
2025-06-01 20:52:25.594773+0900 | |   },
2025-06-01 20:52:25.595472+0900 | |   (__main__.Contact){
2025-06-01 20:52:25.596132+0900 | |   birthday: 1992-03-04, firstName: 'Yukari', id: 2, lastName: 'Apple'
2025-06-01 20:52:25.596794+0900 | |   }
2025-06-01 20:52:25.597437+0900 | | ] (readme_example.py:19)
2025-06-01 20:52:25.598082+0900 | | 
2025-06-01 20:52:25.598823+0900 | Leave func2 (readme_example.py:14) duration: 0:00:00.010653
2025-06-01 20:52:25.599625+0900 Leave func1 (readme_example.py:22) duration: 0:00:00.013041

4. Functions

There are mainly the following functions.

Function list

Name	Discription
enter	Outputs an entering log Also outputs a leaving log at the end of the code block. Arguments: invoker (object, optional): Pass the self or cls of the invoker. Examples: _ = debugtrace.enter(self) _ = debugtrace.enter(cls) _ = debugtrace.enter()
print	Outputs the variable name and value Arguments: name (str): Variable name, etc value (object, optional): Value to output (output only name if omitted) The following are keyword arguments reflection (bool, optional): If True, outputs using reflection even if it has a __str__ or __repr__ method (default: False) output_private (bool, optional): If True, also outputs private members when using reflection (default: False) output_method (bool, optional): If True, also outputs method members when using reflection (default: False) collection_limit (int, optional): The limit value of elements such as list, tuple and dict to output (default: -1) bytes_limit (int, optional): The limit value of elements for bytes and bytearray to output (default: -1) string_limit (int, optional): The limit value of characters for string to output (default: -1) reflection_limit (int, optional): The The limit value for reflection nesting (default: -1) Examples: debugtrace.print('Hellow') debugtrace.print('foo', foo) debugtrace.print('foo', foo, reflection=True) debugtrace.print('foos', foos, collection_limit=1024)

5. Options that can be specified in the configuration file

DebugTrace-py reads the file specified by the environment variable DEBUGTRACE_CONFIG or the debugtrace.ini file in the current directory as a configuration file at initialization. The section in the configuration file is [debugtrace].

You can specify the following options in the configuration file.

debugtrace.ini

Option Name	Description
logger	The logger used by debugtrace Examples: stdout - Output to sys.stdout stderr - Output to sys.stderr logger - Output using logging package file:< log file path> - Output directly to the file Default Value: stderr
logging_config_file	The configuration file name specified in logging package Default Value: logging.conf
logging_logger_name	The logger name when using the logging package Default Value: debugtrace
log_datetime_format	Log date and time format when logger is StdOut or StdErr Default Value: %Y-%m-%d %H:%M:%S.%f%z
enabled	Enables logging if true,disables logging if false Examples: False: Log output is disabled True: Log output is enabled Default Value: True
enter_format	The format string of log output when entering functions or methods Parameters: {0}: The function or method name {1}: The file name {2}: The line number {3}: The file name of the caller {4}: The line number of the caller Default Value: Enter {0} ({1}:{2}) <- ({3}:{4})
leave_format	The format string of log output when leaving functions or methods Parameters: {0}: The function or method name {1}: The file name {2}: The line number {3}: The time since entered Default Value: Leave {0} ({1}:{2}) duration: {3}
thread_boundary_format	The format string of logging at threads boundary Parameters: {0}: The thread name {1}: The thread ID Default Value: ______________________________ {0} #{1} ______________________________
maximum_indents	The maximum number of indents Default Value: 32
indent_string	The indentation string for code Default Value: \s
data_indent_string	The indentation string for data Default Value: \s\s
limit_string	The string to represent that it has exceeded the limit Default Value: ...
non_output_string (Currently unused)	The string to be output instead of not outputting value Default Value: ...
circular_reference_string	The string to represent that the cyclic reference occurs Default Value: *** Cyclic Reference ***
varname_value_separator	The separator string between the variable name and value Default Value: \s=\s
key_value_separator	The separator string between the key and value of dictionary and between the attribute name and value Default Value: :\s
print_suffix_format	The format string of print method suffix Default Value: \s({1}:{2})
count_format	The format string of the number of elements for list, tuple and dict Default Value: count:{}
minimum_output_count	The minimum value to output the number of elements for list, tuple and dict Default Value: 128
length_format	The format string of the length of string and bytes Default Value: length:{}
minimum_output_length	The minimum value to output the length of string and bytes Default Value: 256
data_output_width	The maximum output width of data Default Value: 70
bytes_count_in_line	The count in line of bytes Default Value: 16
collection_limit	The limit value of elements for list, tuple and dict to output Default Value: 128
bytes_limit	The limit value of elements for bytes and bytearray to output Default Value: 256
string_limit	The limit value of characters for string to output Default Value: 256
reflection_limit	The The limit value for reflection nesting Default Value: 4

Converts \s to space.

6. CHANGELOG

CHANGELOG

7. License

MIT License (MIT)

© 2020 Masato Kokubo