easydebugger

a Python debugging tool made by blob2763

contents

• setting it up
• docs
• faq
• changelog
• future plans

setting it up

simple stuff for installing any library

1. installation

install the library using pip install easydebugger

2. importing the library

import easydebugger as ed

docs

messages

there are 3 types of messages to choose from:

• error
• warn
• success

you can make any of these messages with their corresponding functions:

import easydebugger as ed

ed.error("error message")
ed.warn("warn message")
ed.success("success message")

you can add a code to each of these to make them easier to find. here's what the messages look like with a code:

import easydebugger as ed

ed.error("error message", "ERROR CODE")
ed.warn("warn message", "WARN CODE")
ed.success("success message", "SUCCESS CODE")

parameters

each message function looks something like this:

# Not a real function, but represents any of the 3 message functions
ed.message(message, code)

parameter	required	default	description
message	yes	N/A	the message
code	no	""	the code displayed with the message to easily identify them

logs

logs are just print() statements but they look better. functionally, they are the basically same as the 3 message functions

import easydebugger as ed

ed.log("some data")
ed.log("some labelled data", "LABEL")

parameters

ed.log(message, label)

parameter	required	default	description
message	yes	N/A	the message
label	no	""	the label displayed with the message to easily identify them

variables

there is a special function just for logging variables. while you could use ed.log() for this, ed.variable() stands out more and should be used instead

import easydebugger as ed

my_variable = 12345
ed.variable(my_variable, "my_variable")

parameters

ed.variable(value, name)

parameter	required	default	description
value	yes	N/A	the variable's value
name	yes	N/A	the variable's name

timers

you can time how long code takes to run using ed.start_timer() and ed.end_timer()

import easydebugger as ed
import time as t

def foo():
    t.sleep(2)
    
ed.start_timer("foo")
foo()
ed.end_timer("foo")

you can have multiple timers running at once

import easydebugger as ed
import time as t

ed.start_timer("everything")

def foo():
    t.sleep(2)

ed.start_timer("foo")
foo()
ed.end_timer("foo")
ed.end_timer("everything")

if you use ed.start_timer() for a timer that is already running, the timer starts again

import easydebugger as ed
import time as t

def foo():
    t.sleep(2)

ed.start_timer("foo")
foo()
ed.start_timer("foo")  # resets timer
ed.end_timer("foo")

parameters

ed.start_timer(code)

parameter	required	default	description
code	yes	N/A	the timer's name

ed.end_timer(code)

parameter	required	default	description
code	yes	N/A	the timer's name

timer storage

if you ever need to see all active timers, you can use ed.timers

import easydebugger as ed
import time as t

def foo():
    t.sleep(2)

ed.start_timer("foo")
ed.start_timer("bar")
foo()
ed.log(ed.timers)
ed.end_timer("bar")
ed.end_timer("foo")

ed.timers is a dictionary, each key is the name of the timer and each value is the UNIX time in seconds when the timer started

trace

you can use ed.trace() to show when a function is entered and exited

import easydebugger as ed
import time as t

def foo():
    ed.trace()  # when used the first time, the code sees this as the function being entered
    ...
    ed.trace()  # when used the second time, the code sees this as the function being exited

foo()

ed.trace() works best in a function, but won't throw an error if used outside of a function

import easydebugger as ed

ed.trace()
ed.trace()

parameters

there are no parameters for ed.trace() because the function name is detected automatically

trace storage

if you ever need to see any active traces, use ed.traces

import easydebugger as ed

def foo():
    ed.trace()
    bar()
    ed.trace()


def bar():
    ed.trace()
    ed.log(ed.traces)
    ed.trace()


foo()

ed.traces is a list of all the names of the functions currently being traced

history

easydebugger keeps a record of any messages, logs, timers, and traces used since the code started. you can display this record using ed.display_history()

import easydebugger as ed

ed.error("error")
ed.display_history()

each history entry is timestamped in milliseconds since the code started

if a history entry is made in a function, the entry is indented

import easydebugger as ed

def foo():
    ed.trace()
    ...
    ed.trace()

ed.error("error")
foo()
ed.display_history()

parameters

ed.display_history() has no parameters

history storage

if you ever need to use the history storage, use ed.history

ed.history is a list of dictionaries, one dictionary for each history log entry

each log entry looks like this:

key	description
time	timestamp of when the log was made in milliseconds since the code started
stack	the stack when the log was made. if you don't know what this means, you don't need to worry about it
stack_length	length of the stack when the log was made. used for indentation in ed.display_history()
symbol	the symbol used by the message, log, timer, or trace. eg: "!" for ed.error()
colour	the 8-bit ANSI colour code of the message, log, timer, or trace. eg: "9" for ed.error()
message	the message, log, variable value, or timer/trace message depending on the function that created the entry
label	the code, label, variable name, timer name, or traced function name depending on the function that created the entry
line_number	the line number that the function that created the entry is on

history export

you can export the history with ed.export_history(). this makes a text file in a folder called debug_logs, the folder is created if it doesn't exist

parameters

ed.export_history(file_name)

parameter	required	default	description
file_name	no	str(round(t.time() * 1000))	the name of the txt file being made. default is the current UNIX milliseconds as a string

hiding messages

if you want to hide debug messages for a certain area of code, you can use ed.DISPLAY

set ed.DISPLAY to False to hide the messages and set it to True if you want to show the messages again

import easydebugger as ed

ed.error("error")
ed.DISPLAY = False
ed.error("another error")  # this won't be shown
ed.DISPLAY = True
ed.error("error")  # this will be shown

ed.show_history() will still work even if ed.DISPLAY is set to False

custom messages

if you want to make a custom debug message, use ed.display_message()

import easydebugger as ed

ed.display_message("^", "LABEL", "message", 123, "65")

parameters

ed.display_message(symbol, label, message, line_number, colour_code, indent)

parameter	required	default	description
symbol	yes	N/A	the symbol used by the message. eg: "!" for ed.error(). symbols should be 1 character, but there is nothing stopping you from making longer ones if you want
label	yes	N/A	the text next to the symbol
message	yes	N/A	the main part of the debug message
line_number	yes	N/A	the line number shown after the message
colour_code	yes	N/A	the 8-bit ANSI colour code of the message. eg: "9" for ed.error()
indent	no	0	the indentation of the message (used in ed.display_history(). an indent of 1 is 3 spaces

re-callable debug messages

instead of using ed.display_message() every time, you can use ed.Message to create custom messages that you can use as many times as you want. you log it using Message.log()

import easydebugger as ed

custom_message = ed.Message("i", "123")
custom_message.log("custom message", "label")

instance variables

ed.Message has 2 instance variables:

instance variable	description
self.symbol	the symbol used by the message. eg: "!" for ed.error()
self.colour	the 8-bit ANSI colour code of the message. eg: "9" for ed.error()

parameters

ed.Message(symbol, colour_code)

parameter	required	default	description
symbol	yes	N/A	the symbol used by the message. eg: "!" for ed.error(). symbols should be 1 character, but there is nothing stopping you from making longer ones if you want
colour_code	yes	N/A	the 8-bit ANSI colour code of the message. eg: "9" for ed.error()

Message.log(symbol, colour_code)

parameter	required	default	description
message	yes	N/A	the main part of the debug message
label	no	""	the text next to the symbol

changing colours

you can change the colour of debug messages with its corresponding variable. colour codes are 8-bit ANSI colour codes

import easydebugger as ed

ed.error("red")
ed.ERROR = "208"  # changes colour
ed.error("orange")
ed.error("also orange")

the colour does not change back after you have used it

here are the variables for each function:

function	variable	default value
ed.error()	ERROR	"9"
ed.warn()	WARN	"220"
ed.success()	SUCCESS	"120"
ed.variable()	VARIABLE	"208"
ed.log()	LOG	"15"
ed.start_timer()	TIME	"93"
ed.end_timer()	TIME	"93"
ed.trace()	TRACE	"27"
ed.display_history()	HISTORY	"57"
ed.display_stack()	STACK	"37"
all functions above (and ed.display_message()	ESCAPE	u"\u001b[0m"

ed.ESCAPE contains the escape characters to stop formatting at the end of a message. you shouldn't edit this variable, but you can if you want to

import easydebugger as ed

print(ed.ESCAPE)
ed.ESCAPE = u"\u001b[48;5;225m"  # ANSI escape code to turn the background pink
ed.error("error message")
ed.warn("warn message")
ed.success("success message")

start time

ed.START_TIME is the UNIX time in seconds when the code started. it is used for timestamps in history, but you can use it in other places if you want

the stack

the stack stores the part of the code which is currently running. you can display the stack using ed.display_stack()

import easydebugger as ed

ed.display_stack()

each layer of the stack is called a frame. here is how to read each frame

here's another example with more frames

import easydebugger as ed


def foo():
    ed.display_stack()
    

def bar():
    foo()


bar()

here's a diagram to explain the same stack:

faq

why don't i have all the features?

make sure you are using the latest version of easydebugger. run pip install --upgrade easydebugger in the terminal. if you aren't on the latest version, this command will update easydebugger for you.

i have found a bug, what do i do?

if you have found a bug, check any existing issues first to make sure someone else hasn't already found it. if you've found a new bug, create an issue. here are some tips to create the best bug report:

• explain clearly what the bug is. what was the intended result and what actually happened?
• explain or show how to recreate the bug. if you can, include code that recreates the bug
• try to include a screenshot of the bug, especially what happened as a result of the bug
• include any other information you find relevant
• most importantly, add the bug label to the issue. this helps me find it faster

i have an idea for a feature to be added, what should i do?

all ideas are welcome! if you have an idea you think would make easydebugger better, create an issue. follow these steps to create the best feature request:

• explain clearly what you want to see added.
• give a reason why you want to see it added. something like "i think it would be cool" is a valid reason, but try to be more specific if you can.
• most importantly, add the enhancement label to the issue. this helps me find it faster

i have a question that isn't answered here

create an issue using the question label, and put a question you have in the issue. i will try to answer your question, and it might even make it to the faq!

changelog

0.0.1

• library first published

1.0.0

• initial release
• long description added to pypi

1.0.1

• added docs

1.1.0

• attempted to fix #1

1.1.1

• actually fixed #1

1.2.0

• added ed.display_stack()

1.2.1

• fixed #2

1.3

• added #3

future plans

im really happy with how this has turned out, but i still want to add more:

• automatically try to detect variable name in ed.variable()
• make some usage examples