Skip to main content

Output trace logs when debugging Python programs

Project description

DebugTrace-python is a library that outputs trace logs when debugging your Python programs. It supports Python 3.5 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 callers 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 debuggee and related functions or 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-python and a log when it is executed.

import datetime
import debugtrace # for Debugging

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

def func2():
    _ = debugtrace.enter() # for Debugging
    contact = [
        Contact(1, "Akane" , "Apple",, 2, 3)),
        Contact(2, "Yukari", "Apple",, 3, 4))
    debugtrace.print_("contact", contact) # for Debugging

def func1():
    _ = debugtrace.enter() # for Debugging


Log output contents:

2020-01-13 11:38:02.421897 debugtrace 1.0.0b1 logger: StdErr
2020-01-13 11:38:02.424168 Enter func1 (
2020-01-13 11:38:02.424248 |   Enter func2 (
2020-01-13 11:38:02.424727 |   |   contact = (list)[
2020-01-13 11:38:02.424743 |   |     (__main__.Contact){
2020-01-13 11:38:02.424750 |   |       birthday: 1991-02-03,
2020-01-13 11:38:02.424756 |   |       firstName: (length:5)'Akane',
2020-01-13 11:38:02.424761 |   |       id: 1,
2020-01-13 11:38:02.424766 |   |       lastName: (length:5)'Apple',
2020-01-13 11:38:02.424771 |   |     },
2020-01-13 11:38:02.424777 |   |     (__main__.Contact){
2020-01-13 11:38:02.424782 |   |       birthday: 1992-03-04,
2020-01-13 11:38:02.424787 |   |       firstName: (length:6)'Yukari',
2020-01-13 11:38:02.424798 |   |       id: 2,
2020-01-13 11:38:02.424804 |   |       lastName: (length:5)'Apple',
2020-01-13 11:38:02.424809 |   |     },
2020-01-13 11:38:02.424814 |   |   ]
2020-01-13 11:38:02.424824 |   Leave func2
2020-01-13 11:38:02.424833 Leave func1

4. Functions

There are mainly the following functions.

Function list
Name Arguments Discription
enter None
Outputs an entering log.
Also outputs a leaving log at the end of the code block.
_ = debugtrace.enter()
name: Variable name, etc.
value: Output value
Outputs the variable name and value.
debugtrace.print_('foo', foo)`

5. Options that can be specified in the debugtrace.ini file

DebugTrace-python 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 used by debugtrace
StdOut: Output to sys.stdout
StdErr: Output to sys.stderr
Logger: Output using logging package
logging_config_file Configuration file name specified in logging package logging.conf
logging_logger_name Logger name when using the logging package debugtrace
logging_level Log level when using the logging package DEBUG
False: Log output is disabled
True: Log output is enabled
enter_string String to be output when entering functions and methods Enter
leave_string String to output when leaving functions and methods Leave
limit_string String output when limit is exceeded ...
maximum_indents Maximum number of indents 20
code_indent_string Indentation string for code |␠␠␠
data_indent_string Indentation string for data
(2 spaces)
non_output_string String to be output instead of not outputting value ...
cyclic_reference_string String to be output when referring to a cycle *** Cyclic Reference ***
varname_value_separator String separating variable name and value ␠=␠
String separating the dictionary key and value
And separating the attribute name and value
log_datetime_format Log date and time format when logger is StdOut or StdErr %Y-%m-%d %H:%M:%S.%f
Format of the log output when entering function or method
{0}: function or method name
{1}: file name
{2}: line number
{0} ({1}:{2})
Format of log output when leaving function or method
{0}: function or method name
count_format Output format of the number of elements such as list, tuple, dict and etc. count:{}
minimum_output_count Minimum value to output the number of elements such as list, tuple, dict and etc. 5
string_length_format Output format for string length length:{}
minimum_output_string_length Minimum value to output string length 5
maximum_data_output_width Maximum output width of data 80
collection_limit Maximum number of elements to output such as list, tuple, dict and etc. 256
string_limit Maximum number of output characters for string values 2048
reflection_nest_limit Maximum number of reflection nests 4

6. License

MIT License (MIT)

7. Release notes

DebugTrace-python 1.0.0b1 - 2020-01-13

  • First release (beta version)

(C) 2020 Masato Kokubo

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for debugtrace, version 1.0.0b2
Filename, size File type Python version Upload date Hashes
Filename, size debugtrace-1.0.0b2-py3-none-any.whl (9.5 kB) File type Wheel Python version py3 Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page