Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

internal: add marimo._internal exports (#7910)

Myles Scolnick211886e5b411
diff --git a/marimo/_internal/__init__.py b/marimo/_internal/__init__.py
deleted file mode 100644
index 491a2384ee..0000000000
--- a/marimo/_internal/__init__.py
+++ /dev/null
@@ -1,6 +0,0 @@
-# Copyright 2026 Marimo. All rights reserved.
-"""Internal API - DO NOT USE."""
-
-import marimo._internal.templates as templates
-
-__all__ = ["templates"]
diff --git a/marimo/_internal/commands.py b/marimo/_internal/commands.py
new file mode 100644
index 0000000000..47b4ac9ef2
--- /dev/null
+++ b/marimo/_internal/commands.py
@@ -0,0 +1,80 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Internal API for commands."""
+
+from marimo._runtime.commands import (
+ AppMetadata,
+ ClearCacheCommand,
+ CodeCompletionCommand,
+ Command,
+ CommandMessage,
+ CreateNotebookCommand,
+ DebugCellCommand,
+ DeleteCellCommand,
+ ExecuteCellCommand,
+ ExecuteCellsCommand,
+ ExecuteScratchpadCommand,
+ ExecuteStaleCellsCommand,
+ GetCacheInfoCommand,
+ HTTPRequest,
+ InstallPackagesCommand,
+ InvokeFunctionCommand,
+ ListDataSourceConnectionCommand,
+ ListOrValue,
+ ListSecretKeysCommand,
+ ListSQLTablesCommand,
+ ModelMessage,
+ PreviewDatasetColumnCommand,
+ PreviewSQLTableCommand,
+ Primitive,
+ RefreshSecretsCommand,
+ RenameNotebookCommand,
+ SerializedCLIArgs,
+ SerializedQueryParams,
+ StopKernelCommand,
+ SyncGraphCommand,
+ UpdateCellConfigCommand,
+ UpdateUIElementCommand,
+ UpdateUserConfigCommand,
+ UpdateWidgetModelCommand,
+ ValidateSQLCommand,
+ kebab_case,
+)
+
+__all__ = [
+ "AppMetadata",
+ "ClearCacheCommand",
+ "CodeCompletionCommand",
+ "Command",
+ "CommandMessage",
+ "CreateNotebookCommand",
+ "DebugCellCommand",
+ "DeleteCellCommand",
+ "ExecuteCellCommand",
+ "ExecuteCellsCommand",
+ "ExecuteScratchpadCommand",
+ "ExecuteStaleCellsCommand",
+ "GetCacheInfoCommand",
+ "HTTPRequest",
+ "InstallPackagesCommand",
+ "InvokeFunctionCommand",
+ "ListDataSourceConnectionCommand",
+ "ListOrValue",
+ "ListSQLTablesCommand",
+ "ListSecretKeysCommand",
+ "ModelMessage",
+ "PreviewDatasetColumnCommand",
+ "PreviewSQLTableCommand",
+ "Primitive",
+ "RefreshSecretsCommand",
+ "RenameNotebookCommand",
+ "SerializedCLIArgs",
+ "SerializedQueryParams",
+ "StopKernelCommand",
+ "SyncGraphCommand",
+ "UpdateCellConfigCommand",
+ "UpdateUIElementCommand",
+ "UpdateUserConfigCommand",
+ "UpdateWidgetModelCommand",
+ "ValidateSQLCommand",
+ "kebab_case",
+]
diff --git a/marimo/_internal/config.py b/marimo/_internal/config.py
new file mode 100644
index 0000000000..4cd8ce0f55
--- /dev/null
+++ b/marimo/_internal/config.py
@@ -0,0 +1,20 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Internal API for configuration management."""
+
+from marimo._config.config import (
+ DisplayConfig,
+ MarimoConfig,
+ PartialMarimoConfig,
+)
+from marimo._config.manager import (
+ MarimoConfigManager,
+ get_default_config_manager,
+)
+
+__all__ = [
+ "DisplayConfig",
+ "MarimoConfig",
+ "MarimoConfigManager",
+ "PartialMarimoConfig",
+ "get_default_config_manager",
+]
diff --git a/marimo/_internal/converters.py b/marimo/_internal/converters.py
new file mode 100644
index 0000000000..d712dadf9f
--- /dev/null
+++ b/marimo/_internal/converters.py
@@ -0,0 +1,8 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Internal API for notebook converters."""
+
+from marimo._convert.converters import MarimoConvert
+
+__all__ = [
+ "MarimoConvert",
+]
diff --git a/marimo/_internal/ids.py b/marimo/_internal/ids.py
new file mode 100644
index 0000000000..8905acd9ae
--- /dev/null
+++ b/marimo/_internal/ids.py
@@ -0,0 +1,18 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Internal API for ID types."""
+
+from marimo._types.ids import (
+ CellId_t,
+ ConsumerId,
+ SessionId,
+ UIElementId,
+ VariableName,
+)
+
+__all__ = [
+ "CellId_t",
+ "ConsumerId",
+ "SessionId",
+ "UIElementId",
+ "VariableName",
+]
diff --git a/marimo/_internal/ipc.py b/marimo/_internal/ipc.py
new file mode 100644
index 0000000000..f53385393d
--- /dev/null
+++ b/marimo/_internal/ipc.py
@@ -0,0 +1,14 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Internal API for inter-process communication (IPC)."""
+
+from marimo._ipc.connection import Channel, Connection
+from marimo._ipc.queue_manager import QueueManager
+from marimo._ipc.types import ConnectionInfo, KernelArgs
+
+__all__ = [
+ "Channel",
+ "Connection",
+ "ConnectionInfo",
+ "KernelArgs",
+ "QueueManager",
+]
diff --git a/marimo/_internal/notifications.py b/marimo/_internal/notifications.py
new file mode 100644
index 0000000000..1ddb49ff07
--- /dev/null
+++ b/marimo/_internal/notifications.py
@@ -0,0 +1,94 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Internal API for notifications."""
+
+from marimo._messaging.notification import (
+ AlertNotification,
+ BannerNotification,
+ CacheClearedNotification,
+ CacheInfoNotification,
+ CellNotification,
+ ColumnPreview,
+ CompletedRunNotification,
+ CompletionResultNotification,
+ DataColumnPreviewNotification,
+ DatasetsNotification,
+ DataSourceConnectionsNotification,
+ FocusCellNotification,
+ FunctionCallResultNotification,
+ HumanReadableStatus,
+ InstallingPackageAlertNotification,
+ InterruptedNotification,
+ KernelCapabilitiesNotification,
+ KernelReadyNotification,
+ KernelStartupErrorNotification,
+ MissingPackageAlertNotification,
+ Notification,
+ NotificationMessage,
+ PackageStatusType,
+ QueryParamsAppendNotification,
+ QueryParamsClearNotification,
+ QueryParamsDeleteNotification,
+ QueryParamsSetNotification,
+ ReconnectedNotification,
+ ReloadNotification,
+ RemoveUIElementsNotification,
+ SecretKeysResultNotification,
+ SQLMetadata,
+ SQLTableListPreviewNotification,
+ SQLTablePreviewNotification,
+ StartupLogsNotification,
+ UIElementMessageNotification,
+ UpdateCellCodesNotification,
+ UpdateCellIdsNotification,
+ ValidateSQLResultNotification,
+ VariableDeclarationNotification,
+ VariablesNotification,
+ VariableValue,
+ VariableValuesNotification,
+)
+
+__all__ = [
+ "AlertNotification",
+ "BannerNotification",
+ "CacheClearedNotification",
+ "CacheInfoNotification",
+ "CellNotification",
+ "ColumnPreview",
+ "CompletedRunNotification",
+ "CompletionResultNotification",
+ "DataColumnPreviewNotification",
+ "DataSourceConnectionsNotification",
+ "DatasetsNotification",
+ "FocusCellNotification",
+ "FunctionCallResultNotification",
+ "HumanReadableStatus",
+ "InstallingPackageAlertNotification",
+ "InterruptedNotification",
+ "KernelCapabilitiesNotification",
+ "KernelReadyNotification",
+ "KernelStartupErrorNotification",
+ "MissingPackageAlertNotification",
+ "Notification",
+ "NotificationMessage",
+ "PackageStatusType",
+ "QueryParamsAppendNotification",
+ "QueryParamsClearNotification",
+ "QueryParamsDeleteNotification",
+ "QueryParamsSetNotification",
+ "ReconnectedNotification",
+ "ReloadNotification",
+ "RemoveUIElementsNotification",
+ "SQLMetadata",
+ "SQLTableListPreviewNotification",
+ "SQLTablePreviewNotification",
+ "SecretKeysResultNotification",
+ "StartupLogsNotification",
+ "UIElementMessageNotification",
+ "UpdateCellCodesNotification",
+ "UpdateCellIdsNotification",
+ "VariableDeclarationNotification",
+ "VariableValue",
+ "VariableValuesNotification",
+ "VariablesNotification",
+ "ValidateSQLResultNotification",
+]
diff --git a/marimo/_internal/packages.py b/marimo/_internal/packages.py
new file mode 100644
index 0000000000..dabcbeaa83
--- /dev/null
+++ b/marimo/_internal/packages.py
@@ -0,0 +1,14 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Internal API for package management."""
+
+from marimo._runtime.packages.package_manager import (
+ PackageDescription,
+ PackageManager,
+)
+from marimo._runtime.packages.package_managers import create_package_manager
+
+__all__ = [
+ "PackageDescription",
+ "PackageManager",
+ "create_package_manager",
+]
diff --git a/marimo/_internal/schemas.py b/marimo/_internal/schemas.py
new file mode 100644
index 0000000000..81ebba2d00
--- /dev/null
+++ b/marimo/_internal/schemas.py
@@ -0,0 +1,12 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Internal API for notebook schemas."""
+
+import marimo._schemas.notebook as notebook
+import marimo._schemas.serialization as serialization
+import marimo._schemas.session as session
+
+__all__ = [
+ "notebook",
+ "serialization",
+ "session",
+]
diff --git a/marimo/_internal/server/__init__.py b/marimo/_internal/server/__init__.py
new file mode 100644
index 0000000000..139beedc09
--- /dev/null
+++ b/marimo/_internal/server/__init__.py
@@ -0,0 +1,6 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Internal API for server types."""
+
+import marimo._internal.server.requests as requests
+
+__all__ = ["requests"]
diff --git a/marimo/_internal/server/requests.py b/marimo/_internal/server/requests.py
new file mode 100644
index 0000000000..49e704dfd2
--- /dev/null
+++ b/marimo/_internal/server/requests.py
@@ -0,0 +1,18 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Internal API for server request types."""
+
+from marimo._server.models.export import (
+ ExportAsHTMLRequest,
+ ExportAsIPYNBRequest,
+ ExportAsMarkdownRequest,
+ ExportAsScriptRequest,
+)
+from marimo._server.models.models import InstantiateNotebookRequest
+
+__all__ = [
+ "ExportAsHTMLRequest",
+ "ExportAsIPYNBRequest",
+ "ExportAsMarkdownRequest",
+ "ExportAsScriptRequest",
+ "InstantiateNotebookRequest",
+]
diff --git a/marimo/_internal/session/__init__.py b/marimo/_internal/session/__init__.py
new file mode 100644
index 0000000000..5a67a2b584
--- /dev/null
+++ b/marimo/_internal/session/__init__.py
@@ -0,0 +1,18 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Internal API for session management."""
+
+import marimo._internal.session.extensions as extensions
+from marimo._session.model import SessionMode
+from marimo._session.queue import ProcessLike
+from marimo._session.state.session_view import SessionView
+from marimo._session.types import KernelManager, QueueManager, Session
+
+__all__ = [
+ "extensions",
+ "KernelManager",
+ "ProcessLike",
+ "QueueManager",
+ "Session",
+ "SessionMode",
+ "SessionView",
+]
diff --git a/marimo/_internal/session/extensions.py b/marimo/_internal/session/extensions.py
new file mode 100644
index 0000000000..a40f3b96f9
--- /dev/null
+++ b/marimo/_internal/session/extensions.py
@@ -0,0 +1,24 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Internal API for session extensions."""
+
+from marimo._session.extensions.extensions import (
+ CachingExtension,
+ HeartbeatExtension,
+ LoggingExtension,
+ NotificationListenerExtension,
+ QueueExtension,
+ ReplayExtension,
+ SessionViewExtension,
+)
+from marimo._session.extensions.types import SessionExtension
+
+__all__ = [
+ "CachingExtension",
+ "HeartbeatExtension",
+ "LoggingExtension",
+ "NotificationListenerExtension",
+ "QueueExtension",
+ "ReplayExtension",
+ "SessionExtension",
+ "SessionViewExtension",
+]
diff --git a/marimo/_ipc/connection.py b/marimo/_ipc/connection.py
index b4073afb59..55b3f8c0db 100644
--- a/marimo/_ipc/connection.py
+++ b/marimo/_ipc/connection.py
@@ -8,14 +8,14 @@ import queue
import sys
import typing
-import zmq
-
from marimo import _loggers
from marimo._ipc.queue_proxy import PushQueue, start_receiver_thread
from marimo._ipc.types import ConnectionInfo
from marimo._session.queue import QueueType
if typing.TYPE_CHECKING:
+ import zmq
+
from marimo._messaging.types import KernelMessage
from marimo._runtime.commands import (
CodeCompletionCommand,
@@ -50,6 +50,8 @@ class Channel(typing.Generic[T]):
Note: maxsize is ignored for push channels as ZeroMQ handles buffering.
"""
+ import zmq
+
socket = context.socket(zmq.PUSH)
return cls(
kind="push",
@@ -67,6 +69,8 @@ class Channel(typing.Generic[T]):
context: ZeroMQ context for creating sockets
maxsize: Maximum queue size (0 = unlimited)
"""
+ import zmq
+
socket = context.socket(zmq.PULL)
return cls(
kind="pull",
@@ -116,6 +120,8 @@ class Connection:
Returns:
Tuple of (Connection instance, ConnectionInfo with port numbers)
"""
+ import zmq
+
context = zmq.Context()
conn = cls(
context=context,
@@ -152,6 +158,8 @@ class Connection:
Returns:
Connected Connection instance
"""
+ import zmq
+
context = zmq.Context()
conn = cls(
diff --git a/marimo/_ipc/queue_proxy.py b/marimo/_ipc/queue_proxy.py
index 62dac6d25d..39bb6e09e3 100644
--- a/marimo/_ipc/queue_proxy.py
+++ b/marimo/_ipc/queue_proxy.py
@@ -7,8 +7,6 @@ import pickle
import threading
import typing
-import zmq
-
from marimo import _loggers
from marimo._session.queue import QueueType
@@ -16,6 +14,9 @@ LOGGER = _loggers.marimo_logger()
T = typing.TypeVar("T")
+if typing.TYPE_CHECKING:
+ import zmq
+
class PushQueue(QueueType[T]):
"""Queue for pushing messages through ZeroMQ socket (sender side only).
@@ -65,6 +66,7 @@ def start_receiver_thread(
receivers: dict[zmq.Socket[bytes], QueueType[typing.Any]],
) -> tuple[threading.Event, threading.Thread]:
"""Start receiver thread."""
+ import zmq
def receive_loop(
receivers: dict[zmq.Socket[bytes], QueueType[typing.Any]],
diff --git a/marimo/_messaging/notification.py b/marimo/_messaging/notification.py
index 861cf25250..95b1e6e77a 100644
--- a/marimo/_messaging/notification.py
+++ b/marimo/_messaging/notification.py
@@ -1,8 +1,5 @@
# Copyright 2026 Marimo. All rights reserved.
-"""Message Types
-
-Messages that the kernel sends to the frontend.
-"""
+"""Notification message types for kernel-to-frontend communication."""
from __future__ import annotations
@@ -42,27 +39,30 @@ LOGGER = loggers.marimo_logger()
class Notification(msgspec.Struct, tag_field="op"):
- name: ClassVar[str]
-
-
-class CellNotification(Notification, tag="cell-op"):
- """Op to transition a cell.
-
- A CellNotification's data has some optional fields:
+ """Base class for all kernel-to-frontend notifications.
- output - a CellOutput
- console - a CellOutput (console msg to append), or a list of
- CellOutputs
- status - execution status
- stale_inputs - whether the cell has stale inputs (variables, modules, ...)
- run_id - the run associated with this cell.
- serialization - the serialization status of the cell
+ Uses msgspec's tagged union with "op" field as discriminator.
+ Subclasses must define both tag="..." and name: ClassVar[str].
+ """
- Omitting a field means that its value should be unchanged!
+ name: ClassVar[str]
- And one required field:
- cell_id - the cell id
+class CellNotification(Notification, tag="cell-op"):
+ """Updates a cell's state in the frontend.
+
+ Only fields that are set (not None) will update the cell state.
+ Omitting a field leaves that aspect unchanged.
+
+ Attributes:
+ cell_id: Unique identifier of the cell being updated.
+ output: Cell's output. Use CellOutput.empty() to clear.
+ console: Console messages. Single/list appends, [] clears, None unchanged.
+ status: Execution status (idle/running/stale/queued/disabled-transitively).
+ stale_inputs: Whether cell has stale inputs from changed dependencies.
+ run_id: Execution run ID for tracing. Auto-set from context.
+ serialization: Serialization status (TopLevelHints).
+ timestamp: Creation timestamp, auto-set.
"""
name: ClassVar[str] = "cell-op"
@@ -96,7 +96,13 @@ class CellNotification(Notification, tag="cell-op"):
class HumanReadableStatus(msgspec.Struct):
- """Human-readable status."""
+ """Human-readable status for operation results.
+
+ Attributes:
+ code: Status code ("ok" or "error").
+ title: Optional short title.
+ message: Optional detailed description.
+ """
code: Literal["ok", "error"]
title: Union[str, None] = None
@@ -104,7 +110,13 @@ class HumanReadableStatus(msgspec.Struct):
class FunctionCallResultNotification(Notification, tag="function-call-result"):
- """Result of calling a function."""
+ """Result of a frontend-initiated function call.
+
+ Attributes:
+ function_call_id: ID matching the original request.
+ return_value: Function return value as JSON.
+ status: Human-readable success/failure status.
+ """
name: ClassVar[str] = "function-call-result"
@@ -114,7 +126,13 @@ class FunctionCallResultNotification(Notification, tag="function-call-result"):
class RemoveUIElementsNotification(Notification, tag="remove-ui-elements"):
- """Invalidate UI elements for a given cell."""
+ """Removes UI elements associated with a cell.
+
+ Sent when cell is re-executed or deleted.
+
+ Attributes:
+ cell_id: Cell whose UI elements should be removed.
+ """
name: ClassVar[str] = "remove-ui-elements"
cell_id: CellId_t
@@ -123,7 +141,14 @@ class RemoveUIElementsNotification(Notification, tag="remove-ui-elements"):
class UIElementMessageNotification(
Notification, tag="send-ui-element-message"
):
- """Send a message to a UI element."""
+ """Sends a message to a UI element/widget.
+
+ Attributes:
+ ui_element: UI element identifier (legacy).
+ model_id: Widget model ID (newer architecture).
+ message: Message payload as dictionary.
+ buffers: Optional binary buffers for large data.
+ """
name: ClassVar[str] = "send-ui-element-message"
ui_element: Optional[str]
@@ -133,18 +158,29 @@ class UIElementMessageNotification(
class InterruptedNotification(Notification, tag="interrupted"):
- """Written when the kernel is interrupted by the user."""
+ """Kernel was interrupted by user (SIGINT/Ctrl+C)."""
name: ClassVar[str] = "interrupted"
class CompletedRunNotification(Notification, tag="completed-run"):
- """Written on run completion (of submitted cells and their descendants."""
+ """Run of submitted cells and descendants completed."""
name: ClassVar[str] = "completed-run"
class KernelCapabilitiesNotification(msgspec.Struct):
+ """Kernel capabilities detected at startup.
+
+ All fields auto-detected in __post_init__.
+
+ Attributes:
+ terminal: Terminal access (unavailable on Windows/Pyodide).
+ pylsp: Python Language Server Protocol installed.
+ ty: ty type checker installed.
+ basedpyright: basedpyright type checker installed.
+ """
+
terminal: bool = False
pylsp: bool = False
ty: bool = False
@@ -159,7 +195,23 @@ class KernelCapabilitiesNotification(msgspec.Struct):
class KernelReadyNotification(Notification, tag="kernel-ready"):
- """Kernel is ready for execution."""
+ """Kernel ready for execution. First notification sent at startup.
+
+ Attributes:
+ cell_ids: Cell IDs in order.
+ codes: Source code for each cell.
+ names: Cell names/titles.
+ layout: Notebook layout config.
+ configs: Per-cell configuration.
+ resumed: Whether resumed from previous session.
+ ui_values: Previous UI element values if resumed.
+ last_executed_code: Last executed code per cell if resumed.
+ last_execution_time: Last execution time per cell if resumed.
+ app_config: Application configuration.
+ kiosk: Whether running in kiosk mode.
+ capabilities: Available kernel capabilities.
+ auto_instantiated: Whether cells already executed (run mode).
+ """
name: ClassVar[str] = "kernel-ready"
cell_ids: tuple[CellId_t, ...]
@@ -167,27 +219,24 @@ class KernelReadyNotification(Notification, tag="kernel-ready"):
names: tuple[str, ...]
layout: Optional[LayoutConfig]
configs: tuple[CellConfig, ...]
- # Whether the kernel was resumed from a previous session
resumed: bool
- # If the kernel was resumed, the values of the UI elements
ui_values: Optional[dict[str, JSONType]]
- # If the kernel was resumed, the last executed code for each cell
last_executed_code: Optional[dict[CellId_t, str]]
- # If the kernel was resumed, the last execution time for each cell
last_execution_time: Optional[dict[CellId_t, float]]
- # App config
app_config: _AppConfig
- # Whether the kernel is kiosk mode
kiosk: bool
- # Kernel capabilities
capabilities: KernelCapabilitiesNotification
- # Whether the kernel has already been instantiated server-side (e.g. run mode)
- # If True, the frontend does not need to instantiate the app.
auto_instantiated: bool = False
class CompletionResultNotification(Notification, tag="completion-result"):
- """Code completion result."""
+ """Code completion result from language server.
+
+ Attributes:
+ completion_id: Request ID this responds to.
+ prefix_length: Length of prefix to replace.
+ options: Completion options to display.
+ """
name: ClassVar[str] = "completion-result"
completion_id: str
@@ -196,9 +245,16 @@ class CompletionResultNotification(Notification, tag="completion-result"):
class AlertNotification(Notification, tag="alert"):
+ """User-facing alert message.
+
+ Attributes:
+ title: Alert title.
+ description: Alert body (may contain HTML).
+ variant: Visual variant (e.g., "danger").
+ """
+
name: ClassVar[str] = "alert"
title: str
- # description may be HTML
description: str
variant: Optional[Literal["danger"]] = None
@@ -206,6 +262,13 @@ class AlertNotification(Notification, tag="alert"):
class MissingPackageAlertNotification(
Notification, tag="missing-package-alert"
):
+ """Alert for missing packages with install option.
+
+ Attributes:
+ packages: Missing package names.
+ isolated: Whether in isolated environment.
+ """
+
name: ClassVar[str] = "missing-package-alert"
packages: list[str]
isolated: bool
@@ -220,71 +283,130 @@ PackageStatusType = dict[
class InstallingPackageAlertNotification(
Notification, tag="installing-package-alert"
):
+ """Package installation progress with streaming logs.
+
+ Attributes:
+ packages: Package name to status (queued/installing/installed/failed).
+ logs: Optional streaming logs per package.
+ log_status: Log stream status (append/start/done).
+ """
+
name: ClassVar[str] = "installing-package-alert"
packages: PackageStatusType
- # Optional fields for streaming logs per package
logs: Optional[dict[str, str]] = None # package name -> log content
log_status: Optional[Literal["append", "start", "done"]] = None
class ReconnectedNotification(Notification, tag="reconnected"):
+ """WebSocket reconnection confirmed."""
+
name: ClassVar[str] = "reconnected"
class StartupLogsNotification(Notification, tag="startup-logs"):
+ """Streaming kernel startup logs.
+
+ Attributes:
+ content: Log content to display.
+ status: Stream status (start/append/done).
+ """
+
name: ClassVar[str] = "startup-logs"
content: str
status: Literal["append", "start", "done"]
class BannerNotification(Notification, tag="banner"):
+ """Persistent banner message at top of notebook.
+
+ Attributes:
+ title: Banner title.
+ description: Banner body (may contain HTML).
+ variant: Visual variant (e.g., "danger").
+ action: Optional user action (e.g., "restart").
+ """
+
name: ClassVar[str] = "banner"
title: str
- # description may be HTML
description: str
variant: Optional[Literal["danger"]] = None
action: Optional[Literal["restart"]] = None
class KernelStartupErrorNotification(Notification, tag="kernel-startup-error"):
- """Notification sent when kernel fails to start (e.g., sandbox build failure)."""
+ """Kernel failed to start.
+
+ Attributes:
+ error: Error message describing failure.
+ """
name: ClassVar[str] = "kernel-startup-error"
error: str
class ReloadNotification(Notification, tag="reload"):
+ """Instructs frontend to reload the page."""
+
name: ClassVar[str] = "reload"
class VariableDeclarationNotification(msgspec.Struct):
+ """Variable declaration and usage for dataflow graph.
+
+ Attributes:
+ name: Variable name.
+ declared_by: Cell IDs that define this variable.
+ used_by: Cell IDs that use this variable.
+ """
+
name: str
declared_by: list[CellId_t]
used_by: list[CellId_t]
class VariableValue(BaseStruct):
+ """Variable value and type for variables panel.
+
+ Attributes:
+ name: Variable name.
+ value: String representation of value.
+ datatype: Data type as string.
+ """
+
name: str
value: Optional[str]
datatype: Optional[str]
class VariablesNotification(Notification, tag="variables"):
- """List of variable declarations."""
+ """Variable dataflow graph.
+
+ Attributes:
+ variables: Variable declarations and usage.
+ """
name: ClassVar[str] = "variables"
variables: list[VariableDeclarationNotification]
class VariableValuesNotification(Notification, tag="variable-values"):
- """List of variables and their types/values."""
+ """Current variable values.
+
+ Attributes:
+ variables: Variables with current values and types.
+ """
name: ClassVar[str] = "variable-values"
variables: list[VariableValue]
class DatasetsNotification(Notification, tag="datasets"):
- """List of datasets."""
+ """Available datasets for data explorer.
+
+ Attributes:
+ tables: Available data tables/datasets.
+ clear_channel: If set, clears tables from this channel first.
+ """
name: ClassVar[str] = "datasets"
tables: list[DataTable]
@@ -292,7 +414,13 @@ class DatasetsNotification(Notification, tag="datasets"):
class SQLMetadata(msgspec.Struct, tag="sql-metadata"):
- """Metadata for a SQL database."""
+ """SQL database and schema metadata.
+
+ Attributes:
+ connection: Connection identifier.
+ database: Database name.
+ schema: Schema name.
+ """
connection: str
database: str
@@ -300,7 +428,14 @@ class SQLMetadata(msgspec.Struct, tag="sql-metadata"):
class SQLTablePreviewNotification(Notification, tag="sql-table-preview"):
- """Preview of a table in a SQL database."""
+ """SQL table preview.
+
+ Attributes:
+ request_id: Request ID this responds to.
+ metadata: Database and schema metadata.
+ table: Table data (None if error).
+ error: Error message if failed.
+ """
name: ClassVar[str] = "sql-table-preview"
request_id: RequestId
@@ -312,7 +447,14 @@ class SQLTablePreviewNotification(Notification, tag="sql-table-preview"):
class SQLTableListPreviewNotification(
Notification, tag="sql-table-list-preview"
):
- """Preview of a list of tables in a schema."""
+ """List of SQL tables in a schema.
+
+ Attributes:
+ request_id: Request ID this responds to.
+ metadata: Database and schema metadata.
+ tables: Tables in schema.
+ error: Error message if failed.
+ """
name: ClassVar[str] = "sql-table-list-preview"
request_id: RequestId
@@ -322,6 +464,16 @@ class SQLTableListPreviewNotification(
class ColumnPreview(msgspec.Struct):
+ """Column preview with stats and visualization.
+
+ Attributes:
+ chart_spec: Vega-Lite chart spec.
+ chart_code: Python code to generate chart.
+ error: Error message if failed.
+ missing_packages: Required but not installed packages.
+ stats: Statistical summary.
+ """
+
chart_spec: Optional[str] = None
chart_code: Optional[str] = None
error: Optional[str] = None
@@ -332,7 +484,14 @@ class ColumnPreview(msgspec.Struct):
class DataColumnPreviewNotification(
Notification, ColumnPreview, kw_only=True, tag="data-column-preview"
):
- """Preview of a column in a dataset."""
+ """Data column preview with stats and visualization.
+
+ Inherits all ColumnPreview attributes.
+
+ Attributes:
+ table_name: Table containing the column.
+ column_name: Column being previewed.
+ """
name: ClassVar[str] = "data-column-preview"
table_name: str
@@ -342,11 +501,26 @@ class DataColumnPreviewNotification(
class DataSourceConnectionsNotification(
Notification, tag="data-source-connections"
):
+ """Available data source connections for SQL cells.
+
+ Attributes:
+ connections: Available data source connections.
+ """
+
name: ClassVar[str] = "data-source-connections"
connections: list[DataSourceConnection]
class ValidateSQLResultNotification(Notification, tag="validate-sql-result"):
+ """SQL query validation result.
+
+ Attributes:
+ request_id: Request ID this responds to.
+ parse_result: SQL parsing result.
+ validate_result: Catalog validation result.
+ error: Error message if failed.
+ """
+
name: ClassVar[str] = "validate-sql-result"
request_id: RequestId
parse_result: Optional[SqlParseResult] = None
@@ -355,7 +529,12 @@ class ValidateSQLResultNotification(Notification, tag="validate-sql-result"):
class QueryParamsSetNotification(Notification, tag="query-params-set"):
- """Set query parameters."""
+ """Sets URL query parameter, replacing existing values.
+
+ Attributes:
+ key: Query parameter key.
+ value: Value(s) to set.
+ """
name: ClassVar[str] = "query-params-set"
key: str
@@ -363,40 +542,70 @@ class QueryParamsSetNotification(Notification, tag="query-params-set"):
class QueryParamsAppendNotification(Notification, tag="query-params-append"):
+ """Appends value to URL query parameter.
+
+ Attributes:
+ key: Query parameter key.
+ value: Value to append.
+ """
+
name: ClassVar[str] = "query-params-append"
key: str
value: str
class QueryParamsDeleteNotification(Notification, tag="query-params-delete"):
+ """Deletes URL query parameter values.
+
+ Attributes:
+ key: Query parameter key.
+ value: Specific value to delete. If None, deletes all values for key.
+ """
+
name: ClassVar[str] = "query-params-delete"
key: str
- # If value is None, delete all values for the key
- # If a value is provided, only that value is deleted
value: Optional[str]
class QueryParamsClearNotification(Notification, tag="query-params-clear"):
- # Clear all query parameters
+ """Clears all URL query parameters."""
+
name: ClassVar[str] = "query-params-clear"
class FocusCellNotification(Notification, tag="focus-cell"):
+ """Focuses a cell (kiosk mode).
+
+ Attributes:
+ cell_id: Cell to focus.
+ """
+
name: ClassVar[str] = "focus-cell"
cell_id: CellId_t
class UpdateCellCodesNotification(Notification, tag="update-cell-codes"):
+ """Updates cell code contents (kiosk mode).
+
+ Attributes:
+ cell_ids: Cells to update.
+ codes: New code for each cell.
+ code_is_stale: If True, code was not executed on backend (output may not match).
+ """
+
name: ClassVar[str] = "update-cell-codes"
cell_ids: list[CellId_t]
codes: list[str]
- # If true, this means the code was not run on the backend when updating
- # the cell codes.
code_is_stale: bool
class SecretKeysResultNotification(Notification, tag="secret-keys-result"):
- """Result of listing secret keys."""
+ """Available secret keys from secret providers.
+
+ Attributes:
+ request_id: Request ID this responds to.
+ secrets: Secret keys with provider info.
+ """
request_id: RequestId
name: ClassVar[str] = "secret-keys-result"
@@ -404,14 +613,26 @@ class SecretKeysResultNotification(Notification, tag="secret-keys-result"):
class CacheClearedNotification(Notification, tag="cache-cleared"):
- """Result of clearing cache."""
+ """Execution cache cleared result.
+
+ Attributes:
+ bytes_freed: Bytes freed by clearing cache.
+ """
name: ClassVar[str] = "cache-cleared"
bytes_freed: int
class CacheInfoNotification(Notification, tag="cache-info"):
- """Cache statistics information."""
+ """Execution cache statistics.
+
+ Attributes:
+ hits: Cache hits.
+ misses: Cache misses.
+ time: Time spent on cache operations (seconds).
+ disk_to_free: Disk space that could be freed (bytes).
+ disk_total: Total disk space used (bytes).
+ """
name: ClassVar[str] = "cache-info"
hits: int
@@ -422,11 +643,10 @@ class CacheInfoNotification(Notification, tag="cache-info"):
class UpdateCellIdsNotification(Notification, tag="update-cell-ids"):
- """
- Update the cell ID ordering of the cells in the notebook.
+ """Updates cell ordering in notebook.
- Right now we send the entire list of cell IDs,
- but in the future we might want to send change-deltas.
+ Attributes:
+ cell_ids: Complete ordered list of cell IDs.
"""
name: ClassVar[str] = "update-cell-ids"
@@ -434,18 +654,18 @@ class UpdateCellIdsNotification(Notification, tag="update-cell-ids"):
NotificationMessage = Union[
- # Cell notifications
+ # Cell operations
CellNotification,
FunctionCallResultNotification,
UIElementMessageNotification,
RemoveUIElementsNotification,
- # Notebook operations
+ # Notebook lifecycle
ReloadNotification,
ReconnectedNotification,
InterruptedNotification,
CompletedRunNotification,
KernelReadyNotification,
- # Editor operations
+ # Editor
CompletionResultNotification,
# Alerts
AlertNotification,
@@ -462,7 +682,7 @@ NotificationMessage = Union[
QueryParamsAppendNotification,
QueryParamsDeleteNotification,
QueryParamsClearNotification,
- # Datasets
+ # Data/SQL
DatasetsNotification,
DataColumnPreviewNotification,
SQLTablePreviewNotification,
@@ -474,7 +694,7 @@ NotificationMessage = Union[
# Cache
CacheClearedNotification,
CacheInfoNotification,
- # Kiosk specific
+ # Kiosk
FocusCellNotification,
UpdateCellCodesNotification,
UpdateCellIdsNotification,
diff --git a/tests/_internal/snapshots/internal_api.txt b/tests/_internal/snapshots/internal_api.txt
index 03aef553c3..0aa2931baf 100644
--- a/tests/_internal/snapshots/internal_api.txt
+++ b/tests/_internal/snapshots/internal_api.txt
@@ -1,3 +1,135 @@
+commands
+ AppMetadata
+ ClearCacheCommand
+ CodeCompletionCommand
+ Command
+ CommandMessage
+ CreateNotebookCommand
+ DebugCellCommand
+ DeleteCellCommand
+ ExecuteCellCommand
+ ExecuteCellsCommand
+ ExecuteScratchpadCommand
+ ExecuteStaleCellsCommand
+ GetCacheInfoCommand
+ HTTPRequest
+ InstallPackagesCommand
+ InvokeFunctionCommand
+ ListDataSourceConnectionCommand
+ ListOrValue
+ ListSQLTablesCommand
+ ListSecretKeysCommand
+ ModelMessage
+ PreviewDatasetColumnCommand
+ PreviewSQLTableCommand
+ Primitive
+ RefreshSecretsCommand
+ RenameNotebookCommand
+ SerializedCLIArgs
+ SerializedQueryParams
+ StopKernelCommand
+ SyncGraphCommand
+ UpdateCellConfigCommand
+ UpdateUIElementCommand
+ UpdateUserConfigCommand
+ UpdateWidgetModelCommand
+ ValidateSQLCommand
+ kebab_case
+config
+ DisplayConfig
+ MarimoConfig
+ MarimoConfigManager
+ PartialMarimoConfig
+ get_default_config_manager
+converters
+ MarimoConvert
+ids
+ CellId_t
+ ConsumerId
+ SessionId
+ UIElementId
+ VariableName
+ipc
+ Channel
+ Connection
+ ConnectionInfo
+ KernelArgs
+ QueueManager
+notifications
+ AlertNotification
+ BannerNotification
+ CacheClearedNotification
+ CacheInfoNotification
+ CellNotification
+ ColumnPreview
+ CompletedRunNotification
+ CompletionResultNotification
+ DataColumnPreviewNotification
+ DataSourceConnectionsNotification
+ DatasetsNotification
+ FocusCellNotification
+ FunctionCallResultNotification
+ HumanReadableStatus
+ InstallingPackageAlertNotification
+ InterruptedNotification
+ KernelCapabilitiesNotification
+ KernelReadyNotification
+ KernelStartupErrorNotification
+ MissingPackageAlertNotification
+ Notification
+ NotificationMessage
+ PackageStatusType
+ QueryParamsAppendNotification
+ QueryParamsClearNotification
+ QueryParamsDeleteNotification
+ QueryParamsSetNotification
+ ReconnectedNotification
+ ReloadNotification
+ RemoveUIElementsNotification
+ SQLMetadata
+ SQLTableListPreviewNotification
+ SQLTablePreviewNotification
+ SecretKeysResultNotification
+ StartupLogsNotification
+ UIElementMessageNotification
+ UpdateCellCodesNotification
+ UpdateCellIdsNotification
+ ValidateSQLResultNotification
+ VariableDeclarationNotification
+ VariableValue
+ VariableValuesNotification
+ VariablesNotification
+packages
+ PackageDescription
+ PackageManager
+ create_package_manager
+schemas
+ notebook
+ serialization
+ session
+server
+ requests
+ ExportAsHTMLRequest
+ ExportAsIPYNBRequest
+ ExportAsMarkdownRequest
+ ExportAsScriptRequest
+ InstantiateNotebookRequest
+session
+ KernelManager
+ ProcessLike
+ QueueManager
+ Session
+ SessionMode
+ SessionView
+ extensions
+ CachingExtension
+ HeartbeatExtension
+ LoggingExtension
+ NotificationListenerExtension
+ QueueExtension
+ ReplayExtension
+ SessionExtension
+ SessionViewExtension
templates
render_notebook
render_static_notebook
\ No newline at end of file
diff --git a/tests/_internal/test_internal_api.py b/tests/_internal/test_internal_api.py
index cd53ac9d04..4d026a119b 100644
--- a/tests/_internal/test_internal_api.py
+++ b/tests/_internal/test_internal_api.py
@@ -1,5 +1,8 @@
from __future__ import annotations
+import importlib
+from pathlib import Path
+
from tests.mocks import snapshotter
from tests.utils import explore_module
@@ -7,8 +10,32 @@ snapshot = snapshotter(__file__)
def test_internal_api():
- import marimo._internal as internal
+ # Get all Python files and folders in marimo/_internal
+ internal_path = (
+ Path(__file__).parent.parent.parent / "marimo" / "_internal"
+ )
+
+ # Get both .py files and directories
+ items = []
+ for item in sorted(internal_path.iterdir()):
+ if item.name.startswith("_"):
+ continue
+ if item.is_file() and item.suffix == ".py":
+ items.append((item.stem, False))
+ elif item.is_dir():
+ items.append((item.name, True))
+
+ all_results = []
+ for name, _is_dir in items:
+ # Import the module dynamically
+ module_name = f"marimo._internal.{name}"
+ module = importlib.import_module(module_name)
+
+ # Explore the module
+ results = explore_module(module)
+ if results:
+ all_results.append(name)
+ all_results.extend([f" {line}" for line in results])
- results = explore_module(internal)
- assert len(results) > 0
- snapshot("internal_api.txt", "\n".join(results))
+ assert len(all_results) > 0
+ snapshot("internal_api.txt", "\n".join(all_results))