IR — bound declarations

Note

Generated from the C++ headers by apiary --emit-cpp-docs-json.

type DirectiveList

A list of parsed annotation directives.

class BoundClass

A bound class or struct, with its members and nested entities.

bool is_template

True for class templates.

bool is_external

True for annotated classes seen in headers OUTSIDE the current module’s source filter. Captured purely for cross-module name resolution in the .pyi emitter — the C++ emitter ignores them (their bindings live in the owning module’s TU).

std::vector<std::string> template_param_names

Template parameter names, e.g. [“T”, “rank”] for template <typename T, size_t rank>.

std::vector<std::string> bases

Base class names.

std::vector<BoundMethod> ctors

Bound constructors.

std::vector<BoundMethod> methods

Bound methods.

std::vector<BoundField> fields

Bound public fields.

std::vector<BoundEnum> nested_enums

Nested enums.

std::vector<BoundClass> nested_classes

Nested classes.

std::vector<BoundInstantiation> instantiations

Requested template instantiations.

std::vector<BoundProperty> properties

/@setter pairs collapsed into properties. Computed by the post-IR pass in Properties.hpp; empty until the pass has run.

class BoundConcept

A C++20 concept.

Captured in docs mode for cpp:concept declarations.

std::vector<std::string> template_param_names

Template parameter names of the concept.

class BoundEntityCommon

Common metadata every bound declaration carries.

Inherited by the concrete bound-* structs below so the emitter can write generic code against this base when convenient.

std::string name

Unqualified name.

std::string qualified_name

Fully qualified name, e.g. ::ns::Class::method.

DirectiveList directives

Annotation directives attached to this entity.

std::string doc

Raw doxygen text, or empty.

SourceLocation location

Source location of the declaration.

std::optional<std::string> submodule

Resolved Python submodule path (from a per-entity or inherited APIARY_MODULE directive on an enclosing namespace). Empty when the entity belongs to the top-level module. The .pyi emitter uses this to decide which <module>.pyi file an entity belongs to (e.g. einsums.linalg, einsums.graph).

class BoundEnum

A bound enumeration.

bool is_scoped

True for scoped enums (enum class).

std::string underlying_type

C++ underlying type as written.

std::string underlying_py_type

Python-stub form of the underlying type.

std::vector<BoundEnumerator> enumerators

The enum’s enumerators.

class BoundEnumerator

A single enumerator within a bound enum.

std::string name

Enumerator name.

std::int64_t value

Enumerator integer value.

std::string doc

Raw doxygen text, or empty.

class BoundField

A bound public data member (field) of a class.

std::string type

C++ type of the field.

std::string py_type

Python-stub form of the type.

bool is_static

True for static data members.

class BoundFunction

A bound free function.

std::string return_type

C++ return type as written.

std::string return_type_canonical

Canonical (typedef-expanded) form of the return type. For per-instantiation .pyi emission we substitute and look up the canonical form so a function returning the typedef alias RuntimeTensor<T> resolves to the same Python class as the underlying GeneralRuntimeTensor<T, std::allocator<T>>.

std::string return_py_type

Python-stub form of the return type.

std::vector<BoundParam> params

Parameters of the function.

bool is_template

True for function templates.

std::vector<std::string> template_param_names

Names of the function template’s template parameters (e.g. ["AType", "BType", "CType"] for template <BasicTensorConcept AType, …>). Used by the emitter to substitute concrete types from per-instantiation type_args into return/parameter types when emitting a static_cast<> to disambiguate overloads.

std::vector<std::string> template_kwargs

Python kwarg names for the leading bool template parameters, from APIARY_TEMPLATE_KWARGS. Empty for functions without that directive. The emitter generates a runtime dispatcher with these as keyword-only arguments when non-empty.

std::vector<BoundInstantiation> instantiations

One per APIARY_INSTANTIATE_AS directive on a templated free function. Empty for non-templated functions and for templated functions without explicit instantiation directives (those skip emission with a TODO comment).

std::vector<PythonOverload> python_overloads

Logical Python-facing entries for this function, computed by a post-IR pass (see PythonOverloads.hpp). The C++ emitter dispatches on each entry’s kind to choose dispatcher style; the .pyi emitter renders one def (with @overload decorators if needed) per entry. Empty when the pass hasn’t run yet.

class BoundInstantiation

One concrete template instantiation requested by an @instantiate or _as directive.

The emitter produces both an explicit template class Foo<args>; declaration and a per-instantiation py::class_<Foo<args>>(m, py_name) binding block from this.

std::string py_name

Python identifier (sanitized or user-supplied).

std::string type_args

Type arguments ready to paste between < and >, e.g. “float, 2”.

class BoundMacro

A documented preprocessor macro.

Macros are not AST declarations, so these are gathered by a raw-text scan of the module header for a doc comment immediately preceding a #define (docs mode only). Rendered as c:macro in the C++ reference.

bool is_function_like

True for function-like macros.

std::vector<std::string> params

Parameter names for function-like macros.

class BoundMethod

A bound class method, constructor, or destructor.

std::string return_type

C++ return type as written.

std::string return_type_canonical

Canonical (typedef-expanded) form of the return type. Same role as BoundFunction::return_type_canonical: the .pyi emitter substitutes member-template bindings on this and re-resolves so per-directive overloads emit concrete return types.

std::string return_py_type

Python-stub form of the return type.

std::vector<BoundParam> params

Parameters of the method.

bool is_const

True for const-qualified methods.

bool is_static

True for static methods.

bool is_virtual

True for virtual methods.

bool is_template

True for member function templates.

std::vector<std::string> template_param_names

Its template parameters (docs mode).

bool is_pure_virtual

True for pure-virtual methods.

bool is_constructor

True if this method is a constructor.

bool is_destructor

True if this method is a destructor.

bool is_operator

True if this method is an operator overload.

bool is_deleted

True if this method is deleted (= delete).

bool has_variadic_pack

Whether the last parameter is a variadic pack (set by APIARY_VARIADIC_FROM).

Set by APIARY_VARIADIC_FROM: the last parameter is a pack expansion whose arity comes from the named template parameter, and each expanded slot has type variadic_element_type. When emitting a per-instantiation binding, the pack slot is replaced with N copies of (variadic_element_type, dim_<i>).

std::string variadic_from_param

Name of the template parameter that supplies the pack arity.

std::string variadic_element_type

Element type of each expanded pack slot.

class BoundParam

A single function parameter.

Default-value text is captured verbatim from the AST so the emitter can re-emit it as a py::arg("x") = ....

Note

py_type and default_value_py carry the Python-stub forms — a best-effort translation populated alongside the C++ form. The .pyi emitter consumes these; the C++ emitter ignores them.

std::string name

Parameter name.

std::string type

C++ type as written.

std::string type_canonical

Canonical (typedef-expanded) C++ type, populated alongside type. Same purpose as BoundFunction::return_type_canonical — lets the .pyi emitter substitute and resolve through typedef aliases like RuntimeTensor<T> ↔ GeneralRuntimeTensor<T, std::allocator<T>>.

std::string py_type

Python-stub form of the type.

std::optional<std::string> default_value

Default-value text as written, or empty.

std::optional<std::string> default_value_py

Python-stub form of the default value.

class BoundProperty

A property aggregated from @getter / @setter directives on class methods.

Computed by a post-IR pass (Properties.hpp) that walks BoundClass.methods. The .pyi emitter consumes this directly; the pybind11 C++ emitter still derives the same merge inline (kept separate to avoid churning the working emit code).

std::string py_name

Python attribute name from @getter(“name”).

std::string type

Getter’s C++ return type, ref/cv stripped.

std::string py_type

Python form (translated from type).

std::string doc

Doxygen text from getter.

bool has_setter

True when a matching @setter exists.

std::size_t getter_index

Index into BoundClass.methods for the getter.

std::size_t setter_index

Index into BoundClass.methods for the setter.

Note

Valid only when has_setter is true.

class BoundTypedef

A typedef / using-alias.

Captured in docs mode so the C++ reference can emit a cpp:type declaration — which makes references to the alias (e.g. einsums::blas::int_t in a function signature) resolve instead of dangling. underlying_type is the aliased type as written.

std::string underlying_type

The aliased type as written.

bool is_template

True for alias templates.

std::vector<std::string> template_param_names

Template parameter names for alias templates.

class Directive

One parsed annotation directive.

The AnnotationParser splits the raw “apiary:<name>[:<arg>[:<arg>…]]” payload into this form so the emitter can switch on name cleanly.

std::string name

Directive name (the <name> token).

std::vector<std::string> args

Directive arguments (the <arg> tokens).

class Module

The full IR for one bound module.

std::vector<BoundClass> classes

Bound classes and structs.

std::vector<BoundFunction> functions

Bound free functions.

std::vector<BoundEnum> enums

Bound enums.

std::vector<BoundTypedef> typedefs

Bound typedefs / aliases (docs mode only).

std::vector<BoundConcept> concepts

Bound concepts (docs mode only).

std::vector<BoundMacro> macros

Bound macros (docs mode only).

class PythonOverload

One logical Python-facing entry on a free function or method.

Computed by a post-IR pass (PythonOverloads.hpp) that groups raw BoundInstantiation entries according to the merge rules pybind11 expects:

• NonTemplate — function has no templates; one m.def, one stub

• SingleInstantiation — one instantiation with this py_name; one m.def

• DtypeDispatcher — N instantiations sharing arg signature, only return type varies; collapse into one m.def taking dtype="..." kwarg

• TemplateKwargsDispatcher — 2^N instantiations from APIARY_INSTANTIATE_BOOLS collapse into one m.def with N bool kwargs

• OverloadSet — multiple instantiations with the same py_name that DON’T merge into a dispatcher; pybind11 picks at runtime via overload resolution

Note

Both the C++ emitter and the .pyi emitter consume this view so the merge rules live in one place.

Kind kind

Which merge rule applies to this entry.

std::string py_name

Python name of this entry.

std::vector<std::size_t> instantiation_indices

Indices into the owning entity’s instantiations vector for this entry.

Empty for NonTemplate (which uses the function itself directly).

std::vector<std::string> dtype_values

For DtypeDispatcher: the C++ scalar type each instantiation contributes.

Parallel to instantiation_indices.

std::string default_dtype

For DtypeDispatcher: the picked default dtype string (e.g. “float64”).

std::vector<std::string> kwarg_names

For TemplateKwargsDispatcher: parallel to f.template_kwargs.

enum class Kind

How the instantiations merge into a Python-facing entry.

enumerator NonTemplate

enumerator SingleInstantiation

enumerator DtypeDispatcher

enumerator TemplateKwargsDispatcher

enumerator OverloadSet

class SourceLocation

Source position (file, line, column) of a captured declaration.

std::string file

Source file path.

unsigned int line

1-based line number.

unsigned int column

1-based column number.

std::string dump(const Module &module_)

Produce a deterministic textual dump of the IR.

For golden-output testing and diagnostics. Phase 3’s emitter produces the actual pybind11 C++; this function exists so Phase 2 has something testable.

Parameters:

module – The IR module to dump.

Returns:

The textual dump.