Skip to main content

easyfabric.fabric.notebook_runner

Notebook Runner for Microsoft FabricAn all-in-one data and analytics platform from Microsoft. Think of it as a "digital warehouse" for all your company's information..

Provides functions to programmatically start, monitor, and retrieve results from Microsoft Fabric notebooks via the REST API.

NotebookRunResult Objects​

@dataclass
class NotebookRunResult()

Result of a completed notebook run.

get_notebook_id​

def get_notebook_id(workspace_id: str, notebook_name: str,
                    headers: dict) -> str

Look up a notebook's ID by its display name.

Arguments:

  • workspace_id - The Fabric workspace ID.
  • notebook_name - The display name of the notebook.
  • headers - HTTP headers (including Authorization).

Returns:

The notebook item ID.

Raises:

  • ValueError - If no notebook with the given name is found.

trigger_notebook​

def trigger_notebook(workspace_id: str,
                     notebook_id: str,
                     headers: dict,
                     parameters: dict | None = None) -> str

Trigger a notebook run via the Fabric REST API.

Arguments:

  • workspace_id - The Fabric workspace ID.
  • notebook_id - The notebook item ID.
  • headers - HTTP headers (including Authorization).
  • parameters - Optional dict of parameters to pass to the notebook. Each value is converted to a string.

Returns:

The polling URL from the Location response header.

Raises:

  • RuntimeError - If the API does not return HTTP 202.

poll_notebook_status​

def poll_notebook_status(
        poll_url: str,
        headers: dict,
        poll_interval: int = 10,
        timeout_seconds: int = 1800,
        token_provider=None,
        token_refresh_seconds: int = 2400) -> NotebookRunResult

Poll a notebook run until it reaches a terminal state.

Arguments:

  • poll_url - The polling URL returned by trigger_notebook.
  • headers - HTTP headers (including Authorization).
  • poll_interval - Seconds to wait between polls.
  • timeout_seconds - Maximum total seconds to wait before raising.
  • token_provider - Optional zero-arg callable returning a fresh bearer token. When given, the loop re-authenticates proactively every token_refresh_seconds and immediately on a 401/403, so polls that outlive the original token (runs longer than ~1h) keep working.
  • token_refresh_seconds - Proactive token refresh interval. Kept below the ~60-75 min Fabric token lifetime.

Returns:

A NotebookRunResult with the final status and timing info.

Raises:

  • TimeoutError - If the notebook does not finish within timeout_seconds.

run_notebook​

def run_notebook(
    workspace_id: str = None,
    notebook_id: str = None,
    notebook_name: str = None,
    parameters: dict | None = None,
    config_manager=None,
    access_token: str = None,
    poll_interval: int = 10,
    timeout_seconds: int = 1800,
    raise_on_failure: bool = False,
    success_states: tuple[str, ...] = ("Completed", "Succeeded")
) -> NotebookRunResult

Run a Fabric notebook end-to-end: authenticate, trigger, poll, return result.

This is the main high-level entry point that orchestrates the full notebook execution lifecycle.

Arguments:

  • workspace_id - The Fabric workspace ID.
  • notebook_id - The notebook item ID. If omitted, notebook_name is used to look it up.
  • notebook_name - Display name of the notebook (used when notebook_id is not provided).
  • parameters - Optional dict of parameters to pass to the notebook.
  • config_manager - Optional ConfigManager with tenant/client/secret info.
  • access_token - Optional pre-existing bearer token.
  • poll_interval - Seconds between status polls.
  • timeout_seconds - Maximum seconds to wait for completion.
  • raise_on_failure - Raise RuntimeError when the final status is not in success_states. Off by default so callers can inspect the result.
  • success_states - Statuses treated as success when raise_on_failure is set.

Returns:

A NotebookRunResult with the final status, log, and timing info.

Raises:

  • ValueError - If neither notebook_id nor notebook_name is provided.
  • RuntimeError - If raise_on_failure is set and the run did not succeed.