PEP 678: new API for add_note()

[Zac-HD]

Just after my last PR - and after we'd asked the Steering Council to consider the PEP - we had some translation-related concerns that ended up prompting a slight redesign. So here's another PR with the new interface!

(and I'm sorry for the churn! Thanks for maintaining the backport 💖)

[agronholm]

Add a changelog entry and we're good.

I take it that the py3.11 tests will start working with the next alpha release?

[Zac-HD]

I take it that the py3.11 tests will start working with the next alpha release?

Yep, should do. If you want to hold off on merging until then that's fine by me.

[agronholm]

If you compile the latest version from main and run the test suite on that and it passes, I'll agree to merge this.

[Zac-HD]

It's currently on the Steering Council agenda and in python/cpython#31317, so holding this PR until the PEP is accepted or a 3.11 alpha released with the new API would make me more comfortable.

And again, I'm sorry for the churn! The "how can you provide localization and translation for notes" discussion thread - which prompted these changes - came up the day after I first sent this to the SC for consideration 😓

[agronholm]

Sure, let's wait until then.

[Zac-HD]

PEP-678 has formally been accepted (🥳), and I've updated this PR accordingly with the final design.

Once python/cpython#31317 is merged upstream, I'll confirm that the 3.11 tests pass on CPython main, and then we'll be all set for 3.11.0b1 in early May.

[Zac-HD]

Having drafted the Hypothesis PR I'll want to use this in, I'm also planning to add a helper function

def add_note(exc: BaseException, note: str) -> None:
    try:
        exc.add_note(note)
    except AttributeError:
        if not isinstance(note, str):
            raise TypeError(f"Note must be a string, got {type(note).__name__}")
        if not hasattr(exc, "__notes__"):
            exc.__notes__ = []
        exc.__notes__.append(note)

on the basis that either we ship it in the backport, or literally everyone who wants to use PEP-678 notes will have to implement it for themselves.

[agronholm]

Have you confirmed that this PR passes against CPython 3.11 main? If so, then I'll merge.

[Zac-HD]

It seems to work, though I wanted to confirm that everything plays well together over the weekend before asking you to merge and release - apologies for the delay, but I was asked to present a tutorial at PyCon next week and that's been a fairly urgent call on my OSS time.

[Zac-HD]

@agronholm - I've retested everything against CPython nightly locally, and it's ready to merge 🚀

Thanks again for your patience!

[agronholm]

Thanks!

[Zac-HD]

Nice! Ping me when you release on PyPI?

[agronholm]

Done.

[Zac-HD]

Awesome!