Repository navigation
new throw() / athrow() syntax w/ single value is not clearly documented or noted as new in python 3.12 #105269
Description
Documentation
the docs at
cpython/Doc/reference/expressions.rst
Line 755 in 94a1eea
throw(value) calling style appears to be new in Python 3.12; docs for 3.11 do not refer to it: cpython/Doc/reference/expressions.rst
Line 743 in 8de607a
throw(). It's not clear to us here if using throw(value) will work identically on older Python versions. Looking at 396b583 it seems to be possibly 3.11 related, but in #96348 @gvanrossum claims "It allows passing either an exception, or a (type, value, traceback) triple where the value and traceback are optional. ", but this does not seem to be documented and is creating some confusion over here.
the changelog as well as the deprecation warning both refer to the "single arg version" , which will "work" on older py3 versions but has different behavior (Edit: or maybe it doesn't. we're not sure :) ).
can this document be clarified as to what differences, if any, exist between athrow(value) and athrow(type, value) and within what Python versions this new style should be accepted as an exact drop-in for the old style? thanks
Linked PRs
- [3.11] Add single value
agen.athrow(value)signature to the 3.11 docs gh-105269 #105468 - [3.9] [3.11] Add single value
agen.athrow(value)signature to the 3.11 docs gh-105269 (GH-105468) #105477 - [3.8] [3.11] Add single value
agen.athrow(value)signature to the 3.11 docs gh-105269 (GH-105468) #105478 - [3.7] [3.11] Add single value
agen.athrow(value)signature to the 3.11 docs gh-105269 (GH-105468) #105479 - [3.10] [3.11] Add single value
agen.athrow(value)signature to the 3.11 docs gh-105269 (GH-105468) #105480
Activity
terryjreedy commentedon Jun 3, 2023
@gvanrossum @iritkatriel Questions about (doc of) athrow(v) vs. athrow(t, v) vs athrow(t,b,t) and versions.
iritkatriel commentedon Jun 3, 2023
@zzzeek Would you like to make a patch with doc updates?
zzzeek commentedon Jun 3, 2023
if you could tell me what the docs would say? Is there any change in behavior for
athrow(value)vs.athrow(type, value, tback)? I vaguely recall similar functions where these are in fact equivalent but my co-maintainer @CaselIT is not sureiritkatriel commentedon Jun 3, 2023
If there is then please file a bug report.
zzzeek commentedon Jun 3, 2023
Hi -
The bug is, "the documentation does not explain this". I dont understand the documentation, and I dont know how to write the documentation because I don't understand the API. Do I need to file a bug report under a different tag? I had the impression that "documentation bugs" was the appropriate place to post this.
iritkatriel commentedon Jun 4, 2023
No this issue is fine for the documentation.
CaselIT commentedon Jun 4, 2023
so the idea here is to document also for version previous to 3.12 the call signature
athrow(value)? so copy paste the 3.12 documentation minus the deprecation?CaselIT commentedon Jun 7, 2023
I've created this PR #105468 to 3.11 branch.
Should I also create backports to other branches? Down to what version?
iritkatriel commentedon Jun 7, 2023
Thank you. We may be able to do automatic backports so hold off for now.
[3.11] Add single value `agen.athrow(value)` signature to the 3.11 docs
[3.11] Add single value `agen.athrow(value)` signature to the 3.11 docs
[3.11] Add single value `agen.athrow(value)` signature to the 3.11 docs
[3.11] Add single value `agen.athrow(value)` signature to the 3.11 docs
[3.11] Add single value `agen.athrow(value)` signature to the 3.11 docs
iritkatriel commentedon Jun 7, 2023
Thank you @zzzeek and @CaselIT !
[3.7] Add single value `agen.athrow(value)` signature to the 3.11 docs …
[3.10] [3.11] Add single value `agen.athrow(value)` signature to the …
[3.9] [3.11] Add single value `agen.athrow(value)` signature to the 3…
[3.8] [3.11] Add single value `agen.athrow(value)` signature to the 3…
[3.9] [3.11] Add single value `agen.athrow(value)` signature to the 3…