[clang] 59f815b - [libclang/python] Deprecate CodeCompletionResults.results (#177764)

[via cfe-commits]

Author: Jannick Kremer
Date: 2026-02-01T23:15:38+09:00
New Revision: 59f815b047c8f2673622550a613ec42adcb809c6

URL: https://github.com/llvm/llvm-project/commit/59f815b047c8f2673622550a613ec42adcb809c6
DIFF: https://github.com/llvm/llvm-project/commit/59f815b047c8f2673622550a613ec42adcb809c6.diff

LOG: [libclang/python] Deprecate CodeCompletionResults.results (#177764)

This partially addresses point 5 from
https://github.com/llvm/llvm-project/issues/156680.

Added: 
    

Modified: 
    clang/bindings/python/clang/cindex.py
    clang/bindings/python/tests/cindex/test_code_completion.py
    clang/docs/ReleaseNotes.rst

Removed: 
    


################################################################################
diff  --git a/clang/bindings/python/clang/cindex.py b/clang/bindings/python/clang/cindex.py
index 38799edb04744..ec077d4154187 100644
--- a/clang/bindings/python/clang/cindex.py
+++ b/clang/bindings/python/clang/cindex.py
@@ -3345,8 +3345,26 @@ def from_param(self) -> _Pointer[CCRStructure]:
     def __del__(self) -> None:
         conf.lib.clang_disposeCodeCompleteResults(self)
 
+    def __len__(self) -> int:
+        return self.ptr.contents.numResults
+
+    def __getitem__(self, key: int) -> CodeCompletionResult:
+        if len(self) <= key:
+            raise IndexError
+
+        return self.ptr.contents.results[key]
+
     @property
     def results(self) -> CCRStructure:
+        warnings.warn(
+            "'CodeCompletionResults.results' will become an implementation detail "
+            "with changed behavior in a future release and should not be used directly. "
+            "Existing uses of 'CodeCompletionResults.results' should be changed "
+            "to directly use 'CodeCompletionResults': it nows supports '__len__' "
+            "and '__getitem__', so it can be used the same as "
+            "'CodeCompletionResults.results'.",
+            DeprecationWarning,
+        )
         return self.ptr.contents
 
     @property

diff  --git a/clang/bindings/python/tests/cindex/test_code_completion.py b/clang/bindings/python/tests/cindex/test_code_completion.py
index 91faebfec66c0..d969bb2fa0e6c 100644
--- a/clang/bindings/python/tests/cindex/test_code_completion.py
+++ b/clang/bindings/python/tests/cindex/test_code_completion.py
@@ -18,7 +18,7 @@ def check_completion_results(self, cr, expected):
         self.assertEqual(len(cr.diagnostics), 0)
 
         with warnings.catch_warnings(record=True) as log:
-            completions = [str(c) for c in cr.results]
+            completions = [str(c) for c in cr]
             self.assertEqual(len(log), 2)
             for warning in log:
                 self.assertIsInstance(warning.message, DeprecationWarning)
@@ -26,6 +26,15 @@ def check_completion_results(self, cr, expected):
         for c in expected:
             self.assertIn(c, completions)
 
+        with warnings.catch_warnings(record=True) as log:
+            completions_deprecated = [str(c) for c in cr.results]
+            self.assertEqual(len(log), 3)
+            for warning in log:
+                self.assertIsInstance(warning.message, DeprecationWarning)
+
+        for c in expected:
+            self.assertIn(c, completions_deprecated)
+
     def test_code_complete(self):
         files = [
             (

diff  --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst
index fe573afc99422..3a3d76112a02b 100644
--- a/clang/docs/ReleaseNotes.rst
+++ b/clang/docs/ReleaseNotes.rst
@@ -363,6 +363,12 @@ Python Binding Changes
 
   Affected methods: ``isKindOptional``, ``isKindTypedText``, ``isKindPlaceHolder``,
   ``isKindInformative`` and ``isKindResultType``.
+- Add a deprecation warning to ``CodeCompletionResults.results``.
+  This property will become an implementation detail with changed behavior in a 
+  future release and should not be used directly.. Existing uses of 
+  ``CodeCompletionResults.results`` should be changed to directly use
+  ``CodeCompletionResults``: it nows supports ``__len__`` and ``__getitem__``,
+  so it can be used the same as ``CodeCompletionResults.results``.
 
 OpenMP Support
 --------------