libclang Python Bindings

Warnings

• gotcha Shared Library Not Found (`SharedLibraryNotFound`) is the most common error. While the `libclang` PyPI package attempts to auto-configure the library path when installed via wheels, this can fail in custom environments (e.g., development setups, using a system-installed LLVM, or manual Python installations).
  Fix: Manually specify the path to your `libclang` shared library (e.g., `libclang.so`, `libclang.dll`, `libclang.dylib`) using `from clang.cindex import Config; Config.set_library_file('/path/to/libclang.so')` or `Config.set_library_path('/path/to/llvm/lib')` before any other `clang.cindex` calls. Ensure the path points to the correct LLVM version.
• breaking API changes in the underlying Clang C API are directly reflected in the `libclang` Python bindings. Upgrading to a new major `libclang` version (e.g., from 17.x to 18.x) may introduce breaking changes in function signatures, enum values, or object structures.
  Fix: Consult the official LLVM Clang C API documentation for the specific version you are targeting. Review the `llvm-project/clang/bindings/python` directory in the LLVM source for changes relevant to the Python bindings.
• breaking The `libclang` Python bindings are primarily designed for Python 3. Support for Python 2.x has been dropped in recent LLVM versions, and wheels for older Python versions are no longer provided.
  Fix: Ensure you are using Python 3.6 or newer. Older versions might have limited or no compatibility.
• gotcha Performance considerations when parsing large codebases. Creating an `Index` and `TranslationUnit` can be resource-intensive, and traversing large ASTs can be slow.
  Fix: For incremental changes, use `TranslationUnit.reparse()` rather than parsing the entire file again. Consider using `Index.parse()` with `options` to reduce the amount of information stored (e.g., `TranslationUnit.PARSE_SKIP_FUNCTION_BODIES`). Profile your application to identify bottlenecks during AST traversal.

Install

• pip install libclang Install latest version

Imports

• Index

  from clang.cindex import Index

  The primary API is exposed through the 'clang.cindex' module, not 'libclang' directly.
• CursorKind

  from clang.cindex import CursorKind

• Config

  from clang.cindex import Config

  Configuration utilities are part of the 'cindex' submodule.

Quickstart

This quickstart demonstrates how to parse C/C++ code, check for diagnostics, iterate through the Abstract Syntax Tree (AST) to find function declarations and their arguments, and access tokens. When installed via the official `libclang` wheel, the library attempts to automatically locate the necessary `libclang` shared library, making manual configuration via `Config.set_library_file()` often unnecessary.

from clang.cindex import Index, TranslationUnit

# Source code to parse
source_code = """
#include <stdio.h>

int add(int a, int b) {
    return a + b;
}

int main() {
    printf("Sum: %d\n", add(5, 3));
    return 0;
}
"""

# Create an index
index = Index.create()

# Parse the source code from a string. For files, use Index.parse('path/to/file.c')
tu = index.parse('test.c', unsaved_files=[('test.c', source_code)])

# Check for diagnostics (errors/warnings)
for diagnostic in tu.diagnostics:
    print(f"Diagnostic: {diagnostic}")

# Iterate through the AST to find functions
print("\nFunctions found:")
for cursor in tu.cursor.get_children():
    if cursor.kind == TranslationUnit.CursorKind.FUNCTION_DECL:
        print(f"  Function: {cursor.spelling}, return type: {cursor.result_type.spelling}")
        for arg in cursor.get_arguments():
            print(f"    Argument: {arg.spelling}, type: {arg.type.spelling}")

print("\nFirst 10 tokens:")
for token in tu.get_tokens(extent=tu.cursor.extent)[:10]:
    print(f"  Token: '{token.spelling}' (kind: {token.kind})")