`sys.exit` unpacks its argument if it is a 0- or 1-element tuple

[dscorbett]

Bug report

Bug description:

The documentation of sys.exit says “The optional argument arg can be an integer giving the exit status (defaulting to zero), or another type of object. [...] If another type of object is passed, None is equivalent to passing zero, and any other object is printed to stderr and results in an exit code of 1.” This is no longer true for 0- and 1-element tuples in Python 3.12 and later. It acts like the argument is unpacked: sys.exit(()) is treated like sys.exit() and sys.exit((x,)) is treated like sys.exit(x).

$ python3.11 -c 'import sys; sys.exit(())'; echo $?
()
1

$ python3.12 -c 'import sys; sys.exit(())'; echo $?
0

$ python3.11 -c 'import sys; sys.exit((2,))'; echo $?
(2,)
1

$ python3.12 -c 'import sys; sys.exit((2,))'; echo $?
2

CPython versions tested on:

3.12, 3.13, CPython main branch

Operating systems tested on:

macOS

Linked PRs

• gh-133548: fix handling of empty and 1-item tuples for sys.exit #135789

[terryjreedy]

Can you find the issue that made the change (git blame) and see if the behavior change was intended? If so, the doc should be changed.

[brianschubert]

This bisects to feec49c (#101607), cc @markshannon

[AndPuQing]

Analysis of the Behavior Change

I've investigated this issue and found the root cause of the behavior change. This appears to be an unintended consequence of the exception normalization process.

Root Cause Analysis

The behavior change occurs through this call chain:

1. sys.exit((2,)) calls sys_exit_impl()
2. Which calls PyErr_SetObject(PyExc_SystemExit, status) where status = (2,)
3. This triggers exception normalization in _PyErr_SetObject()
4. The normalization calls _PyErr_CreateException() which eventually invokes SystemExit.__init__()
5. In SystemExit_init(), when size == 1, it unpacks the single argument:

   if (size == 1) {
       Py_XSETREF(self->code, Py_NewRef(PyTuple_GET_ITEM(args, 0)));
   }

The Issue

When sys.exit((2,)) is called:

• The tuple (2,) gets passed to SystemExit.__init__() as args = (2,)
• Since len(args) == 1, SystemExit unpacks it and sets self.code = 2

However, when directly calling raise SystemExit((2,)):

• The tuple (2,) is passed as args = ((2,),) to SystemExit.__init__()
• The same unpacking occurs, but the exit code handling path is different

Inconsistency

This creates an inconsistency:

• sys.exit((2,)) → exit code 2 (Python 3.12+)
• raise SystemExit((2,)) → exit code 1 (prints the tuple to stderr)

Recommendation

Honestly, this feels like an accidental side effect rather than an intentional design change. The fact that sys.exit() and raise SystemExit() now behave differently with the same arguments seems pretty weird to me.
I think we should probably:

1. Update the docs to match what actually happens now (since the current docs are just wrong, and this behavior has been going on for a long time.)
2. Maybe file another issue about the sys.exit() vs raise SystemExit() inconsistency? It's kind of annoying that these two do different things now.

I'm leaning towards fixing the docs first since that's the immediate problem, but the inconsistency thing bugs me too. What do you think - should I open a separate issue for that?

[picnixz]

Maybe file another issue about the sys.exit() vs raise SystemExit() inconsistency?

No need for another issue. This issue is already about the inconsistency.

Update the docs to match what actually happens now (since the current docs are just wrong, and this behavior has been going on for a long time.)

I don't think it's a doc issue; it's an implementation issue here. I prefer having 3.12 buggy rather than having all versions changed since 3.12. I think it was an unexpected change (and note that sys.exit([1]) behaves correctly, so in this case we should have sys.exit((1,)) and sys.exit([1]) behave the same).

---

The issue itself is different. Actually, SystemExit.__init__() has args = (2,) whether it's invoked as sys.exit(2) or sys.exit((2,). So it's impossible to distinguish between those two. What needs to be done is check this in SystemExit.__init__ (my previous patch only patched sys.exit() but semantics are actually the same, my bad)

[picnixz]

@markshannon Do you prefer to handle the status like that directly in SystemExit or do you prefer to change how normalization happens (but this may be annoying for other reasons). I think we have other places where we wrapped the exception tuple args to prevent the constructor flattening them (though, I don't know if we have a function for that exactly).

[picnixz]

Huh, looking at the tests:

        # call with tuple argument with one entry
        # entry will be unpacked
        with self.assertRaises(SystemExit) as cm:
            sys.exit((42,))
        self.assertEqual(cm.exception.code, 42)

And this check hasn't been touched since 2003... but we actually never tested raise SystemExit here, which is a bit annoying.