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] = [], cxx_standard: str = 'gnu++17', additional_includes: list[str] = [], defines: list[str] = [], verbose: bool = False, bypass_parse_error: bool = False, ) → 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.

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

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.

numbast.bind_cxx_class_template( class_template_decl: ClassTemplate, shim_writer: ShimWriterBase, header_path: str, *, arg_intent: dict | None = None, )

numbast.bind_cxx_class_template_specialization( shim_writer: ShimWriterBase, struct_decl: ClassTemplateSpecialization, instance_type_ref: Type, aliases: dict[str, list[str]] = {}, *, arg_intent: dict | None = None, ) → object

Bind a C++ class template specialization into Numba and return the corresponding Numba instance type.

This registers the C++ name-to-Numba-type mapping, installs a StructModel for the instantiated type, registers attribute and method typing templates, and binds constructors so the specialization can be used from Numba.

Parameters:

shim_writer – ShimWriterBase Utility used to emit shim-layer code for bound methods.
struct_decl – ClassTemplateSpecialization Parsed C++ class template specialization declaration to bind.
instance_type_ref – nbtypes.Type The Numba TypeRef representing the instantiated template; its .instance_type is the returned type.
aliases – dict[str, list[str]], optional Optional name aliases for the C++ type (e.g., typedefs) to register to the same Numba type.
arg_intent – dict | None, optional Optional per-argument intent overrides to influence method parameter/return typing.

Returns:

nbtypes.Type: The Numba instance type for the bound class template specialization (instance_type_ref.instance_type).

numbast.bind_cxx_class_templates( class_templates: list[ClassTemplate], header_path: str, shim_writer: ShimWriterBase, *, arg_intent: dict | None = None, ) → list[object]

Create bindings for a list of C++ class templates.

Parameters:

shim_writer (ShimWriter) – The shim writer to write the shim layer code.
class_templates (list[ClassTemplate]) – List of declarations of the class template types in CXX
header_path (str) – The path to the header file containing the class template declarations.
arg_intent (dict, optional) – Argument intent overrides to apply to bound methods.

Returns:

The Python APIs of the class templates.

Return type:

list[object]

numbast.bind_cxx_enum(e: Enum)

numbast.bind_cxx_enums( enums: list[Enum], ) → list[IntEnum]

Create bindings for a list of C++ enums.

Parameters:: enums (list[pylibastcanopy.Enum]) – A list of enum declarations in CXX.
Returns:: pyenums
Return type:: list[IntEnum]

numbast.bind_cxx_function( shim_writer: MemoryShimWriter, func_decl: Function, skip_prefix: str | None = None, skip_non_device: bool = True, exclude: set[str] = {}, *, arg_intent: dict | None = None, ) → object

Create Python bindings for a C++ function.

Parameters:

shim_writer (ShimWriter) – Writer that emits the generated C/C++ shim code.
func_decl (Function) – C++ function declaration to bind.
skip_prefix (str | None) – If provided, skip functions whose names start with this prefix.
skip_non_device (bool) – If True, skip functions not marked for device or host_device execution.
exclude (set[str]) – Names of functions to exclude from binding.
arg_intent (dict | None) – Optional explicit intent overrides that control which C++ reference parameters are exposed as inputs, outputs, or inout pointers and which parameters are promoted to out-returns.

Returns:

The Numba-CUDA-callable Python binding object for the function, or None if the function is skipped or not exposed.

Return type:

object or None

numbast.bind_cxx_function_template( *, name: str, overloads: list[FunctionTemplate], shim_writer: ShimWriterBase, arg_intent: dict | None = None, ) → object: Create bindings for a (possibly overloaded) templated function.

numbast.bind_cxx_function_templates( *, function_templates: list[FunctionTemplate], shim_writer: ShimWriterBase, skip_prefix: str | None = None, skip_non_device: bool = True, exclude: set[str] | None = None, arg_intent: dict | None = None, ) → list[object]: Create bindings for a list of C++ function templates.

numbast.bind_cxx_functions( shim_writer: MemoryShimWriter, functions: list[Function], skip_prefix: str | None = None, skip_non_device: bool = True, exclude: set[str] = {}, *, arg_intent: dict | None = None, ) → list[object]

Create bindings for a list of C++ functions.

Parameters:

shim_writer (ShimWriter) – The shim writer to write the generated shim layer code.
functions (list[Function]) – A list of function declarations in CXX.
skip_prefix (str | None) – Skip functions with this prefix. Has no effect if None or empty.
skip_non_device (bool) – Skip non device functions. Default to True.
exclude (set[str]) – A set of function names to exclude. Default to empty set.

Returns:

funcs – A list of Numba-CUDA-callable Python APIs for the functions.

Return type:

list[object]

numbast.bind_cxx_struct( shim_writer: MemoryShimWriter, struct_decl: Struct, parent_type: type = <class 'numba.core.types.abstract.Type'>, data_model: type = <class 'numba.core.datamodel.models.StructModel'>, aliases: dict[str, list[str]]={}, *, arg_intent: dict | None = None, ) → object

Create and register a Numba API type and associated bindings for a C++ struct.

Binds the struct type, its data model, public fields, methods, constructors, and conversion operators into the Numba type system and registers any provided aliases.

Parameters:

shim_writer – ShimWriter Writer used to emit generated shim-layer code for method/ctor bindings.
struct_decl – Struct Parsed C++ struct declaration to bind.
parent_type – type, optional Base class for the generated Numba frontend type (defaults to nbtypes.Type).
data_model – type, optional Data model class to use for the struct (defaults to StructModel; can be PrimitiveModel).
aliases – dict[str, list[str]], optional Mapping from the struct’s canonical name to alternate names that should resolve to the same type.
arg_intent – dict | None, optional Optional overrides that guide argument intent (in/out/inout) and influence method overload lowering.

Returns:

object: The Python-facing Numba API type for the bound C++ struct.

Return type:

numbast.bind_cxx_structs( shim_writer: MemoryShimWriter, structs: list[Struct], parent_types: dict[str, type] = {}, data_models: dict[str, type] = {}, aliases: dict[str, list[str]] = {}, *, arg_intent: dict | None = None, ) → list[object]

Create Python API bindings for a sequence of C++ struct declarations.

Parameters:

shim_writer (ShimWriter) – Writer used to emit shim-layer code for each binding.
structs (list[Struct]) – C++ struct declarations to bind.
parent_types (dict[str, type], optional) – Mapping from struct name to the Python API base type to use for that struct.
data_models (dict[str, type], optional) – Mapping from struct name to the data model class to use (e.g., StructModel or PrimitiveModel).
aliases (dict[str, list[str]], optional) – Mapping from a struct name to alternative names (aliases) to consult when a struct is unnamed; used to look up parent_types and data_models.
arg_intent (dict | None, optional) – Optional per-struct/method argument intent overrides that influence parameter and return typing for method bindings.

Returns:

The created Python API types (one per input struct).

Return type:

list[object]

`static`
`tools`

numbast.static#

numbast.static.reset_renderer()#

Clear all renderer cache and api registries.

Sometimes the renderer needs to run multiple times in the same python session (pytest). This function resets the renderer so that it runs in a clean state.