API reference#

ast_canopy#

ast_canopy.parse_declarations_from_source( source_file_path: str, files_to_retain: list[str], compute_capability: str, cudatoolkit_include_dirs: list[str] | None = None, cxx_standard: str = 'gnu++17', additional_includes: list[str] | None = None, defines: list[str] | None = None, verbose: bool = False, bypass_parse_error: bool = False, cuda_header_mode: bool = False, clang_binary: str | None = None, ) → Declarations

Given a source file, parse all top-level declarations from it and return a Declarations object containing lists of declaration objects found in the source.

Parameters:

source_file_path (str) – The path to the source file to parse.
files_to_retain (list[str]) – A list of file paths whose parsed declarations should be retained in the result. A header file usually references other headers. A semantically intact AST should, in theory, include all referenced headers. In practice, you may not need all of them. To retain only declarations from source_file_path, pass [source_file_path].
compute_capability (str) – The compute capability of the target GPU. e.g. “sm_70”.
cudatoolkit_include_dirs (list[str], optional) – The paths to the CUDA Toolkit include directories to override the default CUDA include directories. If not provided, ast_canopy will use cuda.pathfinder to find the CUDA include directories. If provided, the default CUDA include directories will be ignored.
cxx_standard (str, optional) – The C++ standard to use. Default is “gnu++17”.
additional_includes (list[str], optional) – A list of additional include directories to search for headers.
defines (list[str], optional) – A list of implicit defines that are passed to clangTooling via the “-D” flag.
verbose (bool, optional) – If True, print stderr from the clang++ invocation.
bypass_parse_error (bool, optional) – If True, bypass parse error and continue generating bindings.
cuda_header_mode (bool, optional) – If True, enable cuda-header-parsing-flags. This mode disables Clang’s implicit CUDA include injection so declarations are attributed to the provided header path.
clang_binary (str | None, optional) – Path to a specific clang binary to use. If None, ast_canopy attempts to resolve clang++ from PATH. When that resolution fails, a warning is emitted and command invocation falls back to the bare clang++ string. If a non-None value is provided but cannot be resolved, a RuntimeError is raised.

Returns:

See Declarations struct definition for details.

Return type:

Declarations

ast_canopy.value_from_constexpr_vardecl( source: str, vardecl_name: str, compute_capability: str, cxx_standard: str = 'gnu++17', verbose: bool = False, clang_binary: str | None = None, ) → ConstExprVar | None

Extract the value from a constexpr VarDecl with the given name.

Parameters:

source (str) – The source code to parse.
vardecl_name (str) – The name of the constexpr variable declaration to extract the value from.
compute_capability (str) – The compute capability of the target GPU. e.g. “sm_70”.
cxx_standard (str, optional) – The C++ standard to use. Default is “gnu++17”.
verbose (bool, optional) – If True, print the stderr from clang++ invocation.
clang_binary (str | None, optional) – Path to a specific clang binary to use. If None, ast_canopy attempts to resolve clang++ from PATH. When that resolution fails, a warning is emitted and command invocation falls back to the bare clang++ string. If a non-None value is provided but cannot be resolved, a RuntimeError is raised.

Returns:

See ConstExprVar struct definition for details.

Return type:

ConstExprVar | None

decl

ast_canopy.decl#

All objects in this module represent serialized information extracted from the C++ Clang AST.

class ast_canopy.decl.ClassTemplate( record: TemplatedStruct, template_parameters: list[TemplateParam], num_min_required_args: int, qual_name: str, parse_entry_point: str, )#

Bases: Template

Represents a C++ class template declaration.

Holds the underlying TemplatedStruct and provides instantiate for building a concrete class instantiation.

classmethod from_c_obj( c_obj: ClassTemplate, parse_entry_point: str, )#

instantiate(**kwargs)#

class ast_canopy.decl.ClassTemplateSpecialization( record: Struct, class_template: ClassTemplate, actual_template_arguments: list[str], )#

Bases: Struct

Represents a C++ class template specialization declaration.

Holds the underlying TemplatedStruct and provides instantiate for building a concrete class instantiation.

property base_name#

constructors()#

classmethod from_c_obj( c_obj: ClassTemplateSpecialization, parse_entry_point: str, )#

property name#

property qual_name#

property specialized_name#

class ast_canopy.decl.ConstExprVar( name: str, type_: Type, value_serialized: str, )#

Bases: object

Represents a constexpr variable extracted from C++.

Stores the C++ type and serialized value; value converts it to the corresponding Python value based on the type mapping.

classmethod from_c_obj( c_obj: ConstExprVar, )#

property value#

class ast_canopy.decl.Function( name: str, qual_name: str, return_type: Type, params: list[ParamVar], exec_space: execution_space, is_constexpr: bool, mangled_name: str, attributes: str, parse_entry_point: str, )#

Bases: object

Represents a C++ function.

For C++ operator types, see https://en.cppreference.com/w/cpp/language/operators.

classmethod from_c_obj( c_obj: Function, parse_entry_point: str, )#

is_allocation_operator() → bool#

is_conversion_operator() → bool#

is_copy_assignment_operator() → bool#

is_cowait_operator() → bool#

is_deallocation_operator() → bool#

is_overloaded_operator() → bool#

is_user_defined_literal() → bool#

property overloaded_operator_to_python_operator#

property param_types: list[Type]#

class ast_canopy.decl.FunctionTemplate( template_parameters: list[TemplateParam], num_min_required_args: int, function: Function, qual_name: str, parse_entry_point: str, )#

Bases: Template

Represents a C++ function template declaration.

Wraps a parsed function template and provides instantiate for building a concrete instantiation.

classmethod from_c_obj( c_obj: FunctionTemplate, parse_entry_point: str, )#

instantiate(**kwargs)#

class ast_canopy.decl.Struct( name: str, qual_name: str, fields: list[Field], methods: list[StructMethod], templated_methods: list[FunctionTemplate], nested_records: list[Record], nested_class_templates: list[ClassTemplate], sizeof_: int, alignof_: int, parse_entry_point: str, )#

Bases: object

Represents a C++ record (struct/class) and its metadata.

Contains fields, methods, templated methods, nested records and class templates, as well as size/align information and the parse entry point.

constructors()#

conversion_operators()#

classmethod from_c_obj( c_obj: Record, parse_entry_point: str, )#

property name#

overloaded_operators()#

public_fields() → list[Field]#

property qual_name#

regular_member_functions()#: Generator for methods that are not constructors, overload operators and conversion operators.

templated_member_functions()#: Generator for templated methods.

class ast_canopy.decl.StructMethod( name: str, qual_name: str, return_type: Type, params: list[ParamVar], kind: method_kind, exec_space: execution_space, is_constexpr: bool, is_move_constructor: bool, mangled_name: str, attributes: str, parse_entry_point: str, )#

Bases: Function

Represents a method of a C++ struct/class.

Includes constructors, conversion operators, and overloaded operators. Extends Function with method-specific metadata.

classmethod from_c_obj( c_obj: Method, parse_entry_point: str, )#

property overloaded_operator_to_python_operator#

class ast_canopy.decl.Template( template_parameters: list[TemplateParam], num_min_required_args: int, )#

Bases: object

Base class for C++ template declarations.

Stores the list of template parameters and the minimum number of required template arguments.

property tparam_dict#

class ast_canopy.decl.TemplatedStruct( name: str, qual_name: str, fields: list[Field], methods: list[StructMethod], templated_methods: list[FunctionTemplate], nested_records: list[Record], nested_class_templates: list[ClassTemplate], sizeof_: int, alignof_: int, parse_entry_point: str, )#

Bases: Struct

A Struct whose methods include templated methods.

Specializes method handling to use TemplatedStructMethod.

classmethod from_c_obj( c_obj: Record, parse_entry_point: str, )#

templated_methods: list[TemplatedStructMethod]#

class ast_canopy.decl.TemplatedStructMethod( name: str, qual_name: str, return_type: Type, params: list[ParamVar], kind: method_kind, exec_space: execution_space, is_constexpr: bool, is_move_constructor: bool, mangled_name: str, attributes: str, parse_entry_point: str, )#

Bases: StructMethod

Struct/class method whose name may include template parameters.

Provides utilities for working with the declaration name without template arguments.

property decl_name#

Return the declaration name without template parameters.

For templated struct methods, if the name contains template parameters, the declaration name is the base name without parameters.

Example:

template<typename T, int n>
struct Foo { Foo() {} };

The constructor name is Foo<T, n>; the declaration name is Foo.

numbast#

class numbast.FileShimWriter(preceding_text='')

Write shim functions to files via file I/O.

For all Numba bindings, the shim functions are combined and written to a single file. For each PTX, a separate file is created.

property links: Callable[[], Iterator[str | CUSource | PTXSource]]

Return an iterator of file paths containing shim functions and PTXes.

Usage: declare_device(..., link=[*shim_writer.links()])

write_to_ptx_shim(ptx: str, id: str): Write PTX to files, each keyed by id to avoid duplication (one file per PTX).

write_to_shim(content: str, id: str): Write a shim function to the source file, keyed by id to avoid duplication.

class numbast.MemoryShimWriter(preceding_text='')

Manage shim functions and PTX in memory.

For each Numba bindings, the shim functions are combined into a single cuda.CUSource object. For each PTX, a separate cuda.PTXSource object is created.

property links: Callable[[], Iterator[str | CUSource | PTXSource]]

Return an iterator over memory objects containing shim functions and PTXes.

Usage: declare_device(..., link=[*shim_writer.links()])

write_to_ptx_shim(ptx: str, id: str): Write PTX into PTXSource objects, each keyed by id to avoid duplication.

write_to_shim(content: str, id: str): Write a shim function into the in-memory CUSource, keyed by id to avoid duplication.

`types`	Define names for built-in types that aren't directly accessible as a builtin.
`tools`

API reference#

ast_canopy#

ast_canopy.decl#

numbast#

numbast.static#