[clang] [libclang/python] Add CompletionChunkKind enum and deprecate old CompletionChunk.Kind (PR #176631)

[via cfe-commits]

llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-clang

Author: Jannick Kremer (DeinAlptraum)

<details>
<summary>Changes</summary>

Add tests to ensure string-comparability with CompletionChunk.Kind

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


3 Files Affected:

- (modified) clang/bindings/python/clang/cindex.py (+48) 
- (modified) clang/bindings/python/tests/cindex/test_code_completion.py (+12-1) 
- (modified) clang/bindings/python/tests/cindex/test_enums.py (+2) 


``````````diff
diff --git a/clang/bindings/python/clang/cindex.py b/clang/bindings/python/clang/cindex.py
index 29c35628cf60c..45a8ddf83bb27 100644
--- a/clang/bindings/python/clang/cindex.py
+++ b/clang/bindings/python/clang/cindex.py
@@ -3117,6 +3117,54 @@ def isKindInformative(self) -> bool:
     def isKindResultType(self) -> bool:
         return self.__kindNumber == 15
 
+### Completion Chunk Kinds ###
+class CompletionChunkKind(BaseEnumeration):
+    """
+    Describes a single piece of text within a code-completion string.
+    """
+
+    def __str__(self) -> str:
+        """
+        Converts enum value to string in the old camelCase format.
+        This is a temporary measure that will be changed in the future release
+        to return string in ALL_CAPS format, like for other enums.
+        """
+
+        warnings.warn(
+            "String representation of 'CompletionChunkKind' will be "
+            "changed in a future release from 'camelCase' to 'ALL_CAPS' to "
+            "match other enums. 'CompletionChunkKind's can be "
+            "compared to one another without conversion to string.",
+            DeprecationWarning,
+        )
+        # Remove underscores
+        components = self.name.split("_")
+        # Upper-camel case each split component
+        components = [component.lower().capitalize() for component in components]
+        return "".join(components)
+
+    OPTIONAL = 0
+    TYPED_TEXT = 1
+    TEXT = 2
+    PLACEHOLDER = 3
+    INFORMATIVE = 4
+    CURRENT_PARAMETER = 5
+    LEFT_PAREN = 6
+    RIGHT_PAREN = 7
+    LEFT_BRACKET = 8
+    RIGHT_BRACKET = 9
+    LEFT_BRACE = 10
+    RIGHT_BRACE = 11
+    LEFT_ANGLE = 12
+    RIGHT_ANGLE = 13
+    COMMA = 14
+    RESULT_TYPE = 15
+    COLON = 16
+    SEMI_COLON = 17
+    EQUAL = 18
+    HORIZONTAL_SPACE = 19
+    VERTICAL_SPACE = 20
+
 
 completionChunkKindMap = {
     0: CompletionChunk.Kind("Optional"),
diff --git a/clang/bindings/python/tests/cindex/test_code_completion.py b/clang/bindings/python/tests/cindex/test_code_completion.py
index 4c0ecca85e4f4..e4924e1f8f4c6 100644
--- a/clang/bindings/python/tests/cindex/test_code_completion.py
+++ b/clang/bindings/python/tests/cindex/test_code_completion.py
@@ -1,4 +1,4 @@
-from clang.cindex import AvailabilityKind, CompletionString, TranslationUnit
+from clang.cindex import AvailabilityKind, CompletionChunkKind, completionChunkKindMap, CompletionString, TranslationUnit
 
 import unittest
 from pathlib import Path
@@ -174,3 +174,14 @@ def test_compat_str(self):
         for id, string in kindStringMap.items():
             kind = CompletionString.AvailabilityKindCompat.from_id(id)
             self.assertEqual(str(kind), string)
+
+    def test_completion_chunk_kind_compatibility(self):
+        # Check that all new kinds correspond to an old kind
+        for new_kind in CompletionChunkKind:
+            old_kind = completionChunkKindMap[new_kind.value]
+            self.assertEqual(str(old_kind), str(new_kind))
+
+        # Check that all old kinds correspond to a new kind
+        for value, old_kind in completionChunkKindMap.items():
+            new_kind = CompletionChunkKind.from_id(value)
+            self.assertEqual(str(old_kind), str(new_kind))
diff --git a/clang/bindings/python/tests/cindex/test_enums.py b/clang/bindings/python/tests/cindex/test_enums.py
index f50bd219cee77..283a54998470c 100644
--- a/clang/bindings/python/tests/cindex/test_enums.py
+++ b/clang/bindings/python/tests/cindex/test_enums.py
@@ -5,6 +5,7 @@
     AccessSpecifier,
     AvailabilityKind,
     BinaryOperator,
+    CompletionChunkKind,
     CompletionString,
     CursorKind,
     ExceptionSpecificationKind,
@@ -45,6 +46,7 @@ def test_all_variants(self):
             "CX_StorageClass": StorageClass,
             "CXAvailabilityKind": AvailabilityKind,
             "CXBinaryOperatorKind": BinaryOperator,
+            "CXCompletionChunkKind": CompletionChunkKind,
             "CXCursorKind": CursorKind,
             "CXCursor_ExceptionSpecificationKind": ExceptionSpecificationKind,
             "CXLanguageKind": LanguageKind,

``````````

</details>


https://github.com/llvm/llvm-project/pull/176631