Core

The core package (jumper_extension.core) defines the domain model, configuration, and parsing logic that underpin the JUmPER IPython extension. For the public Python API of PerfmonitorService, see the Python API section; the content below focuses on supporting modules and helper functions and is generated directly from the code.

State

The state module contains dataclasses describing runtime settings for monitoring, automatic reports, and exported or loaded variables.

Configuration and state models for the JUmPER core.

This module defines dataclasses that hold runtime configuration for monitoring, performance reports, and names of exported or loaded variables.

ExportVars dataclass

Names of variables used when exporting data frames.

Attributes:

Name	Type	Description
perfdata	str	Variable name for exported performance data.
cell_history	str	Variable name for exported cell history.

Source code in jumper_extension/core/state.py

@dataclass
class ExportVars:
    """Names of variables used when exporting data frames.

    Attributes:
        perfdata: Variable name for exported performance data.
        cell_history: Variable name for exported cell history.
    """

    perfdata: str = "perfdata_df"
    cell_history: str = "cell_history_df"

LoadedVars dataclass

Names of variables used when loading data frames.

Attributes:

Name	Type	Description
perfdata	str	Variable name for loaded performance data.
cell_history	str	Variable name for loaded cell history.

Source code in jumper_extension/core/state.py

@dataclass
class LoadedVars:
    """Names of variables used when loading data frames.

    Attributes:
        perfdata: Variable name for loaded performance data.
        cell_history: Variable name for loaded cell history.
    """

    perfdata: str = "loaded_perfdata_df"
    cell_history: str = "loaded_cell_history_df"

PerfomanceReports dataclass

Configuration for automatic per-cell performance reports.

Attributes:

Name	Type	Description
enabled	bool	Whether per-cell reports are enabled.
level	str	Monitoring level used when generating reports.
text	bool	If True, use text reports instead of HTML.

Source code in jumper_extension/core/state.py

@dataclass
class PerfomanceReports:
    """Configuration for automatic per-cell performance reports.

    Attributes:
        enabled: Whether per-cell reports are enabled.
        level: Monitoring level used when generating reports.
        text: If True, use text reports instead of HTML.
    """

    enabled: bool = False
    level: str = "process"
    text: bool = False

PerformanceMonitoring dataclass

Configuration for the performance monitoring loop.

Attributes:

Name	Type	Description
default_interval	float	Default sampling interval in seconds.
user_interval	Optional[float]	User-provided interval overriding the default.
running	bool	Whether monitoring is currently running.

Source code in jumper_extension/core/state.py

@dataclass
class PerformanceMonitoring:
    """Configuration for the performance monitoring loop.

    Attributes:
        default_interval: Default sampling interval in seconds.
        user_interval: User-provided interval overriding the default.
        running: Whether monitoring is currently running.
    """

    default_interval: float = 1.0
    user_interval: Optional[float] = None
    running: bool = False

Settings dataclass

Top-level configuration container for the extension.

Groups performance reports, monitoring configuration, and variable names used when exporting or loading data.

Attributes:

Name	Type	Description
perfreports	PerfomanceReports	Settings for per-cell performance reports.
monitoring	PerformanceMonitoring	Settings for the monitoring loop.
export_vars	ExportVars	Names for exported data variables.
loaded_vars	LoadedVars	Names for loaded data variables.
visualizer_backend	str	Default backend used for plotting.

Source code in jumper_extension/core/state.py

@dataclass
class Settings:
    """Top-level configuration container for the extension.

    Groups performance reports, monitoring configuration, and variable
    names used when exporting or loading data.

    Attributes:
        perfreports: Settings for per-cell performance reports.
        monitoring: Settings for the monitoring loop.
        export_vars: Names for exported data variables.
        loaded_vars: Names for loaded data variables.
        visualizer_backend: Default backend used for plotting.
    """

    perfreports: PerfomanceReports = field(default_factory=PerfomanceReports)
    monitoring: PerformanceMonitoring = field(default_factory=PerformanceMonitoring)
    export_vars: ExportVars = field(default_factory=ExportVars)
    loaded_vars: LoadedVars = field(default_factory=LoadedVars)
    visualizer_backend: str = "matplotlib"

    def snapshot(self) -> "Settings":
        """Return a deep copy of the current settings.

        Returns:
            Settings: Independent copy of the current configuration.
        """
        return copy.deepcopy(self)

snapshot()

Return a deep copy of the current settings.

Returns:

Name	Type	Description
Settings	Settings	Independent copy of the current configuration.

Source code in jumper_extension/core/state.py

def snapshot(self) -> "Settings":
    """Return a deep copy of the current settings.

    Returns:
        Settings: Independent copy of the current configuration.
    """
    return copy.deepcopy(self)

Parsers

Module containing parser utilities for the JUmPER extension.

ArgParsers dataclass

Configuration for command-line argument parsers.

Source code in jumper_extension/core/parsers.py

@dataclass
class ArgParsers:
    """Configuration for command-line argument parsers."""
    perfmonitor_start: argparse.ArgumentParser
    perfreport: argparse.ArgumentParser
    auto_perfreports: argparse.ArgumentParser
    perfmonitor_plot: argparse.ArgumentParser
    export_perfdata: argparse.ArgumentParser
    export_cell_history: argparse.ArgumentParser
    import_perfdata: argparse.ArgumentParser
    import_cell_history: argparse.ArgumentParser
    export_session: argparse.ArgumentParser
    import_session: argparse.ArgumentParser

build_export_session_parser()

Build parser for exporting a full session package.

Usage examples in magics

%export_session # uses default directory name %export_session my_dir # export into directory %export_session my_session.zip # export and zip (auto-detected by .zip extension)

Source code in jumper_extension/core/parsers.py

def build_export_session_parser() -> argparse.ArgumentParser:
    """Build parser for exporting a full session package.

    Usage examples in magics:
      %export_session                        # uses default directory name
      %export_session my_dir                 # export into directory
      %export_session my_session.zip         # export and zip (auto-detected by .zip extension)
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "path",
        nargs="?",
        default=None,
        help="Target directory or .zip path (defaults to jumper-session-<timestamp>)",
    )
    return parser

build_import_session_parser()

Build parser for importing a full session package from directory or zip.

Source code in jumper_extension/core/parsers.py

def build_import_session_parser() -> argparse.ArgumentParser:
    """Build parser for importing a full session package from directory or zip."""
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "path",
        type=str,
        help="Path to exported session directory or .zip archive",
    )
    return parser

build_perfmonitor_start_parser()

Build an ArgumentParser for the perfmonitor_start command.

Source code in jumper_extension/core/parsers.py

def build_perfmonitor_start_parser() -> argparse.ArgumentParser:
    """Build an ArgumentParser for the perfmonitor_start command."""
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "interval",
        nargs="?",
        type=float,
        default=None,
        help="Sampling interval in seconds (default: 1.0)",
    )
    parser.add_argument(
        "--monitor",
        type=str,
        default="default",
        choices=["default", "native_c", "subprocess_python", "thread", "slurm_multinode"],
        help="Monitor backend to use (default: subprocess-based Python collector, "
             "'native_c' for native C collector, "
             "'subprocess_python' for explicit Python subprocess collector, "
             "'thread' for in-process threaded monitor)",
    )
    parser.add_argument(
        "--check-sanity",
        dest="check_sanity",
        action="store_true",
        help="Run a short sanity check of the selected monitor before "
             "starting real monitoring. Tailored for thread, "
             "subprocess_python and native_c monitors; other monitors "
             "are expected to fail this check.",
    )
    return parser

build_perfreport_parser()

Build an ArgumentParser instance for JUmPER commands.

Source code in jumper_extension/core/parsers.py

def build_perfreport_parser() -> argparse.ArgumentParser:
    """Build an ArgumentParser instance for JUmPER commands."""
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument(
        "--cell",
        type=str,
        help="Cell index or range (e.g., 5, 2:8, :5)"
    )
    parser.add_argument(
        "--level",
        default="process",
        choices=get_available_levels(),
        help="Performance level",
    )
    parser.add_argument(
        "--text",
        action="store_true",
        help="Show report in text format"
    )
    return parser

parse_arguments(parser, line)

Parse common command line arguments for JUmPER commands.

Parameters:

Name	Type	Description	Default
line	str	The command line string to parse	required
parser	ArgumentParser	Optional existing ArgumentParser instance	required

Returns:

Type	Description
Optional[Namespace]	Parsed arguments or None if parsing failed

Source code in jumper_extension/core/parsers.py

def parse_arguments(parser: argparse.ArgumentParser, line: str) -> Optional[argparse.Namespace]:
    """Parse common command line arguments for JUmPER commands.

    Args:
        line: The command line string to parse
        parser: Optional existing ArgumentParser instance

    Returns:
        Parsed arguments or None if parsing failed
    """
    try:
        args = (
            parser.parse_args(shlex.split(line))
            if line
            else parser.parse_args([])
        )
    except (SystemExit, Exception):
        args = None
    return args

parse_cell_range(cell_str, cell_history_length)

Parse a cell range string into start and end indices.

Parameters:

Name	Type	Description	Default
cell_str	str	String representing cell range (e.g., "1:3", "5", ":10")	required
cell_history_length	int	Length of cell history	required

Returns:

Type	Description
Optional[Tuple[int, int]]	Tuple of (start_idx, end_idx) or None if invalid

Source code in jumper_extension/core/parsers.py

def parse_cell_range(cell_str: str, cell_history_length: int) -> Optional[Tuple[int, int]]:
    """Parse a cell range string into start and end indices.

    Args:
        cell_str: String representing cell range (e.g., "1:3", "5", ":10")
        cell_history_length: Length of cell history

    Returns:
        Tuple of (start_idx, end_idx) or None if invalid
    """
    if not cell_str:
        return None

    try:
        max_idx = cell_history_length - 1
        if ":" in cell_str:
            start_str, end_str = cell_str.split(":", 1)
            start_idx = 0 if not start_str else int(start_str)
            end_idx = max_idx if not end_str else int(end_str)
        else:
            start_idx = end_idx = int(cell_str)

        if 0 <= start_idx <= end_idx <= max_idx:
            return start_idx, end_idx
    except (ValueError, IndexError, AttributeError):
        pass

    return None

Messages

The messages module defines error and info codes together with their human-readable message templates.

Message codes and templates used by the JUmPER extension.

This module defines enums for error and info codes, maps them to human-readable message templates, and exposes helpers for working with those messages.

ExtensionErrorCode

Bases: Enum

Error codes emitted by the extension.

Source code in jumper_extension/core/messages.py

class ExtensionErrorCode(Enum):
    """Error codes emitted by the extension."""

    PYNVML_NOT_AVAILABLE = auto()
    NVIDIA_DRIVERS_NOT_AVAILABLE = auto()
    ADLX_NOT_AVAILABLE = auto()
    AMD_DRIVERS_NOT_AVAILABLE = auto()
    NO_PERFORMANCE_DATA = auto()
    INVALID_CELL_RANGE = auto()
    INVALID_INTERVAL_VALUE = auto()
    INVALID_METRIC_SUBSET = auto()
    NO_ACTIVE_MONITOR = auto()
    MONITOR_ALREADY_RUNNING = auto()
    UNSUPPORTED_FORMAT = auto()
    INVALID_LEVEL = auto()
    DEFINE_LEVEL = auto()
    NO_CELL_HISTORY = auto()

ExtensionInfoCode

Bases: Enum

Informational codes emitted by the extension.

Source code in jumper_extension/core/messages.py

class ExtensionInfoCode(Enum):
    """Informational codes emitted by the extension."""

    IMPRECISE_INTERVAL = auto()
    MISSED_MEASUREMENTS = auto()
    PERFORMANCE_REPORTS_DISABLED = auto()
    EXTENSION_LOADED = auto()
    PERFORMANCE_REPORTS_ENABLED = auto()
    MONITOR_STARTED = auto()
    MONITOR_STOPPED = auto()
    EXPORT_SUCCESS = auto()
    PERFORMANCE_DATA_AVAILABLE = auto()
    HTML_REPORTS_NOT_AVAILABLE = auto()
    PLOTS_NOT_AVAILABLE = auto()
    SESSION_IMPORTED = auto()
    IMPORTED_SESSION_PLOT = auto()
    IMPORTED_SESSION_RESOURCES = auto()

get_jumper_process_error_hint()

Return a hint pointing to the error log file.

Returns:

Name	Type	Description
str	str	Human-readable hint with the path to the error log file.

Source code in jumper_extension/core/messages.py

def get_jumper_process_error_hint() -> str:
    """Return a hint pointing to the error log file.

    Returns:
        str: Human-readable hint with the path to the error log file.
    """
    jumper_process_error_hint = (
        "\nHint: full error info saved to log file: "
        f"{LOGGING['handlers']['error_file']['filename']}"
    )
    return jumper_process_error_hint

Service helpers

The service itself is documented in the public API; this section exposes the helper functions that construct it.

build_perfmonitor_service(plots_disabled=False, plots_disabled_reason='Plotting not available.', display_disabled=False, display_disabled_reason='Display not available.', visualizer_backend='matplotlib')

Build a new :class:PerfmonitorService instance.

This factory configures the default monitor, visualizer, reporter, cell history, and script writer for use in Python code.

Parameters:

Name	Type	Description	Default
plots_disabled	bool	If True, disable plotting in the visualizer.	False
plots_disabled_reason	str	Human-readable reason shown when plots are disabled.	'Plotting not available.'
display_disabled	bool	If True, disable rich display for reports.	False
display_disabled_reason	str	Human-readable reason shown when rich display is disabled.	'Display not available.'
visualizer_backend	str	Visualizer backend to use. Supported values: "matplotlib" (default) and "plotly".	'matplotlib'

Returns:

Name	Type	Description
PerfmonitorService	PerfmonitorService	A fully initialized service instance.

Examples:

>>> from jumper_extension.core.service import build_perfmonitor_service
>>> service = build_perfmonitor_service()

Source code in jumper_extension/core/service.py

def build_perfmonitor_service(
        plots_disabled: bool = False,
        plots_disabled_reason: str = "Plotting not available.",
        display_disabled: bool = False,
        display_disabled_reason: str = "Display not available.",
        visualizer_backend: str = "matplotlib",
) -> PerfmonitorService:
    """Build a new :class:`PerfmonitorService` instance.

    This factory configures the default monitor, visualizer, reporter,
    cell history, and script writer for use in Python code.

    Args:
        plots_disabled: If ``True``, disable plotting in the visualizer.
        plots_disabled_reason: Human-readable reason shown when plots
            are disabled.
        display_disabled: If ``True``, disable rich display for reports.
        display_disabled_reason: Human-readable reason shown when rich
            display is disabled.
        visualizer_backend: Visualizer backend to use. Supported values:
            ``"matplotlib"`` (default) and ``"plotly"``.

    Returns:
        PerfmonitorService: A fully initialized service instance.

    Examples:
        >>> from jumper_extension.core.service import build_perfmonitor_service
        >>> service = build_perfmonitor_service()
    """
    settings = Settings()
    settings.visualizer_backend = (
        visualizer_backend.strip().lower()
        if visualizer_backend
        else "matplotlib"
    )
    monitor = PerformanceMonitor()
    cell_history = CellHistory()
    visualizer = build_performance_visualizer(
        cell_history,
        plots_disabled=plots_disabled,
        plots_disabled_reason=plots_disabled_reason,
        backend=visualizer_backend,
    )
    reporter = build_performance_reporter(
        cell_history,
        display_disabled=display_disabled,
        display_disabled_reason=display_disabled_reason,
    )
    script_writer = NotebookScriptWriter(cell_history)

    return PerfmonitorService(
        settings=settings,
        monitor=monitor,
        visualizer=visualizer,
        reporter=reporter,
        cell_history=cell_history,
        script_writer=script_writer,
    )

build_perfmonitor_magic_adapter(plots_disabled=False, plots_disabled_reason='Plotting not available.', display_disabled=False, display_disabled_reason='Display not available.', visualizer_backend='matplotlib')

Build a new :class:PerfmonitorMagicAdapter instance.

This factory constructs a :class:PerfmonitorService and wraps it with a string-based adapter suitable for IPython magics or other command-style interfaces.

Parameters:

Name	Type	Description	Default
plots_disabled	bool	If True, disable plotting in the visualizer.	False
plots_disabled_reason	str	Human-readable reason shown when plots are disabled.	'Plotting not available.'
display_disabled	bool	If True, disable rich display for reports.	False
display_disabled_reason	str	Human-readable reason shown when rich display is disabled.	'Display not available.'
visualizer_backend	str	Visualizer backend to use. Supported values: "matplotlib" (default) and "plotly".	'matplotlib'

Returns:

Name	Type	Description
PerfmonitorMagicAdapter	PerfmonitorMagicAdapter	Adapter instance wrapping the service.

Examples:

>>> from jumper_extension.core.service import (
...     build_perfmonitor_magic_adapter,
... )
>>> adapter = build_perfmonitor_magic_adapter()

Source code in jumper_extension/core/service.py

def build_perfmonitor_magic_adapter(
        plots_disabled: bool = False,
        plots_disabled_reason: str = "Plotting not available.",
        display_disabled: bool = False,
        display_disabled_reason: str = "Display not available.",
        visualizer_backend: str = "matplotlib",
) -> PerfmonitorMagicAdapter:
    """Build a new :class:`PerfmonitorMagicAdapter` instance.

    This factory constructs a :class:`PerfmonitorService` and wraps it
    with a string-based adapter suitable for IPython magics or other
    command-style interfaces.

    Args:
        plots_disabled: If ``True``, disable plotting in the visualizer.
        plots_disabled_reason: Human-readable reason shown when plots
            are disabled.
        display_disabled: If ``True``, disable rich display for reports.
        display_disabled_reason: Human-readable reason shown when rich
            display is disabled.
        visualizer_backend: Visualizer backend to use. Supported values:
            ``"matplotlib"`` (default) and ``"plotly"``.

    Returns:
        PerfmonitorMagicAdapter: Adapter instance wrapping the service.

    Examples:
        >>> from jumper_extension.core.service import (
        ...     build_perfmonitor_magic_adapter,
        ... )
        >>> adapter = build_perfmonitor_magic_adapter()
    """
    service = build_perfmonitor_service(
        plots_disabled=plots_disabled,
        plots_disabled_reason=plots_disabled_reason,
        display_disabled=display_disabled,
        display_disabled_reason=display_disabled_reason,
        visualizer_backend=visualizer_backend,
    )

    parsers = ArgParsers(
        perfmonitor_start=build_perfmonitor_start_parser(),
        perfreport=build_perfreport_parser(),
        auto_perfreports=build_auto_perfreports_parser(),
        perfmonitor_plot=build_perfmonitor_plot_parser(),
        export_perfdata=build_export_perfdata_parser(),
        export_cell_history=build_export_cell_history_parser(),
        import_perfdata=build_import_perfdata_parser(),
        import_cell_history=build_import_cell_history_parser(),
        export_session=build_export_session_parser(),
        import_session=build_import_session_parser(),
    )

    return PerfmonitorMagicAdapter(
        service=service,
        parsers=parsers,
    )