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
# 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:
2024-03-29 18:43:38.112156+0900 DebugTrace-py 1.4.0 on Python 3.12.0
2024-03-29 18:43:38.112209+0900 config file path: <No config file>
2024-03-29 18:43:38.112244+0900 logger: sys.stderr
2024-03-29 18:43:38.112329+0900
2024-03-29 18:43:38.112367+0900 ______________________________ MainThread #134705475060800 ______________________________
2024-03-29 18:43:38.112384+0900
2024-03-29 18:43:38.113719+0900 Enter func1 (readme_example.py:22) <- (readme_example.py:26)
2024-03-29 18:43:38.113813+0900 | Hello, World! (readme_example.py:23)
2024-03-29 18:43:38.113907+0900 | Enter func2 (readme_example.py:14) <- (readme_example.py:24)
2024-03-29 18:43:38.114001+0900 | | Enter Contact.__init__ (readme_example.py:7) <- (readme_example.py:16)
2024-03-29 18:43:38.114074+0900 | | Leave Contact.__init__ (readme_example.py:7) duration: 0:00:00.000008
2024-03-29 18:43:38.114166+0900 | |
2024-03-29 18:43:38.114202+0900 | | Enter Contact.__init__ (readme_example.py:7) <- (readme_example.py:17)
2024-03-29 18:43:38.114240+0900 | | Leave Contact.__init__ (readme_example.py:7) duration: 0:00:00.000007
2024-03-29 18:43:38.114534+0900 | |
2024-03-29 18:43:38.114574+0900 | | contacts = [
2024-03-29 18:43:38.114596+0900 | | (__main__.Contact){
2024-03-29 18:43:38.114609+0900 | | birthday: 1991-02-03, firstName: 'Akane', id: 1, lastName: 'Apple'
2024-03-29 18:43:38.114646+0900 | | },
2024-03-29 18:43:38.114703+0900 | | (__main__.Contact){
2024-03-29 18:43:38.114727+0900 | | birthday: 1992-03-04, firstName: 'Yukari', id: 2, lastName: 'Apple'
2024-03-29 18:43:38.114738+0900 | | }
2024-03-29 18:43:38.114748+0900 | | ] (readme_example.py:19)
2024-03-29 18:43:38.114778+0900 | |
2024-03-29 18:43:38.114818+0900 | Leave func2 (readme_example.py:14) duration: 0:00:00.000863
2024-03-29 18:43:38.114859+0900 Leave func1 (readme_example.py:22) duration: 0:00:00.001086
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: -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_nest_limit (int, optional) : The The limit value for reflection nesting (default: -1 )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 |
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
|
128 |
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 |
256 |
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 |
bytes_limit |
The limit value of elements for bytes and bytearray to output |
256 |
string_limit |
The limit value of characters for string 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.4.0 - March 31, 2024
print
method now returns thevalue
of the argument.- Changed default values for the following properties.
Property Name | New Default Value | Old Default Value |
---|---|---|
minimum_output_count | 128 | 16 |
minimum_output_length | 256 | 16 |
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 |
bytes_limit | 256 | 8192 |
string_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
File details
Details for the file debugtrace-1.4.0-py3-none-any.whl
.
File metadata
- Download URL: debugtrace-1.4.0-py3-none-any.whl
- Upload date:
- Size: 20.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.12.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
438fcde550973f4936e5a5226c9bd16db02126439e82d4b3d8b2e865932e51af
|
|
MD5 |
e2cc30b9b90f36049ff7d131b7509492
|
|
BLAKE2b-256 |
6dd03fa6015dedec771b3c655a3473969ab7abd09b603b855162c27fe1207eb3
|