Init

Author: stribny

.gitignore

@@ -0,0 +1,2 @@
+.vscode/
+log.txt

Pipfile

@@ -0,0 +1,13 @@
+[[source]]
+url = "https://pypi.org/simple"
+verify_ssl = true
+name = "pypi"
+
+[packages]
+stackprinter = "*"
+pysnooper = "*"
+
+[dev-packages]
+
+[requires]
+python_version = "3.7"

Pipfile.lock

@@ -0,0 +1,31 @@
+# Python debugging
+
+This project demonstrates various ways to debug Python programs:
+
+- [Debugging with f-strings](examples/debug_with_console_f_strings.py)
+- [Debugging with PySnooper](examples/debug_with_pysnooper.py)
+- [Debugging with logging](examples/debug_with_default_logging.py)
+- [Debugging with `breakpoint()`](examples/debug_with_breakpoint.py)
+- [Debugging with VSCode](examples/debug_with_vscode.py)
+- [Debugging with stackprinter](examples/debug_with_stackprinter.py)
+
+## Installation & Usage
+
+To install the project:
+```
+# inside python-debugging
+pipenv install
+```
+
+To run the examples, we need to enter the virtual environment:
+```
+pipenv shell
+```
+
+Now just follow the instructions inside each example.
+
+## Licence
+
+Author: [Petr Stříbný](http://stribny.name)
+
+License: The MIT License (MIT)

README.md

@@ -0,0 +1,41 @@
+"""
+We can stop execution of the Python program with `breakpoint()` function which
+will stop execution of the program in the given place and switches to Python debugger
+
+This is useful to open a debugger right at the place where we need to examine
+the state of the program
+
+How to use:
+- run the script with `python debug_with_breakpoint.py`
+- the program will stop in the first `for` iteration, on the breakpoint() line
+- we will get into pdb (Python debugger)
+- while now in pdb:
+    - we can see what `i` variable is by typing `i`
+    - we can examine `processed_word` variable by typing `processed_word`
+    - we can use any other pdb functionality
+    - we can continue the execution of the program by typing `continue` and repeat the examination ^
+"""
+
+# Example of the interactive session:
+# > python-debugging/debug_with_breakpoint.py(22)process_words()
+# -> for i, word in enumerate(words_to_process):
+# (Pdb) i
+# 0
+# (Pdb) processed_word
+# 'Debugging'
+# (Pdb) continue
+# > python-debugging/debug_with_breakpoint.py(22)process_words()
+# -> for i, word in enumerate(words_to_process):
+# (Pdb) i
+# 1
+# (Pdb) processed_word
+# 'With'
+
+words = ['debugging', 'with', 'breakpoint()']
+
+def process_words(words_to_process):
+    for i, word in enumerate(words_to_process):
+        processed_word = str.capitalize(word)
+        breakpoint()
+
+process_words(words)

examples/debug_with_breakpoint.py

@@ -0,0 +1,25 @@
+"""
+We can use modern Python f-strings to easily print variables to the output
+console of the program
+
+How to use:
+- run the script with `python debug_with_console_f_strings.py`
+- observe our state (i, processed_word) printed in the console
+"""
+
+# The output:
+# i=0, processed_word=Debugging
+# i=1, processed_word=With
+# i=2, processed_word=Console
+# i=3, processed_word=F-strings
+
+words = ['debugging', 'with', 'console', 'f-strings']
+
+def process_words(words_to_process):
+    for i, word in enumerate(words_to_process):
+        processed_word = str.capitalize(word)
+        print(f"i={i}, processed_word={processed_word}")
+        # In Python 3.8 we can use = specifier
+        # print(f"{i=}, {processed_word=}")
+
+process_words(words)

examples/debug_with_console_f_strings.py

@@ -0,0 +1,51 @@
+"""
+We can use Python's logging module (https://docs.python.org/3/library/logging.html) 
+to print information to a console, file or the network to examine what is happening in the program
+
+The advantage of using logging instead of other debugging techniques is that it is suitable to 
+be commited with the source and used in production
+
+There is a lot of options we can use to configure where and how the information is printed, 
+e.g. there are several log levels (debug, info, error), several formatting options (%, str.format)
+
+How to use:
+- run the script with `python debug_with_default_logging.py`
+- observe state (i, processed_word) and exception printed with additional info such as name of
+  the function or a line number
+- observe that information is printed to the console and to a file at the same time
+"""
+
+# The output:
+# DEBUG    process_words() 47	 i=0, processed_word=Debugging
+# DEBUG    process_words() 47	 i=1, processed_word=With
+# DEBUG    process_words() 47	 i=2, processed_word=Default
+# DEBUG    process_words() 47	 i=3, processed_word=Logging
+# ERROR    process_words() 49	 The word is not a string
+
+import logging
+
+FORMAT = '%(levelname)-8s %(funcName)s() %(lineno)d\t %(message)s'
+formatter = logging.Formatter(FORMAT)
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.DEBUG)
+
+console_handler = logging.StreamHandler()
+console_handler.setFormatter(formatter)
+logger.addHandler(console_handler)
+
+file_handler = logging.FileHandler("log.txt")
+file_handler.setFormatter(formatter)
+logger.addHandler(file_handler)
+
+words = ['debugging', 'with', 'default', 'logging', 42]
+
+def process_words(words_to_process):
+    for i, word in enumerate(words_to_process):
+        try:
+            processed_word = str.capitalize(word)
+            logger.debug('i=%d, processed_word=%s', i, processed_word)
+        except TypeError:
+            logger.error('The word is not a string')
+
+process_words(words)

examples/debug_with_default_logging.py

@@ -0,0 +1,43 @@
+"""
+We can use PySnooper (https://github.com/cool-RR/pysnooper) to automatically
+print the state of the program as it is executed line by line
+
+Many options exists to configure the output
+
+How to use:
+- run the script with `python debug_with_pysnooper.py`
+- observe the state of the program as it is executed printed in the console
+"""
+
+# The output:
+# Starting var:.. words_to_process = ['debugging', 'with', 'PySnooper']
+# 12:04:18.919933 call        15 def process_words(words_to_process):
+# 12:04:18.920111 line        16     for i, word in enumerate(words_to_process):
+# New var:....... i = 0
+# New var:....... word = 'debugging'
+# 12:04:18.920229 line        17         processed_word = str.capitalize(word)
+# New var:....... processed_word = 'Debugging'
+# 12:04:18.920332 line        16     for i, word in enumerate(words_to_process):
+# Modified var:.. i = 1
+# Modified var:.. word = 'with'
+# 12:04:18.920437 line        17         processed_word = str.capitalize(word)
+# Modified var:.. processed_word = 'With'
+# 12:04:18.920526 line        16     for i, word in enumerate(words_to_process):
+# Modified var:.. i = 2
+# Modified var:.. word = 'PySnooper'
+# 12:04:18.920635 line        17         processed_word = str.capitalize(word)
+# Modified var:.. processed_word = 'Pysnooper'
+# 12:04:18.920754 line        16     for i, word in enumerate(words_to_process):
+# 12:04:18.920846 return      16     for i, word in enumerate(words_to_process):
+# Return value:.. None
+
+import pysnooper
+
+words = ['debugging', 'with', 'PySnooper']
+
+@pysnooper.snoop()
+def process_words(words_to_process):
+    for i, word in enumerate(words_to_process):
+        processed_word = str.capitalize(word)
+
+process_words(words)

examples/debug_with_pysnooper.py

@@ -0,0 +1,43 @@
+"""
+We can use stackprinter (https://github.com/cknd/stackprinter/) to enhance
+the printed information that we get when an exeption is thrown
+
+How to use:
+- run the script with `python debug_with_stackprinter.py`
+- observe a different stack trace printed in the console
+"""
+
+# The output:
+# File debug_with_stackprinter.py, line 22, in <module>
+#     18   def process_words(words_to_process):
+#     19       for i, word in enumerate(words_to_process):
+#     20           processed_word = str.capitalize(word)
+#     21   
+# --> 22   process_words(words)
+#     ..................................................
+#      words = ['debugging', 'with', 'stackprinter', 42, ]
+#     ..................................................
+
+# File debug_with_stackprinter.py, line 20, in process_words
+#     18   def process_words(words_to_process):
+#     19       for i, word in enumerate(words_to_process):
+# --> 20           processed_word = str.capitalize(word)
+#     ..................................................
+#      words_to_process = ['debugging', 'with', 'stackprinter', 42, ]
+#      i = 3
+#      word = 42
+#      processed_word = 'Stackprinter'
+#     ..................................................
+
+# TypeError: descriptor 'capitalize' requires a 'str' object but received a 'int'
+
+import stackprinter
+stackprinter.set_excepthook(style='darkbg2')
+
+words = ['debugging', 'with', 'stackprinter', 42]
+
+def process_words(words_to_process):
+    for i, word in enumerate(words_to_process):
+        processed_word = str.capitalize(word)
+
+process_words(words)

examples/debug_with_stackprinter.py

@@ -0,0 +1,25 @@
+"""
+We can use the built-in debugger in Visual Studio Code editor to interactively
+step-through the program's execution and examine the variables
+
+How to use:
+- install VSCode (https://code.visualstudio.com/)
+- install Python extension (https://marketplace.visualstudio.com/items?itemName=ms-python.python)
+- open debug_with_vscode.py in VSCode
+- make sure Python's execution path is set to the virtual environment that we created with pipenv
+  (see python.pythonPath in .vscode/settings.json for that)
+- switch to Debug panel and add a new debug configuration (choose current file), this will create
+  .vscode/launch.json configuration
+- set breakpoints by clicking on the left side of the line number where you want to stop the execution
+- click run on the Debug panel
+- the program will start and stop at the line you have selected
+- you will see all variables displayed in the debug panel and a new floating control panel to control the execution
+"""
+
+words = ['debugging', 'with', 'vscode']
+
+def process_words(words_to_process):
+    for i, word in enumerate(words_to_process):
+        processed_word = str.capitalize(word) # set breakpoint here
+
+process_words(words)