pywry.notebook¶
Notebook environment detection and widget creation helpers.
Environment Detection¶
Bases: Enum
Detected notebook environment type.
cached
¶
detect_notebook_environment() -> NotebookEnvironment
Detect the current notebook environment.
This function is cached - environment detection only happens once.
Returns:
| Type | Description |
|---|---|
NotebookEnvironment
|
The detected environment. NONE means use native window, IPYTHON_TERMINAL means use native window (not inline). |
Check if inline notebook rendering should be used.
Returns True for: - Notebook environments (Jupyter, Colab, VS Code, etc.) - When PYWRY_SERVER__FORCE_NOTEBOOK=true (for headless web deployments)
Returns False for: - No IPython - IPython terminal - Unknown environments (unless force_notebook is set)
Returns:
| Type | Description |
|---|---|
bool
|
True if inline rendering should be used. |
Check if anywidget is installed and available.
Returns:
| Type | Description |
|---|---|
bool
|
True if anywidget >= 0.9.0 is available. |
Check if running in a cloud-hosted notebook environment.
Cloud environments may use CDN assets instead of embedded.
Returns:
| Type | Description |
|---|---|
bool
|
True for Colab, Kaggle, Azure, Databricks. |
Clear the cached environment detection.
Useful for testing or when environment changes.
Widget Factories¶
create_plotly_widget(figure_json: str, widget_id: str, title: str = 'PyWry', theme: str = 'dark', width: str = '100%', height: int = 500, port: int | None = None, toolbars: list[Any] | None = None, modals: list[Any] | None = None, force_iframe: bool = False) -> Any
Create a Plotly widget using the best available backend.
Automatically selects: 1. PyWryPlotlyWidget (anywidget) if available - best performance 2. InlineWidget (FastAPI) as fallback - broader compatibility
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
figure_json
|
str
|
Plotly figure as JSON string (should include 'config' if needed). |
required |
widget_id
|
str
|
Unique widget identifier. |
required |
title
|
str
|
Widget title. |
'PyWry'
|
theme
|
str
|
'dark' or 'light'. |
'dark'
|
width
|
str
|
Widget width (CSS). |
'100%'
|
height
|
int
|
Widget height in pixels. |
500
|
port
|
int
|
Server port (only for InlineWidget fallback). |
None
|
toolbars
|
list[Toolbar | dict]
|
List of toolbars. Each can be a Toolbar model or dict with: - position: "top", "bottom", "left", "right", "inside" - items: list of item configs (Button, Select, etc.) |
None
|
modals
|
list[Modal | dict]
|
List of modals. Each can be a Modal model or dict with: - component_id: unique identifier for the modal - title: modal header title - items: list of content items (HTML, form elements, etc.) - size: 'small', 'medium', 'large', or 'fullscreen' |
None
|
force_iframe
|
bool
|
If True, force use of InlineWidget instead of anywidget. Required for BROWSER mode which needs open_in_browser() method. Default: False. |
False
|
Returns:
| Type | Description |
|---|---|
BaseWidget
|
Widget instance implementing BaseWidget protocol. |
create_dataframe_widget(config: Any, widget_id: str, title: str = 'PyWry', theme: str = 'dark', aggrid_theme: str = 'alpine', width: str = '100%', height: int = 500, header_html: str = '', toolbars: list[Any] | None = None, modals: list[Any] | None = None, port: int | None = None, force_iframe: bool = False) -> Any
Create a DataFrame/AG Grid widget using the best available backend.
Automatically selects: 1. PyWryAgGridWidget (anywidget) if available - best performance 2. InlineWidget (FastAPI) as fallback - broader compatibility
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
GridConfig
|
Unified grid configuration from grid.build_grid_config(). |
required |
widget_id
|
str
|
Unique widget identifier. |
required |
title
|
str
|
Widget title. |
'PyWry'
|
theme
|
str
|
'dark' or 'light'. |
'dark'
|
aggrid_theme
|
str
|
AG Grid theme name. |
'alpine'
|
width
|
str
|
Widget width (CSS). |
'100%'
|
height
|
int
|
Widget height in pixels. |
500
|
header_html
|
str
|
Custom HTML for header section. |
''
|
toolbars
|
list[Toolbar | dict]
|
List of toolbars. Each can be a Toolbar model or dict with: - position: "top", "bottom", "left", "right", "inside" - items: list of item configs (Button, Select, etc.) |
None
|
modals
|
list[Modal | dict]
|
List of modals. Each can be a Modal model or dict with: - component_id: unique identifier for the modal - title: modal header title - items: list of content items (HTML, form elements, etc.) - size: 'small', 'medium', 'large', or 'fullscreen' |
None
|
port
|
int
|
Server port (only for InlineWidget fallback). |
None
|
force_iframe
|
bool
|
If True, force use of InlineWidget instead of anywidget. Required for BROWSER mode which needs open_in_browser() method. Default: False. |
False
|
Returns:
| Type | Description |
|---|---|
BaseWidget
|
Widget instance implementing BaseWidget protocol. |