Output trace logs when debugging Python programs
Project description
DebugTrace-py
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 # 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:
2023-02-26 21:05:06.623919+0900 DebugTrace-py 1.3.0 on Python 3.11.0
2023-02-26 21:05:06.623973+0900 config file path: <No config file>
2023-02-26 21:05:06.623990+0900 logger: sys.stderr
2023-02-26 21:05:06.624044+0900
2023-02-26 21:05:06.624091+0900 ______________________________ MainThread #140621580739648 ______________________________
2023-02-26 21:05:06.624106+0900
2023-02-26 21:05:06.625608+0900 Enter func1 (readme_example.py:22) <- (readme_example.py:26)
2023-02-26 21:05:06.625701+0900 | Hello, World! (readme_example.py:23)
2023-02-26 21:05:06.625806+0900 | Enter func2 (readme_example.py:14) <- (readme_example.py:24)
2023-02-26 21:05:06.625902+0900 | | Enter Contact.__init__ (readme_example.py:7) <- (readme_example.py:16)
2023-02-26 21:05:06.625964+0900 | | Leave Contact.__init__ (readme_example.py:7) duration: 0:00:00.000008
2023-02-26 21:05:06.626055+0900 | |
2023-02-26 21:05:06.626091+0900 | | Enter Contact.__init__ (readme_example.py:7) <- (readme_example.py:17)
2023-02-26 21:05:06.626123+0900 | | Leave Contact.__init__ (readme_example.py:7) duration: 0:00:00.000005
2023-02-26 21:05:06.627114+0900 | |
2023-02-26 21:05:06.627155+0900 | | contacts = [
2023-02-26 21:05:06.627190+0900 | | (__main__.Contact){
2023-02-26 21:05:06.627218+0900 | | birthday: 1991-02-03, firstName: 'Akane', id: 1, lastName: 'Apple'
2023-02-26 21:05:06.627235+0900 | | },
2023-02-26 21:05:06.627246+0900 | | (__main__.Contact){
2023-02-26 21:05:06.627257+0900 | | birthday: 1992-03-04, firstName: 'Yukari', id: 2, lastName: 'Apple'
2023-02-26 21:05:06.627279+0900 | | }
2023-02-26 21:05:06.627314+0900 | | ] (readme_example.py:19)
2023-02-26 21:05:06.627348+0900 | |
2023-02-26 21:05:06.627390+0900 | Leave func2 (readme_example.py:14) duration: 0:00:00.001537
2023-02-26 21:05:06.627430+0900 Leave func1 (readme_example.py:22) duration: 0:00:00.001769
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.
_ = debugtrace.enter(self)
|
print |
Outputs the variable name and value Arguments: name (str) : Variable name, etcvalue (object, optional) : Value to output (output only name if omitted)The following are keyword arguments force_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: None )bytes_limit (int, optional) : The limit value of elements for bytes and bytearray to output (default: None )string_limit (int, optional) : The limit value of characters for string to output (default: None )reflection_nest_limit (int, optional) : The The limit value for reflection nesting (default: None )Examples:
debugtrace.print('Hellow')
|
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 Specifiable Values: stdout - Output to sys.stdout stderr - Output to sys.stderr logger - Output using logging packagefile: < log file path> - Output directly to the file
|
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 |
is_enabled |
Specifiable Values:False : Log output is disabledTrue : 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{3} : The file name of the caller{4} : The line number of the caller
|
Enter {0} ({1}:{2}) <- ({3}:{4}) |
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 since entered
|
Leave {0} ({1}:{2}) duration: {3} |
thread_boundary_format |
The format string of logging at threads boundary{0} : The thread name{1} : The thread ID
|
______________________________ {0} #{1} ______________________________
|
maximum_indents |
イThe maximum number of indents | 32 |
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 (Currently unused) |
The string to be output instead of not outputting value | ... |
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<c/ode> |
The format string of print method suffix |
\s({1}:{2}) |
count_format |
The format string of the number of elements for list , tuple and dict
|
count:{} |
minimum_output_count |
The minimum value to output the number of elements for list , tuple and dict
|
16 |
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 |
16 |
log_datetime_format |
Log date and time format when logger is StdOut or StdErr |
%Y-%m-%d %H:%M:%S.%f%z |
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 for list , tuple and dict to output
|
128 |
string_limit |
The limit value of characters for string to output | 256 |
bytes_limit |
The limit value of elements for bytes and bytearray to output |
256 |
reflection_nest_limit |
The The limit value for reflection nesting | 4 |
Converts \s
to space.
6. License
© 2020 Masato Kokubo
7. Release notes
DebugTrace-py 1.3.0 - March 4, 2023
- Added calling source file name and line number to log output of
enter
method. - Abolished
logging_level
setting indebugtrace.ini
and set it to fixed (DEBUG
). - Added
log_datetime_format
todebugtrace.ini
setting item.
DebugTrace-py 1.2.0 - August 15, 2022
- Added the runtime Python version to the startup log.
- Changed to output a log that shows thread switching.
- Changed default values for the following properties.
Property Name | New Default Value | Old Default Value |
---|---|---|
minimum_output_count | 16 | 5 |
minimum_output_length | 16 | 5 |
collection_limit | 128 | 512 |
string_limit | 256 | 8192 |
bytes_limit | 256 | 8192 |
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
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.3.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 659b045435529195fffdd3317a6095a53dbde0173f6bc019091cf6ab56ed896e |
|
MD5 | 9a5e026e0f67c049407692051b599bd9 |
|
BLAKE2b-256 | f446685bc2532af1623a607a686a8f3d8f28945733c1f432b26c5dfbd57965a9 |