[clang] [libclang/python] Add deprecation warnings to CompletionChunk.isKind methods (PR #177854)

[Jannick Kremer via cfe-commits]

https://github.com/DeinAlptraum updated https://github.com/llvm/llvm-project/pull/177854

>From 6539a03fc79ec91f39427aaf8268763ec95073d5 Mon Sep 17 00:00:00 2001
From: Jannick Kremer <jannick.kremer at mailbox.org>
Date: Sun, 25 Jan 2026 22:30:58 +0900
Subject: [PATCH 1/3] Add deprecation warnings to CompletionChunk.is... methods

---
 clang/bindings/python/clang/cindex.py | 36 +++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/clang/bindings/python/clang/cindex.py b/clang/bindings/python/clang/cindex.py
index 6d667c36ef9a4..2120613269ca8 100644
--- a/clang/bindings/python/clang/cindex.py
+++ b/clang/bindings/python/clang/cindex.py
@@ -3157,19 +3157,55 @@ def string(self) -> CompletionString | None:
             return None
         return CompletionString(res)
 
+    __deprecation_message = (
+        "'CompletionChunk.{}' will be removed in a future release. "
+        "All uses of 'CompletionChunk.{}' should be replaced by checking "
+        "if the 'CompletionChunk's kind is 'CompletionChunkKind.{}'."
+    )
+
     def isKindOptional(self) -> bool:
+        deprecation_message = self.__deprecation_message.format(
+            "isKindOptional",
+            "isKindOptional",
+            "OPTIONAL",
+        )
+        warnings.warn(deprecation_message, DeprecationWarning)
         return self.kind == CompletionChunkKind.OPTIONAL
 
     def isKindTypedText(self) -> bool:
+        deprecation_message = self.__deprecation_message.format(
+            "isKindTypedText",
+            "isKindTypedText",
+            "TYPED_TEXT",
+        )
+        warnings.warn(deprecation_message, DeprecationWarning)
         return self.kind == CompletionChunkKind.TYPED_TEXT
 
     def isKindPlaceHolder(self) -> bool:
+        deprecation_message = self.__deprecation_message.format(
+            "isKindPlaceHolder",
+            "isKindPlaceHolder",
+            "PLACEHOLDER",
+        )
+        warnings.warn(deprecation_message, DeprecationWarning)
         return self.kind == CompletionChunkKind.PLACEHOLDER
 
     def isKindInformative(self) -> bool:
+        deprecation_message = self.__deprecation_message.format(
+            "isKindInformative",
+            "isKindInformative",
+            "INFORMATIVE",
+        )
+        warnings.warn(deprecation_message, DeprecationWarning)
         return self.kind == CompletionChunkKind.INFORMATIVE
 
     def isKindResultType(self) -> bool:
+        deprecation_message = self.__deprecation_message.format(
+            "isKindResultType",
+            "isKindResultType",
+            "RESULT_TYPE",
+        )
+        warnings.warn(deprecation_message, DeprecationWarning)
         return self.kind == CompletionChunkKind.RESULT_TYPE
 
 

>From 68e6b8bf682547cde863df63f7bbf69c0cf7f04b Mon Sep 17 00:00:00 2001
From: Jannick Kremer <jannick.kremer at mailbox.org>
Date: Sun, 25 Jan 2026 22:36:55 +0900
Subject: [PATCH 2/3] Add release note

---
 clang/docs/ReleaseNotes.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst
index df4b21fc26ff1..9cad4974cb33b 100644
--- a/clang/docs/ReleaseNotes.rst
+++ b/clang/docs/ReleaseNotes.rst
@@ -302,6 +302,10 @@ Sanitizers
 
 Python Binding Changes
 ----------------------
+- Add deprecation warnings to ``CompletionChunk.isKind...`` methods.
+  These will be removed in a future release. Existing uses should be adapted
+  to directly compare equality of the ``CompletionChunk`` kind with
+  the corresponding ``CompletionChunkKind`` variant.
 
 OpenMP Support
 --------------

>From 90b8631ad477ee8a0e7a36b0433a6198021181a9 Mon Sep 17 00:00:00 2001
From: Jannick Kremer <jannick.kremer at mailbox.org>
Date: Mon, 26 Jan 2026 09:02:03 +0900
Subject: [PATCH 3/3] Add method names to release note

---
 clang/docs/ReleaseNotes.rst | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst
index 9cad4974cb33b..4c02f8c5b16a3 100644
--- a/clang/docs/ReleaseNotes.rst
+++ b/clang/docs/ReleaseNotes.rst
@@ -307,6 +307,9 @@ Python Binding Changes
   to directly compare equality of the ``CompletionChunk`` kind with
   the corresponding ``CompletionChunkKind`` variant.
 
+  Affected methods: ``isKindOptional``, ``isKindTypedText``, ``isKindPlaceHolder``,
+  ``isKindInformative`` and ``isKindResultType``.
+
 OpenMP Support
 --------------
 - Added support for ``transparent`` clause in task and taskloop directives.