:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { useActions, useMountedLogic, useValues } from 'kea'
import { useEffect, useMemo, useRef } from 'react'
import { useNotebookJupyterCommands, useNotebookJupyterStoreValue } from 'lib/components/MarkdownNotebook/jupyterMode'
import { CodeEditorResizeable } from 'lib/monaco/CodeEditorResizable'
import { createPostHogWidgetNode } from 'scenes/notebooks/Nodes/NodeWrapper'
import type { NotebookNodeRunTerminalStatus } from 'scenes/notebooks/Notebook/notebookNodeStalenessLogic'
import { notebookCodeCellLogic } from 'products/notebooks/frontend/notebookCodeCellLogic'
import { notebookJupyterLogic } from '../Notebook/notebookJupyterLogic'
import { NotebookNodeAttributeProperties, NotebookNodeProps, NotebookNodeType } from '../types'
import { NotebookCellOutputHeader } from './components/NotebookCellOutputHeader'
import { NotebookCellOutputNameFooter } from './components/NotebookCellOutputNameFooter'
import { NotebookDataframeTable } from './components/NotebookDataframeTable'
import { NotebookJupyterCellOutput } from './components/NotebookJupyterCellOutput'
import { NotebookRunDownstreamBanner } from './components/NotebookRunDownstreamBanner'
import { NotebookStaleCellBanner } from './components/NotebookStaleCellBanner'
import { notebookNodeLogic } from './notebookNodeLogic'
import { countTextLines, initialSizedRunId, outputHeightForShape } from './notebookNodeOutputHeight'
import type { NotebookNodeSQLV2Result } from './NotebookNodeSQLV2'
import { SQL_V2_DEFAULT_PAGE_SIZE } from './notebookNodeSQLV2Logic'
import { NotebookDataframeResult } from './pythonExecution'
// The revamped Python cell: code runs in the notebook's sandbox kernel via the SQLV2 run
// path, with sibling SQLV2 frames materialized as pandas frames. A separate node type from
// the legacy ph-python cell (in-browser kernel) so the two flows never share run wiring.
export type NotebookNodePythonV2Attributes = {
code: string
// The dataframe name this cell's result is exposed as to later cells.
returnVariable: string
runId?: string | null
result?: NotebookNodeSQLV2Result | null
// How the run that produced `result` ended. An interrupt persists whatever the cell printed
// before the stop landed, so the result alone can't tell the two apart on a reload.
runStatus?: NotebookNodeRunTerminalStatus | null
}
const PYTHON_EDITOR_MIN_HEIGHT = 160
// About 20 lines at Monaco's 18px line height. An MCP-written cell is often far longer than that,
// and an editor that grows with the code pushes the output and the next cell off the screen.
// Past the cap the editor scrolls, and the drag handle expands it.
const PYTHON_EDITOR_MAX_HEIGHT = 360
// A Jupyter cell starts one line tall and grows with its code, so the whole cell stays in view.
const JUPYTER_EDITOR_MIN_HEIGHT = 34
const JUPYTER_EDITOR_MAX_HEIGHT = 100000
const toDataframeResult = (result: NotebookNodeSQLV2Result): NotebookDataframeResult => {
const columns = result.columns ?? []
const firstPage = result.first_page ?? []
return {
columns,
rows: firstPage.map((row) => Object.fromEntries(columns.map((column, index) => [column, row[index] ?? null]))),
rowCount: firstPage.length,
}
}
const Component = ({
attributes,
updateAttributes,
}: NotebookNodeProps<NotebookNodePythonV2Attributes>): JSX.Element | null => {
const nodeLogic = useMountedLogic(notebookNodeLogic)
const { nodeId, notebookLogic, expanded, isEditable } = useValues(nodeLogic)
const dataLogic = notebookCodeCellLogic(nodeId, notebookLogic, attributes, updateAttributes)
const {
isRunning,
runError,
isRestoringResult,
resultRestoreUnavailable,
page,
pageSize,
pageResult,
pageLoading,
operationBlockReason,
isStale,
staleReason,
isChainRunning,
staleDownstreamCount,
pendingKernelStart,
result: runResult,
} = useValues(dataLogic)
const { setPage, setPageSize, runStaleChain } = useActions(dataLogic)
const isJupyterMode = !!useNotebookJupyterCommands()
const { executionCounts } = useValues(notebookJupyterLogic({ shortId: notebookLogic.props.shortId }))
const result = runResult ?? attributes.result ?? null
const dataframeResult = useMemo(() => {
if (pageResult) {
return toDataframeResult({
columns: pageResult.columns,
row_count: pageResult.rows.length,
first_page: pageResult.rows,
})
}
return result && result.columns?.length ? toDataframeResult(result) : null
}, [pageResult, result])
const hasMorePages = pageResult
? pageResult.has_more
: (result?.has_more ?? (result?.first_page ?? []).length >= SQL_V2_DEFAULT_PAGE_SIZE)
const hasStreamOutput = !!(result?.stdout || result?.stderr || result?.media?.length)
// Only results get the strip. A run that failed shows a traceback, which "Results" mislabels,
// and a cell that never ran keeps the plain hint.
const hasOutput = hasStreamOutput || !!dataframeResult
// Grow a still-too-short node to fit the output each run lands, so it's readable without a
// manual resize. Sized to what came back — a printed value stays compact, a table or figure
// grows up to a cap. Only grows, and only for a run we haven't sized yet, so a deliberate
// resize is left untouched.
const sizedRunIdRef = useRef<string | null | undefined>(
initialSizedRunId({ hasResult: !!result, height: attributes.height, runId: attributes.runId ?? null })
)
useEffect(() => {
const runId = attributes.runId ?? null
// A read-only notebook lays the node out from its content, so there is no fixed height to
// outgrow — and no editor to persist one into.
if (!result || !isEditable || isJupyterMode || runId === sizedRunIdRef.current) {
return
}
sizedRunIdRef.current = runId
const target = outputHeightForShape({
rowCount: result.columns?.length ? (result.first_page ?? []).length : 0,
textLines: countTextLines(result.stdout, result.stderr),
hasMedia: !!result.media?.length,
})
if (target !== null && (typeof attributes.height !== 'number' || attributes.height < target)) {
updateAttributes({ height: target })
}
// oxlint-disable-next-line exhaustive-deps
}, [result, attributes.runId, isEditable])
if (!expanded) {
return null
}
if (isJupyterMode) {
return (
<NotebookJupyterCellOutput
result={result}
dataframeResult={dataframeResult}
dataframeProps={{
page,
pageSize,
hasMore: hasMorePages,
loading: isRunning || pageLoading || (isRestoringResult && !result?.first_page?.length),
paginationDisabledReason: pageLoading
? 'Fetching page…'
: isRunning
? 'Cell is running'
: (operationBlockReason ?? undefined),
onNextPage: () => setPage(page + 1),
onPreviousPage: () => setPage(page - 1),
}}
runError={runError}
status={
isRunning && pendingKernelStart
? 'Starting compute sandbox…'
: resultRestoreUnavailable
? 'Run the cell again to see its full output.'
: isRestoringResult
? 'Loading saved output…'
: null
}
executionCount={executionCounts[nodeId] ?? null}
returnVariable={attributes.returnVariable ?? ''}
onReturnVariableChange={(returnVariable) => updateAttributes({ returnVariable })}
isEditable={isEditable}
/>
)
}
return (
<div data-attr="notebook-node-python-v2" className="flex h-full min-h-0 flex-col">
<div
className="flex min-h-0 flex-1 flex-col overflow-y-auto"
onMouseDown={(event) => event.stopPropagation()}
onDragStart={(event) => event.stopPropagation()}
>
{isStale ? (
<div className="shrink-0 pb-2" onClick={(event) => event.stopPropagation()}>
<NotebookStaleCellBanner reason={staleReason ?? undefined} />
</div>
) : staleDownstreamCount > 0 && !isChainRunning ? (
<div className="shrink-0 pb-2" onClick={(event) => event.stopPropagation()}>
<NotebookRunDownstreamBanner
count={staleDownstreamCount}
onRun={() => runStaleChain(notebookLogic.values.content ?? null, nodeId)}
disabledReason={isRunning ? 'This cell is running' : (operationBlockReason ?? undefined)}
/>
</div>
) : null}
{isRunning && pendingKernelStart ? (
<div className="shrink-0 px-2 pt-1 pb-2 text-xs text-muted">Starting compute sandbox…</div>
) : null}
{hasOutput ? <NotebookCellOutputHeader>Results</NotebookCellOutputHeader> : null}
{hasStreamOutput ? (
<div className="shrink-0 space-y-2 px-2 py-2" onClick={(event) => event.stopPropagation()}>
{result?.stdout ? (
<pre className="text-xs font-mono whitespace-pre-wrap select-text m-0">{result.stdout}</pre>
) : null}
{result?.stderr ? (
<pre className="text-xs font-mono whitespace-pre-wrap text-danger select-text m-0">
{result.stderr}
</pre>
) : null}
{result?.media?.map((item, index) => (
<img
key={index}
src={`data:${item.mime_type};base64,${item.data}`}
alt="Python output"
className="max-w-full rounded border border-border bg-white"
/>
))}
</div>
) : null}
{resultRestoreUnavailable ? (
<div className="p-2 text-xs text-muted">Run the cell again to see its full results.</div>
) : isRestoringResult ? (
<div className="p-2 text-xs text-muted">Loading saved results…</div>
) : null}
{runError ? (
<div className="p-2 text-xs font-mono text-danger whitespace-pre-wrap">{runError}</div>
) : dataframeResult ? (
<div className="min-h-0 flex-1 overflow-y-auto">
<NotebookDataframeTable
result={dataframeResult}
loading={isRunning || pageLoading || (isRestoringResult && !result?.first_page?.length)}
page={page}
pageSize={pageSize}
hasMore={hasMorePages}
// Wide text columns (long strings, JSON blobs) shouldn't make every
// row tall; clamp to one line here and let the user open a cell.
truncateCells
paginationDisabledReason={
pageLoading
? 'Fetching page…'
: isRunning
? 'Cell is running'
: (operationBlockReason ?? undefined)
}
onNextPage={() => setPage(page + 1)}
onPreviousPage={() => setPage(page - 1)}
onPageSizeChange={setPageSize}
/>
</div>
) : hasStreamOutput ? null : (
<div className="text-xs text-muted font-mono p-2">Run the cell to see execution results.</div>
)}
</div>
<NotebookCellOutputNameFooter
returnVariable={attributes.returnVariable ?? ''}
onChange={(returnVariable) => updateAttributes({ returnVariable })}
/>
</div>
)
}
const Settings = ({
attributes,
updateAttributes,
}: NotebookNodeAttributeProperties<NotebookNodePythonV2Attributes>): JSX.Element => {
const nodeLogic = useMountedLogic(notebookNodeLogic)
const { nodeId, notebookLogic, isEditable } = useValues(nodeLogic)
const dataLogic = notebookCodeCellLogic(nodeId, notebookLogic, attributes, updateAttributes)
const { runNode } = useActions(dataLogic)
const isJupyterMode = !!useNotebookJupyterCommands()
const showLineNumbers = useNotebookJupyterStoreValue((state) => state.lineNumbers)
const jupyterEditorOptions = useMemo(
() => ({
lineNumbers: showLineNumbers ? ('on' as const) : ('off' as const),
lineDecorationsWidth: showLineNumbers ? 10 : 4,
folding: false,
renderLineHighlight: 'none' as const,
overviewRulerLanes: 0,
overviewRulerBorder: false,
hideCursorInOverviewRuler: true,
readOnly: !isEditable,
scrollbar: { vertical: 'hidden' as const, handleMouseWheel: false },
}),
[showLineNumbers, isEditable]
)
// Read the run state imperatively: Monaco binds Cmd+Enter once at editor mount, so a captured
// value would be the one from that first render. The guard keeps the keybinding from firing a
// second run mid-flight — overlapping runs race the poller and can strand the spinner.
const runOnCmdEnter = (): void => {
if (!dataLogic.values.isRunning) {
runNode()
}
}
return (
<div
className="h-full min-h-0"
// The editor owns pointer drags in here. Without this the resize handle drags the
// node around the markdown notebook instead of resizing the editor.
onMouseDown={(event) => event.stopPropagation()}
onDragStart={(event) => event.stopPropagation()}
>
<CodeEditorResizeable
language="python"
value={typeof attributes.code === 'string' ? attributes.code : ''}
onChange={(value) => updateAttributes({ code: value ?? '' })}
onPressCmdEnter={runOnCmdEnter}
minHeight={isJupyterMode ? JUPYTER_EDITOR_MIN_HEIGHT : PYTHON_EDITOR_MIN_HEIGHT}
maxHeight={isJupyterMode ? JUPYTER_EDITOR_MAX_HEIGHT : PYTHON_EDITOR_MAX_HEIGHT}
allowManualResize={!isJupyterMode}
options={isJupyterMode ? jupyterEditorOptions : undefined}
embedded
/>
</div>
)
}
export const NotebookNodePythonV2 = createPostHogWidgetNode<NotebookNodePythonV2Attributes>({
nodeType: NotebookNodeType.PythonV2,
titlePlaceholder: 'Python',
Component,
heightEstimate: 120,
minHeight: 80,
resizeable: true,
startExpanded: true,
attributes: {
code: {
default: '',
},
returnVariable: {
default: 'df',
},
runId: {
default: null,
},
result: {
default: null,
},
runStatus: {
default: null,
},
},
Settings,
settingsPlacement: 'inline',
serializedText: (attrs) => attrs.code,
})