bpo-43950: Add documentation for PEP-657

[ammaraskar]

First pass at documenting the feature.

https://bugs.python.org/issue43950

[isidentical]

@ammaraskar can we separate co_positions() from traceback stuff? I think they are two separate features, and one masking the other right now might make users miss the co_positions() API.

[isidentical]

Thanks @ammaraskar for taking the first pass on documentation. I think overall it looks great!

[ammaraskar]

@ammaraskar can we separate co_positions() from traceback stuff? I think they are two separate features, and one masking the other right now might make users miss the co_positions() API.

Added a separate section for this to make it harder to miss.

[isidentical]

LGTM

[ammaraskar]

Rebased and squashed with the CPython specific column limit removed. Hopefully the documentation conveys that you should always be prepared to handle None with the API :)

Anything else to address here?

[pablogsal]

Let's focus next on finishing the specialized formats so the docs are up to date with that

[ammaraskar]

Updated the existing examples for #27037 but maybe we should put an example of a complicated arithmetic expression to show off that specialization as well?

[pablogsal]

Updated the existing examples for #27037 but maybe we should put an example of a complicated arithmetic expression to show off that specialization as well?

Yeah, I want to also prepare in a separate PR some mini tutorial/example on how to use the Python fields.

We should also document "how to read the new tracebacks", especially for the specializations. For that, we should ask the one and only @willingc for advice on what's the best way to document it and where :)

[ammaraskar]

Added an example for binary operations.

We should also document "how to read the new tracebacks"

Definitely, both of those sound good for follow-up docs. Maybe we can ask the overarching docs working group and specifically cc Carol in for help :)

[ammaraskar]

Ready to go 🚀

[pablogsal]

Nice 👍