clang package

clang.cindex module

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.AccessSpecifier(*values)

Bases: BaseEnumeration

Describes the access of a C++ class member

class clang.cindex.AvailabilityKind(*values)

Bases: BaseEnumeration

Describes the availability of an entity.

class clang.cindex.BinaryOperator(*values)

Bases: BaseEnumeration

Describes the BinaryOperator of a declaration

class clang.cindex.CodeCompletionResults(ptr)

Bases: ClangObject

class clang.cindex.CompilationDatabase(obj)

Bases: ClangObject

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.CompileCommand(cmd, ccmds)

Bases: object

Represents the compile command used to build a file

property 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

property directory

Get the working directory for this CompileCommand

property filename

Get the working filename for this CompileCommand

class clang.cindex.CompileCommands(ccmds)

Bases: object

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

class clang.cindex.Cursor

Bases: Structure

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

property access_specifier

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

property availability

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

property binary_operator

Retrieves the opcode if this cursor points to a binary operator :return:

property brief_comment

Returns the brief comment text associated with that Cursor

property 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.

property 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.

property 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.

property enum_value

Return the value of an enum constant.

property exception_specification_kind

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

property 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_base_offsetof(parent)

Returns the offsetof the CXX_BASE_SPECIFIER pointed by 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.

property 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 whether this is a record type without a name, or a field where the type is a record type without a name.

Use is_anonymous_record_decl to check whether a record is an “anonymous union” as defined in the C/C++ standard.

is_anonymous_record_decl()

Check if the record is an anonymous union as defined in the C/C++ standard (or an “anonymous struct”, the corresponding non-standard extension for structs).

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_explicit_method()

Determines if a C++ constructor or conversion function is explicit, returning 1 if such is the case and 0 otherwise.

Constructors or conversion functions are declared explicit through the use of the explicit specifier.

For example, the following constructor and conversion function are not explicit as they lack the explicit specifier:

class Foo {

Foo(); operator int();

};

While the following constructor and conversion function are explicit as they are declared with the explicit specifier.

class Foo {

explicit Foo(); explicit operator int();

};

This method will return 0 when given a cursor pointing to one of the former declarations and it will return 1 for a cursor pointing to the latter declarations.

The explicit specifier allows the user to specify a conditional compile-time expression whose value decides whether the marked element is explicit or not.

For example:

constexpr bool foo(int i) { return i % 2 == 0; }

class Foo {

explicit(foo(1)) Foo(); explicit(foo(2)) operator int();

}

This method will return 0 for the constructor and 1 for the conversion function.

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_base()

Returns whether the CXX_BASE_SPECIFIER pointed by this Cursor is virtual.

is_virtual_method()

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

property kind

Return the kind of this cursor.

property lexical_parent

Return the lexical parent for this cursor.

property linkage

Return the linkage of this cursor.

property location

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

property mangled_name

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

property objc_type_encoding

Return the Objective-C type encoding as a str.

pretty_printed(policy)

Pretty print declarations. Parameters: policy – The policy to control the entities being printed.

property raw_comment

Returns the raw comment text associated with that Cursor

property referenced

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

property result_type

Retrieve the Type of the result for this Cursor.

property semantic_parent

Return the semantic parent for this cursor.

property spelling

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

property storage_class

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

property tls_kind

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

property translation_unit

Returns the TranslationUnit to which this Cursor belongs.

property type

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

property 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.CursorKind(*values)

Bases: BaseEnumeration

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.Diagnostic(ptr)

Bases: object

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.

property category_name

The string name of the category for this diagnostic.

property category_number

The category number for this diagnostic or 0 if unavailable.

property 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.

property option

The command-line option that enables this diagnostic.

class clang.cindex.ExceptionSpecificationKind(*values)

Bases: BaseEnumeration

An ExceptionSpecificationKind describes the kind of exception specification that a function has.

class clang.cindex.File(obj)

Bases: ClangObject

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.

property name

Return the complete file and path name of the file.

property time

Return the last modification time of the file.

class clang.cindex.FixIt(range, value)

Bases: object

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

class clang.cindex.Index(obj)

Bases: ClangObject

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(*values)

Bases: BaseEnumeration

Describes the kind of linkage of a cursor.

class clang.cindex.PrintingPolicy(ptr)

Bases: ClangObject

The PrintingPolicy is a wrapper class around clang::PrintingPolicy

It allows specifying how declarations, expressions, and types should be pretty-printed.

static create(cursor)

Creates a new PrintingPolicy Parameters: cursor – Any cursor for a translation unit.

get_property(property)

Get a property value for the given printing policy.

set_property(property, value)

Set a property value for the given printing policy.

class clang.cindex.PrintingPolicyProperty(*values)

Bases: BaseEnumeration

A PrintingPolicyProperty identifies a property of a PrintingPolicy.

class clang.cindex.RefQualifierKind(*values)

Bases: BaseEnumeration

Describes a specific ref-qualifier of a type.

class clang.cindex.SourceLocation

Bases: Structure

A SourceLocation represents a particular location within a source file.

property column

Get the column represented by this source location.

property 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.

property is_in_system_header

Returns true if the given source location is in a system header.

property line

Get the line represented by this source location.

property offset

Get the file offset represented by this source location.

class clang.cindex.SourceRange

Bases: Structure

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

property end

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

property start

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

class clang.cindex.StorageClass(*values)

Bases: BaseEnumeration

Describes the storage class of a declaration

class clang.cindex.TLSKind(*values)

Bases: BaseEnumeration

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

class clang.cindex.TemplateArgumentKind(*values)

Bases: BaseEnumeration

A TemplateArgumentKind describes the kind of entity that a template argument represents.

class clang.cindex.Token

Bases: Structure

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.

property cursor

The Cursor this Token corresponds to.

property extent

The SourceRange this Token occupies.

property kind

Obtain the TokenKind of the current token.

property location

The SourceLocation this Token occurs at.

property spelling

The spelling of this token.

This is the textual representation of the token in source.

class clang.cindex.TokenKind(*values)

Bases: BaseEnumeration

Describes a specific type of a Token.

classmethod from_value(value)

Obtain a registered TokenKind instance from its value.

class clang.cindex.TranslationUnit(ptr, index)

Bases: ClangObject

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.

property cursor

Retrieve the cursor that represents the given translation unit.

property diagnostics: NoSliceSequence[Diagnostic]

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).

property spelling

Get the original translation unit source file name.

exception clang.cindex.TranslationUnitLoadError

Bases: Exception

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.Type

Bases: Structure

The type of an element in the abstract syntax tree.

argument_types() → NoSliceSequence[Type]

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.

property element_count

Retrieve the number of elements in this type.

Returns an int.

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

property 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_bases()

Return an iterator for accessing the base classes of this type.

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.

property kind

Return the kind of this type.

pretty_printed(policy)

Pretty-prints this Type with the given PrintingPolicy

property spelling

Retrieve the spelling of this Type.

property translation_unit

The TranslationUnit to which this Type is associated.

class clang.cindex.TypeKind(*values)

Bases: BaseEnumeration

Describes the kind of type.

property spelling

Retrieve the spelling of this TypeKind.

Module contents

Clang Library Bindings

This package provides access to the Clang compiler and libraries.

The available modules are:

cindex

Bindings for the Clang indexing library.