https://github.com/Endilll created https://github.com/llvm/llvm-project/pull/229374
This patch documents the existing way `ClangObject` is used in `cindex.py` and renames it to `OpaqueClangObject` to better reflect its purpose. In one case (`CodeCompletionResults`) it's used as a base class for objects that wrap a transparent C object, but this case will be eliminated by #224678. >From f5aea87ca72498ace37d02a05e43ef5522f33b82 Mon Sep 17 00:00:00 2001 From: Vlad Serebrennikov <[email protected]> Date: Tue, 6 Oct 2026 13:26:06 +0300 Subject: [PATCH] [clang][python] Rename ClangObject to OpaqueClangObject and update its description --- clang/bindings/python/clang/cindex.py | 38 +++++++++++++-------------- 1 file changed, 18 insertions(+), 20 deletions(-) diff --git a/clang/bindings/python/clang/cindex.py b/clang/bindings/python/clang/cindex.py index 06da37bb24aaa7..f479b152b165a9 100644 --- a/clang/bindings/python/clang/cindex.py +++ b/clang/bindings/python/clang/cindex.py @@ -3050,17 +3050,15 @@ def __ne__(self, other: object) -> bool: return not self.__eq__(other) -## CIndex Objects ## +## Opaque Clang Objects ## -# CIndex objects (derived from ClangObject) are essentially lightweight -# wrappers attached to some underlying object, which is exposed via CIndex as -# a void*. - - -class ClangObject: +class OpaqueClangObject: """ - A helper for Clang objects. This class helps act as an intermediary for - the ctypes library and the Clang CIndex library. + A helper for Python objects that mirror opaque types of the C API. + It stores opaque pointer returned by the C API, and implements + `from_param` function, allowing Python object to be implicitly converted + to the stored opaque pointer when it is passed as an argument to the + C API. """ def __init__(self, obj): @@ -3184,7 +3182,7 @@ def string(self) -> CompletionString | None: return CompletionString(res) -class CompletionString(ClangObject): +class CompletionString(OpaqueClangObject): def __len__(self) -> int: return self.num_chunks @@ -3257,7 +3255,7 @@ def __getitem__(self, key: int) -> CodeCompletionResult: return self.results[key] -class CodeCompletionResults(ClangObject): +class CodeCompletionResults(OpaqueClangObject): def __init__(self, ptr: _Pointer[CCRStructure]): assert isinstance(ptr, POINTER(CCRStructure)) and ptr self.ptr = self._as_parameter_ = ptr @@ -3305,7 +3303,7 @@ def __getitem__(self, key: int) -> Diagnostic: return DiagnosticsItr(self) -class Index(ClangObject): +class Index(OpaqueClangObject): """ The Index type provides the primary interface to the Clang CIndex library, primarily by providing an interface for reading and parsing translation @@ -3344,7 +3342,7 @@ def parse(self, path, args=None, unsaved_files=None, options=0): return TranslationUnit.from_source(path, args, unsaved_files, options, self) -class TranslationUnit(ClangObject): +class TranslationUnit(OpaqueClangObject): """Represents a source code translation unit. This is one of the main types in the API. Any time you wish to interact @@ -3512,7 +3510,7 @@ def __init__(self, ptr: CObjP, index: Index) -> None: """ assert isinstance(index, Index) self.index = index - ClangObject.__init__(self, ptr) + OpaqueClangObject.__init__(self, ptr) def __del__(self) -> None: conf.lib.clang_disposeTranslationUnit(self) @@ -3765,7 +3763,7 @@ def get_tokens( return TokenGroup.get_tokens(self, extent) -class File(ClangObject): +class File(OpaqueClangObject): """ The File class represents a particular source file that is part of a translation unit. @@ -3926,7 +3924,7 @@ def from_result(res): return CompileCommands(res) -class CompilationDatabase(ClangObject): +class CompilationDatabase(OpaqueClangObject): """ The CompilationDatabase is a wrapper class around clang::tooling::CompilationDatabase @@ -4028,7 +4026,7 @@ def cursor(self): return cursor -class Rewriter(ClangObject): +class Rewriter(OpaqueClangObject): """ The Rewriter is a wrapper class around clang::Rewriter @@ -4045,7 +4043,7 @@ def create(tu): return Rewriter(conf.lib.clang_CXRewriter_create(tu)) def __init__(self, ptr): - ClangObject.__init__(self, ptr) + OpaqueClangObject.__init__(self, ptr) def __del__(self): conf.lib.clang_CXRewriter_dispose(self) @@ -4121,7 +4119,7 @@ class PrintingPolicyProperty(BaseEnumeration): FullyQualifiedName = 25 -class PrintingPolicy(ClangObject): +class PrintingPolicy(OpaqueClangObject): """ The PrintingPolicy is a wrapper class around clang::PrintingPolicy @@ -4139,7 +4137,7 @@ def create(cursor): return PrintingPolicy(conf.lib.clang_getCursorPrintingPolicy(cursor)) def __init__(self, ptr): - ClangObject.__init__(self, ptr) + OpaqueClangObject.__init__(self, ptr) def __del__(self): conf.lib.clang_PrintingPolicy_dispose(self) _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
