[libclang/python] Improve error reporting of TranslationUnit creating functions

[TsXor]

Provide more detailed errors when parsing a translation unit fails.
This is part 2 of #101784

[github-actions]

Thank you for submitting a Pull Request (PR) to the LLVM Project!

This PR will be automatically labeled and the relevant teams will be
notified.

If you wish to, you can add reviewers by using the "Reviewers" section on this page.

If this is not working for you, it is probably because you do not have write
permissions for the repository. In which case you can instead tag reviewers by
name in a comment by using @ followed by their GitHub username.

If you have received no comments on your PR for a week, you can request a review
by "ping"ing the PR by adding a comment “Ping”. The common courtesy "ping" rate
is once a week. Please remember that you are asking for valuable time from other developers.

If you have further questions, they may be answered by the LLVM GitHub User Guide.

You can also ask questions in a comment on this PR, on the LLVM Discord or on the forums.

[llvmbot]

@llvm/pr-subscribers-clang

Author: None (TsXor)

Changes

---

Full diff: https://github.com/llvm/llvm-project/pull/102410.diff

1 Files Affected:

• (modified) clang/bindings/python/clang/cindex.py (+38-1)

diff --git a/clang/bindings/python/clang/cindex.py b/clang/bindings/python/clang/cindex.py
index 2038ef6045c7d..4fcc20169eeb2 100644
--- a/clang/bindings/python/clang/cindex.py
+++ b/clang/bindings/python/clang/cindex.py
@@ -152,6 +152,41 @@ def b(x: str | bytes) -> bytes:
 ### Exception Classes ###
 
 
+class CXError(Exception):
+    '''Represents C error of type enum CXErrorCode.'''
+
+    # A generic error code, no further details are available.
+    #
+    # Errors of this kind can get their own specific error codes in future
+    # libclang versions.
+    ERROR_FAILURE = 1
+
+    # libclang crashed while performing the requested operation.
+    ERROR_CRASHED = 2
+
+    # The function detected that the arguments violate the function
+    # contract.
+    ERROR_INVALID_ARGUMENTS = 3
+
+    # An AST deserialization error has occurred.
+    ERROR_AST_READ_ERROR = 4
+
+    error_code: int
+
+    def __init__(self, enumeration: int, message: str):
+        assert isinstance(enumeration, int)
+
+        if enumeration < 1 or enumeration > 4:
+            raise Exception(
+                "Encountered undefined CXError "
+                "constant: %d. Please file a bug to have this "
+                "value supported." % enumeration
+            )
+
+        self.error_code = enumeration
+        Exception.__init__(self, "Error %d: %s" % (enumeration, message))
+
+
 class TranslationUnitLoadError(Exception):
     """Represents an error that occurred when loading a TranslationUnit.
 
@@ -3263,9 +3298,11 @@ def reparse(self, unsaved_files=None, options=0):
             unsaved_files = []
 
         unsaved_files_array = self.process_unsaved_files(unsaved_files)
-        ptr = conf.lib.clang_reparseTranslationUnit(
+        result = conf.lib.clang_reparseTranslationUnit(
             self, len(unsaved_files), unsaved_files_array, options
         )
+        if result != 0:
+            raise CXError(result, 'Error reparsing TranslationUnit.')
 
     def save(self, filename):
         """Saves the TranslationUnit to a file.

[DeinAlptraum]

Thanks for this change! Looks good to me, aside from a few minor comments, most importantly a release note.

Generally: for PR titles, a prefix ala "[libclang/python]" woud be good to denote the component or area of the code base, and empty descriptions are discouraged. Use these to add a few more details, as this is what will end up in the git log later.

On a side note, I see that there are not currently any tests for a failing reparse call. If you'd like to add some, that would be great, but imo not strictly necessary in the scope of this PR.

[github-actions]

✅ With the latest revision this PR passed the Python code formatter.

[TsXor]

CXError is merged into TranslationUnitLoadError, and error code is preserved in another commit.

[DeinAlptraum]

A couple minor comments, and the code formatting should be fixed (see output of the failing CI run), and then this is good to go!

[DeinAlptraum]

LGTM. Thanks for adding better error handling!
@Endilll do you also want to take a look at this before it is merged? Otherwise, this is good to go imo.