class based add_analysis

[paddymul]

Checks

• I have checked that this enhancement has not already been requested

How would you categorize this request. You can select multiple if not sure

Developer ergonomics (defaults, error messages)

Enhancement Description

Adding analysis methods to buckaroo is awkward. I copy the existing list of analysis_klasses, extend it with the new analysis_klass, then create a new class extending buckaroo with the analysis plumbed in. This should be built into BuckarooWidget

Pseudo Code Implementation

    class A:

        b = 12
        def foo(self):
            return 10
        
        @classmethod
        def foo(kls, new_b):
            class t_class(kls):
                b = new_b
            return t_class
    #A.foo(), A().foo()
    new_class = A.foo(8)
    new_class().b
    return

Prior Art

n/a

[paddymul]

Implementation Plan

Overview

Improve the add_analysis API to be more ergonomic and class-based.

Steps

1. Design the API — proposed interface:

   @buckaroo_analysis
   class MyAnalysis(ColAnalysis):
       provides = ["my_stat"]
       def summary(self, col):
           return {"my_stat": col.mean()}
   
   widget = BuckarooWidget(df, extra_analysis=[MyAnalysis])
   # Or:
   widget.add_analysis(MyAnalysis)

2. Registration mechanism:

   • extra_analysis parameter on widget constructor — adds classes at init time
   • add_analysis() method — adds at runtime, triggers re-analysis
   • @buckaroo_analysis decorator — optional, registers in a global registry for auto-discovery

3. Validation — when adding an analysis class:

   • Verify it has required attributes (provides, requires)
   • Check for circular dependencies in the analysis graph
   • Raise clear errors for invalid classes

4. Coordinate with add_analysis no longer works #413 — fix the broken add_analysis first, then enhance the API in this issue.

5. Tests: test custom analysis registration, re-analysis trigger, and graph validation.

Files to modify

• buckaroo/buckaroo_widget.py — constructor param + method
• buckaroo/pluggable_analysis_framework/analysis_management.py — registration
• Documentation / examples

@codex

[chatgpt-codex-connector]

Summary

• Added class-based analysis registration primitives in the analysis pipeline:
  • introduced @buckaroo_analysis, a global REGISTERED_ANALYSIS, and get_registered_analysis(),
  • added contract normalization/validation so analysis classes can use ergonomic aliases (provides / requires) while still interoperating with existing pipeline fields (provides_defaults / requires_summary),
  • and wired validation into pipeline verification and add_analysis(). buckaroo/pluggable_analysis_framework/analysis_management.pyL21-L64 buckaroo/pluggable_analysis_framework/analysis_management.pyL262-L280
• Extended widget ergonomics by adding constructor-time registration:
  • extra_analysis and include_registered_analysis are now available on BuckarooWidgetBase and BuckarooInfiniteWidget,
  • constructor-time classes are applied immediately via self.dataflow.add_analysis(...). buckaroo/buckaroo_widget.pyL108-L150 buckaroo/buckaroo_widget.pyL373-L383
• Exported buckaroo_analysis at package top-level for easier usage (from buckaroo import buckaroo_analysis). buckaroo/init.pyL1-L7
• Added/updated tests for:
  • alias-based class registration,
  • invalid contract rejection,
  • decorator registration,
  • widget constructor-time registration (extra_analysis and include_registered_analysis). tests/unit/analysis_management_test.pyL8-L14 tests/unit/analysis_management_test.pyL300-L335 tests/unit/dataflow/customizable_dataflow_test.pyL6-L7 tests/unit/dataflow/customizable_dataflow_test.pyL591-L609
• Added README documentation showing the new class-based flow (@buckaroo_analysis, extra_analysis, include_registered_analysis). README.mdL114-L136

Testing

• ⚠️ pytest -q tests/unit/analysis_management_test.py tests/unit/dataflow/customizable_dataflow_test.py -q (initial run failed because pandas is not installed in the system interpreter).
• ⚠️ .venv/bin/pytest -q tests/unit/analysis_management_test.py tests/unit/dataflow/customizable_dataflow_test.py -q (first venv run failed because buckaroo/static/widget.js was missing in this environment).
• ✅ .venv/bin/pytest -q tests/unit/analysis_management_test.py tests/unit/dataflow/customizable_dataflow_test.py -q

Also completed follow-up actions requested:

• ✅ committed changes on the current branch (129dc34).
• ✅ created a new PR via make_pr with title “Follow-up: class-based add_analysis API and registration ergonomics”.

View task →

[paddymul]

Related: PR #515

PR #515 (merged): "Add Pluggable Analysis Framework v2 with typed DAG" — this was a major refactor of the analysis framework. It introduced:

• Typed DAG for analysis dependency management
• Cycle detection
• Better analysis class registration

This may have addressed some of the ergonomic concerns. See also #413 (add_analysis working) and #414 (add_pinned_analysis). Worth reviewing the v2 API to see if the class-based improvements proposed here are already covered.