Exceptions that inherit from BaseException should not be treated as Uncaught Exceptions

[danielniccoli]

Before creating a new issue, please check the FAQ to see if your question is answered there.

Environment data

• debugpy version: 1.8.1
• OS and version: Windows 11
• Python version: 3.11
• Using VS Code or Visual Studio: VS Code

Actual behavior

exit(1) halts the debugging session due to an "uncaught exception"

Expected behavior

The program program should exit without the debugger halting.

Exceptions that inherit from exception.BaseException should not fall under the category of "uncaught exceptions", since they are "technically not an error"¹.

exception.BaseException

The base class for all built-in exceptions. It is not meant to be directly inherited by user-defined classes (for that, use Exception).

https://docs.python.org/3/library/exceptions.html#BaseException

One of these exceptions is exception.SystemExit, which is called when calling exit(1).

exception SystemExit

This exception is raised by the sys.exit() function. It inherits from BaseException instead of Exception so that it is not accidentally caught by code that catches Exception. This allows the exception to properly propagate up and cause the interpreter to exit. When it is not handled, the Python interpreter exits; no stack traceback is printed.

https://docs.python.org/3/library/exceptions.html#SystemExit

There are only three other Exceptions that inherit from exception.BaseException, not counting exception.Exception, which does fall under the category of "Uncaught Exceptions":

BaseException
 ├── BaseExceptionGroup
 ├── GeneratorExit
 ├── KeyboardInterrupt
 ├── SystemExit
 └── Exception

https://docs.python.org/3/library/exceptions.html#exception-hierarchy

exception KeyboardInterrupt

Raised when the user hits the interrupt key (normally Control-C or Delete). During execution, a check for interrupts is made regularly. The exception inherits from BaseException so as to not be accidentally caught by code that catches Exception and thus prevent the interpreter from exiting.

exception GeneratorExit

Raised when a generator or coroutine is closed; see generator.close() and coroutine.close(). It directly inherits from BaseException instead of Exception since it is technically not an error.

Footnotes

1. https://docs.python.org/3/library/exceptions.html#GeneratorExit ↩

[rchiodo]

Transferring to dicussions for up votes

[int19h]

This behavior existed all the way back to the original ptvsd even.

That said, given that "breakOnSystemExitZero" is already a launch.json option, it would be nice to make this more generic and to allow explicitly specifying ranges of error codes. Then one could disable this behavior entirely by not specifying any, e.g.:

"breakOnSystemExit": [0, 2, {"from": 3, "to": 100}];

"breakOnSystemExit": [];  // never break

As it is, this is already special-cased for some libraries. E.g. Django uses exitcode 3 to indicate reloading, and so pydevd doesn't break on SystemExit(3) if "django":true is set. This is hardcoded, though.

[indigane]

This? https://github.com/fabioz/PyDev.Debugger/blob/0e0d434/_pydevd_bundle/pydevd_process_net_command_json.py#L432-L435

Weird that there is such a special case.

Using these terms I would want a special case to ignore this for pytest:

https://github.com/pytest-dev/pytest/blob/0d96a5bf9059e51324ac24ec24d68af1c35db6d8/_pytest/main.py#L28

because the use case for the debugger with pytest is to pause during the tests, not after the tests when pytest is exiting every time there are any failed tests. There is nothing to debug during the exit, the tests are already long gone.

I think more special cases is a bad idea but do you think an issue should be opened @ pydevd for this use case?

[danielniccoli]

The user wanted the exact behavior we have

@rchiodo

A debugger should first and foremost conform to the programming language it's written for. And the docs are clear about these exceptions being only for internal use, and that a debugger should not halt execution. It is that, which gives any questions a foundation for discussion. Debugpy violates that, leading to where we are: an argument, rather than a discussion… and hard-coded workarounds for behaviour in Django (thanks @int19h).

It also misleads people's expectations. The comment you linked (#489 (comment)) is a perfect example of that.

The expected behavior in default should be: […] sys.exit(n) for nonzero n breaks

What is this expectation based on? I don't say that because I want to invalidate his opinion. But as everybody has a different opinion, the best option for a baseline is to stick to the documented behaviour first, and then give people the option to change this behaviour so it suits their needs.

– or you disregard all of that, in which case all the people that know what should happen, have their expectations failed by debugpy. And from the rest of the people, half of them have their expectations also failed. I don't think this is what anybody wants.

I have one more point.

I can imagine use cases where one would want the debugger to pause on non-zero SystemExit, as those are usually errors.

@indigane

exit(1) is deliberate. It does indicate an error, but it does not indicate an exception. This should throw an uncaught exception, which should be handled by debugpy:

./test.py 1 0

import sys

n1 = float(sys.argv[1])  # n1 = 1
n2 = float(sys.argv[2])  # n2 = 0

print(n1/n2)

This should not

./test.py 1 0

import sys

n1 = float(sys.argv[1])
n2 = float(sys.argv[2])

try:
    print(n1/n2)
except ZeroDivisionError:
    exit(1)

In conclusion, the way it is currently implemented is not conform to the docs and imposes truly unexpected behaviour upon the developer that cannot be altered. Fixing this behaviour would solve so many problems, would allow you to remove hardcoded workarounds from your code base and would result in a package that respects the Python specs.

And if it's important to you (which I can see) implement a configuration option that let's a developers alter debugpy's behaviour, if they want debugpy to halt on exit(), as @int19h suggested.

[int19h]

The Python documentation doesn't say anything about how debuggers should behave, only about how user code should behave. It talks about "catching" exceptions, but debugger isn't doing that - it is reporting them. Thus this is not an issue of conformance. Debugger is reporting exceptions, and SystemExit is an exception. Whether to exclude it or not by default should be based on whether it makes sense for most scenarios or not. Given that a non-zero exit code is the standard way of reporting errors to the OS on all major platforms, thus it makes sense that it is reported by default.

In general, debuggers are inherently "meta" wrt user code and what it does, and it is, in fact, not uncommon for them to expose things that are normally under the hood. For example, they will show you private slots of an object.

[Sorontik]

I would say the fact that SystemExit does not inherit from Exception but from BaseException already shows, that it is not a "normal" exception and therefore it would make sense that it is not always treated like other Exceptions.

---

I totally agree with danielniccolis statement:

exit(1) is deliberate. It does indicate an error, but it does not indicate an exception.

I would rephrase this like so:

• An Exception indicates an unexpected situation that requires special treatment by surrounding code or the developer
  (not necessarily an Error, see GeneratorExit or StopIteration)
• whereas exit() (regardless of the return code) indicates a situation, where there is nothing more to be done in this program, except exiting cleanly.

This also shows that Exceptions are very interesting during development, because they are targeted at the surrounding code (which we are working on). When a SystemExit is raised, we're already headed for the exit because a developer decided that that is the best (or only) thing left to do, so there's usually not much left to debug anyway.

---

From a naive perspective, one could complain

"I am calling sys.exit() and not raising an Exception, so why does the debugger treat it as such".

This is obviously very simplified - but personally I would still consider it bad style if a SystemExit-Exception was raised manually instead of calling exit().
Similarly, catching SystemExit is only necessary in very specific "meta"-circumstances like debuggers or error-reporters, in most cases a try-finally-construct should be the preferred way to react on a SystemExit.
So SystemExit is not really used like the other exceptions and can be almost invisible in the majority of programs.

---

If wanting to be nitpicky, one could also argue that BaseException would, based on its meaning or role, better be called 'Raisable' (similar to java's 'Throwable') and is a technical detail of the implementation of pythons Error-handling-mechanism.
If you look at it like that, BaseExceptionGroup, GeneratorExit, KeyboardInterrupt and also SystemExit are 'Raisables', rather than actual Exceptions and treating them like actual Exceptions (which inherit from Exception) could cause confusion.

---

Regarding @int19h comment

In general, debuggers are inherently "meta" wrt user code and what it does, and it is, in fact, not uncommon for them to expose things that are normally under the hood. For example, they will show you private slots of an object.

Just because something is "not uncommon" or helpful in some cases, does not mean it's good in all cases.
It is good to allow deep-dives if necessary - but it is not helpful to bombard the user with loads of internal details when they haven't asked for them.

---

On the other hand, changing the current behaviour is not ideal - and there are use-cases, where one want's to break on raised SystemExits (maybe sometimes even on ones with code 0).

A solution like #1591 (reply in thread) is neat and minimally invasive, but it is still a rather narrow special-case for SystemExit.

By implementing a more generalized solution, not only could this problem be solved, but the debugging experience in general could also be improved.
I imagine a system, where there is a set of rules that determine how/ when an exception should be reported.
Each rule would target one Class and determine if it should be reported when raised, when uncaught or user-uncaught and whether this rule should apply to subclasses as well or be restricted to this class only.
Such rules could also include conditions (e.g. "Report SystemExit exceptions on raise, but only if code != 0), similar to conditional breakpoints.
Exceptions that don't match any rule would be ignored.

The current behaviour could then be remodeled by a default set of rules, so the default behaviour would not change - but it would become fully customizable and projects like django, flask or pytest could provide rule suggestions without the need for actual special-casing.

Allowing a rule to be (partially) overridden by subsequent rules would allow the debugger to have a internal default list of rules, but the behaviour could still be overridden explicitly.

That would allow for very flexible and fine-grained tuning for those that want it, remove the need for speical cases and (with reasonable default rules) would not change the current behaviour.

Unfortunately i have not the faintest Idea if such a System would even be feasible with the current debugger and interpreter structure.
I also fear that it might have a very negative impact on debugging performance because of the overhead of checking all the rules and conditions - but that is only necessary once an exception was actually raised and that is rather expensive already, so it might not make much of a difference and people already have to be careful when using exceptions in performance-critical situations (also, debugging is probably rarely done in performance-critical situations)

---

Overall, i think the current behaviour is not completely wrong - but also not completely right.
Since there are several big projects and probably a lot of people affected by this, i think it is worth addressing.
And as i outlined above, there are possible solutions that solve this problem and enhance the functionality quite a bit while still keep the established behaviour as default.

And to rchiodos concern

This behavior has existed since debugpy was created AFAIK and I believe this is the first complaint. My assumption is that changing this behavior would affect a lot of people, some of whom may want it to behave this way.

I have to respond:
Just because no one was bothered enough to complain before, does not mean that no one was affected or annoyed by it.

[thomas-brandstaetter]

Handling SystemExit as a regular Exception is a bas design decision.

1. SystemExit is not an error
   Every part of the stdlib, every framework, every test runner and every daemon treats it differently from exceptions. debugpy silently turns correct shutdown into “something went wrong”.

2. sys.exit() / raise SystemExit is the only sanctioned way to propagate shutdown through many nested context managers and finally blocks and debugpy eats it.

3. Most test runners (pytest, unittest, nose2, tox, hypothesis, etc.) deliberately raise SystemExit to exit with a specific code
   debugpy catches it → test session appears to “crash with exception” instead of “finished with exit code 1”.

4. pdb / ipdb / debug statements in the standard library and most IDE debuggers do not catch SystemExit
   debugpy is the outlier.

5. Many libraries use except Exception and then re-raise with modified message / different type. When debugpy catches SystemExit they accidentally turn clean shutdown into noisy exception

6. It breaks the long-standing Python convention / type-checker expectation that Exception ≈ “something went wrong that the program can recover from”

7. Microsoft is basically telling library authors: “you cannot rely on the most fundamental termination primitive anymore if someone uses VS Code to debug”

Fix it!

[rchiodo]

There was a proposal above on how to 'fix' this problem. Feel free to submit a PR if you want different behavior.

[rchiodo]

This one in particular seems like an easy out for this scenario:

#1591 (reply in thread)

[rchiodo]

Note to anybody trying this, it really comes down to setting the ignore_system_exit_codes list. Maybe if that's empty as @int19h suggested, it ignores all system exits.