[libclang/python] Add Cursor.from_translation_unit

[Endilll]

This should complete the list of things Cursor can be made from.

[llvmbot]

@llvm/pr-subscribers-clang

Author: Vlad Serebrennikov (Endilll)

Changes

This should complete the list of things Cursor can be made from.

---

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

3 Files Affected:

• (modified) clang/bindings/python/clang/cindex.py (+4)
• (modified) clang/bindings/python/tests/cindex/test_cursor.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 f65bcad780a70..615b70d5afb0f 100644
--- a/clang/bindings/python/clang/cindex.py
+++ b/clang/bindings/python/clang/cindex.py
@@ -1595,6 +1595,10 @@ class Cursor(Structure):
     def from_location(tu: TranslationUnit, location: SourceLocation) -> Cursor | None:
         return Cursor.from_result(conf.lib.clang_getCursor(tu, location), tu)
 
+    @staticmethod
+    def from_translation_unit(tu: TranslationUnit) -> Cursor | None:
+        return Cursor.from_result(conf.lib.clang_getTranslationUnitCursor(tu), tu)
+
     # This function is not null-guarded because it is used in cursor_null_guard itself
     def __eq__(self, other: object) -> bool:
         if not isinstance(other, Cursor):
diff --git a/clang/bindings/python/tests/cindex/test_cursor.py b/clang/bindings/python/tests/cindex/test_cursor.py
index eb0d1d50601a6..aeb387f7a6f62 100644
--- a/clang/bindings/python/tests/cindex/test_cursor.py
+++ b/clang/bindings/python/tests/cindex/test_cursor.py
@@ -1064,3 +1064,9 @@ def test_null_cursor(self):
             nc.is_definition()
         with self.assertRaises(Exception):
             nc.spelling
+
+    def test_cursor_from_tu(self):
+        tu = get_tu("int a = 0;")
+        cursor = Cursor.from_translation_unit(tu)
+        reference_cursor = tu.cursor
+        self.assertEqual(cursor, reference_cursor)        
diff --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst
index 4a3c1bee82831..8676c5a5e2cd5 100644
--- a/clang/docs/ReleaseNotes.rst
+++ b/clang/docs/ReleaseNotes.rst
@@ -959,6 +959,7 @@ Sanitizers
 Python Binding Changes
 ----------------------
 - Made ``Cursor`` hashable.
+- Added ``Cursor.from_translation_unit``, mirroring ``TranslationUnit.cursor``.
 - Added ``Cursor.has_attrs``, a binding for ``clang_Cursor_hasAttrs``, to check
   whether a cursor has any attributes.
 - Added ``Cursor.specialized_template``, a binding for

[github-actions]

⚠️ Python code formatter, darker found issues in your code. ⚠️

You can test this locally with the following command:

darker --check --diff -r HEAD~1...HEAD clang/bindings/python/clang/cindex.py clang/bindings/python/tests/cindex/test_cursor.py

View the diff from darker here.

--- tests/cindex/test_cursor.py	2025-05-19 06:20:55.000000 +0000
+++ tests/cindex/test_cursor.py	2025-05-19 06:25:20.022200 +0000
@@ -1067,6 +1067,6 @@
 
     def test_cursor_from_tu(self):
         tu = get_tu("int a = 0;")
         cursor = Cursor.from_translation_unit(tu)
         reference_cursor = tu.cursor
-        self.assertEqual(cursor, reference_cursor)        
+        self.assertEqual(cursor, reference_cursor)

[DeinAlptraum]

LGTM, but are you sure there is a need for this API? This just seems like a slighly less convenient version of TranslationUnit.cursor.

This should complete the list of things Cursor can be made from.

There is also a cursor property on Tokens

[Endilll]

Hmm, so the reason we have Cursor.from_source_location is that SourceLocation doesn't hold a reference to TU. Yeah, I guess we don't need this.