Deprecate gen.throw(typ, val, tb)

[gvanrossum]

CC: @iritkatriel

Issue GH-89874 gets rid of exception triples where it makes sense. I don't know if it was considered, but another place where such triples are supported is the gen.throw(). It allows passing either an exception, or a (type, value, traceback) triple where the value and traceback are optional. I think it makes sense to keep allowing passing an exception type, but I don't see the use case for passing separate type and value. We could deprecate this easily by adding a warning to gen_throw() when more than one argument is present.

Thoughts?

[rhettinger]

This would be a nice simplification. AFAICT, the three argument form is rarely used, so deprecating that variant won't be disruptive. Also, when the signature becomes METH_O, calls to gen.throw will get faster.

[iritkatriel]

Yes, this would be good. The triplet is not just wasteful, it's also ambiguous when val.__traceback__ != tb.

[gvanrossum]

I wonder if this could be marked as an "easy" issue for someone with moderate C skills to tackle? All you have to do (for now) is issue a deprecation warning if the arg count is larger than 1. (And update some docs.)

[iritkatriel]

Marked as easy, but also as release-blocker for 3.12 so we won't forget.

[ofey404]

I wonder if this could be marked as an "easy" issue for someone with moderate C skills to tackle? All you have to do (for now) is issue a deprecation warning if the arg count is larger than 1. (And update some docs.)

Does it locate in Objects/iterobject.c? I'm trying to become a core developer and willing to help.

cpython/Objects/iterobject.c

Lines 413 to 416 in af368a7

	static PyObject *
	anextawaitable_throw(anextawaitableobject *obj, PyObject *arg) {
	return anextawaitable_proxy(obj, "throw", arg);
	}

And the (type, value, traceback) triple documentation:

help(a.throw)
Help on built-in function throw:

throw(...) method of builtins.generator instance
    throw(typ[,val[,tb]]) -> raise exception in generator,
    return next yielded value or raise StopIteration.

[gvanrossum]

No, I'm looking at gen_throw in genobject.c. Looks like you found another instance of the same problem!

[ofey404]

I got it, here is the genobject.c:gen_throw doc:

cpython/Objects/genobject.c

Lines 1145 to 1150 in af368a7

	PyDoc_STRVAR(coro_throw_doc,
	"throw(value)\n\
	throw(type[,value[,traceback]])\n\
	\n\
	Raise exception in coroutine, return next iterated value or raise\n\
	StopIteration.");

Besides, there is another occurrence in genobject.c, the async_gen_athrow:

cpython/Objects/genobject.c

Lines 1539 to 1540 in af368a7

	PyDoc_STRVAR(async_athrow_doc,
	"athrow(typ[,val[,tb]]) -> raise exception in generator.");

And how to throw deprecation warning from cpython c code? I searched the web but didn't find much useful material.

[arhadthedev]

The keywords here are PyExc_DeprecationWarning and PyErr_WarnEx (I've briefly seen these names before but didn't use them in practice). Here are relevant examples, though I don't know how to determine the last parameter of the function (7 in two examples, 2 in the third):

cpython/Modules/spwdmodule.c

Lines 256 to 267 in 692e907

	PyMODINIT_FUNC
	PyInit_spwd(void)
	{
	if (PyErr_WarnEx(PyExc_DeprecationWarning,
	"'spwd' is deprecated and slated for removal in "
	"Python 3.13",
	7)) {
	return NULL;
	}
	return PyModuleDef_Init(&spwdmodule);
	}

cpython/Modules/nismodule.c

Lines 524 to 534 in 804f252

	PyMODINIT_FUNC
	PyInit_nis(void)
	{
	if (PyErr_WarnEx(PyExc_DeprecationWarning,
	"'nis' is deprecated and slated for removal in "
	"Python 3.13",
	7)) {
	return NULL;
	}
	return PyModuleDef_Init(&nismodule);
	}

cpython/Modules/_asynciomodule.c

Lines 1110 to 1126 in b2afe48

	static PyObject *
	_asyncio_Future_cancel_impl(FutureObj *self, PyObject *msg)
	/*[clinic end generated code: output=3edebbc668e5aba3 input=925eb545251f2c5a]*/
	{
	if (msg != Py_None) {
	if (PyErr_WarnEx(PyExc_DeprecationWarning,
	"Passing 'msg' argument to Future.cancel() "
	"is deprecated since Python 3.11, and "
	"scheduled for removal in Python 3.14.",
	2))
	{
	return NULL;
	}
	}
	ENSURE_FUTURE_ALIVE(self)
	return future_cancel(self, msg);
	}

[ofey404]

The keywords here are PyExc_DeprecationWarning and PyErr_WarnEx (I've briefly seen these names before but didn't use them in practice).

Besides, I wonder are there any unit test catching depreciated warning? I randomly delete one warning in cpython source code, but all test suite still passed.

[CharlieZhao95]

Besides, I wonder are there any unit test catching depreciated warning? I randomly delete one warning in cpython source code, but all test suite still passed.

You might refer to a historical commit(beea26b) from vstinner, which uses assertWarns to check if the DeprecationWarning is thrown.

with self.assertWarns(DeprecationWarning):
    do_something()

Also, you can check the git log of the deprecated module to see if the unit test was also committed :)

[gvanrossum]

I don't know how to determine the last parameter of the function (7 in two examples, 2 in the third)

This is the number of (Python) stack levels to skip when computing the file name and line number to appear in the message. I'd start setting it to 1 and see what warning message actually gets printed. Increase it until the filename is reasonable.

[kumaraditya303]

While we are at it, the same should be done for async generators too.

[ofey404]

I opened a pull request: #96428

One problem: raise DeprecationWarning will break so many lib tests, since they use the (type, val, tb) exception representation.

Eg:

cpython/Lib/contextlib.py

Lines 154 to 155 in 22ed523

	try:
	self.gen.throw(typ, value, traceback)

[gvanrossum]

Would it be reasonable to fix the failing tests in the same PR? Or are there too many? They should all just switch to throwing the middle value of the triple (the exception instance).

[iritkatriel]

You'll get pretty far with the tests if you fix this one:

--- a/Lib/contextlib.py
+++ b/Lib/contextlib.py
@@ -152,7 +152,7 @@ def __exit__(self, typ, value, traceback):
                 # tell if we get the same exception back
                 value = typ()
             try:
-                self.gen.throw(typ, value, traceback)
+                self.gen.throw(value)
             except StopIteration as exc:
                 # Suppress StopIteration *unless* it's the same exception that
                 # was passed to throw().  This prevents a StopIteration

[ofey404]

The problem size is not so large. I'll try to submit a version fixing them.

With regex throw\(.*,.*,.*\), there are 51 results in 12 files.

• 3 file is under Lib
• 1 is in Lib/lib2to3/fixes
• The rest are tests.
• 51 results in 12 files.txt

[iritkatriel]

Not all of them need to be ‘fixed’ though.

Some of the tests are testing the deprecated API and need to stay (with the deprecation warning suppressed).

lib2to3 maps the deprecated form to the single arg form. It should not change.

Also, I would run the tests and see what fails rather than rely on a regex search.

[iritkatriel]

Note also that just emitting a deprecation warning doesn’t cause tests to fail (we don’t run the tests with warnings-as-errors in CI).

This is why I suggested the change in #96348 (comment), because that actually causes most (if not all) of the test failures.

[ofey404]

This is why I suggested the change in #96348 (comment), because that actually causes most (if not all) of the test failures.

You're right.

[ofey404]

Should we close this since the PR is merged?

[gvanrossum]

Search other C files in the same directory for DeprecationWarning.

…

-- --Guido (mobile)

[AdamWill]

Wasn't this deprecation rather aggressive?

For generators at least, the single-argument form was only added in Python 3.9, at least according to the docs. It's not mentioned in the 3.8 docs, it only appears in the 3.9 docs.

3.8 is still in support for another whole year. So if I'm trying to fix something - like twisted - to not print deprecation warnings constantly on Python 3.12, I either have to break it for a still-supported version of Python, or use some kind of rather ugly conditional to figure out what to pass it, right?

[AdamWill]

...or is this similar to #105269 and the single-argument form was actually added earlier, but not documented?