[Terry]
> If you write 'How to debug Python code' rather than just "How to use pdb",
That is my intention.

> I would start with the use of print statements
You, Ezio and I concur :)

> and binary search.
I’m not familiar with that term.  Is it hg bisect?

> Have short sections on using trace and profile.
I haven’t thought about these, thanks.

> Very useful would be a list of error messages and possible un-obvious
> to beginners but common causes.
These would be great additions to the programming FAQ, and my document could link to it.


[Ezio]
> People coming from other languages often feel the need of using a debugger because that's
> what works best with the other languages, but it's not necessarily true for Python.
I’ll be sure to make this clear, thanks.

> I'm not sure focusing on pdb is the best idea then.
My initial message did not do justice to my outline.  The part about pdb is probably the one that’ll take me more time, because I nearly don’t know it at all, but it won’t be the focus of the document.  A quick “getting started with pdb” section is what I have in mind, something more newbie-level than the pdb module docs (which seem to assume basic knowledge of how a Unix debugger program works).

> Mentioning unittest and coverage as a way to find errors earlier might also be a good idea
Hadn’t though about coverage.  Will mention it and add a link to the devguide part that talks about it.

I don’t think I’ll have much time for this in the following few weeks, but as your replies appear to accept the idea, I will set up a clone to let us work on this.


Here’s my initial outline:

=== Introduction

- running a script in a terminal or IDLE
- getting a traceback (file and line)
- making sense of the exception message

=== Simple Troubleshooting Techniques

- print debugging
- using facilities provided by modules used
  - increasing logging verbosity
  - httplib.debuglevel
  - your web framework's debug helper
- going into interactive mode

* Using lint tools to catch mistakes early

- pyflakes first
- pylint -E
- pychecker?

* Getting more information out of failing tests

- using the most specialized methods to get diffs
- msg argument for boolean-returning methods
- print! suspend!  All is fair in debugging.

* Automating troubleshooting

- emacs/vim quickfix (mode that runs tests and open faulty files at the right line)


=== Using a Debugger

- pdb intro that does not duplicate what’s in library/pdb.rst
- definitions (breakpoint, etc.)


=== Debugging C code

(just a few pointers, this could have a whole howto in itself)

- running Python in gdb
- using faulthandler


Links to add somewhere: traceback module, cgitb