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 = True,
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,
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, ClassInstantiation

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#
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,
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,
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,
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]#
regular_member_functions()#

Generator for methods that are not constructors, overload operators and conversion operators.

class ast_canopy.decl.StructMethod(
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,
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,
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,
)
numbast.bind_cxx_class_template_specialization(
shim_writer: ShimWriterBase,
struct_decl: ClassTemplateSpecialization,
instance_type_ref: Type,
aliases: dict[str, list[str]] = {},
) → object

Create bindings for a C++ struct.

Parameters:

  • shim_writer (ShimWriterBase) – The shim writer to write the shim layer code.

  • struct_decl (Struct) – Declaration of the struct type in CXX

  • parent_type (nbtypes.Type, optional) – Parent type of the Python API, by default nbtypes.Type

  • data_model (type, optional) – Data model for the struct, by default StructModel

  • aliases (dict[str, list[str]], optional) – Mappings from the name of the struct to a list of aliases. For example in C++: typedef A B; typedef A C; then aliases = {“A”: [“B”, “C”]}

Returns:

  • S (object) – The Python API of the struct.

  • shim (str) – The generated shim layer code for struct methods.

numbast.bind_cxx_class_templates(
class_templates: list[ClassTemplate],
header_path: str,
shim_writer: ShimWriterBase,
) → 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.

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] = {},
) → object

Create bindings for a C++ function.

Parameters:

  • shim_writer (ShimWriter) – The shim writer to write the generated shim layer code.

  • func_decl (Function) – Declaration of the function 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:

func – The Numba-CUDA-callable Python API for the function.

Return type:

object

numbast.bind_cxx_functions(
shim_writer: MemoryShimWriter,
functions: list[Function],
skip_prefix: str | None = None,
skip_non_device: bool = True,
exclude: set[str] = {},
) → 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]]={},
) → object

Create bindings for a C++ struct.

Parameters:

  • shim_writer (ShimWriter) – The shim writer to write the shim layer code.

  • struct_decl (Struct) – Declaration of the struct type in CXX

  • parent_type (nbtypes.Type, optional) – Parent type of the Python API, by default nbtypes.Type

  • data_model (type, optional) – Data model for the struct, by default StructModel

  • aliases (dict[str, list[str]], optional) – Mappings from the name of the struct to a list of aliases. For example in C++: typedef A B; typedef A C; then aliases = {“A”: [“B”, “C”]}

Returns:

  • S (object) – The Python API of the struct.

  • shim (str) – The generated shim layer code for struct methods.

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]] = {},
) → list[object]

Create bindings for a list of C++ structs.

Parameters:

  • shim_writer (ShimWriter) – The shim writer to write the shim layer code.

  • structs (list[Struct]) – List of declarations of the struct types in CXX

  • parent_type (nbtypes.Type, optional) – Parent type of the Python API, by default nbtypes.Type

  • data_model (type, optional) – Data model for the struct, by default StructModel

  • aliases (dict[str, list[str]], optional) – Mappings from the name of the struct to a list of aliases. For example in C++: typedef A B; typedef A C; then aliases = {“A”: [“B”, “C”]}

Returns:

The Python APIs of the structs.

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.