add API to generate leaf exception from exceptongroup

exceptiongroup/__init__.py

@@ -2,7 +2,7 @@
 
 from ._version import __version__
 
-__all__ = ["ExceptionGroup", "split", "catch"]
+__all__ = ["ExceptionGroup", "split", "catch", "leaf_exceptions"]
 
 
 class ExceptionGroup(BaseException):
@@ -64,4 +64,4 @@ def __repr__(self):
 
 
 from . import _monkeypatch
-from ._tools import split, catch
+from ._tools import split, catch, leaf_exceptions

exceptiongroup/_tests/test_tools.py

@@ -1,5 +1,7 @@
+from collections.abc import Iterable
 import pytest
-from exceptiongroup import ExceptionGroup, split
+
+from exceptiongroup import ExceptionGroup, split, leaf_exceptions
 
 
 def raise_error(err):
@@ -117,3 +119,39 @@ def test_split_and_check_attributes_same():
     assert unmatched.__cause__ is new_group.__cause__
     assert unmatched.__context__ is new_group.__context__
     assert unmatched.__suppress_context__ is new_group.__suppress_context__
+
+
+def test_leaf_exceptions_iterable():
+    group = ExceptionGroup("error", [RuntimeError("error1")], ["error1"])
+    result = leaf_exceptions(group)
+    assert isinstance(result, Iterable)
+
+
+def test_leaf_exceptions_values():
+    leaf_error1 = RuntimeError("Error1")
+    leaf_error2 = RuntimeError("Error2")
+    group = ExceptionGroup(
+        "error", [leaf_error1, leaf_error2], ["Error1", "Error2"]
+    )
+    result = list(leaf_exceptions(group))
+    assert result == [leaf_error1, leaf_error2]
+
+    # test for exception group which contains nested group
+    group = ExceptionGroup(
+        "error",
+        [leaf_error1, ExceptionGroup("Error2", [leaf_error2], ["Error2"])],
+        ["Error1", "Error2"],
+    )
+    result = list(leaf_exceptions(group))
+    assert result == [leaf_error1, leaf_error2]
+
+
+def test_leaf_exceptions_with_bare_exception():
+    error1 = RuntimeError("Error1")
+    result = list(leaf_exceptions(error1))
+    assert result == [error1]
+
+
+def test_leaf_exception_with_non_exception_object():
+    with pytest.raises(TypeError):
+        list(leaf_exceptions(None))

exceptiongroup/_tools.py

@@ -6,6 +6,37 @@
 from . import ExceptionGroup
 
 
+def leaf_exceptions(exc):
+    """ Iterate and extract sub exceptions from given exception.
+    When sub exceptions is also ExceptionGroup, it will iterate the
+    ExceptionGroup's sub-exceptions recursively.
+
+    Args:
+        exc (BaseException): Exception object we want to extract.
+    Returns:
+        An iterable of BaseException object.
+
+    Examples:
+        error1 = RuntimeError("Error1")
+        error2 = RuntimeError("Error2")
+        group = ExceptionGroup(
+            "errorGroup",
+            [error1, error2],
+            ["Error1", "Error2"]
+        )
+        assert list(leaf_exceptions(group)) == [error1, error2]
+    """
+    if not isinstance(exc, BaseException):
+        raise TypeError(
+            "Argument `exc` should be an instance of BaseException."
+        )
+    if isinstance(exc, ExceptionGroup):
+        for subexc in exc.exceptions:
+            yield from leaf_exceptions(subexc)
+    else:
+        yield exc
+
+
 def split(exc_type, exc, *, match=None):
     """ splits the exception into one half (matched) representing all the parts of
     the exception that match the predicate, and another half (not matched)