Jupyter Core

A foundational Python package that provides core functionality for the Jupyter ecosystem. It contains base application classes, configuration management systems, path utilities, and command-line tools that serve as the foundation for notebooks, kernels, and other Jupyter components. Designed for maximum reusability across the Jupyter ecosystem with built-in cross-platform compatibility.

Package Information

• Package Name: jupyter_core
• Language: Python
• Installation: pip install jupyter_core
• Minimum Python Version: 3.8+

Core Imports

import jupyter_core

For version information:

from jupyter_core import __version__, version_info

For application development:

from jupyter_core.application import JupyterApp, JupyterAsyncApp

For path utilities:

from jupyter_core.paths import (
    jupyter_config_dir, jupyter_data_dir, jupyter_runtime_dir,
    jupyter_path, jupyter_config_path
)

Basic Usage

from jupyter_core.paths import jupyter_config_dir, jupyter_data_dir
from jupyter_core.application import JupyterApp

# Get standard Jupyter directories
config_dir = jupyter_config_dir()
data_dir = jupyter_data_dir()
print(f"Config directory: {config_dir}")
print(f"Data directory: {data_dir}")

# Create a simple Jupyter application
class MyJupyterApp(JupyterApp):
    name = "my-jupyter-app"
    description = "My custom Jupyter application"
    
    def start(self):
        self.log.info("Starting my Jupyter application")
        print(f"Using config directory: {self.config_dir}")
        print(f"Using data directory: {self.data_dir}")

# Launch the application
if __name__ == "__main__":
    MyJupyterApp.launch_instance()

Architecture

Jupyter Core follows a layered architecture designed for extensibility:

• Application Layer: Base application classes (JupyterApp, JupyterAsyncApp) that provide common functionality for Jupyter applications including configuration loading, logging, and directory management
• Path Management Layer: Cross-platform utilities for discovering and managing Jupyter directories with support for user, environment, and system-wide installations
• Configuration Layer: Integration with traitlets for declarative configuration with support for config files, command-line arguments, and environment variables
• Utility Layer: Core utilities for directory creation, async event loop management, deprecation warnings, and platform-specific operations
• Command-Line Layer: Tools for subcommand discovery and execution, migration from IPython, and system troubleshooting

This design enables consistent behavior across all Jupyter components while supporting the diverse needs of notebooks, kernels, extensions, and custom applications.

Capabilities

Application Framework

Base application classes and infrastructure for building Jupyter applications with built-in configuration management, logging, path handling, and lifecycle management.

class JupyterApp:
    def __init__(self): ...
    def initialize(self, argv=None): ...
    def start(self): ...
    @classmethod
    def launch_instance(cls, argv=None, **kwargs): ...

class JupyterAsyncApp(JupyterApp):
    async def initialize_async(self, argv=None): ...
    async def start_async(self): ...

Application Framework

Path Management

Cross-platform directory discovery and path utilities for managing Jupyter configuration, data, and runtime directories with support for user-level, environment-level, and system-wide installations.

def jupyter_config_dir() -> str: ...
def jupyter_data_dir() -> str: ...
def jupyter_runtime_dir() -> str: ...
def jupyter_path(*subdirs: str) -> list[str]: ...
def jupyter_config_path() -> list[str]: ...

Path Management

Command-Line Tools

Command-line utilities for Jupyter ecosystem management including the main jupyter command dispatcher, migration tools, and troubleshooting utilities.

def main() -> None: ...
def list_subcommands() -> list[str]: ...
def migrate() -> bool: ...
def get_data() -> dict[str, Any]: ...

Command-Line Tools

Utility Functions

Core utility functions for directory management, deprecation warnings, async support, and platform-specific operations used throughout the Jupyter ecosystem.

def ensure_dir_exists(path: str | Path, mode: int = 0o777) -> None: ...
def deprecation(message: str, internal: str | list[str] = "jupyter_core/") -> None: ...
def run_sync(coro: Callable[..., Awaitable[T]]) -> Callable[..., T]: ...
def ensure_event_loop(prefer_selector_loop: bool = False) -> AbstractEventLoop: ...

Utility Functions

Types

from typing import Any, Awaitable, Callable, TypeVar
from pathlib import Path
from traitlets.config.application import Application

# Version information
__version__: str
version_info: tuple[int, int, int, ...]

# Exception types  
class NoStart(Exception): ...

# Type variables
T = TypeVar("T")