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|? ============================== _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
