Clang Indexing Library Bindings

This module provides an interface to the Clang indexing library. It is a low-level interface to the indexing library which attempts to match the Clang API directly while also being “pythonic”. Notable differences from the C API are:

• string results are returned as Python strings, not CXString objects.
• null cursors are translated to None.
• access to child cursors is done via iteration, not visitation.

The major indexing objects are:

Index

The top-level object which manages some global library state.

TranslationUnit

High-level object encapsulating the AST for a single translation unit. These can be loaded from .ast files or parsed on the fly.

Cursor

Generic object for representing a node in the AST.

SourceRange, SourceLocation, and File

Objects representing information about the input source.

Most object information is exposed using properties, when the underlying API call is efficient.

class clang.cindex.AvailabilityKind(value)

Describes the availability of an entity.

class clang.cindex.CodeCompletionResults(ptr)

class clang.cindex.CompilationDatabase(obj)

The CompilationDatabase is a wrapper class around clang::tooling::CompilationDatabase

It enables querying how a specific source file can be built.

static fromDirectory(buildDir)

Builds a CompilationDatabase from the database found in buildDir

getAllCompileCommands()

Get an iterable object providing all the CompileCommands available from the database.

getCompileCommands(filename)

Get an iterable object providing all the CompileCommands available to build filename. Returns None if filename is not found in the database.

class clang.cindex.CompileCommands(ccmds)

CompileCommands is an iterable object containing all CompileCommand that can be used for building a specific file.

class clang.cindex.CompileCommand(cmd, ccmds)

Represents the compile command used to build a file

arguments

Get an iterable object providing each argument in the command line for the compiler invocation as a _CXString.

Invariant : the first argument is the compiler executable

directory

Get the working directory for this CompileCommand

filename

Get the working filename for this CompileCommand

class clang.cindex.CursorKind(value)

A CursorKind describes the kind of entity that a cursor points to.

static get_all_kinds()

Return all CursorKind enumeration instances.

is_attribute()

Test if this is an attribute kind.

is_declaration()

Test if this is a declaration kind.

is_expression()

Test if this is an expression kind.

is_invalid()

Test if this is an invalid kind.

is_preprocessing()

Test if this is a preprocessing kind.

is_reference()

Test if this is a reference kind.

is_statement()

Test if this is a statement kind.

is_translation_unit()

Test if this is a translation unit kind.

is_unexposed()

Test if this is an unexposed kind.

class clang.cindex.Cursor

The Cursor class represents a reference to an element within the AST. It acts as a kind of iterator.

access_specifier

Retrieves the access specifier (if any) of the entity pointed at by the cursor.

availability

Retrieves the availability of the entity pointed at by the cursor.

brief_comment

Returns the brief comment text associated with that Cursor

canonical

Return the canonical Cursor corresponding to this Cursor.

The canonical cursor is the cursor which is representative for the underlying entity. For example, if you have multiple forward declarations for the same class, the canonical cursor for the forward declarations will be identical.

displayname

Return the display name for the entity referenced by this cursor.

The display name contains extra information that helps identify the cursor, such as the parameters of a function or template or the arguments of a class template specialization.

enum_type

Return the integer type of an enum declaration.

Returns a Type corresponding to an integer. If the cursor is not for an enum, this raises.

enum_value

Return the value of an enum constant.

exception_specification_kind

Retrieve the exception specification kind, which is one of the values from the ExceptionSpecificationKind enumeration.

extent

Return the source range (the range of text) occupied by the entity pointed at by the cursor.

get_arguments()

Return an iterator for accessing the arguments of this cursor.

get_bitfield_width()

Retrieve the width of a bitfield.

get_children()

Return an iterator for accessing the children of this cursor.

get_definition()

If the cursor is a reference to a declaration or a declaration of some entity, return a cursor that points to the definition of that entity.

get_field_offsetof()

Returns the offsetof the FIELD_DECL pointed by this Cursor.

get_included_file()

Returns the File that is included by the current inclusion cursor.

get_num_template_arguments()

Returns the number of template args associated with this cursor.

get_template_argument_kind(num)

Returns the TemplateArgumentKind for the indicated template argument.

get_template_argument_type(num)

Returns the CXType for the indicated template argument.

get_template_argument_unsigned_value(num)

Returns the value of the indicated arg as an unsigned 64b integer.

get_template_argument_value(num)

Returns the value of the indicated arg as a signed 64b integer.

get_tokens()

Obtain Token instances formulating that compose this Cursor.

This is a generator for Token instances. It returns all tokens which occupy the extent this cursor occupies.

get_usr()

Return the Unified Symbol Resolution (USR) for the entity referenced by the given cursor (or None).

A Unified Symbol Resolution (USR) is a string that identifies a particular entity (function, class, variable, etc.) within a program. USRs can be compared across translation units to determine, e.g., when references in one translation refer to an entity defined in another translation unit.

hash

Returns a hash of the cursor as an int.

is_abstract_record()

Returns True if the cursor refers to a C++ record declaration that has pure virtual member functions.

is_anonymous()

Check if the record is anonymous.

is_bitfield()

Check if the field is a bitfield.

is_const_method()

Returns True if the cursor refers to a C++ member function or member function template that is declared ‘const’.

is_converting_constructor()

Returns True if the cursor refers to a C++ converting constructor.

is_copy_assignment_operator_method()

Returnrs True if the cursor refers to a copy-assignment operator.

A copy-assignment operator X::operator= is a non-static, non-template member function of _class_ X with exactly one parameter of type X, X&, const X&, volatile X& or const volatile X&.

That is, for example, the operator= in:

class Foo {

bool operator=(const volatile Foo&);

};

Is a copy-assignment operator, while the operator= in:

class Bar {

bool operator=(const int&);

};

Is not.

is_copy_constructor()

Returns True if the cursor refers to a C++ copy constructor.

is_default_constructor()

Returns True if the cursor refers to a C++ default constructor.

is_default_method()

Returns True if the cursor refers to a C++ member function or member function template that is declared ‘= default’.

is_definition()

Returns true if the declaration pointed at by the cursor is also a definition of that entity.

is_deleted_method()

Returns True if the cursor refers to a C++ member function or member function template that is declared ‘= delete’.

is_move_assignment_operator_method()

Returnrs True if the cursor refers to a move-assignment operator.

A move-assignment operator X::operator= is a non-static, non-template member function of _class_ X with exactly one parameter of type X&&, const X&&, volatile X&& or const volatile X&&.

That is, for example, the operator= in:

class Foo {

bool operator=(const volatile Foo&&);

};

Is a move-assignment operator, while the operator= in:

class Bar {

bool operator=(const int&&);

};

Is not.

is_move_constructor()

Returns True if the cursor refers to a C++ move constructor.

is_mutable_field()

Returns True if the cursor refers to a C++ field that is declared ‘mutable’.

is_pure_virtual_method()

Returns True if the cursor refers to a C++ member function or member function template that is declared pure virtual.

is_scoped_enum()

Returns True if the cursor refers to a scoped enum declaration.

is_static_method()

Returns True if the cursor refers to a C++ member function or member function template that is declared ‘static’.

is_virtual_method()

Returns True if the cursor refers to a C++ member function or member function template that is declared ‘virtual’.

kind

Return the kind of this cursor.

lexical_parent

Return the lexical parent for this cursor.

linkage

Return the linkage of this cursor.

location

Return the source location (the starting character) of the entity pointed at by the cursor.

mangled_name

Return the mangled name for the entity referenced by this cursor.

objc_type_encoding

Return the Objective-C type encoding as a str.

raw_comment

Returns the raw comment text associated with that Cursor

referenced

For a cursor that is a reference, returns a cursor representing the entity that it references.

result_type

Retrieve the Type of the result for this Cursor.

semantic_parent

Return the semantic parent for this cursor.

spelling

Return the spelling of the entity pointed at by the cursor.

storage_class

Retrieves the storage class (if any) of the entity pointed at by the cursor.

tls_kind

Return the thread-local storage (TLS) kind of this cursor.

translation_unit

Returns the TranslationUnit to which this Cursor belongs.

type

Retrieve the Type (if any) of the entity pointed at by the cursor.

underlying_typedef_type

Return the underlying type of a typedef declaration.

Returns a Type for the typedef this cursor is a declaration for. If the current cursor is not a typedef, this raises.

walk_preorder()

Depth-first preorder walk over the cursor and its descendants.

Yields cursors.

class clang.cindex.Diagnostic(ptr)

A Diagnostic is a single instance of a Clang diagnostic. It includes the diagnostic severity, the message, the location the diagnostic occurred, as well as additional source ranges and associated fix-it hints.

category_name

The string name of the category for this diagnostic.

category_number

The category number for this diagnostic or 0 if unavailable.

disable_option

The command-line option that disables this diagnostic.

format(options=None)

Format this diagnostic for display. The options argument takes Diagnostic.Display* flags, which can be combined using bitwise OR. If the options argument is not provided, the default display options will be used.

option

The command-line option that enables this diagnostic.

class clang.cindex.File(obj)

The File class represents a particular source file that is part of a translation unit.

static from_name(translation_unit, file_name)

Retrieve a file handle within the given translation unit.

name

Return the complete file and path name of the file.

time

Return the last modification time of the file.

class clang.cindex.FixIt(range, value)

A FixIt represents a transformation to be applied to the source to “fix-it”. The fix-it shouldbe applied by replacing the given source range with the given value.

class clang.cindex.Index(obj)

The Index type provides the primary interface to the Clang CIndex library, primarily by providing an interface for reading and parsing translation units.

static create(excludeDecls=False)

Create a new Index. Parameters: excludeDecls – Exclude local declarations from translation units.

parse(path, args=None, unsaved_files=None, options=0)

Load the translation unit from the given source code file by running clang and generating the AST before loading. Additional command line parameters can be passed to clang via the args parameter.

In-memory contents for files can be provided by passing a list of pairs to as unsaved_files, the first item should be the filenames to be mapped and the second should be the contents to be substituted for the file. The contents may be passed as strings or file objects.

If an error was encountered during parsing, a TranslationUnitLoadError will be raised.

read(path)

Load a TranslationUnit from the given AST file.

class clang.cindex.LinkageKind(value)

Describes the kind of linkage of a cursor.

class clang.cindex.SourceLocation

A SourceLocation represents a particular location within a source file.

column

Get the column represented by this source location.

file

Get the file represented by this source location.

static from_offset(tu, file, offset)

Retrieve a SourceLocation from a given character offset.

tu – TranslationUnit file belongs to file – File instance to obtain offset from offset – Integer character offset within file

static from_position(tu, file, line, column)

Retrieve the source location associated with a given file/line/column in a particular translation unit.

line

Get the line represented by this source location.

offset

Get the file offset represented by this source location.

class clang.cindex.SourceRange

A SourceRange describes a range of source locations within the source code.

end

Return a SourceLocation representing the last character within a source range.

start

Return a SourceLocation representing the first character within a source range.

class clang.cindex.TLSKind(value)

Describes the kind of thread-local storage (TLS) of a cursor.

class clang.cindex.TokenKind(value, name)

Describes a specific type of a Token.

static from_value(value)

Obtain a registered TokenKind instance from its value.

static register(value, name)

Register a new TokenKind enumeration.

This should only be called at module load time by code within this package.

class clang.cindex.Token

Represents a single token from the preprocessor.

Tokens are effectively segments of source code. Source code is first parsed into tokens before being converted into the AST and Cursors.

Tokens are obtained from parsed TranslationUnit instances. You currently can’t create tokens manually.

cursor

The Cursor this Token corresponds to.

extent

The SourceRange this Token occupies.

kind

Obtain the TokenKind of the current token.

location

The SourceLocation this Token occurs at.

spelling

The spelling of this token.

This is the textual representation of the token in source.

exception clang.cindex.TranslationUnitLoadError

Represents an error that occurred when loading a TranslationUnit.

This is raised in the case where a TranslationUnit could not be instantiated due to failure in the libclang library.

FIXME: Make libclang expose additional error information in this scenario.

class clang.cindex.TranslationUnit(ptr, index)

Represents a source code translation unit.

This is one of the main types in the API. Any time you wish to interact with Clang’s representation of a source file, you typically start with a translation unit.

codeComplete(path, line, column, unsaved_files=None, include_macros=False, include_code_patterns=False, include_brief_comments=False)

Code complete in this translation unit.

In-memory contents for files can be provided by passing a list of pairs as unsaved_files, the first items should be the filenames to be mapped and the second should be the contents to be substituted for the file. The contents may be passed as strings or file objects.

cursor

Retrieve the cursor that represents the given translation unit.

diagnostics

Return an iterable (and indexable) object containing the diagnostics.

classmethod from_ast_file(filename, index=None)

Create a TranslationUnit instance from a saved AST file.

A previously-saved AST file (provided with -emit-ast or TranslationUnit.save()) is loaded from the filename specified.

If the file cannot be loaded, a TranslationUnitLoadError will be raised.

index is optional and is the Index instance to use. If not provided, a default Index will be created.

filename can be str or PathLike.

classmethod from_source(filename, args=None, unsaved_files=None, options=0, index=None)

Create a TranslationUnit by parsing source.

This is capable of processing source code both from files on the filesystem as well as in-memory contents.

Command-line arguments that would be passed to clang are specified as a list via args. These can be used to specify include paths, warnings, etc. e.g. [“-Wall”, “-I/path/to/include”].

In-memory file content can be provided via unsaved_files. This is an iterable of 2-tuples. The first element is the filename (str or PathLike). The second element defines the content. Content can be provided as str source code or as file objects (anything with a read() method). If a file object is being used, content will be read until EOF and the read cursor will not be reset to its original position.

options is a bitwise or of TranslationUnit.PARSE_XXX flags which will control parsing behavior.

index is an Index instance to utilize. If not provided, a new Index will be created for this TranslationUnit.

To parse source from the filesystem, the filename of the file to parse is specified by the filename argument. Or, filename could be None and the args list would contain the filename(s) to parse.

To parse source from an in-memory buffer, set filename to the virtual filename you wish to associate with this source (e.g. “test.c”). The contents of that file are then provided in unsaved_files.

If an error occurs, a TranslationUnitLoadError is raised.

Please note that a TranslationUnit with parser errors may be returned. It is the caller’s responsibility to check tu.diagnostics for errors.

Also note that Clang infers the source language from the extension of the input filename. If you pass in source code containing a C++ class declaration with the filename “test.c” parsing will fail.

get_extent(filename, locations)

Obtain a SourceRange from this translation unit.

The bounds of the SourceRange must ultimately be defined by a start and end SourceLocation. For the locations argument, you can pass:

• 2 SourceLocation instances in a 2-tuple or list.
• 2 int file offsets via a 2-tuple or list.
• 2 2-tuple or lists of (line, column) pairs in a 2-tuple or list.

e.g.

get_extent(‘foo.c’, (5, 10)) get_extent(‘foo.c’, ((1, 1), (1, 15)))

get_file(filename)

Obtain a File from this translation unit.

get_includes()

Return an iterable sequence of FileInclusion objects that describe the sequence of inclusions in a translation unit. The first object in this sequence is always the input file. Note that this method will not recursively iterate over header files included through precompiled headers.

get_location(filename, position)

Obtain a SourceLocation for a file in this translation unit.

The position can be specified by passing:

• Integer file offset. Initial file offset is 0.
• 2-tuple of (line number, column number). Initial file position is (0, 0)

get_tokens(locations=None, extent=None)

Obtain tokens in this translation unit.

This is a generator for Token instances. The caller specifies a range of source code to obtain tokens for. The range can be specified as a 2-tuple of SourceLocation or as a SourceRange. If both are defined, behavior is undefined.

reparse(unsaved_files=None, options=0)

Reparse an already parsed translation unit.

In-memory contents for files can be provided by passing a list of pairs as unsaved_files, the first items should be the filenames to be mapped and the second should be the contents to be substituted for the file. The contents may be passed as strings or file objects.

save(filename)

Saves the TranslationUnit to a file.

This is equivalent to passing -emit-ast to the clang frontend. The saved file can be loaded back into a TranslationUnit. Or, if it corresponds to a header, it can be used as a pre-compiled header file.

If an error occurs while saving, a TranslationUnitSaveError is raised. If the error was TranslationUnitSaveError.ERROR_INVALID_TU, this means the constructed TranslationUnit was not valid at time of save. In this case, the reason(s) why should be available via TranslationUnit.diagnostics().

filename – The path to save the translation unit to (str or PathLike).

spelling

Get the original translation unit source file name.

class clang.cindex.TypeKind(value)

Describes the kind of type.

spelling

Retrieve the spelling of this TypeKind.

class clang.cindex.Type

The type of an element in the abstract syntax tree.

argument_types()

Retrieve a container for the non-variadic arguments for this type.

The returned object is iterable and indexable. Each item in the container is a Type instance.

element_count

Retrieve the number of elements in this type.

Returns an int.

If the Type is not an array or vector, this raises.

element_type

Retrieve the Type of elements within this Type.

If accessed on a type that is not an array, complex, or vector type, an exception will be raised.

get_align()

Retrieve the alignment of the record.

get_array_element_type()

Retrieve the type of the elements of the array type.

get_array_size()

Retrieve the size of the constant array.

get_canonical()

Return the canonical type for a Type.

Clang’s type system explicitly models typedefs and all the ways a specific type can be represented. The canonical type is the underlying type with all the “sugar” removed. For example, if ‘T’ is a typedef for ‘int’, the canonical type for ‘T’ would be ‘int’.

get_class_type()

Retrieve the class type of the member pointer type.

get_declaration()

Return the cursor for the declaration of the given type.

get_exception_specification_kind()

Return the kind of the exception specification; a value from the ExceptionSpecificationKind enumeration.

get_fields()

Return an iterator for accessing the fields of this type.

get_named_type()

Retrieve the type named by the qualified-id.

get_offset(fieldname)

Retrieve the offset of a field in the record.

get_pointee()

For pointer types, returns the type of the pointee.

get_ref_qualifier()

Retrieve the ref-qualifier of the type.

get_result()

Retrieve the result type associated with a function type.

get_size()

Retrieve the size of the record.

is_const_qualified()

Determine whether a Type has the “const” qualifier set.

This does not look through typedefs that may have added “const” at a different level.

is_function_variadic()

Determine whether this function Type is a variadic function type.

is_pod()

Determine whether this Type represents plain old data (POD).

is_restrict_qualified()

Determine whether a Type has the “restrict” qualifier set.

This does not look through typedefs that may have added “restrict” at a different level.

is_volatile_qualified()

Determine whether a Type has the “volatile” qualifier set.

This does not look through typedefs that may have added “volatile” at a different level.

kind

Return the kind of this type.

spelling

Retrieve the spelling of this Type.

translation_unit

The TranslationUnit to which this Type is associated.