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.