0
# anywidget
1
2
A comprehensive toolkit for creating reusable, interactive web-based widgets for Jupyter environments without requiring complex cookiecutter templates. anywidget enables developers to build custom Jupyter widgets using modern web technologies and provides seamless integration across multiple platforms including Jupyter, JupyterLab, Google Colab, VSCode, and marimo.
3
4
## Package Information
5
6
- **Package Name**: anywidget
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install anywidget`
10
11
## Core Imports
12
13
```python
14
import anywidget
15
```
16
17
Most common usage:
18
19
```python
20
from anywidget import AnyWidget
21
```
22
23
For experimental features:
24
25
```python
26
from anywidget.experimental import widget, dataclass, MimeBundleDescriptor
27
```
28
29
## Basic Usage
30
31
```python
32
import anywidget
33
import traitlets as t
34
35
# Basic widget with inline ES module
36
class CounterWidget(anywidget.AnyWidget):
37
_esm = """
38
function render({ model, el }) {
39
let count = () => model.get("value");
40
let btn = document.createElement("button");
41
btn.innerHTML = `count is ${count()}`;
42
btn.addEventListener("click", () => {
43
model.set("value", count() + 1);
44
});
45
el.appendChild(btn);
46
model.on("change:value", () => {
47
btn.innerHTML = `count is ${count()}`;
48
});
49
}
50
export default { render };
51
"""
52
53
value = t.Int(0).tag(sync=True)
54
55
# Create and display the widget
56
widget = CounterWidget()
57
widget # In Jupyter, this displays the widget
58
```
59
60
## Architecture
61
62
anywidget provides a flexible architecture for creating custom Jupyter widgets:
63
64
- **AnyWidget Base Class**: Main entry point that handles Jupyter widget protocol and communication
65
- **File Contents System**: Dynamic file loading with hot reloading for development
66
- **Experimental Decorators**: Advanced patterns for dataclass and function-based widgets
67
- **Communication Layer**: Bidirectional state sync between Python and JavaScript
68
- **Multi-Platform Support**: Consistent behavior across Jupyter environments
69
70
The system supports multiple widget creation patterns: class-based inheritance, decorator-based composition, and dataclass-based reactive widgets, making it suitable for simple prototypes to complex interactive applications.
71
72
## Capabilities
73
74
### Core Widget Class
75
76
The fundamental AnyWidget base class that provides the foundation for creating custom Jupyter widgets with ES modules and CSS styling.
77
78
```python { .api }
79
class AnyWidget(ipywidgets.DOMWidget):
80
def __init__(*args, **kwargs): ...
81
def __init_subclass__(**kwargs): ...
82
def _repr_mimebundle_(**kwargs): ...
83
```
84
85
[Core Widget](./core-widget.md)
86
87
### Experimental Decorators
88
89
Advanced decorator-based patterns for creating widgets using modern Python features including dataclasses, event systems, and function-based approaches.
90
91
```python { .api }
92
def widget(*, esm: str | Path, css: str | Path | None = None, **kwargs): ...
93
def dataclass(cls=None, *, esm: str | Path, css: str | Path | None = None, **dataclass_kwargs): ...
94
```
95
96
[Experimental Features](./experimental.md)
97
98
### File Contents Management
99
100
Dynamic file loading system with live reloading capabilities for development workflows and virtual file management for inline content.
101
102
```python { .api }
103
class FileContents:
104
def __init__(path: str | Path, start_thread: bool = True): ...
105
def __str__() -> str: ...
106
107
class VirtualFileContents:
108
def __init__(contents: str = ""): ...
109
def __str__() -> str: ...
110
```
111
112
[File Management](./file-management.md)
113
114
### IPython Integration
115
116
Cell magic support for creating virtual files and managing widget development workflows within Jupyter notebooks.
117
118
```python { .api }
119
def load_ipython_extension(ipython): ...
120
121
class AnyWidgetMagics:
122
def vfile(line: str, cell: str): ...
123
def clear_vfiles(line: str): ...
124
```
125
126
[IPython Integration](./ipython-integration.md)
127
128
## Types
129
130
```python { .api }
131
# Core widget types
132
class AnyWidget(ipywidgets.DOMWidget):
133
"""Main widget base class"""
134
_model_name: str
135
_model_module: str
136
_model_module_version: str
137
_view_name: str
138
_view_module: str
139
_view_module_version: str
140
141
# File content types
142
class FileContents:
143
"""File watcher with change signals"""
144
changed: Signal
145
deleted: Signal
146
147
class VirtualFileContents:
148
"""In-memory file contents with change signals"""
149
changed: Signal
150
contents: str
151
152
# Descriptor types
153
class MimeBundleDescriptor:
154
"""Descriptor for widget representation"""
155
def __init__(*, follow_changes: bool = True, autodetect_observer: bool = True, no_view: bool = False, **extra_state): ...
156
157
class ReprMimeBundle:
158
"""Widget representation with comm management"""
159
def send_state(include: str | list[str] | None = None): ...
160
def sync_object_with_view(py_to_js: bool = True, js_to_py: bool = True): ...
161
def unsync_object_with_view(): ...
162
163
# Protocol types
164
class WidgetBase(Protocol):
165
"""Base widget protocol for custom messages"""
166
def send(msg: str | dict | list, buffers: list[bytes]): ...
167
def on_msg(callback): ...
168
```