[clang] a648128 - [libclang/python] Add CompletionChunkKind enum and deprecate old CompletionChunk.Kind (#176631)
via cfe-commits
cfe-commits at lists.llvm.org
Fri Jan 23 01:05:45 PST 2026
Author: Jannick Kremer
Date: 2026-01-23T18:05:39+09:00
New Revision: a6481281940298cd96507e808ec56909bd34992c
URL: https://github.com/llvm/llvm-project/commit/a6481281940298cd96507e808ec56909bd34992c
DIFF: https://github.com/llvm/llvm-project/commit/a6481281940298cd96507e808ec56909bd34992c.diff
LOG: [libclang/python] Add CompletionChunkKind enum and deprecate old CompletionChunk.Kind (#176631)
This adresses point 1 from
https://github.com/llvm/llvm-project/issues/156680.
Since step 4 is already completed, `CompletionChunk.Kind` becomes unused
in this PR, so it is removed.
Added:
Modified:
clang/bindings/python/clang/cindex.py
clang/bindings/python/tests/cindex/test_code_completion.py
clang/bindings/python/tests/cindex/test_enums.py
clang/docs/ReleaseNotes.rst
Removed:
################################################################################
diff --git a/clang/bindings/python/clang/cindex.py b/clang/bindings/python/clang/cindex.py
index 29c35628cf60c..9dce404a183aa 100644
--- a/clang/bindings/python/clang/cindex.py
+++ b/clang/bindings/python/clang/cindex.py
@@ -3053,46 +3053,29 @@ class _CXUnsavedFile(Structure):
class CompletionChunk:
- class Kind:
- def __init__(self, name: str):
- self.name = name
-
- def __str__(self) -> str:
- return self.name
-
- def __repr__(self) -> str:
- return "<ChunkKind: %s>" % self
+ __kind_id: int
def __init__(self, completionString: CObjP, key: int):
self.cs = completionString
self.key = key
- self.__kindNumberCache = -1
def __repr__(self) -> str:
return "{'" + self.spelling + "', " + str(self.kind) + "}"
@CachedProperty
def spelling(self) -> str:
- if self.__kindNumber in SPELLING_CACHE:
- return SPELLING_CACHE[self.__kindNumber]
+ kind_id = conf.lib.clang_getCompletionChunkKind(self.cs, self.key)
+ if kind_id in SPELLING_CACHE:
+ return SPELLING_CACHE[kind_id]
return _CXString.from_result(
conf.lib.clang_getCompletionChunkText(self.cs, self.key)
)
- # We do not use @CachedProperty here, as the manual implementation is
- # apparently still significantly faster. Please profile carefully if you
- # would like to add CachedProperty back.
- @property
- def __kindNumber(self) -> int:
- if self.__kindNumberCache == -1:
- self.__kindNumberCache = conf.lib.clang_getCompletionChunkKind(
- self.cs, self.key
- )
- return self.__kindNumberCache
-
@CachedProperty
- def kind(self) -> Kind:
- return completionChunkKindMap[self.__kindNumber]
+ def kind(self) -> CompletionChunkKind:
+ return CompletionChunkKind.from_id(
+ conf.lib.clang_getCompletionChunkKind(self.cs, self.key)
+ )
@CachedProperty
def string(self) -> CompletionString | None:
@@ -3103,44 +3086,67 @@ def string(self) -> CompletionString | None:
return CompletionString(res)
def isKindOptional(self) -> bool:
- return self.__kindNumber == 0
+ return self.kind == CompletionChunkKind.OPTIONAL
def isKindTypedText(self) -> bool:
- return self.__kindNumber == 1
+ return self.kind == CompletionChunkKind.TYPED_TEXT
def isKindPlaceHolder(self) -> bool:
- return self.__kindNumber == 3
+ return self.kind == CompletionChunkKind.PLACEHOLDER
def isKindInformative(self) -> bool:
- return self.__kindNumber == 4
+ return self.kind == CompletionChunkKind.INFORMATIVE
def isKindResultType(self) -> bool:
- return self.__kindNumber == 15
-
-
-completionChunkKindMap = {
- 0: CompletionChunk.Kind("Optional"),
- 1: CompletionChunk.Kind("TypedText"),
- 2: CompletionChunk.Kind("Text"),
- 3: CompletionChunk.Kind("Placeholder"),
- 4: CompletionChunk.Kind("Informative"),
- 5: CompletionChunk.Kind("CurrentParameter"),
- 6: CompletionChunk.Kind("LeftParen"),
- 7: CompletionChunk.Kind("RightParen"),
- 8: CompletionChunk.Kind("LeftBracket"),
- 9: CompletionChunk.Kind("RightBracket"),
- 10: CompletionChunk.Kind("LeftBrace"),
- 11: CompletionChunk.Kind("RightBrace"),
- 12: CompletionChunk.Kind("LeftAngle"),
- 13: CompletionChunk.Kind("RightAngle"),
- 14: CompletionChunk.Kind("Comma"),
- 15: CompletionChunk.Kind("ResultType"),
- 16: CompletionChunk.Kind("Colon"),
- 17: CompletionChunk.Kind("SemiColon"),
- 18: CompletionChunk.Kind("Equal"),
- 19: CompletionChunk.Kind("HorizontalSpace"),
- 20: CompletionChunk.Kind("VerticalSpace"),
-}
+ return self.kind == CompletionChunkKind.RESULT_TYPE
+
+### 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
class CompletionString(ClangObject):
diff --git a/clang/bindings/python/tests/cindex/test_code_completion.py b/clang/bindings/python/tests/cindex/test_code_completion.py
index 4c0ecca85e4f4..c376b0e5cce40 100644
--- a/clang/bindings/python/tests/cindex/test_code_completion.py
+++ b/clang/bindings/python/tests/cindex/test_code_completion.py
@@ -1,4 +1,9 @@
-from clang.cindex import AvailabilityKind, CompletionString, TranslationUnit
+from clang.cindex import (
+ AvailabilityKind,
+ CompletionChunkKind,
+ CompletionString,
+ TranslationUnit,
+)
import unittest
from pathlib import Path
@@ -137,7 +142,7 @@ class Q : public P {
]
self.check_completion_results(cr, expected)
- def test_availability_kind_compat_(self):
+ def test_availability_kind_compat(self):
numKinds = len(CompletionString.AvailabilityKindCompat)
# Compare with regular kind
@@ -174,3 +179,38 @@ 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):
+ value_to_old_str = {
+ 0: "Optional",
+ 1: "TypedText",
+ 2: "Text",
+ 3: "Placeholder",
+ 4: "Informative",
+ 5: "CurrentParameter",
+ 6: "LeftParen",
+ 7: "RightParen",
+ 8: "LeftBracket",
+ 9: "RightBracket",
+ 10: "LeftBrace",
+ 11: "RightBrace",
+ 12: "LeftAngle",
+ 13: "RightAngle",
+ 14: "Comma",
+ 15: "ResultType",
+ 16: "Colon",
+ 17: "SemiColon",
+ 18: "Equal",
+ 19: "HorizontalSpace",
+ 20: "VerticalSpace",
+ }
+
+ # Check that all new kinds correspond to an old kind
+ for new_kind in CompletionChunkKind:
+ old_str = value_to_old_str[new_kind.value]
+ self.assertEqual(old_str, str(new_kind))
+
+ # Check that all old kinds correspond to a new kind
+ for value, old_str in value_to_old_str.items():
+ new_kind = CompletionChunkKind.from_id(value)
+ self.assertEqual(old_str, 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,
diff --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst
index 791212dafd342..a734804865c57 100644
--- a/clang/docs/ReleaseNotes.rst
+++ b/clang/docs/ReleaseNotes.rst
@@ -58,13 +58,20 @@ Clang Python Bindings Potentially Breaking Changes
- ``CompletionString.availability`` now returns instances of ``CompletionString.AvailabilityKindCompat``.
Instances of ``AvailabilityKindCompat`` have the same ``__str__`` representation
- as the previous ``CompletionChunk.Kind``s and are equality-comparable with
+ as the previous ``CompletionChunk.Kind`` and are equality-comparable with
the existing ``AvailabilityKind`` enum. It will be replaced by ``AvailabilityKind``
in a future release. When this happens, the return type of ``CompletionString.availability``
will change to ``AvailabilityKind``, so it is recommended to use ``AvailabilityKind``
to compare with the return values of ``CompletionString.availability``.
- Remove ``availabilityKinds``. In this release, uses of ``availabilityKinds``
need to be replaced by ``CompletionString.AvailabilityKind``.
+- ``CompletionChunk.kind`` now returns instances of ``CompletionChunkKind``.
+
+ Instances of ``CompletionChunkKind`` have the same ``__str__`` representation
+ as the previous ``CompletionChunk.Kind`` for compatibility.
+ These representations will be changed in a future release to match other enums.
+- Remove ``completionChunkKindMap``. In this release, uses of ``completionChunkKindMap``
+ need to be replaced by ``CompletionChunkKind``.
What's New in Clang |release|?
==============================
More information about the cfe-commits
mailing list