[clang] Use existing AvailabilityKind enum for code completion availability (PR #160296)
Jannick Kremer via cfe-commits
cfe-commits at lists.llvm.org
Sun Jan 4 08:37:32 PST 2026
https://github.com/DeinAlptraum updated https://github.com/llvm/llvm-project/pull/160296
>From e29ee6463042dc9c8b4366af2d884c1c20e6a1f5 Mon Sep 17 00:00:00 2001
From: Jannick Kremer <jannick.kremer at mailbox.org>
Date: Tue, 23 Sep 2025 22:26:44 +0900
Subject: [PATCH 1/8] Use existing AvailabilityKind enum for code completion
availability
---
clang/bindings/python/clang/cindex.py | 24 +++++++++++++-----------
1 file changed, 13 insertions(+), 11 deletions(-)
diff --git a/clang/bindings/python/clang/cindex.py b/clang/bindings/python/clang/cindex.py
index 13a91d83ede1c..7f2c2183ec1bb 100644
--- a/clang/bindings/python/clang/cindex.py
+++ b/clang/bindings/python/clang/cindex.py
@@ -3039,6 +3039,16 @@ class _CXUnsavedFile(Structure):
}
+# Converting the new enum names (full upper-case, underscore separated)
+# to the old ones (separated by capitalization), e.g. RESULT_TYPE -> ResultType
+def _kind_to_old_name(kind: BaseEnumeration):
+ # Remove underscores
+ components = kind.name.split("_")
+ # Upper-camel case each split component
+ components = [component.lower().capitalize() for component in components]
+ return "".join(components)
+
+
class CompletionChunk:
class Kind:
def __init__(self, name: str):
@@ -3165,9 +3175,9 @@ def priority(self) -> int:
return conf.lib.clang_getCompletionPriority(self.obj) # type: ignore [no-any-return]
@property
- def availability(self) -> CompletionChunk.Kind:
+ def availability(self) -> AvailabilityKind:
res = conf.lib.clang_getCompletionAvailability(self.obj)
- return availabilityKinds[res]
+ return AvailabilityKind.from_id(res)
@property
def briefComment(self) -> str:
@@ -3179,20 +3189,12 @@ def __repr__(self) -> str:
+ " || Priority: "
+ str(self.priority)
+ " || Availability: "
- + str(self.availability)
+ + _kind_to_old_name(self.availability)
+ " || Brief comment: "
+ str(self.briefComment)
)
-availabilityKinds = {
- 0: CompletionChunk.Kind("Available"),
- 1: CompletionChunk.Kind("Deprecated"),
- 2: CompletionChunk.Kind("NotAvailable"),
- 3: CompletionChunk.Kind("NotAccessible"),
-}
-
-
class CodeCompletionResult(Structure):
_fields_ = [("cursorKind", c_int), ("completionString", c_object_p)]
>From b67b19b2d3d880a307be0e9216bb51e57a26c8be Mon Sep 17 00:00:00 2001
From: Jannick Kremer <jannick.kremer at mailbox.org>
Date: Wed, 24 Sep 2025 22:18:25 +0900
Subject: [PATCH 2/8] Turn comment into docstring
---
clang/bindings/python/clang/cindex.py | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/clang/bindings/python/clang/cindex.py b/clang/bindings/python/clang/cindex.py
index 7f2c2183ec1bb..4b9abfb829b6c 100644
--- a/clang/bindings/python/clang/cindex.py
+++ b/clang/bindings/python/clang/cindex.py
@@ -3039,9 +3039,11 @@ class _CXUnsavedFile(Structure):
}
-# Converting the new enum names (full upper-case, underscore separated)
-# to the old ones (separated by capitalization), e.g. RESULT_TYPE -> ResultType
def _kind_to_old_name(kind: BaseEnumeration):
+ """
+ Converting the new enum names (full upper-case, underscore separated)
+ to the old ones (separated by capitalization), e.g. RESULT_TYPE -> ResultType
+ """
# Remove underscores
components = kind.name.split("_")
# Upper-camel case each split component
>From 9e200ecb1bfd5481aff5057d960ceffaf18b2df3 Mon Sep 17 00:00:00 2001
From: Jannick Kremer <jannick.kremer at mailbox.org>
Date: Wed, 24 Sep 2025 22:19:19 +0900
Subject: [PATCH 3/8] Change converter function name
---
clang/bindings/python/clang/cindex.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/clang/bindings/python/clang/cindex.py b/clang/bindings/python/clang/cindex.py
index 4b9abfb829b6c..220e05f69eacf 100644
--- a/clang/bindings/python/clang/cindex.py
+++ b/clang/bindings/python/clang/cindex.py
@@ -3191,7 +3191,7 @@ def __repr__(self) -> str:
+ " || Priority: "
+ str(self.priority)
+ " || Availability: "
- + _kind_to_old_name(self.availability)
+ + _convert_screaming_caps_to_pascal_case(self.availability)
+ " || Brief comment: "
+ str(self.briefComment)
)
>From c0753a2ec0d213896e4c60e582d8d0e5600f1f55 Mon Sep 17 00:00:00 2001
From: Jannick Kremer <jannick.kremer at mailbox.org>
Date: Wed, 24 Sep 2025 17:02:44 +0200
Subject: [PATCH 4/8] Update clang/bindings/python/clang/cindex.py
Co-authored-by: Vlad Serebrennikov <serebrennikov.vladislav at gmail.com>
---
clang/bindings/python/clang/cindex.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/clang/bindings/python/clang/cindex.py b/clang/bindings/python/clang/cindex.py
index 220e05f69eacf..7fda120913477 100644
--- a/clang/bindings/python/clang/cindex.py
+++ b/clang/bindings/python/clang/cindex.py
@@ -3039,7 +3039,7 @@ class _CXUnsavedFile(Structure):
}
-def _kind_to_old_name(kind: BaseEnumeration):
+def _convert_screaming_caps_to_pascal_case(kind: BaseEnumeration):
"""
Converting the new enum names (full upper-case, underscore separated)
to the old ones (separated by capitalization), e.g. RESULT_TYPE -> ResultType
>From 05f45e20a1a9195fb073241d7ac743e1b61c8899 Mon Sep 17 00:00:00 2001
From: Jannick Kremer <jannick.kremer at mailbox.org>
Date: Sun, 4 Jan 2026 17:24:03 +0900
Subject: [PATCH 5/8] Remove unused CompletionString.Availability
---
clang/bindings/python/clang/cindex.py | 10 ----------
1 file changed, 10 deletions(-)
diff --git a/clang/bindings/python/clang/cindex.py b/clang/bindings/python/clang/cindex.py
index 7fda120913477..756b8564e1e01 100644
--- a/clang/bindings/python/clang/cindex.py
+++ b/clang/bindings/python/clang/cindex.py
@@ -3143,16 +3143,6 @@ def isKindResultType(self) -> bool:
class CompletionString(ClangObject):
- class Availability:
- def __init__(self, name):
- self.name = name
-
- def __str__(self):
- return self.name
-
- def __repr__(self):
- return "<Availability: %s>" % self
-
def __len__(self) -> int:
return self.num_chunks
>From e5971369ac0f21d59072b7966fad188f49df9b86 Mon Sep 17 00:00:00 2001
From: Jannick Kremer <jannick.kremer at mailbox.org>
Date: Sun, 4 Jan 2026 17:27:23 +0900
Subject: [PATCH 6/8] Pass string instead of enum variant to converter
---
clang/bindings/python/clang/cindex.py | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/clang/bindings/python/clang/cindex.py b/clang/bindings/python/clang/cindex.py
index 756b8564e1e01..7c26617718b36 100644
--- a/clang/bindings/python/clang/cindex.py
+++ b/clang/bindings/python/clang/cindex.py
@@ -3039,13 +3039,13 @@ class _CXUnsavedFile(Structure):
}
-def _convert_screaming_caps_to_pascal_case(kind: BaseEnumeration):
+def _convert_screaming_caps_to_pascal_case(kind: str):
"""
Converting the new enum names (full upper-case, underscore separated)
to the old ones (separated by capitalization), e.g. RESULT_TYPE -> ResultType
"""
# Remove underscores
- components = kind.name.split("_")
+ components = kind.split("_")
# Upper-camel case each split component
components = [component.lower().capitalize() for component in components]
return "".join(components)
@@ -3181,7 +3181,7 @@ def __repr__(self) -> str:
+ " || Priority: "
+ str(self.priority)
+ " || Availability: "
- + _convert_screaming_caps_to_pascal_case(self.availability)
+ + _convert_screaming_caps_to_pascal_case(self.availability.name)
+ " || Brief comment: "
+ str(self.briefComment)
)
>From 5c841d1b280afcd3e39d4c7eef7881f03b557606 Mon Sep 17 00:00:00 2001
From: Jannick Kremer <jannick.kremer at mailbox.org>
Date: Mon, 5 Jan 2026 01:17:33 +0900
Subject: [PATCH 7/8] Add AvailabilityKindCompat
---
clang/bindings/python/clang/cindex.py | 52 +++++++++++++------
.../tests/cindex/test_code_completion.py | 36 ++++++++++++-
2 files changed, 72 insertions(+), 16 deletions(-)
diff --git a/clang/bindings/python/clang/cindex.py b/clang/bindings/python/clang/cindex.py
index 7c26617718b36..e8c6fb6ecbc24 100644
--- a/clang/bindings/python/clang/cindex.py
+++ b/clang/bindings/python/clang/cindex.py
@@ -3039,18 +3039,6 @@ class _CXUnsavedFile(Structure):
}
-def _convert_screaming_caps_to_pascal_case(kind: str):
- """
- Converting the new enum names (full upper-case, underscore separated)
- to the old ones (separated by capitalization), e.g. RESULT_TYPE -> ResultType
- """
- # Remove underscores
- components = kind.split("_")
- # Upper-camel case each split component
- components = [component.lower().capitalize() for component in components]
- return "".join(components)
-
-
class CompletionChunk:
class Kind:
def __init__(self, name: str):
@@ -3167,9 +3155,9 @@ def priority(self) -> int:
return conf.lib.clang_getCompletionPriority(self.obj) # type: ignore [no-any-return]
@property
- def availability(self) -> AvailabilityKind:
+ def availability(self) -> AvailabilityKindCompat:
res = conf.lib.clang_getCompletionAvailability(self.obj)
- return AvailabilityKind.from_id(res)
+ return AvailabilityKindCompat.from_id(res)
@property
def briefComment(self) -> str:
@@ -3181,11 +3169,45 @@ def __repr__(self) -> str:
+ " || Priority: "
+ str(self.priority)
+ " || Availability: "
- + _convert_screaming_caps_to_pascal_case(self.availability.name)
+ + str(self.availability)
+ " || Brief comment: "
+ str(self.briefComment)
)
+# AvailabilityKindCompat is an exact copy of AvailabilityKind, except for __str__
+# This is a temporary measure to keep the string representation the same
+# until we unify the return of CompletionString.availability to be AvailabilityKind
+# Note that deriving from AvailabilityKind directly is not possible
+class AvailabilityKindCompat(BaseEnumeration):
+ """
+ Describes the availability of an entity.
+ """
+
+ # Ensure AvailabilityKindCompat is comparable with AvailabilityKind
+ def __eq__(self, other: object) -> bool:
+ if isinstance(other, AvailabilityKind):
+ return self.value == other.value
+ else:
+ return NotImplemented
+
+ def __str__(self) -> str:
+ """
+ Returns the common enum names (full upper-case, underscore separated)
+ to the old format (separated by capitalization), e.g. NOT_ACCESSIBLE -> NotAccessible
+ This is a temporary measure and will be changed in a future release
+ to return the same format (full upper-case, underscore separated) like other Kinds
+ """
+ # Remove underscores
+ components = self.name.split("_")
+ # Upper-camel case each split component
+ components = [component.lower().capitalize() for component in components]
+ return "".join(components)
+
+ AVAILABLE = 0
+ DEPRECATED = 1
+ NOT_AVAILABLE = 2
+ NOT_ACCESSIBLE = 3
+
class CodeCompletionResult(Structure):
_fields_ = [("cursorKind", c_int), ("completionString", c_object_p)]
diff --git a/clang/bindings/python/tests/cindex/test_code_completion.py b/clang/bindings/python/tests/cindex/test_code_completion.py
index c7a86aa82a8eb..d13d0b8c2df45 100644
--- a/clang/bindings/python/tests/cindex/test_code_completion.py
+++ b/clang/bindings/python/tests/cindex/test_code_completion.py
@@ -1,6 +1,6 @@
import os
-from clang.cindex import Config, TranslationUnit
+from clang.cindex import Config, TranslationUnit, AvailabilityKind, AvailabilityKindCompat
if "CLANG_LIBRARY_PATH" in os.environ:
Config.set_library_path(os.environ["CLANG_LIBRARY_PATH"])
@@ -141,3 +141,37 @@ class Q : public P {
"{'void', ResultType} | {'~P', TypedText} | {'(', LeftParen} | {')', RightParen} || Priority: 79 || Availability: Available || Brief comment: ",
]
self.check_completion_results(cr, expected)
+
+ def test_availability_kind_compat_(self):
+ numKinds = len(AvailabilityKindCompat)
+
+ # Compare with regular kind
+ for compatKind in AvailabilityKindCompat:
+ commonKind = AvailabilityKind.from_id(compatKind.value)
+ nextKindId = (compatKind.value+1) % numKinds
+ commonKindUnequal= AvailabilityKind.from_id(nextKindId)
+ self.assertEqual(commonKind, compatKind)
+ self.assertEqual(compatKind, commonKind)
+ self.assertNotEqual(commonKindUnequal, compatKind)
+ self.assertNotEqual(compatKind, commonKindUnequal)
+
+ # Compare two compat kinds
+ for compatKind in AvailabilityKindCompat:
+ compatKind2 = AvailabilityKindCompat.from_id(compatKind.value)
+ nextKindId = (compatKind.value+1) % numKinds
+ compatKind2Unequal = AvailabilityKind.from_id(nextKindId)
+ self.assertEqual(compatKind, compatKind2)
+ self.assertEqual(compatKind2, compatKind)
+ self.assertNotEqual(compatKind2Unequal, compatKind)
+ self.assertNotEqual(compatKind, compatKind2Unequal)
+
+ def test_compat_str(self):
+ kindStringMap = {
+ 0: "Available",
+ 1: "Deprecated",
+ 2: "NotAvailable",
+ 3: "NotAccessible",
+ }
+ for id, string in kindStringMap.items():
+ kind = AvailabilityKindCompat.from_id(id)
+ self.assertEqual(str(kind), string)
>From ff9931a3ed70f04e05086d10aa502f280129faa1 Mon Sep 17 00:00:00 2001
From: Jannick Kremer <jannick.kremer at mailbox.org>
Date: Mon, 5 Jan 2026 01:36:47 +0900
Subject: [PATCH 8/8] Add deprecation warning
---
clang/bindings/python/clang/cindex.py | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/clang/bindings/python/clang/cindex.py b/clang/bindings/python/clang/cindex.py
index e8c6fb6ecbc24..e991dd428acfd 100644
--- a/clang/bindings/python/clang/cindex.py
+++ b/clang/bindings/python/clang/cindex.py
@@ -84,6 +84,7 @@
import os
import sys
from enum import Enum
+import warnings
from typing import (
Any,
@@ -3174,6 +3175,7 @@ def __repr__(self) -> str:
+ str(self.briefComment)
)
+
# AvailabilityKindCompat is an exact copy of AvailabilityKind, except for __str__
# This is a temporary measure to keep the string representation the same
# until we unify the return of CompletionString.availability to be AvailabilityKind
@@ -3197,6 +3199,14 @@ def __str__(self) -> str:
This is a temporary measure and will be changed in a future release
to return the same format (full upper-case, underscore separated) like other Kinds
"""
+
+ warnings.warn(
+ "The CompletionString.availability's return value will be changed in "
+ "a future release to be unified with other kinds. As a result, its string "
+ "representations will change to full upper-case, prefixed with the class name "
+ "(e.g. NotAvailable -> AvailabilityKind.NOT_AVAILABLE).",
+ DeprecationWarning,
+ )
# Remove underscores
components = self.name.split("_")
# Upper-camel case each split component
More information about the cfe-commits
mailing list