Currently, the atexit docs state

"The order in which the functions are called is not defined" in the introduction and

"all functions registered are called in last in, first out order" in the docs of the atexit() function.

While the latter is correct, I don't think we should guarantee that behaviour by documenting it.  Suggestions?

I believe it should be guaranteed behavior and that code may reasonably want to have a predictable sequence of unwinding behaviors.

It is guaranteed by libc's atexit(3), and should also be guaranteed here.

+1 to guaranteeing the order.

> I believe it should be guaranteed behavior and that code may
> reasonably want to have a predictable sequence of unwinding behaviors.

Agreed.

Here's a patch.  I read the implementation to find out what it does, then documented it.  Happily it does the sane thing.

> Here's a patch.  I read the implementation to find out what it does,
> then documented it.  Happily it does the sane thing.

Is it tested for?

See #9788 for previous discussion.

The patch wording is fine.  However, I would avoid the "note" markup.  It is visually distracting and there isn't a reason to pull this out of the main text.

> Is it tested for?

Amusingly enough, yes.  test_order() in Lib/test/test_atexit.py already ensures reverse order.

> I would avoid the "note" markup.  It is visually distracting
> and there isn't a reason to pull this out of the main text.

I think it's an improvement; it helps draw the eye to an important warning.

Does anyone else have an opinion one way or another?

> Does anyone else have an opinion one way or another?

I'm neutral.

I agree with Raymond. You might, however, emphasize 'normal' in 'normal
interpreter termination'. That is the key point. The 'note' merely explains 'abnormal'.

Okay, I'll remove the ".. note".  Checking in shortly.

New changeset f8b520b6f654 by Larry Hastings in branch 'default':
- Issue #15233: Python now guarantees that callables registered with
http://hg.python.org/cpython/rev/f8b520b6f654

So, it's checked in to trunk.  Shall I also backport to 2.7 and 3.2 as the issue suggests?

> Shall I also backport to 2.7 and 3.2 as the issue suggests?

If the tests are there, yes!

I have been meditating on this, and I'm not sure we should change 2.7.  3.2 might be okay.

The thing is, I fear we're not just talking about CPython implementation details, we're talking about the Python Standard Library.  The existing documentation clearly gives alternative implementations free license to call atexit registered functions in any order they like.  So it's conceivable that other implementations don't guarantee reverse order.

I don't know what the right thing is to do here.  It seems like we could define atexit's behavior for 2.7 *if* all the major alternative implementations happily also implicitly guarantee reverse order.  Failing that we probably shouldn't touch it.  Or we could just document that reverse order is guaranteed in CPython only.

Of course, there are no alternative implementations that support 3.2.  That's why I think 3.2 might be okay.  It does seem strange to redefine part of the implicit language spec more than a year after the release shipped though.

+1 for backport.  There's no benefit to leaving ambiguity floating about, nor was there ever any intention for the behavior to have been different.

Ping.
Like Raymond, I think there's no reason to leave ambiguity in 2.7 and 3.2,  so this doc patch is probably worth backporting.

Unless anyone objects, I'll backport it soonish.

New changeset 84d74eb7a341 by Charles-François Natali in branch '2.7':
Issue #15233: Python now guarantees that callables registered with the atexit
http://hg.python.org/cpython/rev/84d74eb7a341

Backported to 2.7.