It's sometimes useful to be able to programatically inject a breakpoint when debugging CPython.

For example, sometimes you want a conditional breakpoint, but the logic involved is too complex to be expressed in the debugger (e.g. runtime complexity of evaluating the conditional in the debugger process, or deficiency of the debugger itself).

I'm attaching a patch which:
  - adds a Py_BREAKPOINT macro to pyport.h   This is available as a quick and dirty way of hardcoding a breakpoint in code (e.g. in extension modules); so that when you need to you can put of these in (perhaps guarded by C-level conditionals):
       if (complex_conditional()) {
           Py_BREAKPOINT();
       }

  - when Py_BREAKPOINT is defined, adds a sys.breakpoint() method.  This means that you can add C-level breakpoints to Python scripts, perhaps guarded by python-level conditionals:
       if foo and bar and not baz:
          sys.breakpoint()

Naturally this is highly system-dependent.   Only tested on Linux (Fedora 13 x86_64 with gcc-4.4.4).  The Windows implementation was copied from http://bugs.python.org/issue8863 but I don't have a Windows box to test it on.

I note that the GLib library within GNOME has a similar idea with a G_BREAKPOINT macro, which has accumulated a collection of platform-specific logic:
  http://git.gnome.org/browse/glib/tree/glib/gbacktrace.h
(unfortunately that's LGPLv2+ licensed)

Doesn't yet have a unit test.

Note that when running on Linux when _not_ under a debugger, the default for SIGTRAP is to get a coredump:
   Trace/breakpoint trap (core dumped)
so people should be strongly discouraged from adding these calls to their code.

> Note that when running on Linux when _not_ under a debugger, the 
> default for SIGTRAP is to get a coredump:
>   Trace/breakpoint trap (core dumped)
> so people should be strongly discouraged from adding these calls to
> their code.
Looks like Windows' DebugBreak has similar behavior here; according to:
  http://msdn.microsoft.com/en-us/library/ms679297(VS.85).aspx
"If the process is not being debugged, the function uses the search logic of a standard exception handler. In most cases, this causes the calling process to terminate because of an unhandled breakpoint exception."

Adding updated version of patch, which adds documentation to sys.rst and adds a unit test.

I'm a little wary of this: it seems useful but also too much like a self-destruct button for my taste.

I renamed it from sys.breakpoint to sys._breakpoint, since this is CPython-specific

I would rename Py_BREAKPOINT to _Py_BREAKPOINT since we don't really want to support this. Also, why do you allow any arguments to sys._breakpoint()?