Output trace logs when debugging Python programs
Project description
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.
# ReadmeExample.py import datetime import debugtrace # ToDo: Remove after debugging # Contact class class Contact(object): def __init__(self, id: int, firstName: str, lastName: str, birthday: datetime.date) -> None: _ = debugtrace.enter(self) # ToDo: Remove after debugging self.id = id self.firstName = firstName self.lastName = lastName self.birthday = birthday def func2(): _ = debugtrace.enter() # ToDo: Remove after debugging contact = [ Contact(1, 'Akane' , 'Apple', datetime.date(1991, 2, 3)), Contact(2, 'Yukari', 'Apple', datetime.date(1992, 3, 4)) ] debugtrace.print('contact', contact) # ToDo: Remove after debugging def func1(): _ = debugtrace.enter() # ToDo: Remove after debugging debugtrace.print('Hello, World!') # ToDo: Remove after debugging func2() func1()
Log output contents:
2021-11-27 12:31:10.543520 DebugTrace-py 1.1.0 2021-11-27 12:31:10.543564 config file path: <No config file> 2021-11-27 12:31:10.543591 logger: sys.stderr 2021-11-27 12:31:10.543611 2021-11-27 12:31:10.544491 Enter func1 (ReadmeExample.py:22) 2021-11-27 12:31:10.544561 | Hello, World! (ReadmeExample.py:23) 2021-11-27 12:31:10.544619 | Enter func2 (ReadmeExample.py:14) 2021-11-27 12:31:10.544684 | | Enter Contact.__init__ (ReadmeExample.py:7) 2021-11-27 12:31:10.544722 | | Leave Contact.__init__ (ReadmeExample.py:7) duration: 0:00:00.000005 2021-11-27 12:31:10.544777 | | 2021-11-27 12:31:10.544806 | | Enter Contact.__init__ (ReadmeExample.py:7) 2021-11-27 12:31:10.544840 | | Leave Contact.__init__ (ReadmeExample.py:7) duration: 0:00:00.000004 2021-11-27 12:31:10.545193 | | 2021-11-27 12:31:10.545220 | | contacts = [ 2021-11-27 12:31:10.545243 | | (__main__.Contact){ 2021-11-27 12:31:10.545266 | | birthday: 1991-02-03, firstName: (length:5)'Akane', id: 1, 2021-11-27 12:31:10.545295 | | lastName: (length:5)'Apple' 2021-11-27 12:31:10.545318 | | }, 2021-11-27 12:31:10.545345 | | (__main__.Contact){ 2021-11-27 12:31:10.545368 | | birthday: 1992-03-04, firstName: (length:6)'Yukari', id: 2, 2021-11-27 12:31:10.545395 | | lastName: (length:5)'Apple' 2021-11-27 12:31:10.545417 | | } 2021-11-27 12:31:10.545444 | | ] (ReadmeExample.py:19) 2021-11-27 12:31:10.545470 | | 2021-11-27 12:31:10.545506 | Leave func2 (ReadmeExample.py:14) duration: 0:00:00.000824 2021-11-27 12:31:10.545537 Leave func1 (ReadmeExample.py:22) duration: 0:00:00.001010
4. Functions
There are mainly the following functions.
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. (Optional)
Examples:
_ = debugtrace.enter(self)
_ = debugtrace.enter(cls)
_ = debugtrace.enter()
|
Outputs the variable name and value.
Arguments:
name (str): Variable name, etc.
value (object): Output value
output_private (bool): Output private member if True (default: False)
output_method (bool): Output method if True (default: False)
The following are keyword arguments and can be omitted.
force_reflection (bool): If true, outputs using reflection even if it has a __str__ or __repr__ method (default: False)
output_private (bool): If true, also outputs private members when using reflection (default: False)
output_method (bool): If true, also outputs method members when using reflection (default: False)
collection_limit (int): The limit value of elements such as list, tuple and dict to output (default: None)
bytes_limit (int): The limit value of elements for bytes and bytearray to output (default: None)
string_limit (int): The limit value of characters for string to output (default: None)
reflection_nest_limit (int): The The limit value for reflection nesting (default: None)
Examples:
debugtrace.print('Hellow')
debugtrace.print('foo', foo)
debugtrace.print('foo', foo, force_reflection=True)
debugtrace.print('foos', foos, collection_limit=1024)
|
5. Options that can be specified in the debugtrace.ini file
DebugTrace-py reads the debugtrace.ini file in the current directory for initialization. The section is [debugtrace].
You can specify the following options in the debugtrace.ini file.
Option Name |
Description |
Default Value |
---|---|---|
logger |
The logger used by debugtrace
StdOut: Output to sys.stdout
StdErr: Output to sys.stderr
Logger: Output using logging package
|
StdErr |
logging_config_file |
The configuration file name specified in logging package |
logging.conf |
logging_logger_name |
The logger name when using the logging package |
debugtrace |
logging_level |
The log level when using the logging package |
DEBUG |
is_enabled |
False: Log output is disabled
True: Log output is enabled
|
True |
enter_format |
The format string of log output when entering functions or methods
{0}: The function or method name
{1}: The file name
{2}: The line number
|
Enter {0} ({1}:{2}) |
leave_format |
The format string of log output when leaving functions or methods
{0}: The function or method name
{1}: The file name
{2}: The line number
{3}: The time from entering
|
Leave {0} ({1}:{2}) duration: {3} |
maximum_indents |
The maximum number of indents |
20 |
indent_string |
The indentation string for code |
|\s |
data_indent_string |
The indentation string for data |
\s\s |
limit_string |
The string to represent that it has exceeded the limit |
... |
non_output_string |
The string to be output instead of not outputting value
(Currently unused)
|
... |
cyclic_reference_string |
The string to represent that the cyclic reference occurs |
*** Cyclic Reference *** |
varname_value_separator |
The separator string between the variable name and value |
\s=\s |
key_value_separator |
The separator string between the key and value of dictionary and between the attribute name and value |
:\s |
print_suffix_format |
The format string of print method suffix |
\s({1}:{2}) |
count_format |
The format string of the number of elements such as list, tuple and dict |
count:{} |
minimum_output_count |
The minimum value to output the number of elements such as list, tuple and dict |
5 |
length_format |
The format string of the length of string and bytes |
length:{} |
minimum_output_length |
The minimum value to output the length of string and bytes |
5 |
log_datetime_format |
Log date and time format when logger is StdOut or StdErr
(Currently not configurable)
|
%Y-%m-%d %H:%M:%S.%f |
maximum_data_output_width |
The maximum output width of data |
70 |
bytes_count_in_line |
The count in line of bytes |
16 |
collection_limit |
The limit value of elements such as list, tuple and dict to output |
512 |
bytes_limit |
The limit value of elements for bytes and bytearray to output |
8192 |
string_limit |
The limit value of characters for string to output |
8192 |
reflection_nest_limit |
The The limit value for reflection nesting |
4 |
Converts \s to space.
6. License
MIT License (MIT)
7. Release notes
DebugTrace-py 1.1.0 - November 28, 2021
Fixed a bug that an error occurs when outputting an object of a class that implements __str__ or __repr__.
- Do not output tuple, set, dict data types.
- (1, 2, 3) ← (tuple)(1, 2, 3)(1,) ← (tuple)(1)() ← (tuple)(){1, 2, 3} ← (set){1, 2, 3}{} ← (set){}{1: 'A', 2: 'B', 3; 'C'} ← (dict){1: 'A', 2: 'B', 3; 'C'}{:} ← (dict){}
DebugTrace-py 1.0.3 - August 12, 2021
Improved the line break handling of data output
DebugTrace-py 1.0.2 - November 29, 2020
Change the start message. ('DebugTrace-py ...' <- 'DebugTrace-python ...')
DebugTrace-py 1.0.1 - July 19, 2020
Improved the line break handling of data output.
DebugTrace-py 1.0.0 - May 26, 2020
First release
(C) 2020 Masato Kokubo
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for debugtrace-1.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | cb624b1dc3798c87dc93b9f944af80a067bbc7657dabca31d8d425324bff0307 |
|
MD5 | c1b6404160c8c6c728569b30198fbcec |
|
BLAKE2b-256 | 1210f158e2ee4236fdc6a16f39a6b93d07f9f01d7f5567ffc9a68110eef0f024 |