tessl/pypi-jupyter-core

Core foundational package providing base application classes, path utilities, and configuration management for the Jupyter ecosystem.

—

Pending

Overview

Eval results

Files

Application Framework

Name: tessl/pypi-jupyter-core
Author: tessl

Base application classes and infrastructure for building Jupyter applications. Provides standardized configuration management, logging, path handling, and lifecycle management that ensures consistency across the Jupyter ecosystem.

Capabilities

Base Application Class

The foundational application class that all Jupyter applications should inherit from. Provides configuration loading, directory management, and standardized initialization patterns.

class JupyterApp(Application):
    """Base class for Jupyter applications"""
    
    # Class attributes
    name: str  # Application name (override in subclasses)
    description: str  # Application description  
    aliases: dict[str, Any]  # Command-line aliases
    flags: dict[str, Any]  # Command-line flags
    
    # Directory properties
    config_dir: str  # Jupyter config directory
    data_dir: str  # Jupyter data directory
    runtime_dir: str  # Jupyter runtime directory
    jupyter_path: list[str]  # Jupyter data search paths
    
    # Configuration properties
    config_file_paths: list[str]  # Config file search paths
    config_file_name: str  # Config file name pattern
    config_file: str  # Specific config file path
    generate_config: bool  # Whether to generate default config
    answer_yes: bool  # Auto-answer yes to prompts
    
    def initialize(self, argv=None) -> None:
        """Initialize the application."""
    
    def start(self) -> None:
        """Start the application."""
    
    def load_config_file(self, suppress_errors: bool = True) -> None:
        """Load configuration files."""
    
    def write_default_config(self) -> None:
        """Write default config to file."""
    
    def migrate_config(self) -> None:
        """Migrate config/data from IPython 3."""
    
    @classmethod
    def launch_instance(cls, argv=None, **kwargs) -> None:
        """Launch an instance of a Jupyter Application."""
    
    @property
    def config_file_paths(self) -> list[str]:
        """Return the search path for config files."""

Usage Example:

from jupyter_core.application import JupyterApp

class MyApp(JupyterApp):
    name = "my-app"
    description = "My custom Jupyter application"
    
    def start(self):
        self.log.info("Application starting")
        print(f"Config dir: {self.config_dir}")
        print(f"Data dir: {self.data_dir}")
        # Application logic here

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

Async Application Class

An async-aware version of JupyterApp for applications that need to run on asyncio event loops, such as web servers or real-time applications.

class JupyterAsyncApp(JupyterApp):
    """A Jupyter application that runs on an asyncio loop."""
    
    # Class attributes
    name: str  # Application name (override in subclasses)
    description: str  # Application description
    _prefer_selector_loop: bool  # Prefer selector loop for tornado apps
    
    async def initialize_async(self, argv=None) -> None:
        """Initialize the application asynchronously."""
    
    async def start_async(self) -> None:
        """Run the application in an event loop."""
    
    @classmethod
    def launch_instance(cls, argv=None, **kwargs) -> None:
        """Launch an instance of an async Jupyter Application."""

Usage Example:

from jupyter_core.application import JupyterAsyncApp
import asyncio

class MyAsyncApp(JupyterAsyncApp):
    name = "my-async-app"
    description = "My async Jupyter application"
    
    async def initialize_async(self, argv=None):
        await super().initialize_async(argv)
        self.log.info("Async initialization complete")
    
    async def start_async(self):
        self.log.info("Starting async application")
        # Async application logic here
        await asyncio.sleep(1)  # Example async operation

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

Exception Classes

Exception types used by the application framework for controlling application flow and handling errors.

class NoStart(Exception):
    """Exception to raise when an application shouldn't start"""

This exception is used internally to signal that an application should exit without error, such as when generating config files or displaying help information.

Configuration Aliases and Flags

Pre-defined command-line aliases and flags that applications can inherit for consistent CLI behavior across the Jupyter ecosystem.

# Base aliases inherited from traitlets + Jupyter-specific aliases
base_aliases: dict[str, Any] = {
    "log-level": "Application.log_level",
    "config": "JupyterApp.config_file",
    # ... additional aliases
}

# Base flags inherited from traitlets + Jupyter-specific flags
base_flags: dict[str, Any] = {
    "debug": (
        {"Application": {"log_level": logging.DEBUG}},
        "set log level to logging.DEBUG (maximize logging output)"
    ),
    "generate-config": (
        {"JupyterApp": {"generate_config": True}}, 
        "generate default config file"
    ),
    "y": (
        {"JupyterApp": {"answer_yes": True}},
        "Answer yes to any questions instead of prompting."
    ),
    # ... additional flags
}

These provide standard command-line options like --debug, --generate-config, and --config that users expect across all Jupyter applications.

Configuration System Integration

The application framework integrates deeply with the traitlets configuration system to provide:

Hierarchical config loading: System → Environment → User → CLI overrides
Multiple config formats: Python (.py) and JSON (.json) config files
Config file discovery: Automatic searching in standard locations
CLI integration: Automatic CLI argument parsing and validation
Type safety: Automatic type conversion and validation
Documentation: Self-documenting configuration with help text

Directory Management

Applications automatically get access to standard Jupyter directories:

config_dir: User configuration directory (~/.jupyter or platform equivalent)
data_dir: User data directory (~/.local/share/jupyter or platform equivalent)
runtime_dir: Runtime directory for temporary files (typically {data_dir}/runtime)
jupyter_path: Search path for data files (user → environment → system)

All directories are created automatically with appropriate permissions when accessed.