노트북 인터페이스

이 문서는 Jupyter 노트북과 IPython 환경에서 사용할 수 있는 ctx.notebook 인터페이스에 대해 설명합니다.

ctx.notebook은 현재 Contexta 객체에 연결된 NotebookSurface를 반환하는 퍼사드 프로퍼티입니다.

이 프로퍼티는 실행 스냅샷, 실행 비교, 메트릭 추세 같은 Contexta 조사 결과를 HTML로 렌더링하거나 노트북 셀에 인라인으로 표시할 때 사용합니다.

개요

ctx.notebook은 현재 Contexta 인스턴스에 바인딩된 NotebookSurface 객체를 반환합니다.

from contexta import Contexta

ctx = Contexta(...)

# 노트북 셀에 실행 스냅샷을 인라인으로 표시합니다.
ctx.notebook.show_run("run:my-proj.run-01")

이 프로퍼티는 지연 초기화됩니다. 즉, NotebookSurface는 ctx.notebook에 처음 접근할 때 생성되고, 이후에는 같은 객체가 재사용됩니다.

메서드

`show_run`

show_run(run_id, *, display=True) 메서드는 하나의 실행 스냅샷을 HTML로 렌더링하며, display=True가 기본값입니다.

IPython을 사용할 수 있는 환경에서는 IPython.display.display(HTML(...))를 호출해 결과를 노트북 셀에 인라인으로 표시합니다.

반환값은 NotebookFragment이며, 원시 HTML은 .html 속성에서 확인할 수 있습니다.

fragment = ctx.notebook.show_run("run:my-proj.run-01", display=False)
print(fragment.html[:200])

`compare_runs`

compare_runs(left_run_id, right_run_id, *, display=True) 메서드는 두 실행을 나란히 비교해 HTML로 렌더링합니다.

ctx.notebook.compare_runs(
    "run:my-proj.run-01",
    "run:my-proj.run-02",
)

`show_metric_trend`

show_metric_trend(metric_key, *, ...) 메서드는 여러 실행에 걸친 메트릭 추세 차트를 렌더링합니다.

ctx.notebook.show_metric_trend("accuracy", project_name="my-proj")

project_name이나 stage_name을 지정하면 특정 프로젝트 또는 단계 범위로 추세를 좁혀 볼 수 있습니다.

`render`

render(value) 메서드는 Contexta 결과 객체를 HTML 문자열로 렌더링합니다.

이 메서드는 실행 스냅샷, 리포트, 실행 비교 결과처럼 노트북에서 확인할 수 있는 객체에 사용할 수 있습니다.

snapshot = ctx.get_run_snapshot("run:my-proj.run-01")
html = ctx.notebook.render(snapshot)

`to_pandas` / `to_polars`

to_pandas(value) / to_polars(value) 메서드는 Contexta 결과를 pandas 또는 polars DataFrame으로 변환합니다.

# pandas 또는 polars 설치 필요
df = ctx.notebook.to_pandas(ctx.list_runs("my-proj"))

이 메서드는 노트북에서 실행 목록, 비교 결과, 추세 데이터 등을 표 형태로 살펴볼 때 유용합니다.

이 메서드를 사용하는 경우에는 변환 대상에 따라 pandas 또는 polars가 미리 설치되어 있어야 합니다.

IPython 사용 가능 여부

ctx.notebook은 IPython이 없어도 동작합니다.

설치 O : show_* 메서드가 IPython.display를 사용해 결과를 노트북 셀에 인라인으로 표시합니다.
설치 X : show_* 메서드는 NotebookFragment를 반환하지만 화면에 표시하지는 않습니다. 이 경우에도 에러는 발생하지 않습니다.

따라서 같은 코드를 노트북 환경과 일반 Python 실행 환경에서 모두 사용할 수 있습니다.

화면 표시가 필요한 경우에는 IPython 환경에서 display=True로 호출하고, HTML 문자열만 필요하면 display=False로 호출하세요.

`NotebookFragment`

모든 show_* 메서드는 NotebookFragment 데이터클래스를 반환합니다.

from contexta.surfaces.notebook import NotebookFragment

fragment: NotebookFragment = ctx.notebook.show_run(..., display=False)

fragment.html        # 원시 HTML 문자열
fragment.title       # 페이지 또는 섹션 제목
fragment.metadata    # run_ref 등 렌더링 대상과 관련된 메타데이터

NotebookFragment를 통해 노트북 없이도 HTML를 저장하거나, 다른 렌더링 흐름으로 전달하거나, 테스트에서 일부 문자열을 검증할 수 있습니다.

직접 가져오기

NotebookSurface와 관련 헬퍼 함수는 다음 경로에서도 직접 가져올 수 있습니다.

from contexta.adapters.notebook import (
    NotebookSurface,
    NotebookFragment,
    display_run_snapshot,
    display_run_comparison,
    display_metric_trend,
    render_html_fragment,
    to_pandas,
    to_polars,
)

전체 Contexta 인스턴스를 통해 접근하는 일반적인 사용법은 ctx.notebook입니다.

반면 특정 렌더링 함수만 독립적으로 사용해야 하거나, 별도의 표면 객체를 직접 구성해야 한다면 위 경로를 사용할 수 있습니다.

개요​

메서드​

show_run​

compare_runs​

show_metric_trend​

render​

to_pandas / to_polars​

IPython 사용 가능 여부​

NotebookFragment​

직접 가져오기​

관련 문서​

개요

메서드