While reviewing #140539, I realized that our Python API for code completion leaves much to be desired. Specific problems and suggested solutions are outlined below.

First, our current API poorly emulates CXCompletionChunkKind enum with a dictionary of bespoke objects (completionChunkKindMap) that effectively can only converted to strings. I expect that users compare them using string equality, which is not the best way to work with enums. What I think we should do is:

• remove CompletionChunk.__kindNumber;
• mirror CXCompletionChunkKind in the Python wrapper like we do with all the other enums;
• preserve convertibility of the new enum to the same strings users get today (e.g. "CurrentParameter"), so that nothing breaks for the current users of CompletionChunk.kind;
• in Clang 22, issue a FutureWarning asking people to compare enums normally, without string conversions. I think we can even go as far as to customize the warning for every enumerator. Then get rid of old strings in Clang 23.

Second, CompletionChunk has a lookup table for spellings of parentheses and such named SPELLING_CACHE. This cache should be migrated to use enumerators for keys. On top of that, we should move it into the scope of CompletionChunk to avoid polluting module namespace, but I'm afraid there are users who depend on its current location according to Hyrum's law, so we should keep it as a deprecated alias for at least one release.

Third, CompletionChunk has isKindOptional and 4 more similar methods. We typically don't duplicate enumerators yet another time as methods, they can be easily replaced with equality checks without losing readability on the consumer side, and on top of all that, they don't follow snake_case naming convention. I think we again should deprecate them, and after one release cycle remove them entirely.

Fourth, CompletionString.Availability and availabilityKinds unnecessarily duplicate AvailabilityKind enum. I think they should be given the same treatment as CompletionChunk.kind.

Fifth, facilities to work with code completion results seem to be confusingly split between CCRStructure and CodeCompletionResults. I think we should fold them into the latter, and add from_result method to handle the value that comes out of foreign functions, like we do everywhere else.

CC @DeinAlptraum