Skip to content

: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.

15.7 KB
Raw Blame
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,
})