release/21.x: [libclang/python] Return None instead of null cursors from Token.cursor (#163183)

[DeinAlptraum]

Backport 38a5282

[DeinAlptraum]

From #163183

[llvmbot]

@llvm/pr-subscribers-clang

Author: Jannick Kremer (DeinAlptraum)

Changes

Backport 38a5282

---

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

3 Files Affected:

• (modified) clang/bindings/python/clang/cindex.py (+2)
• (modified) clang/bindings/python/tests/cindex/test_tokens.py (+6)
• (modified) clang/docs/ReleaseNotes.rst (+1)

diff --git a/clang/bindings/python/clang/cindex.py b/clang/bindings/python/clang/cindex.py
index 824674309d262..5ce7b5781bcb4 100644
--- a/clang/bindings/python/clang/cindex.py
+++ b/clang/bindings/python/clang/cindex.py
@@ -3853,6 +3853,8 @@ def cursor(self):
         cursor._tu = self._tu
 
         conf.lib.clang_annotateTokens(self._tu, byref(self), 1, byref(cursor))
+        if cursor.is_null():
+            return None
 
         return cursor
 
diff --git a/clang/bindings/python/tests/cindex/test_tokens.py b/clang/bindings/python/tests/cindex/test_tokens.py
index b6c1fc8b83600..6658579c63835 100644
--- a/clang/bindings/python/tests/cindex/test_tokens.py
+++ b/clang/bindings/python/tests/cindex/test_tokens.py
@@ -53,3 +53,9 @@ def test_token_extent(self):
 
         self.assertEqual(extent.start.offset, 4)
         self.assertEqual(extent.end.offset, 7)
+
+    def test_null_cursor(self):
+        """Ensure that the cursor property converts null cursors to None"""
+        tu = get_tu("int i = 5;")
+        tokens = list(tu.get_tokens(extent=tu.cursor.extent))
+        self.assertEqual(tokens[-1].cursor, None)
diff --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst
index 43529b0f28c3d..364ea632b40cb 100644
--- a/clang/docs/ReleaseNotes.rst
+++ b/clang/docs/ReleaseNotes.rst
@@ -94,6 +94,7 @@ Clang Frontend Potentially Breaking Changes
 
 Clang Python Bindings Potentially Breaking Changes
 --------------------------------------------------
+- Return ``None`` instead of null cursors from ``Token.cursor``
 - ``Cursor.from_location`` now returns ``None`` instead of a null cursor.
   This eliminates the last known source of null cursors.
 - Almost all ``Cursor`` methods now assert that they are called on non-null cursors.

[AaronBallman]

LGTM!

[DeinAlptraum]

I get
"Merging is blocked
Cannot update this protected ref."
Can one of you merge this?

[Endilll]

I get "Merging is blocked Cannot update this protected ref." Can one of you merge this?

No, it's up to the release managers to merge it.

[github-actions]

@DeinAlptraum (or anyone else). If you would like to add a note about this fix in the release notes (completely optional). Please reply to this comment with a one or two sentence description of the fix. When you are done, please add the release:note label to this PR.

[DeinAlptraum]

Return None instead of null cursors from Token.cursor. This fixes a bug in version 21 where cursors obtained via Token.Cursor were sometimes null cursors that produce errors when used.