Command-Line Tools

def main() -> None:
    """The command entry point for the 'jupyter' command.
    
    Handles subcommand dispatching, path information display,
    version information, and help functionality.
    """

def jupyter_parser() -> JupyterParser:
    """Create a jupyter argument parser.
    
    Returns:
        JupyterParser: Configured argument parser for jupyter command
    """

def list_subcommands() -> list[str]:
    """List all jupyter subcommands.
    
    Searches PATH for `jupyter-name` executables and returns 
    subcommand names without the `jupyter-` prefix.
    
    Returns:
        list[str]: Available subcommand names
    """

from jupyter_core.command import list_subcommands, main

# List available subcommands
subcommands = list_subcommands()
print("Available subcommands:", subcommands)

# The main() function is typically called from command line:
# $ jupyter --version
# $ jupyter --paths
# $ jupyter notebook

class JupyterParser(argparse.ArgumentParser):
    """A Jupyter argument parser with auto-completion support."""
    
    @property
    def epilog(self) -> str:
        """Add subcommands to epilog on request.
        
        Avoids searching PATH for subcommands unless help output is requested.
        """
    
    def argcomplete(self) -> None:
        """Trigger auto-completion, if enabled.
        
        Uses argcomplete library if available for bash/zsh completion.
        """

def migrate() -> bool:
    """Migrate IPython configuration to Jupyter.
    
    Copies (doesn't move) IPython configuration files, kernels,
    extensions, and other data to appropriate Jupyter locations.
    
    Returns:
        bool: True if any files were migrated
    """

def migrate_dir(src: str, dst: str) -> bool:
    """Migrate a directory from src to dst.
    
    Args:
        src: Source directory path
        dst: Destination directory path
        
    Returns:
        bool: True if directory was migrated
    """

def migrate_file(src: str | Path, dst: str | Path, substitutions=None) -> bool:
    """Migrate a single file from src to dst.
    
    Args:
        src: Source file path
        dst: Destination file path  
        substitutions: Optional dict of {regex: replacement} for text substitution
        
    Returns:
        bool: True if file was migrated
    """

def migrate_one(src: str, dst: str) -> bool:
    """Migrate one item from src to dst.
    
    Generic migration dispatcher that handles both files and directories.
    
    Args:
        src: Source path (file or directory)
        dst: Destination path
        
    Returns:
        bool: True if item was migrated
    """

def migrate_static_custom(src: str, dst: str) -> bool:
    """Migrate non-empty custom.js,css from src to dst.
    
    Handles migration of custom CSS and JavaScript files from
    IPython profile directories to Jupyter custom directories.
    
    Args:
        src: Source directory path
        dst: Destination directory path
        
    Returns:
        bool: True if custom files were migrated
    """

def migrate_config(name: str, env: Any) -> list[Any]:
    """Migrate a config file with text substitutions.
    
    Applies regex substitutions to update IPython class names
    and configuration patterns to Jupyter equivalents.
    
    Args:
        name: Configuration file name
        env: Configuration environment/context
        
    Returns:
        list[Any]: List of migrated configuration objects
    """

def get_ipython_dir() -> str:
    """Return the IPython directory location.
    
    Checks IPYTHONDIR environment variable, defaults to ~/.ipython.
    
    Returns:
        str: Path to IPython directory
    """

from jupyter_core.migrate import migrate, get_ipython_dir

# Check if IPython directory exists
ipython_dir = get_ipython_dir()
print(f"IPython directory: {ipython_dir}")

# Perform migration
if migrate():
    print("Successfully migrated IPython configuration to Jupyter")
else:
    print("No migration needed")

class JupyterMigrate(JupyterApp):
    """A Jupyter Migration App.
    
    Command-line application that migrates IPython < 4.0 configuration
    and data to Jupyter locations.
    """
    
    name: str = "jupyter-migrate"
    description: str  # Multi-line description of migration process
    
    def start(self) -> None:
        """Start the migration process."""

def get_data() -> dict[str, Any]:
    """Returns a dict of various user environment data.
    
    Gathers comprehensive system information including:
    - PATH and sys.path
    - Python executable and version
    - Platform information  
    - Jupyter command locations
    - Package lists (pip, conda)
    - Environment exports
    
    Returns:
        dict[str, Any]: Environment data dictionary
    """

def subs(cmd: list[str] | str) -> str | None:
    """Get data from commands that need to run outside of Python.
    
    Args:
        cmd: Command to execute (string or list)
        
    Returns:
        str | None: Command output or None if command failed
    """

def main() -> None:
    """Print out comprehensive system information for troubleshooting."""

from jupyter_core.troubleshoot import get_data, main

# Get structured environment data
env_data = get_data()
print("Python executable:", env_data['sys_exe'])
print("Platform:", env_data['platform'])
print("Jupyter locations:", env_data.get('which'))

# Or run the full troubleshooting report
main()  # Prints comprehensive system information

def _jupyter_abspath(subcommand: str) -> str:
    """Get the absolute path of a specified jupyter subcommand.
    
    Args:
        subcommand: Name of subcommand (without 'jupyter-' prefix)
        
    Returns:
        str: Absolute path to subcommand executable
        
    Raises:
        Exception: If subcommand not found or not executable
    """

def _path_with_self() -> list[str]:
    """Put jupyter's directory at the front of PATH.
    
    Ensures that /path/to/jupyter subcommand will find 
    /path/to/jupyter-subcommand even if other versions 
    are ahead on PATH.
    
    Returns:
        list[str]: Modified PATH directories
    """

def _execvp(cmd: str, argv: list[str]) -> None:
    """Cross-platform execvp that handles Windows properly.
    
    Python's execvp has problematic behavior on Windows,
    so this uses Popen on Windows and execvp on Unix.
    
    Args:
        cmd: Command to execute
        argv: Command arguments
    """

# Show version information
jupyter --version

# Show all Jupyter paths
jupyter --paths

# Show specific directories  
jupyter --config-dir
jupyter --data-dir
jupyter --runtime-dir

# Show paths as JSON
jupyter --paths --json

# Debug path resolution
jupyter --paths --debug

# Run subcommands
jupyter notebook
jupyter lab
jupyter console

# Migrate IPython configuration to Jupyter
jupyter-migrate

# The command is idempotent - safe to run multiple times
# Creates a marker file to avoid duplicate migrations

# Display comprehensive system information
jupyter-troubleshoot

# Output includes PATH, Python info, package lists, etc.
# Useful for diagnosing installation and configuration issues