Class Template - Method Template (Parent-Child pattern) Binding Generation (#286)

This is a demo PR that shows a "Parent-Child" pattern that shows an
end-to-end use case of class template instantiation, template argument
deduction and overload selection working hand in hand.

- Add templated member-function bindings for class template
specializations with overload selection and `arg_intent` support.
- Generate templated-method shims with explicit argument formatting
(array-ref/pointer handling) and intent-aware returns.
- Improve template specialization metadata and typing
(qualified/specialized names, enum NTTP names, CCCL `NullType`/opaque
fallback, quieter parse defaults).
- Add class-template unit tests and CCCL integration tests; run CCCL
tests in conda and wheels CI.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Templated-method support for class templates with per-method
argument-intent overrides

* **Improvements**
  * Enum-aware rendering of template arguments
  * Reduced default parsing verbosity
  * Looser type deduction for opaque mappings
  * More consistent qualified template-name handling

* **Tests**
  * New CCCL (CUB) test suite and CI step to run it
  * Expanded templated-class method tests

* **Chores**
  * Updated CI/test scripts and pre-commit codespell ignores

* **Documentation**
  * Added SPDX headers to third-party test modules
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Michael Wang <isVoid@users.noreply.github.com>

Author: isVoid

.github/workflows/wheels-test.yaml

@@ -135,3 +135,6 @@ jobs:
       - name: Test numbast wheels
         run: |
           python -m pytest numbast/
+      - name: Run numbast_extensions third-party CCCL tests
+        run: |
+          python -m pytest numbast_extensions/tests/thirdparty/CCCL/

.pre-commit-config.yaml

@@ -37,7 +37,7 @@ repos:
       - id: codespell
         additional_dependencies:
           - tomli
-        args: ["--toml", "pyproject.toml", "--ignore-words-list", "inout"]
+        args: ["--toml", "pyproject.toml", "--ignore-words-list", "inout,thirdparty"]
   - repo: https://github.com/google/yamlfmt
     rev: v0.16.0
     hooks:

ast_canopy/ast_canopy/api.py

@@ -341,7 +341,7 @@ def parse_declarations_from_source(
     cxx_standard: str = "gnu++17",
     additional_includes: list[str] = [],
     defines: list[str] = [],
-    verbose: bool = True,
+    verbose: bool = False,
     bypass_parse_error: bool = False,
 ) -> Declarations:
     """Given a source file, parse all top-level declarations from it and return

ast_canopy/ast_canopy/decl.py

@@ -391,6 +391,10 @@ def regular_member_functions(self):
             ):
                 yield m
 
+    def templated_member_functions(self):
+        """Generator for templated methods."""
+        yield from self.templated_methods
+
     @classmethod
     def from_c_obj(cls, c_obj: bindings.Record, parse_entry_point: str):
         return cls(
@@ -509,7 +513,7 @@ def value(self):
         return CXX_TYPE_TO_PYTHON_TYPE[cxx_type_name](self.value_serialized)
 
 
-class ClassTemplateSpecialization(Struct, ClassInstantiation):
+class ClassTemplateSpecialization(Struct):
     """Represents a C++ class template specialization declaration.
 
     Holds the underlying ``TemplatedStruct`` and provides ``instantiate`` for
@@ -535,7 +539,8 @@ def __init__(
             record.alignof_,
             record.parse_entry_point,
         )
-        ClassInstantiation.__init__(self, class_template)
+
+        self._instantiation = ClassInstantiation(class_template)
 
         targ_names: list[str] = [
             tp.name for tp in class_template.template_parameters
@@ -544,7 +549,7 @@ def __init__(
 
         kwargs = dict(zip(targ_names, targ_values))
 
-        self.instantiate(**kwargs)
+        self._instantiation.instantiate(**kwargs)
 
         self.actual_template_arguments = actual_template_arguments
 
@@ -560,11 +565,19 @@ def from_c_obj(
 
     @property
     def name(self):
-        return self.get_instantiated_c_stmt()
+        return self._name
+
+    @property
+    def specialized_name(self):
+        return self._instantiation.get_instantiated_c_stmt(use_qual_name=False)
+
+    @property
+    def qual_name(self):
+        return self._instantiation.get_instantiated_c_stmt(use_qual_name=True)
 
     @property
     def base_name(self):
-        return self.record.name
+        return self._name
 
     def constructors(self):
         for m in self.methods:

ast_canopy/ast_canopy/instantiations.py

@@ -37,14 +37,20 @@ def param_list(self):
             for tparam in self.template_parameters
         ]
 
-    def get_instantiated_c_stmt(self) -> str:
-        name = self.base_name
+    def get_instantiated_c_stmt(self, use_qual_name: bool = False) -> str:
+        if use_qual_name:
+            name = self.qual_name
+        else:
+            name = self.base_name
+
         param_list = self.param_list
 
         flatten = []
         for param in param_list:
             if isinstance(param, BaseInstantiation):
-                flatten.append(param.get_instantiated_c_stmt())
+                flatten.append(
+                    param.get_instantiated_c_stmt(use_qual_name=use_qual_name)
+                )
             else:
                 flatten.append(str(param))
 
@@ -56,6 +62,11 @@ def base_name(self):
             "BaseInstantiation.base_name is not implemented"
         )
 
+    def qual_name(self):
+        raise NotImplementedError(
+            "BaseInstantiation.qual_name is not implemented"
+        )
+
 
 class FunctionInstantiation(BaseInstantiation):
     """Represent an instantiation of a function template."""
@@ -68,6 +79,10 @@ def __init__(self, function_template: ast_canopy.decl.FunctionTemplate):
     def base_name(self):
         return self.function.name
 
+    @property
+    def qual_name(self):
+        return self.function.qual_name
+
     def evaluate_constexpr_value(self, *args, header=None):
         if not self.function.is_constexpr:
             raise ValueError("Function is not constexpr")
@@ -124,3 +139,7 @@ def __init__(self, class_template: ast_canopy.decl.ClassTemplate):
     @property
     def base_name(self):
         return self.record.name
+
+    @property
+    def qual_name(self):
+        return self.record.qual_name

ast_canopy/cpp/src/class_template_specialization.cpp

@@ -23,17 +23,50 @@ ClassTemplateSpecialization::ClassTemplateSpecialization(
 
   for (auto i = 0; i < tparam_list.size(); i++) {
     const auto &targ = tparam_list[i];
+
     clang::TemplateArgument::ArgKind kind = targ.getKind();
     switch (kind) {
     case clang::TemplateArgument::ArgKind::Type:
       actual_template_arguments.push_back(targ.getAsType().getAsString());
       break;
     case clang::TemplateArgument::ArgKind::Integral: {
-      llvm::APSInt integer = targ.getAsIntegral();
-      llvm::SmallString<32> str; // -uint64_t::max() is 21 digits (with sign).
-                                 // This should be enough.
-      integer.toString(str);
-      actual_template_arguments.push_back(str.c_str());
+      clang::QualType T = targ.getIntegralType();
+
+      // If this integral NTTP is actually an enum, try to recover the
+      // enumerator name from the value.
+      if (T->isEnumeralType()) {
+        const auto *ET = T->getAs<clang::EnumType>();
+        const clang::EnumDecl *ED = ET->getDecl();
+        const llvm::APSInt &Val = targ.getAsIntegral();
+
+        const clang::EnumConstantDecl *Matched = nullptr;
+        for (const auto *ECD : ED->enumerators()) {
+          if (ECD->getInitVal() == Val) {
+            Matched = ECD;
+            break;
+          }
+        }
+
+        if (Matched) {
+          // Use the fully-qualified enumerator name if you like,
+          // or just ECD->getNameAsString() for the bare name.
+          actual_template_arguments.push_back(
+              Matched->getQualifiedNameAsString());
+        } else {
+          // No enumerator found with that value; fall back to integer.
+          llvm::APSInt integer = Val;
+          llvm::SmallString<32> str;
+          integer.toString(str);
+          actual_template_arguments.push_back(str.c_str());
+        }
+      } else {
+        // Plain integral (not an enum type) — keep your existing behavior.
+        llvm::APSInt integer = targ.getAsIntegral();
+        llvm::SmallString<32> str; // -uint64_t::max() is 21 digits (with sign).
+        integer.toString(str);
+        actual_template_arguments.push_back(str.c_str());
+      }
+
       break;
     }
     default:

ast_canopy/tests/test_class_template_specialization.py

@@ -19,7 +19,7 @@ def test_ctpsd_unparsed_in_structs(sample_ctsd):
 
     # At this stage, assert that the ctpsd is not parsed.
     assert len(ctsd) == 1
-    assert ctsd[0].name == "BlockScan<int, 128>"
+    assert ctsd[0].specialized_name == "BlockScan<int, 128>"
 
     assert len(ctsd[0].fields) == 0
     assert len(ctsd[0].methods) == 2

ci/run_tests.py

@@ -38,13 +38,15 @@ def run_pytest(lib, test_dir):
 @click.option(
     "--curand_device", is_flag=True, help="Run curand device binding pytests."
 )
+@click.option("--cccl", is_flag=True, help="Run CCCL (CUB) binding pytests.")
 @click.option("--all-tests", is_flag=True, help="Run all pytests.")
 def run(
     ast_canopy: bool,
     numbast: bool,
     bf16: bool,
     fp16: bool,
     curand_device: bool,
+    cccl: bool,
     all_tests: bool,
 ):
     """Selectively run pytests in Numbast repo based on options provided.
@@ -53,7 +55,7 @@ def run(
     package. `--all-tests` option is mutually exclusive to all other options.
     """
     if all_tests:
-        if any([ast_canopy, numbast, bf16, fp16, curand_device]):
+        if any([ast_canopy, numbast, bf16, fp16, curand_device, cccl]):
             raise ValueError(
                 "`all_tests` and any subpackage specs are mutual exclusive."
             )
@@ -82,6 +84,8 @@ def run(
         )
     if all_tests or curand_device:
         run_pytest("curand_device", ["numbast_extensions/tests/test_curand.py"])
+    if all_tests or cccl:
+        run_pytest("cccl", ["numbast_extensions/tests/thirdparty/CCCL/"])
 
 
 if __name__ == "__main__":

ci/test_conda_python.sh

@@ -49,8 +49,7 @@ trap "EXITCODE=1" ERR
 set +e
 
 rapids-logger "Run Tests"
-# Debug print
-python ci/run_tests.py --ast-canopy --numbast
+python ci/run_tests.py --ast-canopy --numbast --cccl
 
 rapids-logger "Test script exiting with value: $EXITCODE"
 exit ${EXITCODE}