Undocumented behavior of predicates in ExceptionGroup methods

[sobolevn]

I want to understand if my finding is a bug, or it works as intended and just needs a better explanation in the docs.

Right now the docs say:

   .. method:: subgroup(condition)

      Returns an exception group that contains only the exceptions from the
      current group that match *condition*, or ``None`` if the result is empty.

      The condition can be either a function that accepts an exception and returns
      true for those that should be in the subgroup, or it can be an exception type
      or a tuple of exception types, which is used to check for a match using the
      same check that is used in an ``except`` clause.

So, basically it promises that it will call this predicate for all exceptions in a group.

Let's test this:

>>> def p(e):
...    print(type(e), e)
...    return isinstance(e, ValueError)
... 
>>> eg = ExceptionGroup('message', [
...             ValueError(1), TypeError(2), ValueError(3),
...         ])
>>> eg.subgroup(p)
<class 'ExceptionGroup'> message (3 sub-exceptions)
<class 'ValueError'> 1
<class 'TypeError'> 2
<class 'ValueError'> 3
ExceptionGroup('message', [ValueError(1), ValueError(3)])

Notice that the first time that it is called, it uses ExceptionGroup argument.

But, let try to always return True this time:

>>> called_times = 0
>>> def p(e):
...    global called_times
...    called_times += 1
...    print(type(e), e)
...    return True
... 
>>> eg = ExceptionGroup('message', [
...             ValueError(1), TypeError(2), ValueError(3),
...         ])
>>> eg.subgroup(p)
<class 'ExceptionGroup'> message (3 sub-exceptions)
ExceptionGroup('message', [ValueError(1), TypeError(2), ValueError(3)])
>>> assert called_times == 1

Now it is only called once.

As far as I understand it works like this:

1. Firstly, it tries to call the predicate function with ExceptionGroup itself
2. If True is returned, it just uses this group as a result and ends
3. If False is returned the first time, it then calls this function again for all the exceptions in a group

Code to illustrate that:

>>> called_times = 0
>>> def p(e):
...             global called_times
...             called_times += 1
...             print(type(e), e)
...             return called_times > 1
... 
>>> eg = ExceptionGroup('message', [
...             ValueError(1), TypeError(2), ValueError(3),
...         ])
>>> 
>>> eg.subgroup(p)
<class 'ExceptionGroup'> message (3 sub-exceptions)
<class 'ValueError'> 1
<class 'TypeError'> 2
<class 'ValueError'> 3
ExceptionGroup('message', [ValueError(1), TypeError(2), ValueError(3)])

Is it correct, @iritkatriel?
I found it while working on python/typeshed#9219

[iritkatriel]

So, basically it promises that it will call this predicate for all exceptions in a group.

No, it says below in the doc:

The condition is checked for all exceptions in the nested exception group, including the top-level and any nested exception groups. If the condition is true for such an exception group, it is included in the result in full.

Is it necessary to state also that it will not recurse into a subtree that is included in the result in its entirety?

[sobolevn]

Thank you for the quick answer!

Is it necessary to state also that it will not recurse into a subtree that is included in the result in its entirety?

It might be worth it, if this is not just an implementation detail.

[iritkatriel]

I'd rather not. It is an implementation detail. I don't think the doc currently implies otherwise.

[sobolevn]

Fair enough! From typeshed's perspective we will be happy with both :)