How koaning/drawdata works
Project Type and Purpose
• drawdata is a Python library that provides interactive Jupyter widgets (ScatterWidget, BarWidget) for hand-drawing datasets in a notebook. Under the hood it leverages the anywidget/ip ywidgets machinery to connect a Python backend (the “kernel”) with a JavaScript frontend running in Jupyter, VS Code or Colab. It ships both Python code (drawdata package) and JavaScript/CSS assets (drawdata/static and js/).
File-Structure Analysis
• Top-level:
• setup.py, readme.md, demo scripts (demo.py, bar-demo.py, scatter-demo.py)
• drawdata/ – the Python package containing:
– __init__.py and widget implementers (ScatterWidget, BarWidget)
– static/ – the compiled widget JS & CSS for the frontend
• js/ – source JS for the widgets (bar_widget.js, scatter_widget.js)
• docs/ – static site (Vite-powered) with built assets for documentation
• Key patterns: separation of Python logic vs frontend assets; use of anywidget/ip ywidgets for comms; standard packaging via setup.py.
README Insights
• Confirms use of anywidget and ipywidgets.
• Describes two main APIs (ScatterWidget, BarWidget).
a. Main Components
1. Jupyter Notebook Frontend (in Browser or VS Code)
2. JavaScript Widget View & Model (drawdata/static + anywidget runtime)
3. Jupyter Comm Layer (WebSocket/JSON comms between frontend & kernel)
4. Python Kernel Backend (drawdata package: widget classes, state management)
5. Data Consumers (user code retrieving widget.data → pandas/polars → scikit-learn)
6. Documentation Site (Vite + static assets under docs/)
b. Relationships & Interactions
• User instantiates ScatterWidget in notebook → Python kernel registers a widget instance.
• Notebook front-end loads the corresponding JS view & model (from drawdata/static).
• As the user draws, mouse events trigger JS updates → sent over the comm channel → Python backend receives new coordinates.
• Python backend updates internal state (widget.data) and notifies any observers.
• User code calls widget.data_as_pandas or widget.data_as_polars → Python side converts the stored list of dicts into a DataFrame.
• Optionally, user feeds X, y into scikit-learn pipelines.
c. Architectural Patterns & Principles
• MVC-style split between JS “View” & Python “Model.”
• Publish-subscribe via Jupyter comms for real-time updates.
• Packaging assets alongside Python code (using anywidget conventions).
• Clear separation of core library vs documentation site.
d. Key Technologies & Frameworks
• Python: anywidget, ipywidgets, pandas, polars, scikit-learn (optional)
• JavaScript: custom widget code (bar_widget.js, scatter_widget.js), d3.v7.js (for drawing), anywidget/browser runtime