[libclang/python] Add a few things to the python api

[RedBeard0531]

I modified a local copy of cindex.py to add these when working on something and wanted to upstream the improvements.

[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: Mathias Stearn (RedBeard0531)

Changes

I modified a local copy of cindex.py to add these when working on something and wanted to upstream the improvements.

---

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

1 Files Affected:

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

diff --git a/clang/bindings/python/clang/cindex.py b/clang/bindings/python/clang/cindex.py
index f8a20a1e224724..2d0c2214ec9260 100644
--- a/clang/bindings/python/clang/cindex.py
+++ b/clang/bindings/python/clang/cindex.py
@@ -1552,6 +1552,9 @@ def from_location(tu, location):
 
         return cursor
 
+    def __hash__(self):
+        return self.hash
+
     def __eq__(self, other):
         return conf.lib.clang_equalCursors(self, other)  # type: ignore [no-any-return]
 
@@ -1797,7 +1800,7 @@ def mangled_name(self):
         return self._mangled_name
 
     @property
-    def location(self):
+    def location(self) -> SourceLocation:
         """
         Return the source location (the starting character) of the entity
         pointed at by the cursor.
@@ -2022,6 +2025,14 @@ def lexical_parent(self):
 
         return self._lexical_parent
 
+    @property
+    def specialized_template(self):
+        """Return the base template that this cursor is a specialization of, if any."""
+        return Cursor.from_cursor_result(
+            conf.lib.clang_getSpecializedCursorTemplate(self),
+            self
+        )
+
     @property
     def translation_unit(self):
         """Returns the TranslationUnit to which this Cursor belongs."""
@@ -2143,6 +2154,9 @@ def get_bitfield_width(self):
         """
         return conf.lib.clang_getFieldDeclBitWidth(self)  # type: ignore [no-any-return]
 
+    def has_attrs(self):
+        return bool(conf.lib.clang_Cursor_hasAttrs(self))
+
     @staticmethod
     def from_result(res, arg):
         assert isinstance(res, Cursor)
@@ -3401,6 +3415,12 @@ def __str__(self):
     def __repr__(self):
         return "<File: %s>" % (self.name)
 
+    def __eq__(self, other):
+        return isinstance(other, File) and bool(conf.lib.clang_File_isEqual(self, other))
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
+
     @staticmethod
     def from_result(res, arg):
         assert isinstance(res, c_object_p)
@@ -3795,6 +3815,7 @@ def write_main_file_to_stdout(self):
     ("clang_getCursorType", [Cursor], Type),
     ("clang_getCursorUSR", [Cursor], _CXString),
     ("clang_Cursor_getMangling", [Cursor], _CXString),
+    ("clang_Cursor_hasAttrs", [Cursor], c_uint),
     # ("clang_getCXTUResourceUsage",
     #  [TranslationUnit],
     #  CXTUResourceUsage),
@@ -3819,6 +3840,7 @@ def write_main_file_to_stdout(self):
     ("clang_getFile", [TranslationUnit, c_interop_string], c_object_p),
     ("clang_getFileName", [File], _CXString),
     ("clang_getFileTime", [File], c_uint),
+    ("clang_File_isEqual", [File, File], c_int),
     ("clang_getIBOutletCollectionType", [Cursor], Type),
     ("clang_getIncludedFile", [Cursor], c_object_p),
     (

[DeinAlptraum]

Hi and thanks for the PR!

To keep our history readable, please split this up into more focused PRs with an appropriate title ("Add a few things" won't be accepted ;)). This could be split into e.g. additions to the File interface, additions to the Cursor interface, and then type annotation(s).

If you add interfaces, please also add tests for them. has_attrs is also missing a doc string.

[github-actions]

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

You can test this locally with the following command:

darker --check --diff -r 6f8afafd308d37d9abc4af0801dd5a4451c13718...1c68440616b555c376a3c227338f23ca80a2c777 clang/bindings/python/clang/cindex.py

View the diff from darker here.

--- cindex.py	2024-12-19 15:22:04.000000 +0000
+++ cindex.py	2024-12-19 16:32:57.052528 +0000
@@ -2027,12 +2027,11 @@
 
     @property
     def specialized_template(self):
         """Return the base template that this cursor is a specialization of, if any."""
         return Cursor.from_cursor_result(
-            conf.lib.clang_getSpecializedCursorTemplate(self),
-            self
+            conf.lib.clang_getSpecializedCursorTemplate(self), self
         )
 
     @property
     def translation_unit(self):
         """Returns the TranslationUnit to which this Cursor belongs."""
@@ -3414,11 +3413,13 @@
 
     def __repr__(self):
         return "<File: %s>" % (self.name)
 
     def __eq__(self, other):
-        return isinstance(other, File) and bool(conf.lib.clang_File_isEqual(self, other))
+        return isinstance(other, File) and bool(
+            conf.lib.clang_File_isEqual(self, other)
+        )
 
     def __ne__(self, other):
         return not self.__eq__(other)
 
     @staticmethod

[DeinAlptraum]

@Endilll since there hasn't been a reply in months, do you think it's appropriate to close this?

[Endilll]

Even though this PR is rather small, it is still a bunch of changes here and there. I'd prefer it to be split up into multiple focused PRs.

[Endilll]

I wonder if "base template" should be replaced with the Standard term "primary template".

[Endilll]

@Endilll since there hasn't been a reply in months, do you think it's appropriate to close this?

Our existing practice is that PRs remain to linger like this until someone picks them up. Closing it would be "we don't want this" answer, and it wouldn't be correct.

That's how we end up with ever-growing number of opened PRs, yeah.

[DeinAlptraum]

Okay, thanks for the explanation & review :D I guess I might take this over if I have time then, which might be some time late in April (work is extremely busy)

[DeinAlptraum]

I am closing this PR since all changes here have been implemented in other PRs:

• Additions to the File interface: [libclang/python] Add equality comparison operators for File #130383
• Additions to the Cursor interface: [libclang/python] Add some bindings to the Cursor interface #132377
• Type annotations: [libclang/python] Add typing annotations for the Cursor class #138103