Jupyter

Source code in src/cocalc_api/hub.py

class Jupyter:

    def __init__(self, parent: "Hub"):
        self._parent = parent

    @api_method("jupyter.kernels")
    def kernels(self, project_id: Optional[str] = None) -> list[dict[str, Any]]:
        """
        Get specifications of available Jupyter kernels.

        Args:
            project_id (Optional[str]): If provided, return kernel specs for this project.
                If not given, a global anonymous project may be used.

        Returns:
            list[dict[str, Any]]: List of kernel specification objects. Each kernel object
                contains information like 'name', 'display_name', 'language', etc.

        Examples:
            Get available kernels for a project:

            >>> import cocalc_api; hub = cocalc_api.Hub(api_key="sk-...")
            >>> kernels = hub.jupyter.kernels(project_id='6e75dbf1-0342-4249-9dce-6b21648656e9')
            >>> # Extract kernel names
            >>> kernel_names = [k['name'] for k in kernels]
            >>> 'python3' in kernel_names
            True
        """
        ...  # pragma: no cover

    @api_method("jupyter.execute", timeout_seconds=True)
    def execute(
        self,
        input: str,
        kernel: str,
        history: Optional[list[str]] = None,
        project_id: Optional[str] = None,
        path: Optional[str] = None,
        timeout: Optional[int] = 90,
    ) -> dict[str, Any]:  # type: ignore[empty-body]
        """
        Execute code using a Jupyter kernel.

        Args:
            input (str): Code to execute.
            kernel (str): Name of kernel to use. Get options using jupyter.kernels().
            history (Optional[list[str]]): Array of previous inputs (they get evaluated every time, but without output being captured).
            project_id (Optional[str]): Project in which to run the code -- if not given, global anonymous project is used, if available.
            path (Optional[str]): File path context for execution.
            timeout (Optional[int]): Timeout in SECONDS for the execute call (defaults to 90 seconds).

        Returns:
            dict[str, Any]: JSON response containing execution results.

        Examples:
            Execute a simple sum using a Jupyter kernel:

            >>> import cocalc_api;  hub = cocalc_api.Hub(api_key="sk-...")
            >>> hub.jupyter.execute(history=['a=100;print(a)'],
                           input='sum(range(a+1))',
                           kernel='python3')
            {'output': [{'data': {'text/plain': '5050'}}], ...}

            Factor a number using the sagemath kernel in a specific project:

            >>> hub.jupyter.execute(history=['a=2025'], input='factor(a)', kernel='sagemath',
            ...     project_id='6e75dbf1-0342-4249-9dce-6b21648656e9')
            {'output': [{'data': {'text/plain': '3^4 * 5^2'}}], ...}
        """
        ...  # pragma: no cover

execute(input, kernel, history=None, project_id=None, path=None, timeout=90)

Execute code using a Jupyter kernel.

Parameters:

Name	Type	Description	Default
input	str	Code to execute.	required
kernel	str	Name of kernel to use. Get options using jupyter.kernels().	required
history	Optional[list[str]]	Array of previous inputs (they get evaluated every time, but without output being captured).	None
project_id	Optional[str]	Project in which to run the code -- if not given, global anonymous project is used, if available.	None
path	Optional[str]	File path context for execution.	None
timeout	Optional[int]	Timeout in SECONDS for the execute call (defaults to 90 seconds).	90

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: JSON response containing execution results.

Examples:

Execute a simple sum using a Jupyter kernel:

>>> import cocalc_api;  hub = cocalc_api.Hub(api_key="sk-...")
>>> hub.jupyter.execute(history=['a=100;print(a)'],
               input='sum(range(a+1))',
               kernel='python3')
{'output': [{'data': {'text/plain': '5050'}}], ...}

Factor a number using the sagemath kernel in a specific project:

>>> hub.jupyter.execute(history=['a=2025'], input='factor(a)', kernel='sagemath',
...     project_id='6e75dbf1-0342-4249-9dce-6b21648656e9')
{'output': [{'data': {'text/plain': '3^4 * 5^2'}}], ...}

Source code in src/cocalc_api/hub.py

@api_method("jupyter.execute", timeout_seconds=True)
def execute(
    self,
    input: str,
    kernel: str,
    history: Optional[list[str]] = None,
    project_id: Optional[str] = None,
    path: Optional[str] = None,
    timeout: Optional[int] = 90,
) -> dict[str, Any]:  # type: ignore[empty-body]
    """
    Execute code using a Jupyter kernel.

    Args:
        input (str): Code to execute.
        kernel (str): Name of kernel to use. Get options using jupyter.kernels().
        history (Optional[list[str]]): Array of previous inputs (they get evaluated every time, but without output being captured).
        project_id (Optional[str]): Project in which to run the code -- if not given, global anonymous project is used, if available.
        path (Optional[str]): File path context for execution.
        timeout (Optional[int]): Timeout in SECONDS for the execute call (defaults to 90 seconds).

    Returns:
        dict[str, Any]: JSON response containing execution results.

    Examples:
        Execute a simple sum using a Jupyter kernel:

        >>> import cocalc_api;  hub = cocalc_api.Hub(api_key="sk-...")
        >>> hub.jupyter.execute(history=['a=100;print(a)'],
                       input='sum(range(a+1))',
                       kernel='python3')
        {'output': [{'data': {'text/plain': '5050'}}], ...}

        Factor a number using the sagemath kernel in a specific project:

        >>> hub.jupyter.execute(history=['a=2025'], input='factor(a)', kernel='sagemath',
        ...     project_id='6e75dbf1-0342-4249-9dce-6b21648656e9')
        {'output': [{'data': {'text/plain': '3^4 * 5^2'}}], ...}
    """
    ...  # pragma: no cover

kernels(project_id=None)

Get specifications of available Jupyter kernels.

Parameters:

Name	Type	Description	Default
project_id	Optional[str]	If provided, return kernel specs for this project. If not given, a global anonymous project may be used.	None

Returns:

Type	Description
list[dict[str, Any]]	list[dict[str, Any]]: List of kernel specification objects. Each kernel object contains information like 'name', 'display_name', 'language', etc.

Examples:

Get available kernels for a project:

>>> import cocalc_api; hub = cocalc_api.Hub(api_key="sk-...")
>>> kernels = hub.jupyter.kernels(project_id='6e75dbf1-0342-4249-9dce-6b21648656e9')
>>> # Extract kernel names
>>> kernel_names = [k['name'] for k in kernels]
>>> 'python3' in kernel_names
True

Source code in src/cocalc_api/hub.py

@api_method("jupyter.kernels")
def kernels(self, project_id: Optional[str] = None) -> list[dict[str, Any]]:
    """
    Get specifications of available Jupyter kernels.

    Args:
        project_id (Optional[str]): If provided, return kernel specs for this project.
            If not given, a global anonymous project may be used.

    Returns:
        list[dict[str, Any]]: List of kernel specification objects. Each kernel object
            contains information like 'name', 'display_name', 'language', etc.

    Examples:
        Get available kernels for a project:

        >>> import cocalc_api; hub = cocalc_api.Hub(api_key="sk-...")
        >>> kernels = hub.jupyter.kernels(project_id='6e75dbf1-0342-4249-9dce-6b21648656e9')
        >>> # Extract kernel names
        >>> kernel_names = [k['name'] for k in kernels]
        >>> 'python3' in kernel_names
        True
    """
    ...  # pragma: no cover