When BaseException.with_traceback(tb) is used, the __traceback__ property is properly set, but the property gets overwritten when the exception is raised. 

The attached file demonstrates the issue by raising exception a, which doesn't use with_traceback, and exception b, which uses with_traceback(a.__traceback__). It also demonstrates that the exception object can't observe this change. Executing the attached file produces output like:

a.__traceback__ before raise: [None]
a.__traceback__ after raise : [<traceback object at 0x7f95c5a21708>]
b.__traceback__ before raise: [<traceback object at 0x7f95c5a21708>]
b.__traceback__ after raise : [<traceback object at 0x7f95c5a21748>]

With_traceback's original oupose is now served by chained tracebacks and 'from'.  However, it is documented to work so it ought to :)

My understanding is that the traceback is a linked list. Every time the exception is raised into a calling function or exception handler, a new traceback object is inserted at the front of the list. Your original traceback is not overwritten, it is just pushed back in the list. See my version of the demonstration script. The output is now:

a.__traceback__ before raise : [None]
a.__traceback__ after raise : [<traceback object at 0xb6fb3b1c>, None]
b.__traceback__ before raise : [<traceback object at 0xb6fb3b1c>, None]
b.__traceback__ after raise : [<traceback object at 0xb6fb3b44>, <traceback object at 0xb6fb3b1c>, None]

Oh,of course.  This issue was bugging the back of my brain after I commented on it, but I hadn't circled back to figure it out.  Thanks, Martin, I'll close this as not a bug.

Thanks, Martin--I should've thought to check to see if it'd just been pushed back in the list. I was just focusing on a workaround for another problem and did a double-take when the traceback value didn't match what was set.

This resolution is fine by me, but a note in the doc for with_traceback (https://docs.python.org/3/library/exceptions.html#BaseException.with_traceback) that it'll be immediately bumped back in the list when raised (as in the documentation's usage example) might help clarify for others.

Yes, a doc note would be a good idea, I think.

I've had a very hard time adding to the doc in a way that elucidates rather than further obfuscating; see if you like this patch.

The new PR has an alternative suggestion for a change, where I tried to incorporate both Travis's and David's points: (1) there are better alternatives now for exception chaining (2) the current frame gets pushed on the traceback when the exception is raised.

New changeset c590c2338e5a36cf3ce5b55e6d366a0675ed1db5 by Irit Katriel in branch 'master':
bpo-23915: update and elucidate documentation of with_traceback (GH-23680)
https://github.com/python/cpython/commit/c590c2338e5a36cf3ce5b55e6d366a0675ed1db5