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
```